Debian Codegraph @

upstream/debian-trixie/man1/chem.1

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