# chem

## Name



           chem - embed chemical structure diagrams in _groff_ documents
    


## Synopsis



           **chem**[**--**] [_file_ ...]
    
           **chem -h**
    
           **chem --help**
    
           **chem -v**
    
           **chem --version**
    


## Description



           _chem_ produces chemical structure diagrams.  Today's version is
           best suited for organic chemistry (bonds, rings).  The _chem_
           program is a _groff_ preprocessor like _eqn_ , _pic_ , _tbl_ , etc.  It
           generates _pic_ output such that all _chem_ parts are translated into
           diagrams of the _pic_ language.
    
           If no operands are given, or if _file_ is “**-** ”, _chem_ reads the
           standard input stream.  **-h** and **--help** display a usage message,
           whereas **-v** and **--version** display version information; all exit.
    
           The program _chem_ originates from the Perl source file _chem.pl_.  It
           tells _pic_ to include a copy of the macro file _chem.pic_.  Moreover
           the _groff_ source file _pic.tmac_ is loaded.
    
           In a style reminiscent of _eqn_ and _pic_ , the _chem_ diagrams are
           written in a special language.
    
           A set of _chem_ lines looks like this
    
                  .cstart
                  _chem data_
                  .cend
    
           Lines containing the keywords **.cstart** and **.cend** start and end the
           input for _chem_ , respectively.  In _pic_ context, i.e., after the
           call of **.PS** , _chem_ input can optionally be started by the line
           **begin chem** and ended by the line with the single word **end** instead.
    
           Anything outside these initialization lines is copied through
           without modification; all data between the initialization lines is
           converted into _pic_ commands to draw the diagram.
    
           As an example,
    
                  .cstart
                  CH3
                  bond
                  CH3
                  .cend
    
           prints two **CH3** groups with a bond between them.
    
           If you want to create just _groff_ output, you must run _chem_
           followed by _groff_ with the option **-p** for the activation of _pic_ :
    
                  _chem_ [_file_ ...] **| groff -p**...
    


## Language



           The _chem_ input language is rather small.  It provides rings of
           several styles and a way to glue them together as desired, bonds
           of several styles, moieties (e.g., **C** , **NH3** , ..., and strings.
    
       **Setting variables**
           There are some variables that can be set by commands.  Such
           commands have two possible forms, either
    
                  _variable value_
    
           or
    
                  _variable_ **=**_value_
    
           This sets the given _variable_ to the argument _value_.  If more
           arguments are given only the last argument is taken, all other
           arguments are ignored.
    
           There are only a few variables to be set by these commands:
    
           **textht** _arg_
                  Set the height of the text to _arg_ ; default is 0.16.
    
           **cwid** _arg_
                  Set the character width to _arg_ ; default is 0.12.
    
           **db** _arg_ Set the bond length to _arg_ ; default is 0.2.
    
           **size** _arg_
                  Scale the diagram to make it look plausible at point size
                  _arg_ ; default is 10 point.
    
       **Bonds**
           **bond**[_direction_] [_length n_] [**from** _Name_ |_picstuff_]
    
           The **bond** command draws a single bond in direction from nearest
           corner of _Name_.  **bond** can also be **double bond** , **front bond** , **back**
           **bond** , etc.  (We will get back to _Name_ soon.)
    
           _direction_ is the angle in degrees (0 up, positive clockwise) or a
           direction word like **up** , **down** , **sw**(= southwest), etc.  If no
           direction is specified, the bond goes in the current direction
           (usually that of the last bond).
    
           Normally the bond begins at the last object placed;  this can be
           changed by naming a **from** place.  For instance, to make a simple
           alkyl chain:
                  **CH3**
                  **bond**(this one goes right from the CH3)
                  **C**(at the right end of the bond)
                  **double bond up**(from the C)
                  **O**(at the end of the double bond)
                  **bond right from C**
                  **CH3**
    
           A length in inches may be specified to override the default
           length.  Other _pic_ commands can be tacked on to the end of a bond
           command, to created dotted or dashed bonds or to specify a **to**
           place.
    
       **Rings**
           There are lots of rings, but only five- and six-sided rings get
           much support.  **ring** by itself is a six-sided ring; **benzene** is the
           benzene ring with a circle inside.  **aromatic** puts a circle into
           any kind of ring.
    
           **ring**[**pointing**(**up** |**right** |**left** |**down**)] [**aromatic**] [**put Mol at** _n_]
                [**double** _i_ ,_j k_ ,_l_ ... [_picstuff_]
    
           The vertices of a ring are numbered 1, 2, ... from the vertex that
           points in the natural compass direction.  So for a hexagonal ring
           with the point at the top, the top vertex is 1, while if the ring
           has a point at the east side, that is vertex 1.  This is expressed
           as
    
                  R1: ring pointing up
                  R2: ring pointing right
    
           The ring vertices are named **.V1** , ..., **.V** _n_ , with **.V1** in the
           pointing direction.  So the corners of **R1** are **R1.V1**(the _top_),
           **R1.V2** , **R1.V3** , **R1.V4**(the _bottom_), etc., whereas for **R2** , **R2.V1** is
           the rightmost vertex and **R2.V4** the leftmost.  These vertex names
           are used for connecting bonds or other rings.  For example,
    
                  R1: benzene pointing right
                  R2: benzene pointing right with .V6 at R1.V2
    
           creates two benzene rings connected along a side.
    
           Interior double bonds are specified as **double** _n1_**,**_n2 n3_**,**_n4_ ...**;**
           each number pair adds an interior bond.  So the alternate form of
           a benzene ring is
    
                  **ring double 1,2 3,4 5,6**
    
           Heterocycles (rings with something other than carbon at a vertex)
           are written as **put** _X_ **at** _V_ , as in
    
                  **R: ring put N at 1 put O at 2**
    
           In this heterocycle, **R.N** and **R.O** become synonyms for **R.V1** and
           **R.V2**.
    
           There are two five-sided rings.  **ring5** is pentagonal with a side
           that matches the six-sided ring; it has four natural directions.
           A **flatring** is a five-sided ring created by chopping one corner of
           a six-sided ring so that it exactly matches the six-sided rings.
    
           The description of a ring has to fit on a single line.
    
       **Moieties and strings**
           A moiety is a string of characters beginning with a capital
           letter, such as N(C2H5)2.  Numbers are converted to subscripts
           (unless they appear to be fractional values, as in N2.5H).  The
           name of a moiety is determined from the moiety after special
           characters have been stripped out: e.g., N(C2H5)2) has the name
           NC2H52.
    
           Moieties can be specified in two kinds.  Normally a moiety is
           placed right after the last thing mentioned, separated by a
           semicolon surrounded by spaces, e.g.,
    
                  **B1: bond ; OH**
    
           Here the moiety is **OH** ; it is set after a bond.
    
           As the second kind a moiety can be positioned as the first word in
           a _pic_ -like command, e.g.,
    
                  **CH3 at C + (0.5,0.5)**
    
           Here the moiety is **CH3**.  It is placed at a position relative to **C** ,
           a moiety used earlier in the chemical structure.
    
           So moiety names can be specified as _chem_ positions everywhere in
           the _chem_ code.  Beneath their printing moieties are names for
           places.
    
           The moiety **BP** is special.  It is not printed but just serves as a
           mark to be referred to in later _chem_ commands.  For example,
    
                  **bond ; BP**
    
           sets a mark at the end of the bond.  This can be used then for
           specifying a place.  The name **BP** is derived from _branch point_
           (i.e., line crossing).
    
           A string within double quotes **"** is interpreted as a part of a _chem_
           command.  It represents a string that should be printed (without
           the quotes).  Text within quotes **"**...**"** is treated more or less
           like a moiety except that no changes are made to the quoted part.
    
       **Names**
           In the alkyl chain above, notice that the carbon atom **C** was used
           both to draw something and as the name for a place.  A moiety
           always defines a name for a place;  you can use your own names for
           places instead, and indeed, for rings you will have to.  A name is
           just
    
                  _Name_**:**...
    
           _Name_ is often the name of a moiety like **CH3** , but it need not to
           be.  Any name that begins with a capital letter and which contains
           only letters and numbers is valid.
    
                  First: bond
                         "bond 30 from First"
    
       **Miscellaneous**
           The specific construction
    
                  **bond**... **; moiety**
    
           is equivalent to
    
                  bond
                  moiety
    
           Otherwise, each item has to be on a separate line (and only one
           line).  Note that there must be whitespace after the semicolon
           which separates the commands.
    
           A period character **.** or a single quote **'** in the first column of a
           line signals a _troff_ command, which is copied through as-is.
    
           A line whose first non-blank character is a hash character (**#**) is
           treated as a comment and thus ignored.  However, hash characters
           within a word are kept.
    
           A line whose first word is **pic** is copied through as-is after the
           word **pic** has been removed.
    
           The command
    
                  **size** _n_
    
           scales the diagram to make it look plausible at point size _n_
           (default is 10 point).
    
           Anything else is assumed to be _pic_ code, which is copied through
           with a label.
    
           Since _chem_ is a _pic_ preprocessor, it is possible to include _pic_
           statements in the middle of a diagram to draw things not provided
           for by _chem_ itself.  Such _pic_ statements should be included in
           _chem_ code by adding **pic** as the first word of this line for
           clarity.
    
           The following _pic_ commands are accepted as _chem_ commands, so no
           **pic** command word is needed:
    
                  **define** Start the definition of _pic_ macro within _chem_.
    
                  **[** Start a block composite.
    
                  **]** End a block composite.
    
                  **{** Start a macro definition block.
    
                  **}** End a macro definition block.
    
           The macro names from **define** statements are stored and their call
           is accepted as a _chem_ command as well.
    
       **Wish list**
           This TODO list was collected by Brian Kernighan.
    
           Error checking is minimal; errors are usually detected and
           reported in an oblique fashion by _pic_.
    
           There is no library or file inclusion mechanism, and there is no
           shorthand for repetitive structures.
    
           The extension mechanism is to create _pic_ macros, but these are
           tricky to get right and don't have all the properties of built-in
           objects.
    
           There is no in-line chemistry yet (e.g., analogous to the **$**...**$**
           construct of _eqn_).
    
           There is no way to control entry point for bonds on groups.
           Normally a bond connects to the carbon atom if entering from the
           top or bottom and otherwise to the nearest corner.
    
           Bonds from substituted atoms on heterocycles do not join at the
           proper place without adding a bit of _pic_.
    
           There is no decent primitive for brackets.
    
           Text (quoted strings) doesn't work very well.
    
           A squiggle bond is needed.
    


## Files



           _/usr/local/share/groff/1.23.0/pic/chem.pic_
                  A collection of _pic_ macros needed by _chem_.
    
           _/usr/local/share/groff/1.23.0/tmac/pic.tmac_
                  A macro file which redefines **.PS** , **.PE** , and **.PF** to center
                  _pic_ diagrams.
    
           _/usr/local/share/doc/groff-1.23.0/examples/chem/_ *_.chem_
                  Example files for _chem_.
    
           _/usr/local/share/doc/groff-1.23.0/examples/chem/122/_ *_.chem_
                  Example files from the _chem_ article by its authors, “CHEM—A
                  Program for Typesetting Chemical Structure Diagrams: User
                  Manual” (CSTR #122).
    


## Authors



           The GNU version of _chem_ was written by Bernd Warken ⟨groff-bernd
           .warken-72@web.de⟩.  It is based on the documentation of Brian
           Kernighan's original _awk_ version of _chem_.
    


## See also



           “CHEM—A Program for Typesetting Chemical Diagrams: User Manual” by
           Jon L. Bentley, Lynn W. Jelinski, and Brian W. Kernighan, 1992,
           AT&T Bell Laboratories Computing Science Technical Report No. 122
    
           _groff_(1), _pic_(1)
    


* * *