1CHEM(1) General Commands Manual CHEM(1)
2
6 chem - groff preprocessor for producing chemical structure diagrams
7
9 chem [option...] [--] [filespec...]
10 chem -h | --help
11 chem -v | --version
12
14 There are no other options than -h, --help, -v, and --version; these
15 options provoke the printing of a version or usage information, respec‐
16 tively, and all filespec arguments are ignored. A filespec argument is
17 either a file name of an existing file or a minus character -, meaning
18 standard input. If no argument is specified then standard input is
19 taken automatically.
20
22 chem produces chemical structure diagrams. Today's version is best
23 suited for organic chemistry (bonds, rings). The chem program is a
24 groff preprocessor like eqn, pic, tbl, etc. It generates pic output
25 such that all chem parts are translated into diagrams of the pic lan‐
26 guage.
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 To actually view this, you must run chem followed by groffer:
61 chem [file...] | groffer
63 If you want to create just groff output, you must run chem followed by
65 groff with the option -p for the activation of pic:
66 chem [file...] | groff -p ...
68
70 The chem input language is rather small. It provides rings of several
71 styles and a way to glue them together as desired, bonds of several
72 styles, moieties (e.g., C, NH3, ...), and strings.
73 Setting Variables
75 There are some variables that can be set by commands. Such commands
76 have two possible forms, either
77 variable value
79 or
81 variable = value
83 This sets the given variable to the argument value. If more arguments
85 are given only the last argument is taken, all other arguments are ig‐
86 nored.
87 There are only a few variables to be set by these commands:
89 textht arg
91 Set the height of the text to arg; default is 0.16.
92 cwid arg
94 Set the character width to arg; default is 0.12.
95 db arg Set the bond length to arg; default is 0.2.
97 size arg
99 Scale the diagram to make it look plausible at point size arg;
100 default is 10 point.
101 Bonds
103 This
104 bond [direction] [length n] [from Name|picstuff]
106 draws a single bond in direction from nearest corner of Name. bond can
108 also be double bond, front bond, back bond, etc. (We will get back to
109 Name soon.)
110 direction is the angle in degrees (0 up, positive clockwise) or a
112 direction word like up, down, sw (= southwest), etc. If no direction
113 is specified, the bond goes in the current direction (usually that of
114 the last bond).
115 Normally the bond begins at the last object placed; this can be
117 changed by naming a from place. For instance, to make a simple alkyl
118 chain:
119 CH3
121 bond (this one goes right from the CH3)
122 C (at the right end of the bond)
123 double bond up (from the C)
124 O (at the end of the double bond)
125 bond right from C
126 CH3
127 A length in inches may be specified to override the default length.
129 Other pic commands can be tacked on to the end of a bond command, to
130 created dotted or dashed bonds or to specify a to place.
131 Rings
133 There are lots of rings, but only 5 and 6-sided rings get much support.
134 ring by itself is a 6-sided ring; benzene is the benzene ring with a
135 circle inside. aromatic puts a circle into any kind of ring.
136 ring [pointing (up|right|left|down)] [aromatic] [put Mol at n]
138 [double i,j k,l ...] [picstuff]
139 The vertices of a ring are numbered 1, 2, ... from the vertex that
141 points in the natural compass direction. So for a hexagonal ring with
142 the point at the top, the top vertex is 1, while if the ring has a
143 point at the east side, that is vertex 1. This is expressed as
144 R1: ring pointing up
146 R2: ring pointing right
147 The ring vertices are named .V1, ..., .Vn, with .V1 in the pointing
149 direction. So the corners of R1 are R1.V1 (the top), R1.V2, R1.V3,
150 R1.V4 (the bottom), etc., whereas for R2, R2.V1 is the rightmost vertex
151 and R2.V4 the leftmost. These vertex names are used for connecting
152 bonds or other rings. For example,
153 R1: benzene pointing right
155 R2: benzene pointing right with .V6 at R1.V2
156 creates two benzene rings connected along a side.
158 Interior double bonds are specified as double n1,n2 n3,n4 ...; each
160 number pair adds an interior bond. So the alternate form of a benzene
161 ring is
162 ring double 1,2 3,4 5,6
164 Heterocycles (rings with something other than carbon at a vertex) are
166 written as put X at V, as in
167 R: ring put N at 1 put O at 2
169 In this heterocycle, R.N and R.O become synonyms for R.V1 and R.V2.
171 There are two 5-sided rings. ring5 is pentagonal with a side that
173 matches the 6-sided ring; it has four natural directions. A flatring
174 is a 5-sided ring created by chopping one corner of a 6-sided ring so
175 that it exactly matches the 6-sided rings.
176 The description of a ring has to fit on a single line.
178 Moieties and Strings
180 A moiety is a string of characters beginning with a capital letter,
181 such as N(C2H5)2. Numbers are converted to subscripts (unless they
182 appear to be fractional values, as in N2.5H). The name of a moiety is
183 determined from the moiety after special characters have been stripped
184 out: e.g., N(C2H5)2) has the name NC2H52.
185 Moieties can be specified in two kinds. Normally a moiety is placed
187 right after the last thing mentioned, separated by a semicolon sur‐
188 rounded by spaces, e.g.,
189 B1: bond ; OH
191 Here the moiety is OH; it is set after a bond.
193 As the second kind a moiety can be positioned as the first word in a
195 pic-like command, e.g.,
196 CH3 at C + (0.5,0.5)
198 Here the moiety is CH3. It is placed at a position relative to C, a
200 moiety used earlier in the chemical structure.
201 So moiety names can be specified as chem positions everywhere in the
203 chem code. Beneath their printing moieties are names for places.
204 The moiety BP is special. It is not printed but just serves as a mark
206 to be referred to in later chem commands. For example,
207 bond ; BP
209 sets a mark at the end of the bond. This can be used then for specify‐
211 ing a place. The name BP is derived from branch point (i.e., line
212 crossing).
213 A string within double quotes " is interpreted as a part of a chem com‐
215 mand. It represents a string that should be printed (without the
216 quotes). Text within quotes "..." is treated more or less like a moi‐
217 ety except that no changes are made to the quoted part.
218 Names
220 In the alkyl chain above, notice that the carbon atom C was used both
221 to draw something and as the name for a place. A moiety always defines
222 a name for a place; you can use your own names for places instead, and
223 indeed, for rings you will have to. A name is just
224 Name: ...
226 Name is often the name of a moiety like CH3, but it need not to be.
228 Any name that begins with a capital letter and which contains only let‐
229 ters and numbers is valid:
230 First: bond
232 bond 30 from First
233 Miscellaneous
235 The specific construction
236 bond ... ; moiety
238 is equivalent to
240 bond
242 moiety
243 Otherwise, each item has to be on a separate line (and only one line).
245 Note that there must be whitespace after the semicolon which separates
246 the commands.
247 A period character . or a single quote ' in the first column of a line
249 signals a troff command, which is copied through as-is.
250 A line whose first non-blank character is a hash character (#) is
252 treated as a comment and thus ignored. However, hash characters within
253 a word are kept.
254 A line whose first word is pic is copied through as-is after the word
256 pic has been removed.
257 The command
259 size n
261 scales the diagram to make it look plausible at point size n (default
263 is 10 point).
264 Anything else is assumed to be pic code, which is copied through with a
266 label.
267 Since chem is a pic preprocessor, it is possible to include pic state‐
269 ments in the middle of a diagram to draw things not provided for by
270 chem itself. Such pic statements should be included in chem code by
271 adding pic as the first word of this line for clarity.
272 The following pic commands are accepted as chem commands, so no pic
274 command word is needed:
275 define Start the definition of pic macro within chem.
277 [ Start a block composite.
279 ] End a block composite.
281 { Start a macro definition block.
283 } End a macro definition block.
285 The macro names from define statements are stored and their call is
287 accepted as a chem command as well.
288 WISH LIST
290 This TODO list was collected by Brian Kernighan.
291 Error checking is minimal; errors are usually detected and reported in
293 an oblique fashion by pic.
294 There is no library or file inclusion mechanism, and there is no short‐
296 hand for repetitive structures.
297 The extension mechanism is to create pic macros, but these are tricky
299 to get right and don't have all the properties of built-in objects.
300 There is no in-line chemistry yet (e.g., analogous to the $...$ con‐
302 struct of eqn).
303 There is no way to control entry point for bonds on groups. Normally a
305 bond connects to the carbon atom if entering from the top or bottom and
306 otherwise to the nearest corner.
307 Bonds from substituted atoms on heterocycles do not join at the proper
309 place without adding a bit of pic.
310 There is no decent primitive for brackets.
312 Text (quoted strings) doesn't work very well.
314 A squiggle bond is needed.
316
318 /usr/share/groff/1.20.1/pic/chem.pic
319 A collection of pic macros needed by chem.
320 /usr/share/groff/1.20.1/tmac/pic.tmac
322 A macro file which redefines .PS and .PE to center pic diagrams.
323 /usr/share/doc/groff/1.20.1/examples/chem/*.chem
325 Example files for chem.
326 /usr/share/doc/groff/1.20.1/examples/chem/122/*.chem
328 Example files from the classical chem book 122.ps.
329
331 Report bugs to the bug-groff mailing list ⟨bug-groff@gnu.org⟩. Include
332 a complete, self-contained example that will allow the bug to be repro‐
333 duced, and say which version of groff and chem you are using. You can
334 get both version numbers by calling chem --version.
335 You can also use the groff mailing list ⟨groff@gnu.org⟩, but you must
337 first subscribe to this list. You can do that by visiting the groff
338 mailing list web page ⟨http://lists.gnu.org/mailman/listinfo/groff⟩.
339 See groff(1) for information on availability.
341
343 groff(1), pic(1), groffer(1).
344 You can still get the original chem awk source ⟨http://cm.bell-
346 labs.com/netlib/typesetting/chem.gz⟩. Its README file was used for
347 this manual page.
348 The other classical document on chem is 122.ps ⟨http://cm.bell-
350 labs.com/cm/cs/cstr/122.ps.gz⟩.
351
353 This file was written by Bernd Warken. It is based on the documenta‐
354 tion of Brian Kernighan ⟨http://cm.bell-labs.com/cm/cs/who/bwk/
355 index.html⟩'s original awk version of chem.
356
358 Copyright (C) 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
359 This file is part of chem, which is part of groff, a free software
361 project. You can redistribute it and/or modify it under the terms of
362 the GNU General Public License as published by the Free Software
363 Foundation, either version 2, or (at your option) any later version.
364 You should have received a copy of the GNU General Public License along
366 with groff, see the files COPYING and LICENSE in the top directory of
367 the groff source package. Or read the man page gpl(1). You can also
368 write to the Free Software Foundation, 51 Franklin St - Fifth Floor,
369 Boston, MA 02110-1301, USA.
370Groff Version 1.20.1 9 January 2009 CHEM(1)