contrib/chem/chem.1.man

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