/contrib/groff/src/preproc/grn/grn.man
Unknown | 652 lines | 649 code | 3 blank | 0 comment | 0 complexity | 1a5bf6accc50b30b9b600a878e9a8440 MD5 | raw file
1'\" t 2.ig 3Copyright (C) 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. 4 5Permission is granted to make and distribute verbatim copies of 6this manual provided the copyright notice and this permission notice 7are preserved on all copies. 8 9Permission is granted to copy and distribute modified versions of this 10manual under the conditions for verbatim copying, provided that the 11entire resulting derived work is distributed under the terms of a 12permission notice identical to this one. 13 14Permission is granted to copy and distribute translations of this 15manual into another language, under the above conditions for modified 16versions, except that this permission notice may be included in 17translations approved by the Free Software Foundation instead of in 18the original English. 19.. 20. 21.do nr grn_C \n[.C] 22.cp 0 23. 24.de TQ 25. br 26. ns 27. TP \\$1 28.. 29. 30.\" Like TP, but if specified indent is more than half 31.\" the current line-length - indent, use the default indent. 32.de Tp 33. ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP 34. el .TP "\\$1" 35.. 36. 37. 38.TH @G@GRN @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@" 39.SH NAME 40@g@grn \- groff preprocessor for gremlin files 41.SH SYNOPSIS 42.BR @g@grn 43[ 44.B \-Cv 45] 46[ 47.BI \-T dev 48] 49[ 50.BI \-M dir 51] 52[ 53.BI \-F dir 54] 55[ 56.IR file\.\.\.\& 57] 58.PP 59It is possible to have whitespace between a command line option and its 60parameter. 61.SH DESCRIPTION 62.I @g@grn 63is a preprocessor for including 64.I gremlin 65pictures in 66.I groff 67input. 68.I @g@grn 69writes to standard output, processing only input lines between two that 70start with 71.B .GS 72and 73.BR .GE. 74Those lines must contain 75.I @g@grn 76commands (see below). 77These commands request a 78.I gremlin 79file, and the picture in that file is 80converted and placed in the 81.I @g@troff 82input stream. 83The 84.B .GS 85request may be followed by a C, L, or R to center, left, or right 86justify the whole 87.I gremlin 88picture (default justification is center). 89If no 90.I file 91is mentioned, the standard input is read. 92At the end of the picture, the position on the page is the bottom of the 93.I gremlin 94picture. 95If the 96.I @g@grn 97entry is ended with 98.B .GF 99instead of 100.BR .GE , 101the position is left at the top of the picture. 102.PP 103Please note that currently only the \-me macro package has support for 104.BR .GS , 105.BR .GE , 106and 107.BR .GF . 108.PP 109The following command-line options are understood: 110.TP 111.BI \-T dev 112Prepare output for printer 113.IR dev . 114The default device is 115.BR @DEVICE@ . 116See 117.BR groff (@MAN1EXT@) 118for acceptable devices. 119.TP 120.BI \-M dir 121Prepend 122.I dir 123to the default search path for 124.I gremlin 125files. 126The default path is (in that order) the current directory, the home 127directory, 128.BR @SYSTEMMACRODIR@ , 129.BR @LOCALMACRODIR@ , 130and 131.BR @MACRODIR@ . 132.TP 133.BI \-F dir 134Search 135.I dir 136for subdirectories 137.BI dev name 138.RI ( name 139is the name of the device) for the 140.B DESC 141file before the default font directories 142.BR @LOCALFONTDIR@ , 143.BR @FONTDIR@ , 144and 145.BR @LEGACYFONTDIR@ . 146.TP 147.B \-C 148Recognize 149.B .GS 150and 151.B .GE 152(and 153.BR .GF ) 154even when followed by a character other than space or newline. 155.\".TP 156.\".B \-s 157.\"This switch causes the picture to be traversed twice: 158.\"The first time, only the interiors of filled polygons (as borderless 159.\"polygons) are printed. 160.\"The second time, the outline is printed as a series of line segments. 161.\"This way, postprocessors that overwrite rather than merge picture elements 162.\"(such as Postscript) can still have text and graphics on a shaded 163.\"background. 164.TP 165.B \-v 166Print the version number. 167.SH GRN COMMANDS 168Each input line between 169.B .GS 170and 171.B .GE 172may have one 173.I @g@grn 174command. 175Commands consist of one or two strings separated by white space, the first 176string being the command and the second its operand. 177Commands may be upper or lower case and abbreviated down to one character. 178.PP 179Commands that affect a picture's environment (those listed before 180.BR default , 181see below) are only in effect for the current picture: 182The environment is reinitialized to the defaults at the start of the next 183picture. 184The commands are as follows: 185.TP 186.BI 1\ N 187.TQ 188.BI 2\ N 189.TQ 190.BI 3\ N 191.TQ 192.BI 4\ N 193Set 194.IR gremlin 's 195text size number 1 (2, 3, or 4) to 196.I N 197points. 198The default is 12 (16, 24, and 36, respectively). 199.TP 200.BI roman\ f 201.TQ 202.BI italics\ f 203.TQ 204.BI bold\ f 205.TQ 206.BI special\ f 207Set the roman (italics, bold, or special) font to 208.IR @g@troff 's 209font 210.I f 211(either a name or number). 212The default is R (I, B, and S, respectively). 213.TP 214.BI l\ f 215.TQ 216.BI stipple\ f 217Set the stipple font to 218.IR @g@troff 's 219stipple font 220.I f 221(name or number). 222The command 223.B stipple 224may be abbreviated down as far as `st' (to avoid 225confusion with 226.BR special ). 227There is 228.I no 229default for stipples (unless one is set by the default command), and it is 230invalid to include a 231.I gremlin 232picture with polygons without specifying a 233stipple font. 234.TP 235.BI x\ N 236.TQ 237.BI scale\ N 238Magnify the picture (in addition to any default magnification) by 239.IR N , 240a floating point number larger than zero. 241The command 242.B scale 243may be abbreviated down to `sc'. 244.TP 245.BI narrow\ N 246.TQ 247.BI medium\ N 248.TQ 249.BI thick\ N 250Set the thickness of 251.IR gremlin 's 252narrow (medium and thick, respectively) lines to 253.I N 254times 0.15pt (this value can be changed at compile time). 255The default is 1.0 (3.0 and 5.0, respectively), which corresponds to 0.15pt 256(0.45pt and 0.75pt, respectively). 257A thickness value of zero selects the smallest available line thickness. 258Negative values cause the line thickness to be proportional to the current 259point size. 260.TP 261.BI pointscale\ <off/on> 262Scale text to match the picture. 263Gremlin text is usually printed in the point size specified with the 264commands 265.BR 1 , 266.BR 2 , 267.BR 3 , 268.RB or\~ 4 , 269regardless of any scaling factors in the picture. 270Setting 271.B pointscale 272will cause the point sizes to scale with the picture (within 273.IR @g@troff 's 274limitations, of course). 275An operand of anything but 276.I off 277will turn text scaling on. 278.TP 279.B default 280Reset the picture environment defaults to the settings in the current 281picture. 282This is meant to be used as a global parameter setting mechanism at the 283beginning of the 284.I @g@troff 285input file, but can be used at any time to reset the 286default settings. 287.TP 288.BI width\ N 289Forces the picture to be 290.I N 291inches wide. 292This overrides any scaling factors present in the same picture. 293.RB ` width 294.IR 0 ' 295is ignored. 296.TP 297.BI height\ N 298Forces picture to be 299.I N 300inches high, overriding other scaling factors. 301If both `width' and `height' are specified the tighter constraint will 302determine the scale of the picture. 303.B Height 304and 305.B width 306commands are not saved with a 307.B default 308command. 309They will, however, affect point size scaling if that option is set. 310.TP 311.BI file\ name 312Get picture from 313.I gremlin 314file 315.I name 316located the current directory (or in the library directory; see the 317.B \-M 318option above). 319If two 320.B file 321commands are given, the second one overrides the first. 322If 323.I name 324doesn't exist, an error message is reported and processing continues from 325the 326.B .GE 327line. 328.SH NOTES ABOUT GROFF 329Since 330.I @g@grn 331is a preprocessor, it doesn't know about current indents, point sizes, 332margins, number registers, etc. 333Consequently, no 334.I @g@troff 335input can be placed between the 336.B .GS 337and 338.B .GE 339requests. 340However, 341.I gremlin 342text is now processed by 343.IR @g@troff , 344so anything legal in a single line of 345.I @g@troff 346input is legal in a line of 347.I gremlin 348text (barring `.' directives at the beginning of a line). 349Thus, it is possible to have equations within a 350.I gremlin 351figure by including in the 352.I gremlin 353file 354.I eqn 355expressions enclosed by previously defined delimiters (e.g. 356.IR $$ ). 357.PP 358When using 359.I @g@grn 360along with other preprocessors, it is best to run 361.I tbl 362before 363.IR @g@grn , 364.IR pic , 365and/or 366.I ideal 367to avoid overworking 368.IR tbl . 369.I Eqn 370should always be run last. 371.PP 372A picture is considered an entity, but that doesn't stop 373.I @g@troff 374from trying to break it up if it falls off the end of a page. 375Placing the picture between `keeps' in \-me macros will ensure proper 376placement. 377.PP 378.I @g@grn 379uses 380.IR @g@troff 's 381number registers 382.B g1 383through 384.B g9 385and sets registers 386.B g1 387and 388.B g2 389to the width and height of the 390.I gremlin 391figure (in device units) before entering the 392.B .GS 393request (this is for those who want to rewrite these macros). 394.SH GREMLIN FILE FORMAT 395There exist two distinct 396.I gremlin 397file formats, the original format from the 398.I AED 399graphic terminal version, and the 400.I SUN 401or 402.I X11 403version. 404An extension to the 405.IR SUN / X11 406version allowing reference points with negative coordinates is 407.B not 408compatible with the 409.I AED 410version. 411As long as a 412.I gremlin 413file does not contain negative coordinates, either format will be read 414correctly by either version of 415.I gremlin 416or 417.IR @g@grn . 418The other difference to the 419.IR SUN / X11 420format is the use of names for picture objects (e.g., POLYGON, CURVE) 421instead of numbers. 422Files representing the same picture are shown in Table 1 in each format. 423.sp 424.TS 425center, tab(@); 426l lw(0.1i) l. 427sungremlinfile@@gremlinfile 4280 240.00 128.00@@0 240.00 128.00 429CENTCENT@@2 430240.00 128.00@@240.00 128.00 431185.00 120.00@@185.00 120.00 432240.00 120.00@@240.00 120.00 433296.00 120.00@@296.00 120.00 434*@@-1.00 -1.00 4352 3@@2 3 43610 A Triangle@@10 A Triangle 437POLYGON@@6 438224.00 416.00@@224.00 416.00 43996.00 160.00@@96.00 160.00 440384.00 160.00@@384.00 160.00 441*@@-1.00 -1.00 4425 1@@5 1 4430@@0 444-1@@-1 445.T& 446css. 447.sp 448Table 1. File examples 449.TE 450.sp 451.IP \(bu 452The first line of each 453.I gremlin 454file contains either the string 455.B gremlinfile 456.RI ( AED 457version) or 458.B sungremlinfile 459.RI ( SUN / X11 ) 460.IP \(bu 461The second line of the file contains an orientation, and 462.B x 463and 464.B y 465values for a positioning point, separated by spaces. 466The orientation, either 467.B 0 468or 469.BR 1 , 470is ignored by the 471.IR SUN / X11 472version. 473.B 0 474means that 475.I gremlin 476will display things in horizontal format (drawing area wider than it is 477tall, with menu across top). 478.B 1 479means that 480.I gremlin 481will display things in vertical format (drawing area taller than it is wide, 482with menu on left side). 483.B x 484and 485.B y 486are floating point values giving a positioning point to be used when this 487file is read into another file. 488The stuff on this line really isn't all that important; a value of ``1 0.00 4890.00'' is suggested. 490.IP \(bu 491The rest of the file consists of zero or more element specifications. 492After the last element specification is a line containing the string ``-1''. 493.IP \(bu 494Lines longer than 127 characters are chopped to this limit. 495.SH ELEMENT SPECIFICATIONS 496.IP \(bu 497The first line of each element contains a single decimal number giving the 498type of the element 499.RI ( AED 500version) or its ASCII name 501.RI ( SUN / X11 502version). 503See Table 2. 504.sp 505.TS 506center, tab(@); 507css 508ccc 509nll. 510\fIgremlin\fP File Format \(mi Object Type Specification 511.sp 512\fIAED\fP Number@\fISUN\fP/\fIX11\fP Name@Description 5130@BOTLEFT@bottom-left-justified text 5141@BOTRIGHT@bottom-right-justified text 5152@CENTCENT@center-justified text 5163@VECTOR@vector 5174@ARC@arc 5185@CURVE@curve 5196@POLYGON@polygon 5207@BSPLINE@b-spline 5218@BEZIER@B\['e]zier 52210@TOPLEFT@top-left-justified text 52311@TOPCENT@top-center-justified text 52412@TOPRIGHT@top-right-justified text 52513@CENTLEFT@left-center-justified text 52614@CENTRIGHT@right-center-justified text 52715@BOTCENT@bottom-center-justified text 528.T& 529css. 530.sp 531Table 2. 532Type Specifications in \fIgremlin\fP Files 533.TE 534.sp 535.IP \(bu 536After the object type comes a variable number of lines, each specifying a 537point used to display the element. 538Each line contains an x-coordinate and a y-coordinate in floating point 539format, separated by spaces. 540The list of points is terminated by a line containing the string ``-1.0 541-1.0'' 542.RI ( AED 543version) or a single asterisk, ``*'' 544.RI ( SUN / X11 545version). 546.IP \(bu 547After the points comes a line containing two decimal values, giving the 548brush and size for the element. 549The brush determines the style in which things are drawn. 550For vectors, arcs, and curves there are six legal brush values: 551.sp 552.TS 553center, tab(@); 554ncw(0.1i)l. 5551 \(mi@@thin dotted lines 5562 \(mi@@thin dot-dashed lines 5573 \(mi@@thick solid lines 5584 \(mi@@thin dashed lines 5595 \(mi@@thin solid lines 5606 \(mi@@medium solid lines 561.TE 562.sp 563For polygons, one more value, 0, is legal. 564It specifies a polygon with an invisible border. 565For text, the brush selects a font as follows: 566.sp 567.TS 568center, tab(@); 569ncw(0.1i)l. 5701 \(mi@@roman (R font in groff) 5712 \(mi@@italics (I font in groff) 5723 \(mi@@bold (B font in groff) 5734 \(mi@@special (S font in groff) 574.TE 575.sp 576If you're using 577.I @g@grn 578to run your pictures through 579.IR groff , 580the font is really just a starting font: 581The text string can contain formatting sequences like 582``\efI'' 583or 584``\ed'' 585which may change the font (as well as do many other things). 586For text, the size field is a decimal value between 1 and 4. 587It selects the size of the font in which the text will be drawn. 588For polygons, this size field is interpreted as a stipple number to fill the 589polygon with. 590The number is used to index into a stipple font at print time. 591.IP \(bu 592The last line of each element contains a decimal number and a string of 593characters, separated by a single space. 594The number is a count of the number of characters in the string. 595This information is only used for text elements, and contains the text 596string. 597There can be spaces inside the text. 598For arcs, curves, and vectors, this line of the element contains the string 599``0''. 600.SH NOTES ON COORDINATES 601.I gremlin 602was designed for 603.IR AED s, 604and its coordinates reflect the 605.I AED 606coordinate space. 607For vertical pictures, x-values range 116 to 511, and y-values from 0 to 608483. 609For horizontal pictures, x-values range from 0 to 511 and y-values range 610from 0 to 367. 611Although you needn't absolutely stick to this range, you'll get best results 612if you at least stay in this vicinity. 613Also, point lists are terminated by a point of (-1, -1), so you shouldn't 614ever use negative coordinates. 615.I gremlin 616writes out coordinates using format ``%f1.2''; it's probably a good idea to 617use the same format if you want to modify the 618.I @g@grn 619code. 620.SH NOTES ON SUN/X11 COORDINATES 621There is no longer a restriction on the range of coordinates used to create 622objects in the 623.IR SUN / X11 624version of 625.IR gremlin . 626However, files with negative coordinates 627.B will 628cause problems if displayed on the 629.IR AED . 630.SH FILES 631.Tp \w'@FONTDIR@/devname/DESC'u+3n 632.BI @FONTDIR@/dev name /DESC 633Device description file for device 634.IR name . 635.SH SEE ALSO 636.BR gremlin (1), 637.BR groff (@MAN1EXT@), 638.BR @g@pic (@MAN1EXT@), 639.BR ideal (1) 640.SH HISTORY 641.PP 642David Slattengren and Barry Roitblat wrote the original Berkeley 643.IR @g@grn . 644.PP 645Daniel Senderowicz and Werner Lemberg modified it for 646.IR groff . 647. 648.cp \n[grn_C] 649. 650.\" Local Variables: 651.\" mode: nroff 652.\" End: