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

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