1 .TH @G@CHEM @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
3 @g@chem \- groff preprocessor for producing chemical structure diagrams
5 .\" @g@chem.1 - man page for @g@chem (section 1).
6 .\" Source file position: <groff_source_top>/contrib/chem/chem.man
7 .\" Installed position: $prefix/share/man/man1/@g@chem.1
10 .\" --------------------------------------------------------------------
12 .\" --------------------------------------------------------------------
15 Copyright \[co] 2006-2014 Free Software Foundation, Inc.
17 This file is part of chem, which is part of groff, a free software
20 You can redistribute it and/or modify it under the terms of the GNU
21 General Public License version 2 (GPL2) as published by the Free
24 The license text for GPL2 is available in the internet at
25 .UR http://www.gnu.org/licenses/gpl-2.0.html
30 This file was written by Bernd Warken <groff-bernd.warken-72@web.de>.
32 It is based on the documentation of Brian Kernighan's original awk
34 .UR http://cm.bell-labs.com/cm/cs/who/bwk/index.html
38 .\" --------------------------------------------------------------------
40 .\" --------------------------------------------------------------------
42 .\" --------------------------------------------------------------------
44 .\" --------------------------------------------------------------------
47 .ie t .ds EL \fS\N'188'\fP
48 .el .ds EL \&.\|.\|.\&\
54 .\" used in `.IP \*(BU 2m' (former .Topic)
57 .\" --------------------------------------------------------------------
60 .\" --------------------------------------------------------------------
61 .\" .FONT (<font name> <text> [<font name> <text> ...])
63 .\" in different fonts: R, I, B, CR, CI, CB
66 . if (\\n[.$] = 0) \{\
67 . \" compatibility to .ft
72 . while (\\n[.$] >= 2) \{\
73 . as result \,\f[\\$1]\\$2
74 . if !"\\$1"P" .as result \f[P]
75 . \" the double-quote " after P above is now ignored in Emacs
78 . if (\\n[.$] = 1) .as result \,\f[\\$1]
86 .\" End of macro definitions
89 .\" --------------------------------------------------------------------
91 .\" --------------------------------------------------------------------
94 .OP \fI\%option \*(EL\fP
96 .OP \fI\%filespec \*(EL\fP
112 .\" --------------------------------------------------------------------
114 .\" --------------------------------------------------------------------
116 There are no other options than
122 these options provoke the printing of a version or usage information,
123 respectively, and all
125 arguments are ignored.
129 argument is either a file name of an existing file or a minus
132 meaning standard input.
134 If no argument is specified then standard input is taken
138 .\" --------------------------------------------------------------------
140 .\" --------------------------------------------------------------------
143 produces chemical structure diagrams.
145 Today's version is best suited for organic chemistry (bonds, rings).
161 parts are translated into diagrams of the
169 originates from the Perl source file
174 to include a copy of the macro file
185 In a style reminiscent of
191 diagrams are written in a special language.
197 lines looks like this
211 Lines containing the keywords
215 start and end the input for
221 context, i.e., after the call of
224 input can optionally be started by the line
226 and ended by the line with the single word
232 Anything outside these initialization lines is copied through
233 without modification;
234 all data between the initialization lines is converted into
236 commands to draw the diagram.
257 groups with a bond between them.
261 To actually view this, you must run
267 .B @g@chem [file \*(EL] | groffer
270 If you want to create just
278 for the activation of
281 .B @g@chem [file \*(EL] | groff \-p \*(EL
284 .\" --------------------------------------------------------------------
286 .\" --------------------------------------------------------------------
290 input language is rather small. It provides rings of several styles
291 and a way to glue them together as desired, bonds of several styles,
298 .\" --------------------------------------------------------------------
299 .SS Setting Variables
300 .\" --------------------------------------------------------------------
302 There are some variables that can be set by commands.
304 Such commands have two possible forms, either
316 .IB "variable " = " value"
324 If more arguments are given only the last argument is taken, all other
325 arguments are ignored.
329 There are only a few variables to be set by these commands:
333 Set the height of the text to
339 Set the character width to
345 Set the bond length to
351 Scale the diagram to make it look plausible at point size
356 .\" --------------------------------------------------------------------
358 .\" --------------------------------------------------------------------
367 .IR Name | picstuff ]
372 draws a single bond in direction from nearest corner of
388 is the angle in degrees (0\~up, positive clockwise)
389 or a direction word like
395 If no direction is specified, the bond goes in the current direction
396 (usually that of the last bond).
400 Normally the bond begins at the last object placed; this
401 can be changed by naming a
405 For instance, to make a simple alkyl chain:
412 bond@(this one goes right from the CH3)
413 C@(at the right end of the bond)
414 double bond up@(from the C)
415 O@(at the end of the double bond)
423 A length in inches may be specified to override the default length.
427 commands can be tacked on to the end of a bond command, to created
428 dotted or dashed bonds or to specify a
433 .\" --------------------------------------------------------------------
435 .\" --------------------------------------------------------------------
437 There are lots of rings, but only 5 and 6-sided rings get
441 by itself is a 6-sided ring;
443 is the benzene ring with a circle inside.
445 puts a circle into any kind of ring.
449 .RB [ \%pointing\ ( up | right | left | down )]
451 .RB [ put\ Mol\ at\ \fIn\/\fP ]
462 The vertices of a ring are numbered 1, 2, \*(EL from the
463 vertex that points in the natural compass direction.
465 So for a hexagonal ring with the point at the top, the top vertex
466 is\~1, while if the ring has a point at the east side, that is
475 R2: ring pointing right
481 The ring vertices are named
487 in the pointing direction.
503 is the rightmost vertex and
507 These vertex names are used for connecting bonds or other rings. For
513 R1: benzene pointing right
514 R2: benzene pointing right with .V6 at R1.V2
518 creates two benzene rings connected along a side.
522 Interior double bonds are specified as
523 .BI \%double\ n1 , n2\ n3 , n4\ \fR\*(EL;\fP
524 each number pair adds an interior bond.
526 So the alternate form of a benzene ring is
529 .B "ring double 1,2 3,4 5,6"
533 Heterocycles (rings with something other than carbon at a vertex) are
535 .BI put\ X\ at\ V\fR,\fP
539 .B "R: ring put N at 1 put O at 2"
554 There are two 5-sided rings.
557 is pentagonal with a side that matches the 6-sided ring; it has four
562 is a 5-sided ring created by chopping one corner of a 6-sided ring so
563 that it exactly matches the 6-sided rings.
567 The description of a ring has to fit on a single line.
570 .\" --------------------------------------------------------------------
571 .SS Moieties and Strings
572 .\" --------------------------------------------------------------------
574 A moiety is a string of characters beginning with a capital letter,
577 Numbers are converted to subscripts (unless they appear to be
578 fractional values, as in N2.5H).
580 The name of a moiety is determined from the moiety after special
581 characters have been stripped out: e.g., N(C2H5)2) has the name NC2H52.
585 Moieties can be specified in two kinds.
587 Normally a moiety is placed right after the last thing mentioned,
588 separated by a semicolon surrounded by spaces, e.g.,
596 it is set after a bond.
600 As the second kind a moiety can be positioned as the first word in a
605 .B "CH3 at C + (0.5,0.5)"
610 It is placed at a position relative to
612 a moiety used earlier in the chemical structure.
616 So moiety names can be specified as
618 positions everywhere in the
622 Beneath their printing moieties are names for places.
630 It is not printed but just serves as a mark to be referred to in later
640 sets a mark at the end of the bond.
642 This can be used then for specifying a place.
648 (i.e., line crossing).
652 A string within double quotes
654 is interpreted as a part of a
658 It represents a string that should be printed (without the quotes).
660 Text within quotes \(dq\*(EL\(dq is treated more or less
661 like a moiety except that no changes are made to the quoted part.
664 .\" --------------------------------------------------------------------
666 .\" --------------------------------------------------------------------
668 In the alkyl chain above, notice that the carbon atom
670 was used both to draw something and as the name for a place.
672 A moiety always defines a name for a place; you can use
673 your own names for places instead, and indeed, for rings
685 is often the name of a moiety like
687 but it need not to be.
689 Any name that begins with a capital letter and which contains
690 only letters and numbers is valid:
698 .B "bond 30 from First"
702 .\" --------------------------------------------------------------------
704 .\" --------------------------------------------------------------------
706 The specific construction
709 .BR bond\ \*(EL " ; moiety"
723 Otherwise, each item has to be on a separate line (and only one line).
724 Note that there must be whitespace after the semicolon which separates
733 in the first column of a line signals a
735 command, which is copied through as-is.
739 A line whose first non-blank character is a hash character
741 is treated as a comment and thus ignored.
743 However, hash characters within a word are kept.
747 A line whose first word is
749 is copied through as-is after the word
760 scales the diagram to make it look plausible at point size\~\c
762 (default is 10\~point).
766 Anything else is assumed to be
768 code, which is copied through with a label.
776 preprocessor, it is possible to include
778 statements in the middle of a diagram to draw things not provided for
785 statements should be included in
789 as the first word of this line for clarity.
795 commands are accepted as
799 command word is needed:
803 Start the definition of
811 Start a block composite.
815 End a block composite.
819 Start a macro definition block.
823 End a macro definition block.
829 statements are stored and their call is accepted as a
834 .\" --------------------------------------------------------------------
836 .\" --------------------------------------------------------------------
839 This TODO list was collected by Brian Kernighan.
843 Error checking is minimal; errors are usually detected and reported in
844 an oblique fashion by
849 There is no library or file inclusion mechanism, and there is no
850 shorthand for repetitive structures.
854 The extension mechanism is to create
856 macros, but these are tricky to get right and don't have all the
857 properties of built-in objects.
861 There is no in-line chemistry yet (e.g., analogous to the $\*(EL$
866 There is no way to control entry point for bonds on groups.
868 Normally a bond connects to the carbon atom if entering from
869 the top or bottom and otherwise to the nearest corner.
873 Bonds from substituted atoms on heterocycles do not join at the proper
874 place without adding a bit of
879 There is no decent primitive for brackets.
883 Text (quoted strings) doesn't work very well.
887 A squiggle bond is needed.
890 .\" --------------------------------------------------------------------
892 .\" --------------------------------------------------------------------
895 .B @DATASUBDIR@/pic/chem.pic
902 .B @MACRODIR@/pic.tmac
903 A macro file which redefines
912 .B @DOCDIR@/examples/chem/*.chem
917 .B @DOCDIR@/examples/chem/122/*.chem
918 Example files from the classical
924 .\" --------------------------------------------------------------------
926 .\" --------------------------------------------------------------------
929 .MT bug-groff@\:gnu.org
930 bug-groff mailing list
933 Include a complete, self-contained example that will allow the bug to
934 be reproduced, and say which version of
940 You can get both version numbers by calling
941 .BR "@g@chem \-\-version" .
949 but you must first subscribe to this list.
951 You can do that by visiting the
952 .UR http://\:lists.gnu.org/\:mailman/\:listinfo/\:groff
953 groff mailing list web page
959 .BR \%groff (@MAN1EXT@)
960 for information on availability.
963 .\" --------------------------------------------------------------------
965 .\" --------------------------------------------------------------------
967 .BR \%groff (@MAN1EXT@),
968 .BR \%@g@pic (@MAN1EXT@),
969 .BR \%groffer (@MAN1EXT@).
973 You can still get the original
974 .UR http://\:cm.bell-labs.com/\:netlib/\:typesetting/\:chem.gz
980 file was used for this manual page.
984 The other classical document on
987 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:122.ps.gz
992 .\" --------------------------------------------------------------------
994 .\" --------------------------------------------------------------------
996 .\" --------------------------------------------------------------------
998 .\" --------------------------------------------------------------------
1002 .\" --------------------------------------------------------------------
1004 .\" --------------------------------------------------------------------
1006 .\" Local Variables: