chem(1)
NAME
chem - groff preprocessor for producing chemical structure diagrams
SYNOPSIS
chem [option ....] [--] [filespec ....] chem -h | --help chem -v | --version
OPTION USAGE
There are no other options than -h, --help, -v, and --version; these options provoke the printing of a version or usage information, respectively, and all filespec arguments are ignored. A filespec argument is either a file name of an existing file or a minus character -, meaning standard input. If no argument is specified then standard input is taken automatically.
DESCRIPTION
chem produces chemical structure diagrams. Today's version is best
suited for organic chemistry (bonds, rings). The chem program is a
groff preprocessor like eqn, pic, tbl, etc. It generates pic output
such that all chem parts are translated into diagrams of the pic
language.
The program chem originates from the Perl source file chem.pl. It
tells pic to include a copy of the macro file chem.pic. Moreover the
groff source file pic.tmac is loaded.
In a style reminiscent of eqn and pic, the chem diagrams are written in
a special language.
A set of chem lines looks like this
.cstart
chem data
.cend
Lines containing the keywords .cstart and .cend start and end the input
for chem, respectively. In pic context, i.e., after the call of .PS,
chem input can optionally be started by the line begin chem and ended
by the line with the single word end instead.
Anything outside these initialization lines is copied through without
modification; all data between the initialization lines is converted
into pic commands to draw the diagram.
As an example,
.cstart
CH3
bond
CH3
.cend
prints two CH3 groups with a bond between them.
To actually view this, you must run chem followed by groffer:
chem [file ....] | groffer
If you want to create just groff output, you must run chem followed by
groff with the option -p for the activation of pic:
chem [file ....] | groff -p ....
THE LANGUAGE
The 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., C, NH3, ...., and strings.
Setting Variables
There are some variables that can be set by commands. Such commands
have two possible forms, either
variable value
or
variable = value
This sets the given variable to the argument value. If more arguments
are given only the last argument is taken, all other arguments are
ignored.
There are only a few variables to be set by these commands:
textht arg
Set the height of the text to arg; default is 0.16.
cwid arg
Set the character width to arg; default is 0.12.
db arg Set the bond length to arg; default is 0.2.
size arg
Scale the diagram to make it look plausible at point size arg;
default is 10 point.
Bonds
This
bond [direction] [length n] [from Name|picstuff]
draws a single bond in direction from nearest corner of Name. bond can
also be double bond, front bond, back bond, etc. (We will get back to
Name soon.)
direction is the angle in degrees (0 up, positive clockwise) or a
direction word like up, down, sw (= southwest), etc. If no direction
is specified, the bond goes in the current direction (usually that of
the last bond).
Normally the bond begins at the last object placed; this can be
changed by naming a from place. For instance, to make a simple alkyl
chain:
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
A length in inches may be specified to override the default length.
Other pic commands can be tacked on to the end of a bond command, to
created dotted or dashed bonds or to specify a to place.
Rings
There are lots of rings, but only 5 and 6-sided rings get much support.
ring by itself is a 6-sided ring; benzene is the benzene ring with a
circle inside. aromatic puts a circle into any kind of ring.
ring [pointing (up|right|left|down)] [aromatic] [put Mol at n]
[double i,j k,l .... [picstuff]
The vertices of a ring are numbered 1, 2, .... 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
R1: ring pointing up
R2: ring pointing right
The ring vertices are named .V1, ...., .Vn, with .V1 in the pointing
direction. So the corners of R1 are R1.V1 (the top), R1.V2, R1.V3,
R1.V4 (the bottom), etc., whereas for R2, R2.V1 is the rightmost vertex
and R2.V4 the leftmost. These vertex names are used for connecting
bonds or other rings. For example,
R1: benzene pointing right
R2: benzene pointing right with .V6 at R1.V2
creates two benzene rings connected along a side.
Interior double bonds are specified as double n1,n2 n3,n4 ....; each
number pair adds an interior bond. So the alternate form of a benzene
ring is
ring double 1,2 3,4 5,6
Heterocycles (rings with something other than carbon at a vertex) are
written as put X at V, as in
R: ring put N at 1 put O at 2
In this heterocycle, R.N and R.O become synonyms for R.V1 and R.V2.
There are two 5-sided rings. ring5 is pentagonal with a side that
matches the 6-sided ring; it has four natural directions. A 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.
The description of a ring has to fit on a single line.
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.
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.,
B1: bond ; OH
Here the moiety is OH; it is set after a bond.
As the second kind a moiety can be positioned as the first word in a
pic-like command, e.g.,
CH3 at C + (0.5,0.5)
Here the moiety is CH3. It is placed at a position relative to C, a
moiety used earlier in the chemical structure.
So moiety names can be specified as chem positions everywhere in the
chem code. Beneath their printing moieties are names for places.
The moiety BP is special. It is not printed but just serves as a mark
to be referred to in later chem commands. For example,
bond ; BP
sets a mark at the end of the bond. This can be used then for
specifying a place. The name BP is derived from branch point (i.e.,
line crossing).
A string within double quotes " is interpreted as a part of a chem
command. It represents a string that should be printed (without the
quotes). Text within quotes "...." is treated more or less like a
moiety except that no changes are made to the quoted part.
Names
In the alkyl chain above, notice that the carbon atom 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
Name: ....
Name is often the name of a moiety like CH3, but it need not to be.
Any name that begins with a capital letter and which contains only
letters and numbers is valid:
First: bond
bond 30 from First
Miscellaneous
The specific construction
bond .... ; moiety
is equivalent to
bond
moiety
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.
A period character . or a single quote ' in the first column of a line
signals a troff command, which is copied through as-is.
A line whose first non-blank character is a hash character (#) is
treated as a comment and thus ignored. However, hash characters within
a word are kept.
A line whose first word is pic is copied through as-is after the word
pic has been removed.
The command
size n
scales the diagram to make it look plausible at point size n (default
is 10 point).
Anything else is assumed to be pic code, which is copied through with a
label.
Since chem is a pic preprocessor, it is possible to include pic
statements in the middle of a diagram to draw things not provided for
by chem itself. Such pic statements should be included in chem code by
adding pic as the first word of this line for clarity.
The following pic commands are accepted as chem commands, so no pic
command word is needed:
define Start the definition of pic macro within chem.
[ Start a block composite.
] End a block composite.
{ Start a macro definition block.
} End a macro definition block.
The macro names from define statements are stored and their call is
accepted as a chem command as well.
WISH LIST
This TODO list was collected by Brian Kernighan.
Error checking is minimal; errors are usually detected and reported in
an oblique fashion by pic.
There is no library or file inclusion mechanism, and there is no
shorthand for repetitive structures.
The extension mechanism is to create pic macros, but these are tricky
to get right and don't have all the properties of built-in objects.
There is no in-line chemistry yet (e.g., analogous to the $....$
construct of eqn).
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.
Bonds from substituted atoms on heterocycles do not join at the proper
place without adding a bit of pic.
There is no decent primitive for brackets.
Text (quoted strings) doesn't work very well.
A squiggle bond is needed.
FILES
/usr/share/groff/1.22.3/pic/chem.pic
A collection of pic macros needed by chem.
/usr/share/groff/1.22.3/tmac/pic.tmac
A macro file which redefines .PS and .PE to center pic diagrams.
/usr/share/doc/groff-base/examples/chem/*.chem
Example files for chem.
/usr/share/doc/groff-base/examples/chem/122/*.chem
Example files from the classical chem book 122.ps.
BUGS
Report bugs to the bug-groff mailing list bug-groff@gnu.org. Include a complete, self-contained example that will allow the bug to be reproduced, and say which version of groff and chem you are using. You can get both version numbers by calling chem --version. You can also use the groff mailing list groff@gnu.org, but you must first subscribe to this list. You can do that by visiting the groff mailing list web page http://lists.gnu.org/mailman/listinfo/groff. See groff(1) for information on availability.
SEE ALSO
groff(1), pic(1), groffer(1). You can still get the original chem awk source http://cm.bell- labs.com/netlib/typesetting/chem.gz. Its README file was used for this manual page. The other classical document on chem is 122.ps http://cm.bell- labs.com/cm/cs/cstr/122.ps.gz.
COPYING
Copyright 2006-2014 Free Software Foundation, Inc. This file is part of chem, which is part of groff, a free software project. You can redistribute it and/or modify it under the terms of the GNU General Public License version 2 (GPL2) as published by the Free Software Foundation. The license text for GPL2 is available in the internet at http://www.gnu.org/licenses/gpl-2.0.html.
AUTHORS
This file was written by Bernd Warken <groff-bernd.warken-72@web.de>. It is based on the documentation of Brian Kernighan's original awk version of chem at http://cm.bell-labs.com/cm/cs/who/bwk/index.html.
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
