# phpman > man > CHEM(1) [CHEM(1)](https://www.chedong.com/phpMan.php/man/CHEM/1/markdown) General Commands Manual [CHEM(1)](https://www.chedong.com/phpMan.php/man/CHEM/1/markdown) ## NAME chem - groff preprocessor for producing chemical structure diagrams ## SYNOPSIS **chem** [**--**] [_filespec_ ...] ### chem -h ### chem --help ### chem -v ### chem --version ## DESCRIPTION _chem_ produces chemical structure diagrams. Today's version is best suited for organic chem‐ istry (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_ lan‐ guage. A _filespec_ argument is either a file name of an existing file or a minus character **-**, meaning standard input. If no argument is specified then standard input is taken automatically. **-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**, respec‐ tively. 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. To actually view this, you must run **chem** followed by **groffer**: **chem** **[file** **...]** **|** **groffer** If you want to create just **groff** output, you must run **chem** followed by **groff** with the option ### -p **chem** **[file** **...]** **|** **groff** **-p** **...** ## THE 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 This **bond** [_direction_] [_length_ _n_] [**from** _Name_|_picstuff_] 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 di‐ rection (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 5 and 6-sided rings get much support. **ring** by itself is a 6-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 com‐ pass 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 cor‐ ners 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 inte‐ rior 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 5-sided rings. **ring5** is pentagonal with a side that matches the 6-sided ring; it has four natural directions. A **flatring** is a 5-sided ring created by chopping one corner of a 6-sided ring so that it exactly matches the 6-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. Num‐ bers 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_ com‐ mand, 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 in‐ cluded 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_ com‐ mand 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/share/groff/1.22.4/pic/chem.pic_ A collection of _pic_ macros needed by **chem**. _/usr/share/groff/1.22.4/tmac/pic.tmac_ A macro file which redefines **.PS** and **.PE** to center _pic_ diagrams. _/usr/share/doc/groff-base/examples/chem/_*_.chem_ Example files for _chem_. _/usr/share/doc/groff-base/examples/chem/122/_*_.chem_ Example files from the classical _chem_ article _CHEM_ _– _A_ _Program_ _for_ _Typesetting_ _Chemi__‐ _cal_ _Structure_ _Diagrams_ [CSTR #122]. ## AUTHORS The GNU version of **chem** was written by Bernd Warken ⟨⟩. It is based on the documentation of Brian Kernighan's original _awk_ version of _chem_ at ⟨http:// cm.bell-labs.com/cm/cs/who/bwk/index.html⟩. ## SEE ALSO [**groff**(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown), [**pic**(1)](https://www.chedong.com/phpMan.php/man/pic/1/markdown), [**groffer**(1)](https://www.chedong.com/phpMan.php/man/groffer/1/markdown). You can still get the original chem awk source ⟨ chem.gz⟩. Its **README** file was used for this manual page. The other classical document on _chem_ is _CHEM_ _– _A_ _Program_ _for_ _Typesetting_ _Chemical_ _Structure_ _Diagrams_ [CSTR #122] ⟨⟩. groff 1.22.4 23 March 2022 [CHEM(1)](https://www.chedong.com/phpMan.php/man/CHEM/1/markdown)