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       chem -h | --help
11       chem -v | --version
12

OPTION USAGE

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

DESCRIPTION

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
28       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
32       In a style reminiscent of eqn and pic, the chem diagrams are written in
33       a special language.
34
35       A set of chem lines looks like this
36
37              .cstart
38              chem data
39              .cend
40
41       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
46       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
50       As an example,
51
52              .cstart
53              CH3
54              bond
55              CH3
56              .cend
57
58       prints two CH3 groups with a bond between them.
59
60       To actually view this, you must run chem followed by groffer:
61
62              chem [file...] | groffer
63
64       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
67              chem [file...] | groff -p ...
68

THE LANGUAGE

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
74   Setting Variables
75       There  are  some  variables that can be set by commands.  Such commands
76       have two possible forms, either
77
78              variable value
79
80       or
81
82              variable = value
83
84       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
88       There are only a few variables to be set by these commands:
89
90       textht arg
91              Set the height of the text to arg; default is 0.16.
92
93       cwid arg
94              Set the character width to arg; default is 0.12.
95
96       db arg Set the bond length to arg; default is 0.2.
97
98       size arg
99              Scale the diagram to make it look plausible at point  size  arg;
100              default is 10 point.
101
102   Bonds
103       This
104
105              bond [direction] [length n] [from Name|picstuff]
106
107       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
111       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
116       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
120              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
128       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
132   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
137              ring [pointing (up|right|left|down)] [aromatic] [put Mol at n]
138                   [double i,j k,l ...] [picstuff]
139
140       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
145              R1: ring pointing up
146              R2: ring pointing right
147
148       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
154              R1: benzene pointing right
155              R2: benzene pointing right with .V6 at R1.V2
156
157       creates two benzene rings connected along a side.
158
159       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
163              ring double 1,2 3,4 5,6
164
165       Heterocycles (rings with something other than carbon at a  vertex)  are
166       written as put X at V, as in
167
168              R: ring put N at 1 put O at 2
169
170       In this heterocycle, R.N and R.O become synonyms for R.V1 and R.V2.
171
172       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
177       The description of a ring has to fit on a single line.
178
179   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
186       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
190              B1: bond ; OH
191
192       Here the moiety is OH; it is set after a bond.
193
194       As the second kind a moiety can be positioned as the first  word  in  a
195       pic-like command, e.g.,
196
197              CH3 at C + (0.5,0.5)
198
199       Here  the  moiety  is CH3.  It is placed at a position relative to C, a
200       moiety used earlier in the chemical structure.
201
202       So moiety names can be specified as chem positions  everywhere  in  the
203       chem code.  Beneath their printing moieties are names for places.
204
205       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
208              bond ; BP
209
210       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
214       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
219   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
225              Name: ...
226
227       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
231              First: bond
232                     bond 30 from First
233
234   Miscellaneous
235       The specific construction
236
237              bond ... ; moiety
238
239       is equivalent to
240
241              bond
242              moiety
243
244       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
248       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
251       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
255       A  line  whose first word is pic is copied through as-is after the word
256       pic has been removed.
257
258       The command
259
260              size n
261
262       scales the diagram to make it look plausible at point size  n  (default
263       is 10 point).
264
265       Anything else is assumed to be pic code, which is copied through with a
266       label.
267
268       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
273       The  following  pic  commands  are accepted as chem commands, so no pic
274       command word is needed:
275
276              define Start the definition of pic macro within chem.
277
278              [      Start a block composite.
279
280              ]      End a block composite.
281
282              {      Start a macro definition block.
283
284              }      End a macro definition block.
285
286       The macro names from define statements are stored  and  their  call  is
287       accepted as a chem command as well.
288
289   WISH LIST
290       This TODO list was collected by Brian Kernighan.
291
292       Error  checking is minimal; errors are usually detected and reported in
293       an oblique fashion by pic.
294
295       There is no library or file inclusion mechanism, and there is no short‐
296       hand for repetitive structures.
297
298       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
301       There is no in-line chemistry yet (e.g., analogous to  the  $...$  con‐
302       struct of eqn).
303
304       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
308       Bonds  from substituted atoms on heterocycles do not join at the proper
309       place without adding a bit of pic.
310
311       There is no decent primitive for brackets.
312
313       Text (quoted strings) doesn't work very well.
314
315       A squiggle bond is needed.
316

FILES

318       /usr/share/groff/1.20.1/pic/chem.pic
319              A collection of pic macros needed by chem.
320
321       /usr/share/groff/1.20.1/tmac/pic.tmac
322              A macro file which redefines .PS and .PE to center pic diagrams.
323
324       /usr/share/doc/groff/1.20.1/examples/chem/*.chem
325              Example files for chem.
326
327       /usr/share/doc/groff/1.20.1/examples/chem/122/*.chem
328              Example files from the classical chem book 122.ps.
329

BUGS

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
336       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
340       See groff(1) for information on availability.
341

SEE ALSO

343       groff(1), pic(1), groffer(1).
344
345       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
349       The  other  classical  document  on  chem  is  122.ps  ⟨http://cm.bell-
350       labs.com/cm/cs/cstr/122.ps.gz⟩.
351

AUTHOR

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

COPYING

358       Copyright (C) 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
359
360       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
365       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.
370
371
372
373Groff Version 1.20.1            9 January 2009                         CHEM(1)
Impressum