1chem(1) General Commands Manual chem(1)
2
6 chem - embed chemical structure diagrams in groff documents
7
9 chem [--] [file ...]
10 chem -h
12 chem --help
13 chem -v
15 chem --version
16
18 chem produces chemical structure diagrams. Today's version is best
19 suited for organic chemistry (bonds, rings). The chem program is a
20 groff preprocessor like eqn, pic, tbl, etc. It generates pic output
21 such that all chem parts are translated into diagrams of the pic lan‐
22 guage.
23 If no operands are given, or if file is “-”, chem reads the standard
25 input stream. -h and --help display a usage message, whereas -v and
26 --version display version information; all exit.
27 The program chem originates from the Perl source file chem.pl. It
29 tells pic to include a copy of the macro file chem.pic. Moreover the
30 groff source file pic.tmac is loaded.
31 In a style reminiscent of eqn and pic, the chem diagrams are written in
33 a special language.
34 A set of chem lines looks like this
36 .cstart
38 chem data
39 .cend
40 Lines containing the keywords .cstart and .cend start and end the input
42 for chem, respectively. In pic context, i.e., after the call of .PS,
43 chem input can optionally be started by the line begin chem and ended
44 by the line with the single word end instead.
45 Anything outside these initialization lines is copied through without
47 modification; all data between the initialization lines is converted
48 into pic commands to draw the diagram.
49 As an example,
51 .cstart
53 CH3
54 bond
55 CH3
56 .cend
57 prints two CH3 groups with a bond between them.
59 If you want to create just groff output, you must run chem followed by
61 groff with the option -p for the activation of pic:
62 chem [file ...] | groff -p ...
64
66 The chem input language is rather small. It provides rings of several
67 styles and a way to glue them together as desired, bonds of several
68 styles, moieties (e.g., C, NH3, ..., and strings.
69 Setting variables
71 There are some variables that can be set by commands. Such commands
72 have two possible forms, either
73 variable value
75 or
77 variable = value
79 This sets the given variable to the argument value. If more arguments
81 are given only the last argument is taken, all other arguments are ig‐
82 nored.
83 There are only a few variables to be set by these commands:
85 textht arg
87 Set the height of the text to arg; default is 0.16.
88 cwid arg
90 Set the character width to arg; default is 0.12.
91 db arg Set the bond length to arg; default is 0.2.
93 size arg
95 Scale the diagram to make it look plausible at point size arg;
96 default is 10 point.
97 Bonds
99 This
100 bond [direction] [length n] [from Name|picstuff]
102 draws a single bond in direction from nearest corner of Name. bond can
104 also be double bond, front bond, back bond, etc. (We will get back to
105 Name soon.)
106 direction is the angle in degrees (0 up, positive clockwise) or a di‐
108 rection word like up, down, sw (= southwest), etc. If no direction is
109 specified, the bond goes in the current direction (usually that of the
110 last bond).
111 Normally the bond begins at the last object placed; this can be
113 changed by naming a from place. For instance, to make a simple alkyl
114 chain:
115 CH3
117 bond (this one goes right from the CH3)
118 C (at the right end of the bond)
119 double bond up (from the C)
120 O (at the end of the double bond)
121 bond right from C
122 CH3
123 A length in inches may be specified to override the default length.
125 Other pic commands can be tacked on to the end of a bond command, to
126 created dotted or dashed bonds or to specify a to place.
127 Rings
129 There are lots of rings, but only five- and six-sided rings get much
130 support. ring by itself is a six-sided ring; benzene is the benzene
131 ring with a circle inside. aromatic puts a circle into any kind of
132 ring.
133 ring [pointing (up|right|left|down)] [aromatic] [put Mol at n]
135 [double i,j k,l ... [picstuff]
136 The vertices of a ring are numbered 1, 2, ... from the vertex that
138 points in the natural compass direction. So for a hexagonal ring with
139 the point at the top, the top vertex is 1, while if the ring has a
140 point at the east side, that is vertex 1. This is expressed as
141 R1: ring pointing up
143 R2: ring pointing right
144 The ring vertices are named .V1, ..., .Vn, with .V1 in the pointing di‐
146 rection. So the corners of R1 are R1.V1 (the top), R1.V2, R1.V3, R1.V4
147 (the bottom), etc., whereas for R2, R2.V1 is the rightmost vertex and
148 R2.V4 the leftmost. These vertex names are used for connecting bonds
149 or other rings. For example,
150 R1: benzene pointing right
152 R2: benzene pointing right with .V6 at R1.V2
153 creates two benzene rings connected along a side.
155 Interior double bonds are specified as double n1,n2 n3,n4 ...; each
157 number pair adds an interior bond. So the alternate form of a benzene
158 ring is
159 ring double 1,2 3,4 5,6
161 Heterocycles (rings with something other than carbon at a vertex) are
163 written as put X at V, as in
164 R: ring put N at 1 put O at 2
166 In this heterocycle, R.N and R.O become synonyms for R.V1 and R.V2.
168 There are two five-sided rings. ring5 is pentagonal with a side that
170 matches the six-sided ring; it has four natural directions. A flatring
171 is a five-sided ring created by chopping one corner of a six-sided ring
172 so that it exactly matches the six-sided rings.
173 The description of a ring has to fit on a single line.
175 Moieties and strings
177 A moiety is a string of characters beginning with a capital letter,
178 such as N(C2H5)2. Numbers are converted to subscripts (unless they ap‐
179 pear to be fractional values, as in N2.5H). The name of a moiety is
180 determined from the moiety after special characters have been stripped
181 out: e.g., N(C2H5)2) has the name NC2H52.
182 Moieties can be specified in two kinds. Normally a moiety is placed
184 right after the last thing mentioned, separated by a semicolon sur‐
185 rounded by spaces, e.g.,
186 B1: bond ; OH
188 Here the moiety is OH; it is set after a bond.
190 As the second kind a moiety can be positioned as the first word in a
192 pic-like command, e.g.,
193 CH3 at C + (0.5,0.5)
195 Here the moiety is CH3. It is placed at a position relative to C, a
197 moiety used earlier in the chemical structure.
198 So moiety names can be specified as chem positions everywhere in the
200 chem code. Beneath their printing moieties are names for places.
201 The moiety BP is special. It is not printed but just serves as a mark
203 to be referred to in later chem commands. For example,
204 bond ; BP
206 sets a mark at the end of the bond. This can be used then for specify‐
208 ing a place. The name BP is derived from branch point (i.e., line
209 crossing).
210 A string within double quotes " is interpreted as a part of a chem com‐
212 mand. It represents a string that should be printed (without the
213 quotes). Text within quotes "..." is treated more or less like a moi‐
214 ety except that no changes are made to the quoted part.
215 Names
217 In the alkyl chain above, notice that the carbon atom C was used both
218 to draw something and as the name for a place. A moiety always defines
219 a name for a place; you can use your own names for places instead, and
220 indeed, for rings you will have to. A name is just
221 Name: ...
223 Name is often the name of a moiety like CH3, but it need not to be.
225 Any name that begins with a capital letter and which contains only let‐
226 ters and numbers is valid:
227 First: bond
229 bond 30 from First
230 Miscellaneous
232 The specific construction
233 bond ... ; moiety
235 is equivalent to
237 bond
239 moiety
240 Otherwise, each item has to be on a separate line (and only one line).
242 Note that there must be whitespace after the semicolon which separates
243 the commands.
244 A period character . or a single quote ' in the first column of a line
246 signals a troff command, which is copied through as-is.
247 A line whose first non-blank character is a hash character (#) is
249 treated as a comment and thus ignored. However, hash characters within
250 a word are kept.
251 A line whose first word is pic is copied through as-is after the word
253 pic has been removed.
254 The command
256 size n
258 scales the diagram to make it look plausible at point size n (default
260 is 10 point).
261 Anything else is assumed to be pic code, which is copied through with a
263 label.
264 Since chem is a pic preprocessor, it is possible to include pic state‐
266 ments in the middle of a diagram to draw things not provided for by
267 chem itself. Such pic statements should be included in chem code by
268 adding pic as the first word of this line for clarity.
269 The following pic commands are accepted as chem commands, so no pic
271 command word is needed:
272 define Start the definition of pic macro within chem.
274 [ Start a block composite.
276 ] End a block composite.
278 { Start a macro definition block.
280 } End a macro definition block.
282 The macro names from define statements are stored and their call is ac‐
284 cepted as a chem command as well.
285 Wish list
287 This TODO list was collected by Brian Kernighan.
288 Error checking is minimal; errors are usually detected and reported in
290 an oblique fashion by pic.
291 There is no library or file inclusion mechanism, and there is no short‐
293 hand for repetitive structures.
294 The extension mechanism is to create pic macros, but these are tricky
296 to get right and don't have all the properties of built-in objects.
297 There is no in-line chemistry yet (e.g., analogous to the $...$ con‐
299 struct of eqn).
300 There is no way to control entry point for bonds on groups. Normally a
302 bond connects to the carbon atom if entering from the top or bottom and
303 otherwise to the nearest corner.
304 Bonds from substituted atoms on heterocycles do not join at the proper
306 place without adding a bit of pic.
307 There is no decent primitive for brackets.
309 Text (quoted strings) doesn't work very well.
311 A squiggle bond is needed.
313
315 /usr/share/groff/1.23.0/pic/chem.pic
316 A collection of pic macros needed by chem.
317 /usr/share/groff/1.23.0/tmac/pic.tmac
319 A macro file which redefines .PS, .PE, and .PF to center pic di‐
320 agrams.
321 /usr/share/doc/groff/examples/chem/*.chem
323 Example files for chem.
324 /usr/share/doc/groff/examples/chem/122/*.chem
326 Example files from the chem article by its authors, “CHEM—A Pro‐
327 gram for Typesetting Chemical Structure Diagrams: User Manual”
328 (CSTR #122).
329
331 The GNU version of chem was written by Bernd Warken ⟨groff-bernd
332 .warken-72@web.de⟩. It is based on the documentation of Brian
333 Kernighan's original awk version of chem.
334
336 “CHEM—A Program for Typesetting Chemical Diagrams: User Manual” by Jon
337 L. Bentley, Lynn W. Jelinski, and Brian W. Kernighan, 1992, AT&T Bell
338 Laboratories Computing Science Technical Report No. 122
339 groff(1), pic(1)
341groff 1.23.0 2 November 2023 chem(1)