contrib/groff/src/preproc/grn/grn.man

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