\environment ppchtex-mkiv-style

\startcomponent ppchtex-mkiv-structures

\chapter{Structures}

The number of commands that is used to typeset chemical structure formulas
is, apart from some bell and whistle commands, limited to four.\footnote{The
concept structure in this manual only refers to the chemical structure. It is
not related to the document structure.} In the following example all of these
commands are used.

\startbuffer
\setupchemical[axis=on,frame=on]

\startchemical
  \chemical[SIX,B,R,RZ][1,2,3,4,5,6]
\stopchemical
\stopbuffer

\startfiguretext
  [left][]
  {none}
  {\getbuffer}
\example[ex:sixring]
\typebuffer
\stopfiguretext

With \type{\setupchemical} we can influence the makeup of the formulas. These
setups influence all the following formulas, unless they are superceded by
local setup variables.\footnote{One can of course limit the scope of the
variables by using \type{{ }} and/or the grouping macros \type{..group}.}

The set up variables can be defined right after \tex{startchemical}. In that
case the set up is only applied to one structure formula.

\startbuffer
\startchemical[frame=on,width=fit,height=fit]
  \chemical[CARBON,CB1][A,B,C,D,E,F]
\stopchemical
\stopbuffer

\startfiguretext
  [left][]
  {none}
  {\getbuffer}
\example
\typebuffer
\stopfiguretext

Both examples show that \type{\chemical} is the essential command. This
command that may be used more than once within a
\type{\start}||\type{\stop}||pair, is accompanied with two arguments. These
arguments are written between~\type{[ ]}. The first argument is used for
defining the chemical bonds, the second argument for the atoms and molecules
that make up the structure.

Text is typeset in mathematical mode, this means that you may type anything
that normally is allowed between~\type{$ $}.

We will explain the first example in more detail. The key \type{SIX} means
that we want to draw a sixring. In analogy we could type \type{ONE},
\type{THREE}, \type{FOUR} and \type{FIVE}, \type{EIGHT}, \type{CARBON},
\type{NEWMAN}, \type{CHAIR}, some alternatives on these keys and some
symbols.

\def\littlestructure[#1]%
  {\vbox
     {\startchemical[frame=on,scale=small,size=small]%
      \chemical[#1][1,2,3,4,5,6,7,8]%
      \stopchemical}}

\placefigure{none}
 \startcombination[4*3]
   {\littlestructure[ONE,SB,Z]}           {One}
   {\littlestructure[THREE,B,R,RZ]}       {Three}
   {\littlestructure[FOUR,B,R,RZ]}        {Four}
   {\littlestructure[FIVE,B,R,CRZ]}       {Five}
   {\littlestructure[SIX,B,R,RZ]}         {Six}
   {\littlestructure[EIGHT,B]}            {Eight}
   {\littlestructure[FIVE,FRONT,B,-R,+R]} {Five Front}
   {\littlestructure[SIX,FRONT,B,-R,+R]}  {Six Front}
   {\littlestructure[CARBON,CB]}          {Carbon}
   {\littlestructure[NEWMAN,STAGGER,CB]}  {Newman Stacker}
   {\littlestructure[NEWMAN,ECLIPSE,CB]}  {Newman Eclipse}
   {\littlestructure[CHAIR,B,-R,+R]}      {Chair}
 \stopcombination

The dimensions of \type{CHAIR} are somewhat different from the others. This
structure is also different in other means. Rotation for example is not
possible.

\startbuffer
\startchemical[frame=on,scale=small]
  \chemical
    [CHAIR,B,+R,-R,
     +RZ1,+RZ2,+RZ3,+RZ4,+RZ5,+RZ6,
     -RZ1,-RZ2,-RZ3,-RZ4,-RZ5,-RZ6]
    [a,b,c,d,e,f,1,2,3,4,5,6]
\stopchemical
\stopbuffer

\startfiguretext
  [left][]
  {none}
  {\getbuffer}
\example
\typebuffer
\stopfiguretext

Within a structure the chemical bonds between the \kap{c}||atoms are defined
in the same way. In this example we use~\type{B} and~\type{R}. Bonds within a
structure are numbered and can be defined by:

\starttyping
\chemical[SIX,B1,B2,B3,B4,B5,B6]
\chemical[SIX,B135]
\chemical[SIX,B1..5]
\stoptyping

These keys draw parts of a sixring. With \type{R} and \type{RZ} we place
substituents on the ring. The key \type{R} draws the bond from a ring corner
to the substituent ($\angle~120^\circ$). The corner is also identified with a
number.

\starttyping
\chemical[SIX,B1..6,R1..6]
\stoptyping

The defininition above draws the six bonds in the sixring and the bonds to
the substituents. The substituents are identified by the key \type{RZ}. Again
numbers are used to mark the position. The substituents themselves are
defined as text in the second argument.

\startbuffer
\startchemical[frame=on,width=6000]
  \chemical[SIX,B1..6,R1..6,RZ1..3][CH_3,CH_3,OH]
\stopchemical
\stopbuffer

\startfiguretext
  [left][]
  {none}
  {\getbuffer}
\example
\typebuffer
\stopfiguretext

When the second argument is left out no text (substituents) are placed on
the ring and the key \type{RZ1..3} has no effect.

Splitting the specification part from the text has the advantage
that we can predefine structures (as we will see later) that we
call within a structure and that pick up text from the calling
structure. In such a nested case the texts are put on a sort of
stack and fetching a text can involve the whole stack

The disadvantage is that in complex structures it might be hard to
see which text belongs to what specification. Therefore the \MKIV\
version provides a key/value variant as well.

\startbuffer
\startchemical[frame=on]
  \chemical[SIX,B,R,RZ1=a]
\stopchemical
\stopbuffer

\startfiguretext[left]{none}{\getbuffer}\example\typebuffer\stopfiguretext

\startbuffer
\startchemical[frame=on]
  \chemical[SIX,B,R,RZ1..3=a]
\stopchemical
\stopbuffer

\startfiguretext[left]{none}{\getbuffer}\example\typebuffer\stopfiguretext

\startbuffer
\startchemical[frame=on]
  \chemical[SIX,B,R,RZ135=a]
\stopchemical
\stopbuffer

\startfiguretext[left]{none}{\getbuffer}\example\typebuffer\stopfiguretext

\startbuffer
\startchemical[frame=on]
  \chemical[SIX,B,R,RZ=a]
\stopchemical
\stopbuffer

As you can see here, the text is repeated in the case of a key
specification that involves more bonds. Compare this with the
split definition approach:

\startfiguretext[left]{none}{\getbuffer}\example\typebuffer\stopfiguretext

\startbuffer
\startchemical[frame=on]
  \chemical[SIX,B,R,RZ] [a]
\stopchemical
\stopbuffer

\startfiguretext[left]{none}{\getbuffer}\example\typebuffer\stopfiguretext

\startbuffer
\startchemical[frame=on]
  \chemical[SIX,B,R,RZ] [a,b]
\stopchemical
\stopbuffer

\startfiguretext[left]{none}{\getbuffer}\example\typebuffer\stopfiguretext

\stopcomponent
