src/preproc/grn/grn.1.man

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