1INSTALLATION 2 3The file chem invokes chem.awk, which is where the dirty 4work gets done. chem.awk tells pic to include a copy 5of chem.macros; you will need to change a pathname on 6the 2nd line of chem.awk. 7 8You need current versions of awk and pic. In particular, 9your awk has to support functions and your pic has to know 10about the copy statement. So if you get weird messages 11from either of those, it's time to update. 12 13There are several test files called *.p. 14 15 16INTRODUCTION 17 18"chem" is yet another preprocessor like eqn, pic, etc., 19this time for producing chemical structure diagrams. 20Today's version is best suited for organic chemistry 21(bonds, rings) and it's excruciatingly slow sometimes. 22Who knows what the future may hold. 23 24In a style reminiscent of eqn and pic, diagrams are 25written in a special language and occur in a document 26surrounded by lines beginning 27 .cstart 28and 29 .cend 30(in the first column, naturally). Anything outside 31these is copied through intact; whatever is between 32.cstart and .cend is converted into pic commands to 33draw the diagram. 34 35So as a bare minimum, 36 37 .cstart 38 CH3 39 bond 40 CH3 41 .cend 42 43prints two CH3 groups with a bond between them. 44To actually print this, you must run chem, pic, 45troff, and your output filter on whatever file 46contains the input: 47 48 chem [file...] | pic | troff ... | ... 49 50(By the way, chem needs the current version of awk; 51you will get some mysterious error messages from awk 52if your version is too old. You will also profit from 53having sensible and consistent definitions for the PS 54and PE macros.) 55 56 57THE LANGUAGE 58 59The chem input language is rather small. It provides 60bonds of several styles, moieties (e.g., C, NH3, ...), 61rings of several styles, and a way to glue them together 62as desired. In addition, since chem is a pic preprocessor, 63it's possible to include pic statements in the middle of 64a diagram to draw things not provided for by chem itself. 65 66Bonds: 67 68 bond [direction] [length n] [from Name | picstuff] 69 70draws a single bond in direction from nearest corner of Name 71"bond" can also be double bond, front bond, back bond, etc. 72(We'll get back to "Name" in a minute.) 73 74"direction" is the angle in degrees (0 up, positive clockwise) 75or a direction word like up, down, sw (= southwest), etc. 76If no direction is specified, the bond goes in the current 77direction (usually that of the last bond). 78 79Normally the bond begins at the last object placed; this 80can be changed by naming a "from" place. For instance, 81to make a simple alkyl chain: 82 83 CH3 84 bond (this one goes right from the CH3) 85 C (at the right end of the bond) 86 double bond up (from the C) 87 O (at the end of the double bond) 88 bond right from C 89 CH3 90 91A length in inches may be specified to override the default length. 92Other pic commands can be tacked on to the end of a bond command, 93to created dotted or dashed bonds or to specify a "to" place. 94 95 96Names: 97 98In the alkyl chain above, notice that the carbon atom C 99was used both to draw something and as the name for a place. 100A moiety always defines a name for a place; you can use 101your own names for places instead, and indeed, for rings 102you will have to. A name is just 103 104 Name: ... 105 106"Name" is often the name of a moiety like CH3, but it 107needn't be. Any name that begins with a capital letter 108and contains only letters and numbers is ok: 109 110 First: bond 111 bond 30 from First 112 113draws something like 114 115 / 116 ____/ 117 118 119Moieties: 120 121A moiety is a string of characters beginning with a capital letter, 122such as N(C2H5)2. Numbers are converted to subscripts (unless 123they appear to be fractional values, as in N2.5H). The moiety 124names itself after special characters have been stripped out: 125N(C2H5)2) has the name NC2H52. 126 127BP is a special "branch point" (i.e., line crossing) that doesn't print. 128 129Normally a moiety is placed right after the last thing mentioned, 130but it may be positioned by pic-like commands, e.g., 131 132 CH3 at C + (0.5,0.5) 133 134Text within quotes "..." is treated more or less like a 135moiety except that no changes are made to the quoted part. 136 137 138Rings: 139 140There are lots of rings, but only 5 and 6-sided rings get 141much support. "ring" by itself is a 6-sided ring; 142"benzene" is the benzene ring with a circle inside. 143"aromatic" puts a circle into any kind of ring. 144 145 ring [pointing up|right|left|down] [aromatic] 146 [put Mol at n] [double i,j k,l ...] 147 [picstuff] 148 149The vertices of a ring are numbered 1,2,... from the vertex 150that points in the natural compass direction. So for a 151hexagonal ring with the point at the top, the top vertex is 1, 152while if the ring has a point at the east side, that is 153vertex 1. This is expressed as 154 155 R1: ring pointing up 156 R2: ring pointing right 157 158The ring vertices are named .V1 .. .Vn, with .V1 in the 159pointing direction. So the corners of R1 are R1.V1 (the "top"), 160R1.V2, R1.V3, R1.V4 (the "bottom"), etc., whereas for R2, 161R2.V1 is the rightmost vertex and R2.V4 the leftmost. These 162vertex names are used for connecting bonds or other rings. 163For example: 164 165 R1: benzene pointing right 166 R2: benzene pointing right with .V6 at R1.V2 167 168creates two benzene rings connected along a side. 169 170Interior double bonds are specified as "double n1,n2 n3,n4 ..."; 171each number pair adds an interior bond. So the alternate form 172of a benzene ring is 173 174 ring double 1,2 3,4 5,6 175 176Heterocycles (rings with something other than carbon at a vertex) 177are written as "put X at V", as in 178 179 R: ring put N at 1 put O at 2 180 181In this heterocycle, R.N and R.O become synonyms for R.V1 and R.V2. 182 183There are two 5-sided rings. "ring5" is pentagonal with a side 184that matches the 6-sided ring; it has four natural directions. 185A "flatring" is a 5-sided ring created by chopping one corner 186of a 6-sided ring so that it exactly matches the 6-sided rings. 187 188The description of a ring has to fit on a single line. 189 190 191Miscellaneous: 192 193The specific construction 194 195 bond... ; moiety (spaces matter!) 196 197is equivalent to 198 199 bond 200 moiety 201 202Otherwise, each item has to be on a separate line (and only one line). 203 204A period "." in column 1 signals a troff command, which is copied 205through as is. 206 207A line whose first non-blank character is a # is treated as a comment. 208 209A line whose first word is "pic" is copied through as is after 210the "pic" has been removed. 211 212The command 213 214 size n 215 216scales the diagram so it looks plausible at point size n 217(default is 10 point). 218 219Anything else is assumed to be pic and is copied through with 220a label. 221 222WISH LIST 223 224It's too slow (but it's too early in the game to optimize). 225 226Error checking is minimal; errors are usually detected 227and reported in an oblique fashion by pic. 228 229There's no library or file inclusion mechanism, and there's 230no shorthand for repetitive structures. 231 232The extension mechanism is to create pic macros, but these 233are tricky to get right and don't have all the properties 234of built-in objects. 235 236There's no in-line chemistry yet (e.g., analogous to 237the $...$ construct of eqn). 238 239There is no way to control entry point for bonds on groups. 240Normally a bond connects to the carbon atom if entering from 241the top or bottom and otherwise to the nearest corner. 242 243Bonds from substituted atoms on heterocycles do not join 244at the proper place without adding a bit of pic. 245 246There is no decent primitive for brackets. 247 248Text (quoted strings) doesn't work very well. 249 250A squiggle bond is needed. 251 252 253COMPLAINTS 254 255If something doesn't work, or if you can see a way to 256make something better, let us know. 257 258 jon bentley, x2315, research!jlb 259 lynn jelinski, x2511, physics!lwj 260 brian kernighan, x6021, research!bwk 261