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

\environment xcommon

\usemodule[chemml]

\StartManual{ChemML}{Hans Hagen}

\Description

The chemical \XML\ markup dialect provided by \CONTEXT\ is
relatively simple, but sufficient for everyday chemistry. Of
course we have elements that represent the building blocks
of chemistry:

\startitemize[packed]
\item atoms
\item ions
\item molecules
\stopitemize

In addition there are methods for:

\startitemize[packed]
\item reactions
\item bonds
\stopitemize

Reactions, molecules and ions can be annotated. For this we
provide:

\startitemize[packed]
\item captions
\stopitemize

For the moment there are no provisions for structure
formulas, but there will be some day (probably build on top
of the \CONTEXT\ module \PPCHTEX).

\blank

{\em Beware: the spacing may be improved and therefore
can change slightly in future versions.}

\Structure

The simplest building block is the atom:

\startbuffer
<chem>
  <atom> H </atom>
</chem>
\stopbuffer

\typebuffer \processXMLbuffer

You can dress up an atom with a couple of ornaments:

\startbuffer
<chem>
  <atom n="6" charge="-5" weight="652" protons="339"> Rx </atom>
</chem>
\stopbuffer

\typebuffer \processXMLbuffer

You (or nature) can combine atoms in molecules:

\startbuffer
<chem> <molecule>
  <atom n="2"> H </atom>
  <atom>       O </atom>
</molecule> </chem>
\stopbuffer

\typebuffer \processXMLbuffer

An efficient way of identifying multiple molecules is the
following:

\startbuffer
<chem> <molecule n="2">
  <atom n="2"> H </atom>
  <atom>       O </atom>
</molecule> </chem>
\stopbuffer

\typebuffer \processXMLbuffer

As you can see, a molecule is just a series of atoms and
again, we can add a couple of ornaments.

\startbuffer
<chem> <molecule n="2">
  <atom n="2" charge="+1"> H </atom>
  <atom       charge="-2"> O </atom>
</molecule> </chem>
\stopbuffer

\typebuffer \processXMLbuffer

Atoms with a charge are called ions. Because a charge can be
associated to a combination of atoms, you can also package
the atoms in an ion element.

\startbuffer
<chem> <molecule n="2">
  <ion charge="+2"> <atom n="2"> H </atom> </ion>
  <ion charge="-2"> <atom>       O </atom> </ion>
</molecule> </chem>
\stopbuffer

\typebuffer \processXMLbuffer

You can influence the appearance of a ion. Take the
following acid:

\startbuffer
<chem> <ion charge="-1">
  <atom> C </atom>
  <atom> O </atom>
  <atom> O </atom>
  <atom> H </atom>
</ion> </chem>
\stopbuffer

\typebuffer \processXMLbuffer

A different way to visualize the charge is to use brackets
around an ion. You can force this with a directive.

\startbuffer
<chem>
  <?context-chemml-directive ion alternative b ?>
  <molecule>
    <ion charge="-1">
      <atom> C </atom>
      <atom> O </atom>
      <atom> O </atom>
      <atom> H </atom>
    </ion>
  </molecule>
</chem>
\stopbuffer

\typebuffer \processXMLbuffer

As you can see in the next example, the negative charge of
the whole end up above the number of Y atoms.

\startbuffer
<chem> <molecule>
  <ion charge="-1">
    <atom> X </atom>
    <atom n="3"> Y </atom>
  </ion>
</molecule> </chem>
\stopbuffer

\typebuffer \processXMLbuffer

A molecule seldom comes alone. This is why we have an
encapsulating element dealing with reactions. This is a
presentational element, which means that we just have a
sequence of items to be represented.

\startbuffer
<formula>
  <chem>
    <reaction>
      <molecule n="2">
        <atom n="2"> H </atom>
      </molecule>
    <plus/>
      <molecule>
        <atom n="2"> O </atom>
      </molecule>
    <equilibrium/>
      <molecule n="2">
        <atom n="2"> H </atom>
        <atom>       O </atom>
      </molecule>
    <gives>
      <caption> wet feet </caption>
    </gives>
      <molecule n="2">
        <atom n="2"> H </atom>
        <atom>       O </atom>
      </molecule>
    </reaction>
  </chem>
</formula>
\stopbuffer

\typebuffer \processXMLbuffer

The following special symbols are available:

\starttabulate[|l|c|]
\HL
\NC element     \NC representation \NC \NR
\HL
\NC plus        \NC \XMLdata{<ichem><reaction><plus/>       </reaction></ichem>} \NC \NR
\NC minus       \NC \XMLdata{<ichem><reaction><minus/>      </reaction></ichem>} \NC \NR
\NC equal       \NC \XMLdata{<ichem><reaction><equal/>      </reaction></ichem>} \NC \NR
\NC gives       \NC \XMLdata{<ichem><reaction><gives/>      </reaction></ichem>} \NC \NR
\NC equilibrium \NC \XMLdata{<ichem><reaction><equilibrium/></reaction></ichem>} \NC \NR
\NC mesomeric   \NC \XMLdata{<ichem><reaction><mesomeric/>  </reaction></ichem>} \NC \NR
\HL
\stoptabulate

You can put some text (often expressing conditions) on top
or below the arrows. In that case you need to add a couple
or more elements and non empty alternatives of the arrow
elements.

\startbuffer
<formula>
  <chem>
    <reaction>
    <gives>
    </gives>
    <gives>
      <caption>first entry</caption>
    </gives>
    <gives>
      <caption>first entry</caption>
      <caption>second entry</caption>
    </gives>
    <gives/>
    </reaction>
  </chem>
</formula>
\stopbuffer

\typebuffer \processXMLbuffer

You can also add captions to molecules and ions. If you want
a caption to an atom, you need to encapsulate it in a
molecule.

\startbuffer
<chem>
  <reaction>
    <molecule n="2">
      <atom n="2"> H </atom>
      <caption> hydrogen </caption>
    </molecule>
  <plus/>
    <molecule>
      <atom n="2"> O </atom>
      <caption> oxygen </caption>
    </molecule>
  <gives>
    <caption> hefty </caption>
  </gives>
    <molecule n="2">
      <atom n="2"> H </atom>
      <atom> O </atom>
      <caption> water </caption>
    </molecule>
  </reaction>
</chem>
\stopbuffer

\typebuffer \processXMLbuffer

Another way to dress up a chemical formula is to visualize
bonds. Therefore we provide a simple bond element.

\startbuffer
<chem> <molecule>
  <atom> H </atom>
    <bond n="1"/>
  <atom> C </atom>
    <bond n="2"/>
  <atom> C </atom>
    <bond n="1"/>
  <atom> H </atom>
</molecule> </chem>
\stopbuffer

\typebuffer \processXMLbuffer

You can also use a more verbose series of commands to
achieve this visualization.

\startbuffer
<chem> <molecule>
  <atom> H </atom>
    <singlebond/>
  <atom> C </atom>
    <doublebond/>
  <atom> C </atom>
    <singlebond/>
  <atom> H </atom>
</molecule> </chem>
\stopbuffer

\typebuffer \processXMLbuffer

Normally the typesetting engine will adapt itself
automatically to either in||line or display chemistry. The
next example shows in||line usage.

\startbuffer
When we manage to bring <chem> <atom> H </atom> </chem>
(hydrogen) in contact with <chem> <atom> O </atom> </chem>
(oxygen) we get a bit of noise and fire but we end up with
<chem> <molecule> <atom n="2"> H </atom> <atom> O </atom>
</molecule> </chem> (water).
\stopbuffer

\typebuffer \processXMLbuffer

However, if you want to have a bit more control, you should
use one of the following capsules. The normal \type
{<chem>} element acts chooses one of these, depending on the
circumstances.

\starttabulate[|l|l|]
\HL
\NC element \NC meaning \NC \NR
\HL
\NC ichem   \NC in||line Chemistry \NC \NR
\NC dchem   \NC display Chemistry \NC \NR
\HL
\stoptabulate

\Usage

This module is loaded as any module:

\starttyping
\usemodule[chemml]
\stoptyping

\XMLexample

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

\Configuring

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

\Documentation

There is no additional documentation. The \TEX\ counterpart
of this module, namely \PPCHTEX, uses a representation more
in tune with the way one codes documents in \TEX.

\StopManual
