Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
CHEM(1)			    General Commands Manual		       CHEM(1)

       chem - groff preprocessor for producing chemical	structure diagrams

       chem [--] [filespec ...]

       chem -h
       chem --help

       chem -v
       chem --version

       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  lan-

       A  filespec argument is either a	file name of an	existing file or a mi-
       nus character -,	meaning	standard input.	 If no argument	 is  specified
       then  standard  input  is taken automatically.  -h and --help display a
       usage message, whereas -v and --version	display	 version  information;
       all exit.

       The  program  chem  originates  from  the Perl source file  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

	      chem data

       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,


       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 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


	      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  ig-

       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.


	      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  di-
       rection	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

	      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

       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.

       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 di-
       rection.	 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 ap-
       pear  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  sur-
       rounded 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 specify-
       ing a place.  The name BP is derived  from  branch  point  (i.e.,  line

       A string	within double quotes " is interpreted as a part	of a chem com-
       mand.  It represents a string  that  should  be	printed	 (without  the
       quotes).	  Text within quotes "..." is treated more or less like	a moi-
       ety except that no changes are made to the quoted part.

       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 let-
       ters and	numbers	is valid:

	      First: bond
		     bond 30 from First

       The specific construction

	      bond ... ; moiety

       is equivalent to


       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

       Since  chem is a	pic preprocessor, it is	possible to include pic	state-
       ments 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 ac-
       cepted as a chem	command	as well.

       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	short-
       hand 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 $...$ con-
       struct 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.

	      A	collection of pic macros needed	by chem.

	      A	macro file which redefines .PS and .PE to center pic diagrams.

	      Example files for	chem.

	      Example  files  from the classical chem article CHEM - A Program
	      for Typesetting Chemical Structure Diagrams [CSTR	#122].

       The   GNU   version   of	  chem	 was   written	 by    Bernd	Warken
       <>.	 It  is	 based on the documentation of
       Brian  Kernighan's  original  awk   version   of	  chem	 at   <http://>.

       groff(1), pic(1), groffer(1).

       You   can   still   get	 the   original	  chem	 awk  source  <http://>.  Its README file was used
       for this	manual page.

       The  other  classical  document	on  chem  is  CHEM  -  A  Program  for
       Typesetting  Chemical   Structure   Diagrams   [CSTR   #122]   <http://>.

groff 1.22.4		       29 November 2018			       CHEM(1)


Want to link to this manual page? Use this URL:

home | help