% content=tex
%
% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa

\environment xcommon

\usemodule[mathml,physml,chemml]

\StartManual{PhysML}{Hans Hagen \& Ton Otten}

\Description

This module runs on top of the \MATHML\ filters and provide
a way to add units to formulas. Since a unit is a property
of a component of a formula, one can imagine it being
defined as an attribute to math elements. In that case, a
typesetting engine should be clever enough to figure out
the final unit. Since this kind of artificial intelligence
is beyond what \CONTEXT\ can offer you, we stick to a
simpler method, based on the already present units engine.

The \CONTEXT\ units engine is responsible for a consistent
representation of units, not only in the symbols used, but
also in correct spacing (for what it's worth).

\Structure

To save keystrokes (and bytes), a simple way to represent a
number or variable with a unit is the following quick and
dirty way.

\startbuffer
<phys>
  <cn> 10 </cn>
  <cu> <Newton/> <Square/> <Meter/> <Per/> <Sec/> </cu>
</phys>
\stopbuffer

\typebuffer \processXMLbuffer

We could have used \type {<pn>} and \type {<pi>} but after
some experiments we found out that this is confusing when
with formula rich of $\pi$'s.

A more content \MATHML||like way of defining a unit is:

\startbuffer
<phys> <apply> <unit/>
  <cn> 10 </cn>
  <csymbol> <Square/> <Meter/> <Per/> <Sec/> </csymbol>
</apply> </phys>
\stopbuffer

\typebuffer \processXMLbuffer

Or, more compact:

\startbuffer
<phys> <apply> <unit/>
  <cn> 10 </cn>
  <cu> <Square/> <Meter/> <Per/> <Sec/> </cu>
</apply> </phys>
\stopbuffer

\typebuffer \processXMLbuffer

A bit more complicated example is the following:

\startbuffer
<phys> <apply> <unit/>
  <apply> <divide/> <ci> a </ci> <cn> 10 </cn> </apply>
  <cu> <Square/> <Meter/> <Per/> <Sec/> </cu>
</apply> </phys>
\stopbuffer

\typebuffer \processXMLbuffer

We also provide an alternative (equivalent) for \type
{</cu>}, where we reflect the sequential aspect in the name
of the element.

\startbuffer
<phys> <apply> <unit/>
  <cn> 10 </cn>
  <cunseq> <Square/> <Meter/> <Per/> <Sec/> </cunseq>
</apply> </phys>
\stopbuffer

\typebuffer \processXMLbuffer

In all these examples you will notice that the unit is
rather presentational in nature. The sequence entered is
similar to a pronounced unit. By using a leading capital we
make sure that no conflicts with existing or future \MATHML\
can arise.

There are two special elements. If a unit is on its own, it
should be preceded with \type {<Unit/>}, as in:

\startbuffer
Do you know what <phys> <cu> <Unit/> <Newton/> <Square/>
<Meter/> <Per/> <Sec/> </cu> </phys> is used for?
\stopbuffer

\typebuffer \processXMLbuffer \blank

The second special element is \type {<NoUnit/>}. You can use
this one when you use a prefix (like pico) on its own.

\startbuffer
Do you know what <phys> <cu> <Unit/> <Pico/> <NoUnit/> </cu>
</phys> stands for?
\stopbuffer

\typebuffer \processXMLbuffer \blank

If we omit \type {<NoUnit/>} here, the prefix will migrate to
the next unit.

\startbuffer
The meaning of <phys> <cu> <Unit/> <Hertz/> </cu> </phys> is
<unitmeaning label="Hertz"/>.
\stopbuffer

\typebuffer \processXMLbuffer

\Usage

This module is loaded as any module:

\starttyping
\usemodule[physml]
\stoptyping

\XMLexample

{\em Here we will collect a few examples.}

\TEXexample

Because the components that make up units are in fact
synonym entries, you can ask for an overview of used units
with their meaning.

\startbuffer
\placelistofunits
\stopbuffer

\typebuffer \getbuffer

\Configuring

{\em We will add some more control over spacing, lettering
and color later.}

\Documentation

More information on units can be found in the manual that
describes the units module and in the module file itself
(\type {m-units.tex}).

\StopManual
