1CHEM(1) General Commands Manual CHEM(1)
2
3
4
6 chem - groff preprocessor for producing chemical structure diagrams
7
9 chem [option ....] [--] [filespec ....]
10
11 chem -h | --help
12
13 chem -v | --version
14
16 There are no other options than -h, --help, -v, and --version; these
17 options provoke the printing of a version or usage information, respec‐
18 tively, and all filespec arguments are ignored. A filespec argument is
19 either a file name of an existing file or a minus character -, meaning
20 standard input. If no argument is specified then standard input is
21 taken automatically.
22
24 chem produces chemical structure diagrams. Today's version is best
25 suited for organic chemistry (bonds, rings). The chem program is a
26 groff preprocessor like eqn, pic, tbl, etc. It generates pic output
27 such that all chem parts are translated into diagrams of the pic lan‐
28 guage.
29
30 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
34 In a style reminiscent of eqn and pic, the chem diagrams are written in
35 a special language.
36
37 A set of chem lines looks like this
38
39 .cstart
40 chem data
41 .cend
42
43 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
48 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
52 As an example,
53
54 .cstart
55 CH3
56 bond
57 CH3
58 .cend
59
60 prints two CH3 groups with a bond between them.
61
62 To actually view this, you must run chem followed by groffer:
63
64 chem [file ....] | groffer
65
66 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
69 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
76 Setting Variables
77 There are some variables that can be set by commands. Such commands
78 have two possible forms, either
79
80 variable value
81
82 or
83
84 variable = value
85
86 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
88 ignored.
89
90 There are only a few variables to be set by these commands:
91
92 textht arg
93 Set the height of the text to arg; default is 0.16.
94
95 cwid arg
96 Set the character width to arg; default is 0.12.
97
98 db arg Set the bond length to arg; default is 0.2.
99
100 size arg
101 Scale the diagram to make it look plausible at point size arg;
102 default is 10 point.
103
104 Bonds
105 This
106
107 bond [direction] [length n] [from Name|picstuff]
108
109 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
113 direction is the angle in degrees (0 up, positive clockwise) or a
114 direction word like up, down, sw (= southwest), etc. If no direction
115 is specified, the bond goes in the current direction (usually that of
116 the last bond).
117
118 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
122 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
130 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
134 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
139 ring [pointing (up|right|left|down)] [aromatic] [put Mol at n]
140 [double i,j k,l .... [picstuff]
141
142 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
147 R1: ring pointing up
148 R2: ring pointing right
149
150 The ring vertices are named .V1, ...., .Vn, with .V1 in the pointing
151 direction. So the corners of R1 are R1.V1 (the top), R1.V2, R1.V3,
152 R1.V4 (the bottom), etc., whereas for R2, R2.V1 is the rightmost vertex
153 and R2.V4 the leftmost. These vertex names are used for connecting
154 bonds or other rings. For example,
155
156 R1: benzene pointing right
157 R2: benzene pointing right with .V6 at R1.V2
158
159 creates two benzene rings connected along a side.
160
161 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
165 ring double 1,2 3,4 5,6
166
167 Heterocycles (rings with something other than carbon at a vertex) are
168 written as put X at V, as in
169
170 R: ring put N at 1 put O at 2
171
172 In this heterocycle, R.N and R.O become synonyms for R.V1 and R.V2.
173
174 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
179 The description of a ring has to fit on a single line.
180
181 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
184 appear 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
188 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
192 B1: bond ; OH
193
194 Here the moiety is OH; it is set after a bond.
195
196 As the second kind a moiety can be positioned as the first word in a
197 pic-like command, e.g.,
198
199 CH3 at C + (0.5,0.5)
200
201 Here the moiety is CH3. It is placed at a position relative to C, a
202 moiety used earlier in the chemical structure.
203
204 So moiety names can be specified as chem positions everywhere in the
205 chem code. Beneath their printing moieties are names for places.
206
207 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
210 bond ; BP
211
212 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
216 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
221 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
227 Name: ....
228
229 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
233 First: bond
234 bond 30 from First
235
236 Miscellaneous
237 The specific construction
238
239 bond .... ; moiety
240
241 is equivalent to
242
243 bond
244 moiety
245
246 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
250 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
253 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
257 A line whose first word is pic is copied through as-is after the word
258 pic has been removed.
259
260 The command
261
262 size n
263
264 scales the diagram to make it look plausible at point size n (default
265 is 10 point).
266
267 Anything else is assumed to be pic code, which is copied through with a
268 label.
269
270 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
275 The following pic commands are accepted as chem commands, so no pic
276 command word is needed:
277
278 define Start the definition of pic macro within chem.
279
280 [ Start a block composite.
281
282 ] End a block composite.
283
284 { Start a macro definition block.
285
286 } End a macro definition block.
287
288 The macro names from define statements are stored and their call is
289 accepted as a chem command as well.
290
291 WISH LIST
292 This TODO list was collected by Brian Kernighan.
293
294 Error checking is minimal; errors are usually detected and reported in
295 an oblique fashion by pic.
296
297 There is no library or file inclusion mechanism, and there is no short‐
298 hand for repetitive structures.
299
300 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
303 There is no in-line chemistry yet (e.g., analogous to the $....$ con‐
304 struct of eqn).
305
306 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
310 Bonds from substituted atoms on heterocycles do not join at the proper
311 place without adding a bit of pic.
312
313 There is no decent primitive for brackets.
314
315 Text (quoted strings) doesn't work very well.
316
317 A squiggle bond is needed.
318
320 /usr/share/groff/1.22.3/pic/chem.pic
321 A collection of pic macros needed by chem.
322
323 /usr/share/groff/1.22.3/tmac/pic.tmac
324 A macro file which redefines .PS and .PE to center pic diagrams.
325
326 /usr/share/doc/groff/examples/chem/*.chem
327 Example files for chem.
328
329 /usr/share/doc/groff/examples/chem/122/*.chem
330 Example files from the classical chem book 122.ps.
331
333 Report bugs to the bug-groff mailing list ⟨bug-groff@gnu.org⟩. Include
334 a complete, self-contained example that will allow the bug to be repro‐
335 duced, and say which version of groff and chem you are using. You can
336 get both version numbers by calling chem --version.
337
338 You can also use the groff mailing list ⟨groff@gnu.org⟩, but you must
339 first subscribe to this list. You can do that by visiting the groff
340 mailing list web page ⟨http://lists.gnu.org/mailman/listinfo/groff⟩.
341
342 See groff(1) for information on availability.
343
345 groff(1), pic(1), groffer(1).
346
347 You can still get the original chem awk source ⟨http://cm.bell-
348 labs.com/netlib/typesetting/chem.gz⟩. Its README file was used for
349 this manual page.
350
351 The other classical document on chem is 122.ps ⟨http://cm.bell-
352 labs.com/cm/cs/cstr/122.ps.gz⟩.
353
355 Copyright © 2006-2014 Free Software Foundation, Inc.
356
357 This file is part of chem, which is part of groff, a free software
358 project.
359
360 You can redistribute it and/or modify it under the terms of the GNU
361 General Public License version 2 (GPL2) as published by the Free Soft‐
362 ware Foundation.
363
364 The license text for GPL2 is available in the internet at
365 ⟨http://www.gnu.org/licenses/gpl-2.0.html⟩.
366
368 This file was written by Bernd Warken <groff-bernd.warken-72@web.de>.
369
370 It is based on the documentation of Brian Kernighan's original awk ver‐
371 sion of chem at ⟨http://cm.bell-labs.com/cm/cs/who/bwk/index.html⟩.
372
373
374
375Groff Version 1.22.3 4 November 2014 CHEM(1)