1CHEM(1) General Commands Manual CHEM(1)
2
6 chem - groff preprocessor for producing chemical structure diagrams
7
9 chem [--] [filespec ...]
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 A filespec argument is either a file name of an existing file or a mi‐
25 nus character -, meaning standard input. If no argument is specified
26 then standard input is taken automatically. -h and --help display a
27 usage message, whereas -v and --version display version information;
28 all exit.
29 The program chem originates from the Perl source file chem.pl. It
31 tells pic to include a copy of the macro file chem.pic. Moreover the
32 groff source file pic.tmac is loaded.
33 In a style reminiscent of eqn and pic, the chem diagrams are written in
35 a special language.
36 A set of chem lines looks like this
38 .cstart
40 chem data
41 .cend
42 Lines containing the keywords .cstart and .cend start and end the input
44 for chem, respectively. In pic context, i.e., after the call of .PS,
45 chem input can optionally be started by the line begin chem and ended
46 by the line with the single word end instead.
47 Anything outside these initialization lines is copied through without
49 modification; all data between the initialization lines is converted
50 into pic commands to draw the diagram.
51 As an example,
53 .cstart
55 CH3
56 bond
57 CH3
58 .cend
59 prints two CH3 groups with a bond between them.
61 To actually view this, you must run chem followed by groffer:
63 chem [file ...] | groffer
65 If you want to create just groff output, you must run chem followed by
67 groff with the option -p for the activation of pic:
68 chem [file ...] | groff -p ...
70
72 The chem input language is rather small. It provides rings of several
73 styles and a way to glue them together as desired, bonds of several
74 styles, moieties (e.g., C, NH3, ..., and strings.
75 Setting Variables
77 There are some variables that can be set by commands. Such commands
78 have two possible forms, either
79 variable value
81 or
83 variable = value
85 This sets the given variable to the argument value. If more arguments
87 are given only the last argument is taken, all other arguments are ig‐
88 nored.
89 There are only a few variables to be set by these commands:
91 textht arg
93 Set the height of the text to arg; default is 0.16.
94 cwid arg
96 Set the character width to arg; default is 0.12.
97 db arg Set the bond length to arg; default is 0.2.
99 size arg
101 Scale the diagram to make it look plausible at point size arg;
102 default is 10 point.
103 Bonds
105 This
106 bond [direction] [length n] [from Name|picstuff]
108 draws a single bond in direction from nearest corner of Name. bond can
110 also be double bond, front bond, back bond, etc. (We will get back to
111 Name soon.)
112 direction is the angle in degrees (0 up, positive clockwise) or a di‐
114 rection word like up, down, sw (= southwest), etc. If no direction is
115 specified, the bond goes in the current direction (usually that of the
116 last bond).
117 Normally the bond begins at the last object placed; this can be
119 changed by naming a from place. For instance, to make a simple alkyl
120 chain:
121 CH3
123 bond (this one goes right from the CH3)
124 C (at the right end of the bond)
125 double bond up (from the C)
126 O (at the end of the double bond)
127 bond right from C
128 CH3
129 A length in inches may be specified to override the default length.
131 Other pic commands can be tacked on to the end of a bond command, to
132 created dotted or dashed bonds or to specify a to place.
133 Rings
135 There are lots of rings, but only 5 and 6-sided rings get much support.
136 ring by itself is a 6-sided ring; benzene is the benzene ring with a
137 circle inside. aromatic puts a circle into any kind of ring.
138 ring [pointing (up|right|left|down)] [aromatic] [put Mol at n]
140 [double i,j k,l ... [picstuff]
141 The vertices of a ring are numbered 1, 2, ... from the vertex that
143 points in the natural compass direction. So for a hexagonal ring with
144 the point at the top, the top vertex is 1, while if the ring has a
145 point at the east side, that is vertex 1. This is expressed as
146 R1: ring pointing up
148 R2: ring pointing right
149 The ring vertices are named .V1, ..., .Vn, with .V1 in the pointing di‐
151 rection. So the corners of R1 are R1.V1 (the top), R1.V2, R1.V3, R1.V4
152 (the bottom), etc., whereas for R2, R2.V1 is the rightmost vertex and
153 R2.V4 the leftmost. These vertex names are used for connecting bonds
154 or other rings. For example,
155 R1: benzene pointing right
157 R2: benzene pointing right with .V6 at R1.V2
158 creates two benzene rings connected along a side.
160 Interior double bonds are specified as double n1,n2 n3,n4 ...; each
162 number pair adds an interior bond. So the alternate form of a benzene
163 ring is
164 ring double 1,2 3,4 5,6
166 Heterocycles (rings with something other than carbon at a vertex) are
168 written as put X at V, as in
169 R: ring put N at 1 put O at 2
171 In this heterocycle, R.N and R.O become synonyms for R.V1 and R.V2.
173 There are two 5-sided rings. ring5 is pentagonal with a side that
175 matches the 6-sided ring; it has four natural directions. A flatring
176 is a 5-sided ring created by chopping one corner of a 6-sided ring so
177 that it exactly matches the 6-sided rings.
178 The description of a ring has to fit on a single line.
180 Moieties and Strings
182 A moiety is a string of characters beginning with a capital letter,
183 such as N(C2H5)2. Numbers are converted to subscripts (unless they ap‐
184 pear to be fractional values, as in N2.5H). The name of a moiety is
185 determined from the moiety after special characters have been stripped
186 out: e.g., N(C2H5)2) has the name NC2H52.
187 Moieties can be specified in two kinds. Normally a moiety is placed
189 right after the last thing mentioned, separated by a semicolon sur‐
190 rounded by spaces, e.g.,
191 B1: bond ; OH
193 Here the moiety is OH; it is set after a bond.
195 As the second kind a moiety can be positioned as the first word in a
197 pic-like command, e.g.,
198 CH3 at C + (0.5,0.5)
200 Here the moiety is CH3. It is placed at a position relative to C, a
202 moiety used earlier in the chemical structure.
203 So moiety names can be specified as chem positions everywhere in the
205 chem code. Beneath their printing moieties are names for places.
206 The moiety BP is special. It is not printed but just serves as a mark
208 to be referred to in later chem commands. For example,
209 bond ; BP
211 sets a mark at the end of the bond. This can be used then for specify‐
213 ing a place. The name BP is derived from branch point (i.e., line
214 crossing).
215 A string within double quotes " is interpreted as a part of a chem com‐
217 mand. It represents a string that should be printed (without the
218 quotes). Text within quotes "..." is treated more or less like a moi‐
219 ety except that no changes are made to the quoted part.
220 Names
222 In the alkyl chain above, notice that the carbon atom C was used both
223 to draw something and as the name for a place. A moiety always defines
224 a name for a place; you can use your own names for places instead, and
225 indeed, for rings you will have to. A name is just
226 Name: ...
228 Name is often the name of a moiety like CH3, but it need not to be.
230 Any name that begins with a capital letter and which contains only let‐
231 ters and numbers is valid:
232 First: bond
234 bond 30 from First
235 Miscellaneous
237 The specific construction
238 bond ... ; moiety
240 is equivalent to
242 bond
244 moiety
245 Otherwise, each item has to be on a separate line (and only one line).
247 Note that there must be whitespace after the semicolon which separates
248 the commands.
249 A period character . or a single quote ' in the first column of a line
251 signals a troff command, which is copied through as-is.
252 A line whose first non-blank character is a hash character (#) is
254 treated as a comment and thus ignored. However, hash characters within
255 a word are kept.
256 A line whose first word is pic is copied through as-is after the word
258 pic has been removed.
259 The command
261 size n
263 scales the diagram to make it look plausible at point size n (default
265 is 10 point).
266 Anything else is assumed to be pic code, which is copied through with a
268 label.
269 Since chem is a pic preprocessor, it is possible to include pic state‐
271 ments in the middle of a diagram to draw things not provided for by
272 chem itself. Such pic statements should be included in chem code by
273 adding pic as the first word of this line for clarity.
274 The following pic commands are accepted as chem commands, so no pic
276 command word is needed:
277 define Start the definition of pic macro within chem.
279 [ Start a block composite.
281 ] End a block composite.
283 { Start a macro definition block.
285 } End a macro definition block.
287 The macro names from define statements are stored and their call is ac‐
289 cepted as a chem command as well.
290 WISH LIST
292 This TODO list was collected by Brian Kernighan.
293 Error checking is minimal; errors are usually detected and reported in
295 an oblique fashion by pic.
296 There is no library or file inclusion mechanism, and there is no short‐
298 hand for repetitive structures.
299 The extension mechanism is to create pic macros, but these are tricky
301 to get right and don't have all the properties of built-in objects.
302 There is no in-line chemistry yet (e.g., analogous to the $...$ con‐
304 struct of eqn).
305 There is no way to control entry point for bonds on groups. Normally a
307 bond connects to the carbon atom if entering from the top or bottom and
308 otherwise to the nearest corner.
309 Bonds from substituted atoms on heterocycles do not join at the proper
311 place without adding a bit of pic.
312 There is no decent primitive for brackets.
314 Text (quoted strings) doesn't work very well.
316 A squiggle bond is needed.
318
320 /usr/share/groff/1.22.4/pic/chem.pic
321 A collection of pic macros needed by chem.
322 /usr/share/groff/1.22.4/tmac/pic.tmac
324 A macro file which redefines .PS and .PE to center pic diagrams.
325 /usr/share/doc/groff/examples/chem/*.chem
327 Example files for chem.
328 /usr/share/doc/groff/examples/chem/122/*.chem
330 Example files from the classical chem article CHEM – A Program
331 for Typesetting Chemical Structure Diagrams [CSTR #122].
332
334 The GNU version of chem was written by Bernd Warken
335 ⟨groff-bernd.warken-72@web.de⟩. It is based on the documentation of
336 Brian Kernighan's original awk version of chem at ⟨http://
337 cm.bell-labs.com/cm/cs/who/bwk/index.html⟩.
338
340 groff(1), pic(1), groffer(1).
341 You can still get the original chem awk source ⟨http://
343 cm.bell-labs.com/netlib/typesetting/chem.gz⟩. Its README file was used
344 for this manual page.
345 The other classical document on chem is CHEM – A Program for
347 Typesetting Chemical Structure Diagrams [CSTR #122] ⟨http://
348 cm.bell-labs.com/cm/cs/cstr/122.ps.gz⟩.
349groff 1.22.4 21 July 2022 CHEM(1)