1CHEM(1)                     General Commands Manual                    CHEM(1)
2
3
4

NAME

6       chem - groff preprocessor for producing chemical structure diagrams
7

SYNOPSIS

9       chem [option ....]  [--] [filespec ....]
10
11       chem -h | --help
12
13       chem -v | --version
14

OPTION USAGE

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

DESCRIPTION

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

THE LANGUAGE

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

FILES

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

BUGS

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

SEE ALSO

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

COPYING

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
365http://www.gnu.org/licenses/gpl-2.0.html⟩.
366

AUTHORS

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)
Impressum