diff options
Diffstat (limited to 'contrib/chem/chem.man')
| -rw-r--r-- | contrib/chem/chem.man | 1017 |
1 files changed, 1017 insertions, 0 deletions
diff --git a/contrib/chem/chem.man b/contrib/chem/chem.man new file mode 100644 index 00000000..b2bf7540 --- /dev/null +++ b/contrib/chem/chem.man @@ -0,0 +1,1017 @@ +.ig +@g@chem.1 - man page for @g@chem (section 1). + +Source file position: <groff_source_top>/contrib/chem/chem.man +Installed position: $prefix/share/man/man1/@g@chem.1 + +Last update: 05 Jan 2009 +.. +. +. +.de au +This file was written by Bernd Warken <groff-bernd.warken-72@web.de>. +It is based on the documentation of +.UR http://\:cm.bell-labs.com/\:cm/\:cs/\:who/\:bwk/\:index.html +Brian Kernighan +.UE 's +original +.I awk +version of +.IR chem . +.. +. +. +.de co +Copyright (C) 2006, 2007, 2008, 2009 Free Software Foundation, Inc. +. +. +.P +This file is part of +.IR chem , +which is part of +.IR groff , +a free software project. +. +You can redistribute it and/or modify it under the terms of the +.nh +.B "GNU General Public License" +.hy +as published by the +.nh +.BR "Free Software Foundation" , +.hy +either version\~2, or (at your option) any later version. +. +. +.P +You should have received a copy of the \f(CRGNU General Public +License\fP along with +.IR groff , +see the files \%\f(CBCOPYING\fP and \%\f(CBLICENSE\fP in the top +directory of the +.I groff +source package. +. +Or read the +.I man page +.BR gpl (1). +You can also write to the +.nh +.B "Free Software Foundation, 51 Franklin St - Fifth Floor, Boston," +.BR "MA 02110-1301, USA" . +.hy +.. +. +. +.\" -------------------------------------------------------------------- +.\" Local macro definitions +. +.ds El \&.\|.\|.\& +. +.\" .File_name (<path_name>) +.\" +.\" Display a file or directory name in CB font. +.\" +.de FN +. CB \\$@ +.. +. +.\" .CB (<path_name>) +.\" +.\" Display a line in CB font, for example after .TP +.\" +.de CB +.nh +\\&\\f(CB\\$1\\fP\\$2 +.hy +.. +. +.\" End of macro definitions +. +. +.TH @G@CHEM @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@" +.SH NAME +@g@chem \- groff preprocessor for producing chemical structure diagrams +. +. +.SH "SYNOPSIS" +.\" -------------------------------------------------------------------- +.\" SH "SYNOPSIS" +.\" -------------------------------------------------------------------- +. +.SY @g@chem +.RI [ "\%option" \*(El] +.OP \-\- +.RI [ "\%filespec" \*(El] +. +.SY @g@chem +.B \-h +| +.B \-\-help +. +.SY @g@chem +.B \-v +| +.B \-\-version +.YS +. +. +.\" -------------------------------------------------------------------- +.SH OPTION USAGE +.\" -------------------------------------------------------------------- +. +.P +There are no other options than +.BR \-h , +.BR \-\-help , +.BR \-v , +and +.BR \%\-\-version ; +these options provoke the printing of a version or usage information, +respectively, and all +.I filespec +arguments are ignored. +. +A +.I filespec +argument is either a file name of an existing file or a minus +character +.BR \- , +meaning standard input. +. +If no argument is specified then standard input is taken +automatically. +. +. +.\" -------------------------------------------------------------------- +.SH DESCRIPTION +.\" -------------------------------------------------------------------- +. +.I chem +produces chemical structure diagrams. +. +Today's version is best suited for organic chemistry (bonds, rings). +. +The +.B @g@chem +program is a +.B groff +preprocessor like +.BR @g@eqn , +.BR @g@pic , +.BR @g@tbl , +etc. +. +It generates +.I pic +output such that all +.I chem +parts are translated into diagrams of the +.I pic +language. +. +. +.P +The program +.B @g@chem +originates from the Perl source file +.FN chem.pl . +It tells +.B @g@pic +to include a copy of the macro file +.FN chem.pic . +. +Moreover the +.I groff +source file +.FN pic.tmac +is loaded. +. +. +.P +In a style reminiscent of +.I eqn +and +.IR pic , +the +.I chem +diagrams are written in a special language. +. +. +.P +A set of +.I chem +lines looks like this +. +. +.IP +.nf +.ft B +\&.cstart +\fIchem data\fP +\&.cend +.ft +.fi +. +. +.P +Lines containing the keywords +.B .cstart +and +.B .cend +start and end the input for +.BR @g@chem , +respectively. +. +In +.I pic +context, i.e., after the call of +.BR .PS , +.I chem +input can optionally be started by the line +.B \%begin\~chem +and ended by the line with the single word +.B end +instead. +. +. +.P +Anything outside these initialization lines is copied through +without modification; +all data between the initialization lines is converted into +.I pic +commands to draw the diagram. +. +. +.P +As an example, +. +.IP +.nf +.ft B +\&.cstart +CH3 +bond +CH3 +\&.cend +.ft +.fi +. +. +.P +prints two +.B CH3 +groups with a bond between them. +. +. +.P +To actually view this, you must run +.B @g@chem +followed by +.BR groffer : +. +.IP +.B "@g@chem [file\*(El] | groffer" +. +.P +If you want to create just +.B groff +output, you must run +.B @g@chem +followed by +.B groff +with the option +.B \-p +for the activation of +.BR @g@pic : +.IP +.B "@g@chem [file\*(El] | groff -p \*(El" +. +. +.\" -------------------------------------------------------------------- +.SH THE LANGUAGE +.\" -------------------------------------------------------------------- +. +The +.I chem +input language is rather small. It provides rings of several styles +and a way to glue them together as desired, bonds of several styles, +moieties (e.g., +.BR C , +.BR NH3 , +\*(El), and strings. +. +. +.\" -------------------------------------------------------------------- +.SS Setting Variables +.\" -------------------------------------------------------------------- +. +There are some variables that can be set by commands. +. +Such commands have two possible forms, either +. +.RS +.P +.I "variable value" +.RE +. +.P +or +. +.RS +.P +.IB "variable " = " value" +.RE +. +.P +This sets the given +.I variable +to the argument +.IR value . +If more arguments are given only the last argument is taken, all other +arguments are ignored. +. +. +.P +There are only a few variables to be set by these commands: +. +.TP +.BI textht " arg" +Set the height of the text to +.IR arg ; +default is 0.16. +. +.TP +.BI cwid " arg" +Set the character width to +.IR arg ; +default is 0.12. +. +.TP +.BI db " arg" +Set the bond length to +.IR arg ; +default is 0.2. +. +.TP +.BI size " arg" +Scale the diagram to make it look plausible at point size +.IR arg ; +default is 10 point. +. +. +.\" -------------------------------------------------------------------- +.SS Bonds +.\" -------------------------------------------------------------------- +. +This +. +.RS +.SY bond +.RI [ direction ] +.RI [ length\ n ] +.RB [ from\ \c +.IR Name | picstuff ] +.YS +.RE +. +.P +draws a single bond in direction from nearest corner of +.IR Name . +.B bond +can also be +.BR "double bond" , +.BR "front bond" , +.BR "back bond" , +etc. +. +(We will get back to +.I Name +soon.) +. +. +.P +.I direction +is the angle in degrees (0\~up, positive clockwise) +or a direction word like +.BR up , +.BR down , +.B sw +(=\~southwest), etc. +. +If no direction is specified, the bond goes in the current direction +(usually that of the last bond). +. +. +.P +Normally the bond begins at the last object placed; this +can be changed by naming a +.B from +place. +. +For instance, to make a simple alkyl chain: +. +.RS +.TS +tab (@); +lb l. +CH3 +bond@(this one goes right from the CH3) +C@(at the right end of the bond) +double bond up@(from the C) +O@(at the end of the double bond) +bond right from C +CH3 +.TE +.RE +. +. +.P +A length in inches may be specified to override the default length. +. +Other +.I pic +commands can be tacked on to the end of a bond command, to created +dotted or dashed bonds or to specify a +.B to +place. +. +. +.\" -------------------------------------------------------------------- +.SS Rings +.\" -------------------------------------------------------------------- +. +There are lots of rings, but only 5 and 6-sided rings get +much support. +. +.B ring +by itself is a 6-sided ring; +.B benzene +is the benzene ring with a circle inside. +.B aromatic +puts a circle into any kind of ring. +. +.RS +.SY ring +.RB [ \%pointing\ ( up | right | left | down )] +.RB [ \%aromatic ] +.RB [ put\ Mol\ at\ \fIn\fP ] +.RB [ \%double\ \c +.IR i , j\ \c +.IR k , l\ \c +\*(El] +.RI [ picstuff ] +.YS +.RE +. +. +.P +The vertices of a ring are numbered 1, 2, \*(El from the +vertex that points in the natural compass direction. +. +So for a hexagonal ring with the point at the top, the top vertex +is\~1, while if the ring has a point at the east side, that is +vertex\~1. +. +This is expressed as +. +.IP +.ft B +.nf +R1: ring pointing up +R2: ring pointing right +.fi +.ft +. +. +.P +The ring vertices are named +.BR .V1 , +\*(El, +.BI .V n\fR,\fP +with +.B .V1 +in the pointing direction. +. +So the corners of +.B R1 +are +.B R1.V1 +(the +.IR top ), +.BR R1.V2 , +.BR R1.V3 , +.B R1.V4 +(the +.IR bottom ), +etc., whereas for +.BR R2 , +.B R2.V1 +is the rightmost vertex and +.B R2.V4 +the leftmost. +. +These vertex names are used for connecting bonds or other rings. For +example, +. +.IP +.ft B +.nf +R1: benzene pointing right +R2: benzene pointing right with .V6 at R1.V2 +.fi +.ft +.P +creates two benzene rings connected along a side. +. +. +.P +Interior double bonds are specified as +.BI \%double\ n1 , n2\ n3 , n4\ \fR\*(El;\fP +each number pair adds an interior bond. +. +So the alternate form of a benzene ring is +. +.IP +.B "ring double 1,2 3,4 5,6" +. +. +.P +Heterocycles (rings with something other than carbon at a vertex) are +written as +.BI put\ X\ at\ V\fR,\fP +as in +. +.IP +.B "R: ring put N at 1 put O at 2" +. +. +.P +In this heterocycle, +.B R.N +and +.B R.O +become synonyms for +.B R.V1 +and +.BR R.V2 . +. +. +.P +There are two 5-sided rings. +. +.B ring5 +is pentagonal with a side that matches the 6-sided ring; it has four +natural directions. +. +A +.B \%flatring +is a 5-sided ring created by chopping one corner of a 6-sided ring so +that it exactly matches the 6-sided rings. +. +. +.P +The description of a ring has to fit on a single line. +. +. +.\" -------------------------------------------------------------------- +.SS Moieties and Strings +.\" -------------------------------------------------------------------- +. +A moiety is a string of characters beginning with a capital letter, +such as N(C2H5)2. +. +Numbers are converted to subscripts (unless they appear to be +fractional values, as in N2.5H). +. +The name of a moiety is determined from the moiety after special +characters have been stripped out: e.g., N(C2H5)2) has the name NC2H52. +. +. +.P +Moieties can be specified in two kinds. +. +Normally a moiety is placed right after the last thing mentioned, +separated by a semicolon surrounded by spaces, e.g., +. +.IP +.B "B1: bond ; OH" +. +.P +Here the moiety is +.BR OH ; +it is set after a bond. +. +. +.P +As the second kind a moiety can be positioned as the first word in a +.IR pic -like +command, e.g., +. +.IP +.B "CH3 at C + (0.5,0.5)" +. +.P +Here the moiety is +.BR CH3 . +It is placed at a position relative to +.BR C , +a moiety used earlier in the chemical structure. +. +. +.P +So moiety names can be specified as +.I chem +positions everywhere in the +.I chem +code. +. +Beneath their printing moieties are names for places. +. +. +.P +The moiety +.B BP +is special. +. +It is not printed but just serves as a mark to be referred to in later +.I chem +commands. +. +For example, +. +.IP +.B "bond ; BP" +. +.P +sets a mark at the end of the bond. +. +This can be used then for specifying a place. +. +The name +.B BP +is derived from +.I branch point +(i.e., line crossing). +. +. +.P +A string within double quotes +.B \(dq +is interpreted as a part of a +.I chem +command. +. +It represents a string that should be printed (without the quotes). +. +Text within quotes \(dq\*(El\(dq is treated more or less +like a moiety except that no changes are made to the quoted part. +. +. +.\" -------------------------------------------------------------------- +.SS Names +.\" -------------------------------------------------------------------- +. +In the alkyl chain above, notice that the carbon atom +.B C +was used both to draw something and as the name for a place. +. +A moiety always defines a name for a place; you can use +your own names for places instead, and indeed, for rings +you will have to. +. +A name is just +. +.IP +.IB Name : +\*(El +. +. +.P +.I Name +is often the name of a moiety like +.BR CH3 , +but it need not to be. +. +Any name that begins with a capital letter and which contains +only letters and numbers is valid: +. +.RS +.TP +.B First: +.B bond +.TQ +\& +.B "bond 30 from First" +.RE +. +. +.\" -------------------------------------------------------------------- +.SS Miscellaneous +.\" -------------------------------------------------------------------- +. +The specific construction +.RS +.TP +.BR bond\ \*(El " ; moiety" +.RE +.P +is equivalent to +.IP +.ft B +.nf +bond +moiety +.fi +.ft +. +. +.P +Otherwise, each item has to be on a separate line (and only one line). +Note that there must be whitespace after the semicolon which separates +the commands. +. +. +.P +A period character +.B .\& +or a single quote +.B ' +in the first column of a line signals a +.I troff +command, which is copied through as-is. +. +. +.P +A line whose first non-blank character is a hash character +.RB ( # ) +is treated as a comment and thus ignored. +. +However, hash characters within a word are kept. +. +. +.P +A line whose first word is +.B pic +is copied through as-is after the word +.B pic +has been removed. +. +. +.P +The command +.IP +.B size +.I n +.P +scales the diagram to make it look plausible at point size\~\c +.I n +(default is 10\~point). +. +. +.P +Anything else is assumed to be +.I pic +code, which is copied through with a label. +. +. +.P +Since +.B @g@chem +is a +.B @g@pic +preprocessor, it is possible to include +.I pic +statements in the middle of a diagram to draw things not provided for +by +.I chem +itself. +. +Such +.I pic +statements should be included in +.I chem +code by adding +.B pic +as the first word of this line for clarity. +. +. +.P +The following +.I pic +commands are accepted as +.I chem +commands, so no +.B pic +command word is needed: +. +.IP +.B define +Start the definition of +.I pic +macro within +.IR chem . +. +.RS +.TP +.B [ +Start a block composite. +. +.TP +.B ] +End a block composite. +. +.TP +.B { +Start a macro definition block. +. +.TP +.B } +End a macro definition block. +.RE +. +.P +The macro names from +.B define +statements are stored and their call is accepted as a +.I chem +command as well. +. +. +.\" -------------------------------------------------------------------- +.SS WISH LIST +.\" -------------------------------------------------------------------- +. +.P +This TODO list was collected by Brian Kernighan. +. +. +.P +Error checking is minimal; errors are usually detected and reported in +an oblique fashion by +.IR pic . +. +. +.P +There is no library or file inclusion mechanism, and there is no +shorthand for repetitive structures. +. +. +.P +The extension mechanism is to create +.I pic +macros, but these are tricky to get right and don't have all the +properties of built-in objects. +. +. +.P +There is no in-line chemistry yet (e.g., analogous to the $\*(El$ +construct of eqn). +. +. +.P +There is no way to control entry point for bonds on groups. +. +Normally a bond connects to the carbon atom if entering from +the top or bottom and otherwise to the nearest corner. +. +. +.P +Bonds from substituted atoms on heterocycles do not join at the proper +place without adding a bit of +.IR pic . +. +. +.P +There is no decent primitive for brackets. +. +. +.P +Text (quoted strings) doesn't work very well. +. +. +.P +A squiggle bond is needed. +. +. +.\" -------------------------------------------------------------------- +.SH "FILES" +.\" -------------------------------------------------------------------- +. +.TP +.FN @DATASUBDIR@/pic/chem.pic +A collection of +.I pic +macros needed by +.BR @g@chem . +. +.TP +.FN @MACRODIR@/pic.tmac +A macro file which redefines +.B .PS +and +.BR .PE +to center +.I pic +diagrams. +. +.TP +.FN @DOCDIR@/examples/chem/*.chem +Example files for +.IR chem . +. +.TP +.FN @DOCDIR@/examples/chem/122/*.chem +Example files from the classical +.I chem +book +.BR 122.ps . +. +. +.\" -------------------------------------------------------------------- +.SH "BUGS" +.\" -------------------------------------------------------------------- +. +Report bugs to the +.MT bug-groff@\:gnu.org +bug-groff mailing list +.ME . +. +Include a complete, self-contained example that will allow the bug to +be reproduced, and say which version of +.I groff +and +.I chem +you are using. +. +You can get both version numbers by calling +.BR "@g@chem --version" . +. +. +.P +You can also use the +.MT groff@\:gnu.org +groff mailing list +.ME , +but you must first subscribe to this list. +. +You can do that by visiting the +.UR http://\:lists.gnu.org/\:mailman/\:listinfo/\:groff +groff mailing list web page +.UE . +. +. +.P +See +.BR \%groff (@MAN1EXT@) +for information on availability. +. +. +.\" -------------------------------------------------------------------- +.SH "SEE ALSO" +.\" -------------------------------------------------------------------- +. +.BR \%groff (@MAN1EXT@), +.BR \%@g@pic (@MAN1EXT@), +.BR \%groffer (@MAN1EXT@). +. +. +.P +You can still get the original +.UR http://\:cm.bell-labs.com/\:netlib/\:typesetting/\:chem.gz +chem awk source +.UE . +. +Its +.FN README +file was used for this manual page. +. +. +.P +The other classical document on +.I chem +is +.UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:122.ps.gz +122.ps +.UE . +. +. +.\" -------------------------------------------------------------------- +.SH "AUTHOR" +.\" -------------------------------------------------------------------- +.au +. +. +.\" -------------------------------------------------------------------- +.SH "COPYING" +.\" -------------------------------------------------------------------- +.co +. +. +.\" -------------------------------------------------------------------- +.\" Emacs settings +.\" -------------------------------------------------------------------- +. +.\" Local Variables: +.\" mode: nroff +.\" End: |