2 @g@chem.1 - man page for @g@chem (section 1).
4 Source file position: <groff_source_top>/contrib/chem/chem.man
5 Installed position: $prefix/share/man/man1/@g@chem.1
7 Last update: 05 Jan 2009
12 This file was written by Bernd Warken.
13 It is based on the documentation of
14 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:who/\:bwk/\:index.html
25 Copyright (C) 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
33 a free software project.
35 You can redistribute it and/or modify it under the terms of the
37 .B "GNU General Public License"
41 .BR "Free Software Foundation" ,
43 either version\~2, or (at your option) any later version.
47 You should have received a copy of the \f(CRGNU General Public
50 see the files \%\f(CBCOPYING\fP and \%\f(CBLICENSE\fP in the top
58 You can also write to the
60 .B "Free Software Foundation, 51 Franklin St - Fifth Floor, Boston,"
61 .BR "MA 02110-1301, USA" .
66 .\" --------------------------------------------------------------------
67 .\" Local macro definitions
71 .\" .File_name (<path_name>)
73 .\" Display a file or directory name in CB font.
81 .\" Display a line in CB font, for example after .TP
89 .\" End of macro definitions
92 .TH @G@CHEM @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
94 @g@chem \- groff preprocessor for producing chemical structure diagrams
98 .\" --------------------------------------------------------------------
100 .\" --------------------------------------------------------------------
103 .RI [ "\%option" \*(El]
105 .RI [ "\%filespec" \*(El]
119 .\" --------------------------------------------------------------------
121 .\" --------------------------------------------------------------------
124 There are no other options than
130 these options provoke the printing of a version or usage information,
131 respectively, and all
133 arguments are ignored.
137 argument is either a file name of an existing file or a minus
140 meaning standard input.
142 If no argument is specified then standard input is taken
146 .\" --------------------------------------------------------------------
148 .\" --------------------------------------------------------------------
151 produces chemical structure diagrams.
153 Today's version is best suited for organic chemistry (bonds, rings).
169 parts are translated into diagrams of the
177 originates from the Perl source file
181 to include a copy of the macro file
192 In a style reminiscent of
198 diagrams are written in a special language.
204 lines looks like this
218 Lines containing the keywords
222 start and end the input for
228 context, i.e., after the call of
231 input can optionally be started by the line
233 and ended by the line with the single word
239 Anything outside these initialization lines is copied through
240 without modification;
241 all data between the initialization lines is converted into
243 commands to draw the diagram.
264 groups with a bond between them.
268 To actually view this, you must run
274 .B "@g@chem [file\*(El] | groffer"
277 If you want to create just
285 for the activation of
288 .B "@g@chem [file\*(El] | groff -p \*(El"
291 .\" --------------------------------------------------------------------
293 .\" --------------------------------------------------------------------
297 input language is rather small. It provides rings of several styles
298 and a way to glue them together as desired, bonds of several styles,
305 .\" --------------------------------------------------------------------
306 .SS Setting Variables
307 .\" --------------------------------------------------------------------
309 There are some variables that can be set by commands.
311 Such commands have two possible forms, either
323 .IB "variable " = " value"
331 If more arguments are given only the last argument is taken, all other
332 arguments are ignored.
336 There are only a few variables to be set by these commands:
340 Set the height of the text to
346 Set the character width to
352 Set the bond length to
358 Scale the diagram to make it look plausible at point size
363 .\" --------------------------------------------------------------------
365 .\" --------------------------------------------------------------------
374 .IR Name | picstuff ]
379 draws a single bond in direction from nearest corner of
395 is the angle in degrees (0\~up, positive clockwise)
396 or a direction word like
402 If no direction is specified, the bond goes in the current direction
403 (usually that of the last bond).
407 Normally the bond begins at the last object placed; this
408 can be changed by naming a
412 For instance, to make a simple alkyl chain:
419 bond@(this one goes right from the CH3)
420 C@(at the right end of the bond)
421 double bond up@(from the C)
422 O@(at the end of the double bond)
430 A length in inches may be specified to override the default length.
434 commands can be tacked on to the end of a bond command, to created
435 dotted or dashed bonds or to specify a
440 .\" --------------------------------------------------------------------
442 .\" --------------------------------------------------------------------
444 There are lots of rings, but only 5 and 6-sided rings get
448 by itself is a 6-sided ring;
450 is the benzene ring with a circle inside.
452 puts a circle into any kind of ring.
456 .RB [ \%pointing\ ( up | right | left | down )]
458 .RB [ put\ Mol\ at\ \fIn\fP ]
469 The vertices of a ring are numbered 1, 2, \*(El from the
470 vertex that points in the natural compass direction.
472 So for a hexagonal ring with the point at the top, the top vertex
473 is\~1, while if the ring has a point at the east side, that is
482 R2: ring pointing right
488 The ring vertices are named
494 in the pointing direction.
510 is the rightmost vertex and
514 These vertex names are used for connecting bonds or other rings. For
520 R1: benzene pointing right
521 R2: benzene pointing right with .V6 at R1.V2
525 creates two benzene rings connected along a side.
529 Interior double bonds are specified as
530 .BI \%double\ n1 , n2\ n3 , n4\ \fR\*(El;\fP
531 each number pair adds an interior bond.
533 So the alternate form of a benzene ring is
536 .B "ring double 1,2 3,4 5,6"
540 Heterocycles (rings with something other than carbon at a vertex) are
542 .BI put\ X\ at\ V\fR,\fP
546 .B "R: ring put N at 1 put O at 2"
561 There are two 5-sided rings.
564 is pentagonal with a side that matches the 6-sided ring; it has four
569 is a 5-sided ring created by chopping one corner of a 6-sided ring so
570 that it exactly matches the 6-sided rings.
574 The description of a ring has to fit on a single line.
577 .\" --------------------------------------------------------------------
578 .SS Moieties and Strings
579 .\" --------------------------------------------------------------------
581 A moiety is a string of characters beginning with a capital letter,
584 Numbers are converted to subscripts (unless they appear to be
585 fractional values, as in N2.5H).
587 The name of a moiety is determined from the moiety after special
588 characters have been stripped out: e.g., N(C2H5)2) has the name NC2H52.
592 Moieties can be specified in two kinds.
594 Normally a moiety is placed right after the last thing mentioned,
595 separated by a semicolon surrounded by spaces, e.g.,
603 it is set after a bond.
607 As the second kind a moiety can be positioned as the first word in a
612 .B "CH3 at C + (0.5,0.5)"
617 It is placed at a position relative to
619 a moiety used earlier in the chemical structure.
623 So moiety names can be specified as
625 positions everywhere in the
629 Beneath their printing moieties are names for places.
637 It is not printed but just serves as a mark to be referred to in later
647 sets a mark at the end of the bond.
649 This can be used then for specifying a place.
655 (i.e., line crossing).
659 A string within double quotes
661 is interpreted as a part of a
665 It represents a string that should be printed (without the quotes).
667 Text within quotes \(dq\*(El\(dq is treated more or less
668 like a moiety except that no changes are made to the quoted part.
671 .\" --------------------------------------------------------------------
673 .\" --------------------------------------------------------------------
675 In the alkyl chain above, notice that the carbon atom
677 was used both to draw something and as the name for a place.
679 A moiety always defines a name for a place; you can use
680 your own names for places instead, and indeed, for rings
692 is often the name of a moiety like
694 but it need not to be.
696 Any name that begins with a capital letter and which contains
697 only letters and numbers is valid:
705 .B "bond 30 from First"
709 .\" --------------------------------------------------------------------
711 .\" --------------------------------------------------------------------
713 The specific construction
716 .BR bond\ \*(El " ; moiety"
730 Otherwise, each item has to be on a separate line (and only one line).
731 Note that there must be whitespace after the semicolon which separates
740 in the first column of a line signals a
742 command, which is copied through as-is.
746 A line whose first non-blank character is a hash character
748 is treated as a comment and thus ignored.
750 However, hash characters within a word are kept.
754 A line whose first word is
756 is copied through as-is after the word
767 scales the diagram to make it look plausible at point size\~\c
769 (default is 10\~point).
773 Anything else is assumed to be
775 code, which is copied through with a label.
783 preprocessor, it is possible to include
785 statements in the middle of a diagram to draw things not provided for
792 statements should be included in
796 as the first word of this line for clarity.
802 commands are accepted as
806 command word is needed:
810 Start the definition of
818 Start a block composite.
822 End a block composite.
826 Start a macro definition block.
830 End a macro definition block.
836 statements are stored and their call is accepted as a
841 .\" --------------------------------------------------------------------
843 .\" --------------------------------------------------------------------
846 This TODO list was collected by Brian Kernighan.
850 Error checking is minimal; errors are usually detected and reported in
851 an oblique fashion by
856 There is no library or file inclusion mechanism, and there is no
857 shorthand for repetitive structures.
861 The extension mechanism is to create
863 macros, but these are tricky to get right and don't have all the
864 properties of built-in objects.
868 There is no in-line chemistry yet (e.g., analogous to the $\*(El$
873 There is no way to control entry point for bonds on groups.
875 Normally a bond connects to the carbon atom if entering from
876 the top or bottom and otherwise to the nearest corner.
880 Bonds from substituted atoms on heterocycles do not join at the proper
881 place without adding a bit of
886 There is no decent primitive for brackets.
890 Text (quoted strings) doesn't work very well.
894 A squiggle bond is needed.
897 .\" --------------------------------------------------------------------
899 .\" --------------------------------------------------------------------
902 .FN @DATASUBDIR@/pic/chem.pic
909 .FN @MACRODIR@/pic.tmac
910 A macro file which redefines
919 .FN @DOCDIR@/examples/chem/*.chem
924 .FN @DOCDIR@/examples/chem/122/*.chem
925 Example files from the classical
931 .\" --------------------------------------------------------------------
933 .\" --------------------------------------------------------------------
936 .MT bug-groff@\:gnu.org
937 bug-groff mailing list
940 Include a complete, self-contained example that will allow the bug to
941 be reproduced, and say which version of
947 You can get both version numbers by calling
948 .BR "@g@chem --version" .
956 but you must first subscribe to this list.
958 You can do that by visiting the
959 .UR http://\:lists.gnu.org/\:mailman/\:listinfo/\:groff
960 groff mailing list web page
966 .BR \%groff (@MAN1EXT@)
967 for information on availability.
970 .\" --------------------------------------------------------------------
972 .\" --------------------------------------------------------------------
974 .BR \%groff (@MAN1EXT@),
975 .BR \%@g@pic (@MAN1EXT@),
976 .BR \%groffer (@MAN1EXT@).
980 You can still get the original
981 .UR http://\:cm.bell-labs.com/\:netlib/\:typesetting/\:chem.gz
987 file was used for this manual page.
991 The other classical document on
994 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:122.ps.gz
999 .\" --------------------------------------------------------------------
1001 .\" --------------------------------------------------------------------
1005 .\" --------------------------------------------------------------------
1007 .\" --------------------------------------------------------------------
1011 .\" --------------------------------------------------------------------
1013 .\" --------------------------------------------------------------------
1015 .\" Local Variables: