Debian Codegraph @

upstream/debian-unstable/man1/chem.1

raw
1 .TH \%chem 1 "2026-04-22" "groff 1.24.1"
2 .SH Name
3 \%chem \- embed chemical structure diagrams in
4 .I groff
5 documents
6 .
7 .
8 .\" ====================================================================
9 .\" Legal Terms
10 .\" ====================================================================
11 .\"
12 .\" Copyright 2006-2020 Free Software Foundation, Inc.
13 .\"
14 .\" This file is part of chem.
15 .\"
16 .\" chem is distributed with groff, the GNU roff typesetting system.
17 .\"
18 .\" groff is free software; you can redistribute it and/or modify it
19 .\" under the terms of the GNU General Public License as published by
20 .\" the Free Software Foundation, either version 3 of the License, or
21 .\" (at your option) any later version.
22 .\"
23 .\" groff is distributed in the hope that it will be useful, but WITHOUT
24 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
25 .\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
26 .\" License for more details.
27 .\"
28 .\" You should have received a copy of the GNU General Public License
29 .\" along with this program. If not, see
30 .\" <https://www.gnu.org/licenses/>.
31 .
32 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
33 .do nr *groff_chem_1_man_C \n[.cp]
34 .cp 0
35 .
36 .\" Define fallback for groff 1.23's MR macro if the system lacks it.
37 .nr do-fallback 0
38 .if !\n(.f .nr do-fallback 1 \" mandoc
39 .if \n(.g .if !d MR .nr do-fallback 1 \" older groff
40 .if !\n(.g .nr do-fallback 1 \" non-groff *roff
41 .if \n[do-fallback] \{\
42 . de MR
43 . ie \\n(.$=1 \
44 . I \%\\$1
45 . el \
46 . IR \%\\$1 (\\$2)\\$3
47 . .
48 .\}
49 .rr do-fallback
50 .
51 .
52 .\" ====================================================================
53 .SH Synopsis
54 .\" ====================================================================
55 .
56 .SY \%chem
57 .RB [ \-\- ]
58 .RI [ file\~ .\|.\|.]
59 .YS
60 .
61 .
62 .P
63 .SY \%chem
64 .B \-h
65 .YS
66 .
67 .SY \%chem
68 .B \-\-help
69 .YS
70 .
71 .
72 .P
73 .SY \%chem
74 .B \-v
75 .YS
76 .
77 .SY \%chem
78 .B \%\-\-version
79 .YS
80 .
81 .
82 .\" ====================================================================
83 .SH Description
84 .\" ====================================================================
85 .
86 .I chem
87 produces chemical structure diagrams.
88 .
89 Today's version is best suited for organic chemistry (bonds, rings).
90 .
91 The
92 .I \%chem
93 program is a
94 .I groff
95 preprocessor like
96 .IR \%eqn ,
97 .IR \%pic ,
98 .IR \%tbl ,
99 etc.
100 .
101 It generates
102 .I pic
103 output such that all
104 .I chem
105 parts are translated into diagrams of the
106 .I pic
107 language.
108 .
109 .
110 .P
111 If no operands are given,
112 or if
113 .I file
114 is
115 .RB \[lq] \- \[rq],
116 .I \%chem
117 reads the standard input stream.
118 .
119 .B \-h
120 and
121 .B \-\-help
122 display a usage message,
123 whereas
124 .B \-v
125 and
126 .B \%\-\-version
127 display version information;
128 all exit.
129 .
130 .
131 .P
132 The program
133 .I \%chem
134 originates from the Perl source file
135 .IR chem.pl .
136 .
137 It tells
138 .I \%pic
139 to include a copy of the macro file
140 .IR chem.pic .
141 .
142 Moreover the
143 .I groff
144 source file
145 .I pic.tmac
146 is loaded.
147 .
148 .
149 .P
150 In a style reminiscent of
151 .I eqn
152 and
153 .IR pic ,
154 the
155 .I chem
156 diagrams are written in a special language.
157 .
158 .
159 .P
160 A set of
161 .I chem
162 lines looks like this
163 .
164 .
165 .IP
166 .EX
167 \&.cstart
168 .I chem data
169 \&.cend
170 .EE
171 .
172 .
173 .P
174 Lines containing the keywords
175 .B .cstart
176 and
177 .B .cend
178 start and end the input for
179 .IR \%chem ,
180 respectively.
181 .
182 In
183 .I pic
184 context, i.e., after the call of
185 .BR .PS ,
186 .I chem
187 input can optionally be started by the line
188 .B \%begin\~chem
189 and ended by the line with the single word
190 .B end
191 instead.
192 .
193 .
194 .P
195 Anything outside these initialization lines is copied through
196 without modification;
197 all data between the initialization lines is converted into
198 .I pic
199 commands to draw the diagram.
200 .
201 .
202 .P
203 As an example,
204 .
205 .IP
206 .EX
207 \&.cstart
208 CH3
209 bond
210 CH3
211 \&.cend
212 .EE
213 .
214 .
215 .P
216 prints two
217 .B CH3
218 groups with a bond between them.
219 .
220 .
221 .P
222 If you want to create just
223 .I groff
224 output, you must run
225 .I \%chem
226 followed by
227 .I groff
228 with the option
229 .B \-p
230 for the activation of
231 .IR \%pic :
232 .IP
233 .I \%chem
234 .RI [ file\~ .\|.\|.\&]
235 .BR "| groff \-p\~" .\|.\|.
236 .
237 .
238 .P
239 .I \%chem
240 requires the
241 .I \%Math::\:Trig
242 Perl module,
243 available via
244 .UR \%https://\:www\:.cpan\:.org/
245 CPAN
246 .UE .
247 .
248 .
249 .\" ====================================================================
250 .SH Language
251 .\" ====================================================================
252 .
253 The
254 .I chem
255 input language is rather small.
256 .
257 It provides rings of several styles and a way to glue them together as
258 desired,
259 bonds of several styles,
260 moieties
261 (e.g.,
262 .BR C ,
263 .BR NH3 ,
264 \&.\|.\|.,
265 and strings.
266 .
267 .
268 .\" ====================================================================
269 .SS "Setting variables"
270 .\" ====================================================================
271 .
272 There are some variables that can be set by commands.
273 .
274 Such commands have two possible forms, either
275 .
276 .RS
277 .P
278 .I "variable value"
279 .RE
280 .
281 .P
282 or
283 .
284 .RS
285 .P
286 .IB "variable " = " value"
287 .RE
288 .
289 .P
290 This sets the given
291 .I variable
292 to the argument
293 .IR value .
294 If more arguments are given only the last argument is taken, all other
295 arguments are ignored.
296 .
297 .
298 .P
299 There are only a few variables to be set by these commands:
300 .
301 .TP
302 .BI textht " arg"
303 Set the height of the text to
304 .IR arg ;
305 default is 0.16.
306 .
307 .TP
308 .BI cwid " arg"
309 Set the character width to
310 .IR arg ;
311 default is 0.12.
312 .
313 .TP
314 .BI db " arg"
315 Set the bond length to
316 .IR arg ;
317 default is 0.2.
318 .
319 .TP
320 .BI size " arg"
321 Scale the diagram to make it look plausible at point size
322 .IR arg ;
323 default is 10 point.
324 .
325 .
326 .\" ====================================================================
327 .SS Bonds
328 .\" ====================================================================
329 .
330 .SY bond
331 .RI [ direction ]
332 .RI [ length\ n ]
333 .RB [ from\ \c
334 .IR Name | picstuff ]
335 .YS
336 .
337 .
338 .P
339 The
340 .B bond
341 command draws a single bond in direction from nearest corner of
342 .IR Name .
343 .B bond
344 can also be
345 .BR "double bond" ,
346 .BR "front bond" ,
347 .BR "back bond" ,
348 etc.
349 .
350 (We will get back to
351 .I Name
352 soon.)
353 .
354 .
355 .P
356 .I direction
357 is the angle in degrees (0\~up, positive clockwise)
358 or a direction word like
359 .BR up ,
360 .BR down ,
361 .B sw
362 (=\~southwest), etc.
363 .
364 If no direction is specified, the bond goes in the current direction
365 (usually that of the last bond).
366 .
367 .
368 .P
369 Normally the bond begins at the last object placed; this
370 can be changed by naming a
371 .B from
372 place.
373 .
374 For instance, to make a simple alkyl chain:
375 .
376 .RS
377 .TS
378 tab (@);
379 lb l.
380 CH3
381 bond@(this one goes right from the CH3)
382 C@(at the right end of the bond)
383 double bond up@(from the C)
384 O@(at the end of the double bond)
385 bond right from C
386 CH3
387 .TE
388 .RE
389 .
390 .
391 .P
392 A length in inches may be specified to override the default length.
393 .
394 Other
395 .I pic
396 commands can be tacked on to the end of a bond command, to created
397 dotted or dashed bonds or to specify a
398 .B to
399 place.
400 .
401 .
402 .\" ====================================================================
403 .SS Rings
404 .\" ====================================================================
405 .
406 There are lots of rings,
407 but only five- and six-sided rings get much support.
408 .
409 .B ring
410 by itself is a six-sided ring;
411 .B benzene
412 is the benzene ring with a circle inside.
413 .B aromatic
414 puts a circle into any kind of ring.
415 .
416 .
417 .P
418 .SY ring
419 .RB \%[ pointing\ ( up | right | left | down )]
420 .RB \%[ aromatic ]
421 .RB [ put\ Mol\ at\ \fIn\/\fP ]
422 .RB \%[ double\ \c
423 .IR i , j\ \/\c
424 .IR k , l\ \/\c
425 \&.\|.\|.\&
426 .RI [ picstuff ]
427 .YS
428 .
429 .
430 .P
431 The vertices of a ring are numbered 1, 2, \&.\|.\|.\& from the
432 vertex that points in the natural compass direction.
433 .
434 So for a hexagonal ring with the point at the top, the top vertex
435 is\~1, while if the ring has a point at the east side, that is
436 vertex\~1.
437 .
438 This is expressed as
439 .
440 .IP
441 .EX
442 R1: ring pointing up
443 R2: ring pointing right
444 .EE
445 .
446 .
447 .P
448 The ring vertices are named
449 .BR .V1 ,
450 \&.\|.\|.,
451 .BI .V n\fR,\fP
452 with
453 .B .V1
454 in the pointing direction.
455 .
456 So the corners of
457 .B R1
458 are
459 .B R1.V1
460 (the
461 .IR top ),
462 .BR R1.V2 ,
463 .BR R1.V3 ,
464 .B R1.V4
465 (the
466 .IR bottom ),
467 etc., whereas for
468 .BR R2 ,
469 .B R2.V1
470 is the rightmost vertex and
471 .B R2.V4
472 the leftmost.
473 .
474 These vertex names are used for connecting bonds or other rings.
475 .
476 For example,
477 .
478 .IP
479 .EX
480 R1: benzene pointing right
481 R2: benzene pointing right with .V6 at R1.V2
482 .EE
483 .
484 .
485 .P
486 creates two benzene rings connected along a side.
487 .
488 .
489 .P
490 Interior double bonds are specified as
491 .B \%double
492 .IB n1 , "n2 n3" , n4
493 .RB .\|.\|. ;
494 each number pair adds an interior bond.
495 .
496 So the alternate form of a benzene ring is
497 .
498 .IP
499 .B "ring double 1,2 3,4 5,6"
500 .
501 .
502 .P
503 Heterocycles (rings with something other than carbon at a vertex) are
504 written as
505 .BI put\ X\ at\ V\fR,\fP
506 as in
507 .
508 .IP
509 .B "R: ring put N at 1 put O at 2"
510 .
511 .
512 .P
513 In this heterocycle,
514 .B R.N
515 and
516 .B R.O
517 become synonyms for
518 .B R.V1
519 and
520 .BR R.V2 .
521 .
522 .
523 .P
524 There are two five-sided rings.
525 .
526 .B ring5
527 is pentagonal with a side that matches the six-sided ring;
528 it has four natural directions.
529 .
530 A
531 .B \%flatring
532 is a five-sided ring created by chopping one corner of a six-sided ring
533 so that it exactly matches the six-sided rings.
534 .
535 .
536 .P
537 The description of a ring has to fit on a single line.
538 .
539 .
540 .\" ====================================================================
541 .SS "Moieties and strings"
542 .\" ====================================================================
543 .
544 A moiety is a string of characters beginning with a capital letter,
545 such as N(C2H5)2.
546 .
547 Numbers are converted to subscripts (unless they appear to be
548 fractional values, as in N2.5H).
549 .
550 The name of a moiety is determined from the moiety after special
551 characters have been stripped out: e.g., N(C2H5)2) has the name NC2H52.
552 .
553 .
554 .P
555 Moieties can be specified in two kinds.
556 .
557 Normally a moiety is placed right after the last thing mentioned,
558 separated by a semicolon surrounded by spaces, e.g.,
559 .
560 .IP
561 .B "B1: bond ; OH"
562 .
563 .P
564 Here the moiety is
565 .BR OH ;
566 it is set after a bond.
567 .
568 .
569 .P
570 As the second kind a moiety can be positioned as the first word in a
571 .IR pic -like
572 command, e.g.,
573 .
574 .IP
575 .B "CH3 at C + (0.5,0.5)"
576 .
577 .P
578 Here the moiety is
579 .BR CH3 .
580 It is placed at a position relative to
581 .BR C ,
582 a moiety used earlier in the chemical structure.
583 .
584 .
585 .P
586 So moiety names can be specified as
587 .I chem
588 positions everywhere in the
589 .I chem
590 code.
591 .
592 Beneath their printing moieties are names for places.
593 .
594 .
595 .P
596 The moiety
597 .B BP
598 is special.
599 .
600 It is not printed but just serves as a mark to be referred to in later
601 .I chem
602 commands.
603 .
604 For example,
605 .
606 .IP
607 .B "bond ; BP"
608 .
609 .P
610 sets a mark at the end of the bond.
611 .
612 This can be used then for specifying a place.
613 .
614 The name
615 .B BP
616 is derived from
617 .I branch point
618 (i.e., line crossing).
619 .
620 .
621 .P
622 A string within double quotes
623 .B \(dq
624 is interpreted as a part of a
625 .I chem
626 command.
627 .
628 It represents a string that should be printed (without the quotes).
629 .
630 Text within quotes
631 .BR \(dq .\|.\|.\& \(dq
632 is treated more or less like a moiety except that no changes are made to
633 the quoted part.
634 .
635 .
636 .\" ====================================================================
637 .SS Names
638 .\" ====================================================================
639 .
640 In the alkyl chain above, notice that the carbon atom
641 .B C
642 was used both to draw something and as the name for a place.
643 .
644 A moiety always defines a name for a place; you can use
645 your own names for places instead, and indeed, for rings
646 you will have to.
647 .
648 A name is just
649 .
650 .IP
651 .IB Name :
652 \&.\|.\|.
653 .
654 .
655 .P
656 .I Name
657 is often the name of a moiety like
658 .BR CH3 ,
659 but it need not to be.
660 .
661 Any name that begins with a capital letter and which contains
662 only letters and numbers is valid.
663 .
664 .
665 .P
666 .RS
667 .EX
668 First: bond
669 "bond 30 from First"
670 .EE
671 .RE
672 .
673 .
674 .\" ====================================================================
675 .SS Miscellaneous
676 .\" ====================================================================
677 .
678 The specific construction
679 .RS
680 .TP
681 .BR bond \~.\|.\|.\&\~ "; moiety"
682 .RE
683 .P
684 is equivalent to
685 .IP
686 .EX
687 bond
688 moiety
689 .EE
690 .
691 .
692 .P
693 Otherwise, each item has to be on a separate line (and only one line).
694 Note that there must be whitespace after the semicolon which separates
695 the commands.
696 .
697 .
698 .P
699 A period character
700 .B .\&
701 or a single quote
702 .B \[aq]
703 in the first column of a line signals a
704 .I troff
705 command, which is copied through as-is.
706 .
707 .
708 .P
709 A line whose first non-blank character is a hash character
710 .RB ( # )
711 is treated as a comment and thus ignored.
712 .
713 However, hash characters within a word are kept.
714 .
715 .
716 .P
717 A line whose first word is
718 .B pic
719 is copied through as-is after the word
720 .B pic
721 has been removed.
722 .
723 .
724 .P
725 The command
726 .IP
727 .B size
728 .I n
729 .P
730 scales the diagram to make it look plausible at point size\~\c
731 .I n
732 (default is 10\~point).
733 .
734 .
735 .P
736 Anything else is assumed to be
737 .I pic
738 code, which is copied through with a label.
739 .
740 .
741 .P
742 Since
743 .I \%chem
744 is a
745 .I \%pic
746 preprocessor, it is possible to include
747 .I pic
748 statements in the middle of a diagram to draw things not provided for
749 by
750 .I chem
751 itself.
752 .
753 Such
754 .I pic
755 statements should be included in
756 .I chem
757 code by adding
758 .B pic
759 as the first word of this line for clarity.
760 .
761 .
762 .P
763 The following
764 .I pic
765 commands are accepted as
766 .I chem
767 commands, so no
768 .B pic
769 command word is needed:
770 .
771 .IP
772 .B define
773 Start the definition of
774 .I pic
775 macro within
776 .IR chem .
777 .
778 .RS
779 .TP
780 .B [
781 Start a block composite.
782 .
783 .TP
784 .B ]
785 End a block composite.
786 .
787 .TP
788 .B {
789 Start a macro definition block.
790 .
791 .TP
792 .B }
793 End a macro definition block.
794 .RE
795 .
796 .P
797 The macro names from
798 .B define
799 statements are stored and their call is accepted as a
800 .I chem
801 command as well.
802 .
803 .
804 .\" ====================================================================
805 .SS "Wish list"
806 .\" ====================================================================
807 .
808 .P
809 This TODO list was collected by Brian Kernighan.
810 .
811 .
812 .P
813 Error checking is minimal; errors are usually detected and reported in
814 an oblique fashion by
815 .IR pic .
816 .
817 .
818 .P
819 There is no library or file inclusion mechanism, and there is no
820 shorthand for repetitive structures.
821 .
822 .
823 .P
824 The extension mechanism is to create
825 .I pic
826 macros, but these are tricky to get right and don't have all the
827 properties of built-in objects.
828 .
829 .
830 .P
831 There is no in-line chemistry yet
832 (e.g.,
833 analogous to the
834 .BR $ .\|.\|. $
835 construct of
836 .IR eqn ).
837 .
838 .
839 .P
840 There is no way to control entry point for bonds on groups.
841 .
842 Normally a bond connects to the carbon atom if entering from
843 the top or bottom and otherwise to the nearest corner.
844 .
845 .
846 .P
847 Bonds from substituted atoms on heterocycles do not join at the proper
848 place without adding a bit of
849 .IR pic .
850 .
851 .
852 .P
853 There is no decent primitive for brackets.
854 .
855 .
856 .P
857 Text (quoted strings) doesn't work very well.
858 .
859 .
860 .P
861 A squiggle bond is needed.
862 .
863 .
864 .\" ====================================================================
865 .SH Files
866 .\" ====================================================================
867 .
868 .TP
869 .I /usr/\:\%share/\:\%groff/\:\%1.24.1/\:pic/\:chem\:.pic
870 A collection of
871 .I pic
872 macros needed by
873 .IR \%chem .
874 .
875 .TP
876 .I /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%tmac/\:pic\:.tmac
877 A macro file which redefines
878 .BR .PS ,
879 .BR .PE ,
880 and
881 .B .PF
882 to center
883 .I pic
884 diagrams.
885 .
886 .TP
887 .IR /usr/\:\%share/\:\%doc/\:\%groff\-base/\:\%examples/\:chem/\: * .chem
888 Example files for
889 .IR chem .
890 .
891 .TP
892 .IR /usr/\:\%share/\:\%doc/\:\%groff\-base/\:\%examples/\:chem/\:122/\: * .chem
893 Example files from the
894 .I chem
895 article by its authors,
896 \[lq]CHEM\[em]A Program for Typesetting Chemical Structure Diagrams:
897 User Manual\[rq]
898 (CSTR\~#122).
899 .
900 .
901 .\" ====================================================================
902 .SH Authors
903 .\" ====================================================================
904 .
905 The GNU version of
906 .I chem
907 was written by
908 .MT groff\-bernd\:.warken\-72@\:web\:.de
909 Bernd Warken
910 .ME .
911 .
912 It is based on the documentation of Brian Kernighan's original
913 .I awk
914 version of
915 .IR chem .
916 .
917 .
918 .\" ====================================================================
919 .SH "See also"
920 .\" ====================================================================
921 .
922 \[lq]CHEM\[em]A Program for Typesetting Chemical Diagrams: User
923 Manual\[rq]
924 by Jon L.\& Bentley,
925 Lynn W.\& Jelinski,
926 and
927 Brian W.\& Kernighan,
928 1992,
929 AT&T Bell Laboratories Computing Science Technical Report No.\& 122
930 .
931 .
932 .P
933 .MR groff 1 ,
934 .MR \%pic 1
935 .
936 .
937 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
938 .cp \n[*groff_chem_1_man_C]
939 .do rr *groff_chem_1_man_C
940 .
941 .
942 .\" Local Variables:
943 .\" fill-column: 72
944 .\" mode: nroff
945 .\" End:
946 .\" vim: set filetype=groff textwidth=72: