man/groff_out.5.man

   1 '\" e
   2 .TH GROFF_OUT @MAN5EXT@ "@MDATE@" "groff @VERSION@"
   3 .SH NAME
   4 groff_out \- groff intermediate output format
   5 .
   6 .\" groff_out(5):
   7 .\" Source file position: <groff_source>/man/groff_out.man
   8 .\" Installed position: <prefix>/share/man/man5/groff_out.5
   9 .
  10 .
  11 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
  12 .do nr groff_out_C \n[.C]
  13 .cp 0
  14 .
  15 .
  16 .\" ====================================================================
  17 .\" Legal Terms
  18 .\" ====================================================================
  19 .\"
  20 .\" Copyright (C) 1989-2018 Free Software Foundation, Inc.
  21 .\"
  22 .\" This file is part of groff, the GNU roff type-setting system.
  23 .\"
  24 .\" Permission is granted to copy, distribute and/or modify this
  25 .\" document under the terms of the GNU Free Documentation License,
  26 .\" Version 1.3 or any later version published by the Free Software
  27 .\" Foundation; with no Invariant Sections, with no Front-Cover Texts,
  28 .\" and with no Back-Cover Texts.
  29 .\"
  30 .\" A copy of the Free Documentation License is included as a file
  31 .\" called FDL in the main directory of the groff source package.
  32 .
  33 .
  34 .\" ====================================================================
  35 .\" Setup
  36 .\" ====================================================================
  37 .
  38 .\" ================= Document configuration
  39 .
  40 .\" Number register to decide whether the commands '{' and '}' are used
  41 .\" 0: disable (actual default); 1: enable
  42 .nr @USE_ENV_STACK 0
  43 .
  44 .ig
  45 Unfortunately, old versions of groff used an illogical position change
  46 after some D\~commands (Dp, DP, Dt).  If the number register
  47 @STUPID_DRAWING_POSITIONING is 1 (actual default) then change position
  48 after these commands, otherwise the position is not changed.
  49 ..
  50 .nr @STUPID_DRAWING_POSITIONING 1
  51 .
  52 .\" ================= Semantical definitions
  53 .
  54 .nr @maxcolor 65536
  55 .ds @backslash \[rs]\"
  56 .ds @linebreak \fR\[la]line-break\[ra]\fP\"
  57 .
  58 .\" Begin of macro definitions
  59 .
  60 .de offset
  61 .RI ( \,\\$1\/ ,\  \,\\$2\/ )\\$3
  62 ..
  63 .de indexed_offset
  64 .offset \fI\\$1\/\fP\d\s-3\\$2\s+3\u\x'\n[.v]/4' \fI\\$3\/\fP\
  65 \d\s-3\\$4\s+3\u\x'\n[.v]/4' \\$5\x'\n[.v]/4'
  66 ..
  67 .\" format: .command <name> "<arguments>" <punctuation>
  68 .de command
  69 \fB\\$1\fP\ \fI\,\\$2\/\fP\\$3
  70 ..
  71 .\" format: .D-command <subcommand> "<arguments>"
  72 .de D-command
  73 \fBD\\$1\fP\ \fI\,\\$2\/\fP\|\*[@linebreak]
  74 ..
  75 .
  76 .\" We set these as troff micromotions rather than eqn because \d and \u
  77 .\" can be lifted to XML subscript/superscript tags.  Don't change
  78 .\" these to a parameterized string, man2html won't handle that.
  79 .ds hv1 \fIh\d\s-3\&1\s+3\u\~v\d\s-3\&1\s+3\u\fP\x'\n[.v]/4'
  80 .ds hv2 \fIh\d\s-3\&2\s+3\u\~v\d\s-3\&2\s+3\u\fP\x'\n[.v]/4'
  81 .ds hvn \fIh\d\s-3\&n\s+3\u\~v\d\s-3\&n\s+3\u\fP\x'\n[.v]/4'
  82 .
  83 .de Da-command
  84 \fBDa\fP\ \*[hv1] \*[hv2]\|\*[@linebreak]
  85 ..
  86 .\" graphics command .D with a variable number of arguments
  87 .\" format: .D-multiarg <subcommand>
  88 .de D-multiarg
  89 \fBD\\$1\fP\ \*[hv1] \*[hv2] .\|.\|. \*[hvn]\|\*[@linebreak]
  90 ..
  91 .\" format: .x-command <subname> "<arguments>"
  92 .de x-command
  93 \fBx\\$1\fP\ \fI\\$2\fP\|\*[@linebreak]
  94 ..
  95 .de xsub
  96 .RI "(" "\\$1" " control command)"
  97 .br
  98 ..
  99 .\" End of macro definitions
 100 .
 101 .
 102 .\" ====================================================================
 103 .SH DESCRIPTION
 104 .\" ====================================================================
 105 .
 106 This manual page describes the
 107 .I intermediate output
 108 format of the GNU
 109 .BR roff (@MAN7EXT@)
 110 text processing system
 111 .BR groff (@MAN1EXT@).
 112 .
 113 This output is produced by a run of the GNU
 114 .BR @g@troff (@MAN1EXT@)
 115 program.
 116 .
 117 It contains already all device-specific information, but it is not yet
 118 fed into a device postprocessor program.
 119 .
 120 .
 121 .P
 122 As the GNU
 123 .I roff
 124 processor
 125 .BR groff (@MAN1EXT@)
 126 is a wrapper program around
 127 .B @g@troff
 128 that automatically calls a
 129 postprocessor, this output does not show up normally.
 130 .
 131 This is why it is called
 132 .I intermediate
 133 within the
 134 .I groff
 135 .IR system .
 136 .
 137 The
 138 .B groff
 139 program provides the option
 140 .B \-Z
 141 to inhibit postprocessing, such that the produced
 142 .I intermediate output
 143 is sent to standard output just like calling
 144 .B @g@troff
 145 manually.
 146 .
 147 .
 148 .P
 149 In this document, the term
 150 .I @g@troff output
 151 describes what is output by the GNU
 152 .B @g@troff
 153 program, while
 154 .I intermediate output
 155 refers to the language that is accepted by the parser that prepares
 156 this output for the postprocessors.
 157 .
 158 This parser is smarter on whitespace and implements obsolete elements
 159 for compatibility, otherwise both formats are the same.
 160 .
 161 Both formats can be viewed directly with
 162 .BR \%gxditview (@MAN1EXT@).
 163 .
 164 .
 165 .P
 166 The main purpose of the
 167 .I intermediate output
 168 concept is to facilitate the development of postprocessors by
 169 providing a common programming interface for all devices.
 170 .
 171 It has a language of its own that is completely different from the
 172 .BR groff (@MAN7EXT@)
 173 language.
 174 .
 175 While the
 176 .I groff
 177 language is a high-level programming language for text processing, the
 178 .I intermediate output
 179 language is a kind of low-level assembler language by specifying all
 180 positions on the page for writing and drawing.
 181 .
 182 .
 183 .P
 184 The
 185 .RI pre- groff
 186 .I roff
 187 versions are denoted as
 188 .I classical
 189 .IR troff .
 190 The
 191 .I intermediate output
 192 produced by
 193 .B groff
 194 is fairly readable, while
 195 .I classical troff
 196 output was hard to understand because of strange habits that are
 197 still supported, but not used any longer by
 198 .I GNU
 199 .IR @g@troff .
 200 .
 201 .
 202 .\" ====================================================================
 203 .SH "LANGUAGE CONCEPTS"
 204 .\" ====================================================================
 205 .
 206 During the run of
 207 .BR @g@troff ,
 208 the
 209 .I roff
 210 input is cracked down to the information on what has to be printed at
 211 what position on the intended device.
 212 .
 213 So the language of the
 214 .I intermediate output
 215 format can be quite small.
 216 .
 217 Its only elements are commands with or without arguments.
 218 .
 219 In this document, the term \[lq]command\[rq] always refers to the
 220 .I intermediate output
 221 language, never to the
 222 .I roff
 223 language used for document formatting.
 224 .
 225 There are commands for positioning and text writing, for drawing, and
 226 for device controlling.
 227 .
 228 .
 229 .\" ====================================================================
 230 .SS "Separation"
 231 .\" ====================================================================
 232 .
 233 .I Classical troff output
 234 had strange requirements on whitespace.
 235 .
 236 The
 237 .B groff
 238 output parser, however, is smart about whitespace by making it
 239 maximally optional.
 240 .
 241 The whitespace characters, i.e., the
 242 .IR tab ,
 243 .IR space ,
 244 and
 245 .I newline
 246 characters, always have a syntactical meaning.
 247 .
 248 They are never printable because spacing within the output is always
 249 done by positioning commands.
 250 .
 251 .
 252 .P
 253 Any sequence of
 254 .I space
 255 or
 256 .I tab
 257 characters is treated as a single
 258 .I syntactical
 259 .IR space .
 260 .
 261 It separates commands and arguments, but is only required when there
 262 would occur a clashing between the command code and the arguments
 263 without the space.
 264 .
 265 Most often, this happens when variable length command names,
 266 arguments, argument lists, or command clusters meet.
 267 .
 268 Commands and arguments with a known, fixed length need not be
 269 separated by
 270 .I syntactical
 271 .IR space .
 272 .
 273 .
 274 .P
 275 A line break is a syntactical element, too.
 276 .
 277 Every command argument can be followed by whitespace, a comment, or a
 278 newline character.
 279 .
 280 Thus a
 281 .I syntactical line break
 282 is defined to consist of optional
 283 .I syntactical space
 284 that is optionally followed by a comment, and a newline character.
 285 .
 286 .
 287 .P
 288 The normal commands, those for positioning and text, consist of a
 289 single letter taking a fixed number of arguments.
 290 .
 291 For historical reasons, the parser allows stacking of such commands on
 292 the same line, but fortunately, in
 293 .I groff intermediate
 294 .IR output ,
 295 every command with at least one argument is followed by a line break,
 296 thus providing excellent readability.
 297 .
 298 .P
 299 The other commands \[em] those for drawing and device controlling \[em]
 300 have a more complicated structure; some recognize long command names,
 301 and some take a variable number of arguments.
 302 .
 303 So all
 304 .B D
 305 and
 306 .B x
 307 commands were designed to request a
 308 .I syntactical line break
 309 after their last argument.
 310 .
 311 Only one command,
 312 .RB \[oq] x\ X \[cq]
 313 has an argument that can stretch over several lines, all other
 314 commands must have all of their arguments on the same line as the
 315 command, i.e., the arguments may not be split by a line break.
 316 .
 317 .P
 318 Empty lines, i.e., lines containing only space and/or a comment, can
 319 occur everywhere.
 320 .
 321 They are just ignored.
 322 .
 323 .
 324 .\" ====================================================================
 325 .SS "Argument Units"
 326 .\" ====================================================================
 327 .
 328 Some commands take integer arguments that are assumed to represent
 329 values in a measurement unit, but the letter for the corresponding
 330 .I scale indicator
 331 is not written with the output command arguments;
 332 see
 333 .BR groff (@MAN7EXT@)
 334 and
 335 .IR "Groff: The GNU Implementation of troff" ,
 336 the
 337 .I groff
 338 Texinfo manual,
 339 for more on this topic.
 340 .
 341 Most commands assume the scale indicator\~\c
 342 .BR u ,
 343 the basic unit of the device, some use\~\c
 344 .BR z ,
 345 the
 346 .I scaled point unit
 347 of the device, while others, such as the color commands expect plain
 348 integers.
 349 .
 350 Note that these scale indicators are relative to the chosen device.
 351 .
 352 They are defined by the parameters specified in the device's
 353 .I DESC
 354 file; see
 355 .BR groff_font (@MAN5EXT@).
 356 .
 357 .
 358 .P
 359 Note that single characters can have the eighth bit set, as can the
 360 names of fonts and special characters (this is, glyphs).
 361 .
 362 The names of glyphs and fonts can be of arbitrary length.
 363 .
 364 A glyph that is to be printed will always be in the current font.
 365 .
 366 .
 367 .P
 368 A string argument is always terminated by the next whitespace
 369 character (space, tab, or newline); an embedded
 370 .B #
 371 character is regarded as part of the argument, not as the beginning of
 372 a comment command.
 373 .
 374 An integer argument is already terminated by the next non-digit
 375 character, which then is regarded as the first character of the next
 376 argument or command.
 377 .
 378 .
 379 .\" ====================================================================
 380 .SS "Document Parts"
 381 .\" ====================================================================
 382 A correct
 383 .I intermediate output
 384 document consists of two parts, the
 385 .I prologue
 386 and the
 387 .IR body .
 388 .
 389 .P
 390 The task of the
 391 .I prologue
 392 is to set the general device parameters using three exactly specified
 393 commands.
 394 .
 395 The
 396 .I groff prologue
 397 is guaranteed to consist of the following three lines (in that order):
 398 .RS
 399 .P
 400 .B x\ T
 401 .I device
 402 .br
 403 .B x\ res
 404 .I n\ h\ v
 405 .br
 406 .B x init
 407 .RE
 408 .P
 409 with the arguments set as outlined in subsection \[lq]Device Control
 410 Commands\[rq] below.
 411 .
 412 However, the parser for the
 413 .I intermediate output
 414 format is able to swallow additional whitespace and comments as well.
 415 .
 416 .
 417 .P
 418 The
 419 .I body
 420 is the main section for processing the document data.
 421 .
 422 Syntactically, it is a sequence of any commands different from the
 423 ones used in the
 424 .IR prologue .
 425 .
 426 Processing is terminated as soon as the first
 427 .B x\ stop
 428 command is encountered; the last line of any
 429 .I groff intermediate output
 430 always contains such a command.
 431 .
 432 .
 433 .P
 434 Semantically, the
 435 .I body
 436 is page oriented.
 437 .
 438 A new page is started by a
 439 .BR p \~command.
 440 .
 441 Positioning, writing, and drawing commands are always done within the
 442 current page, so they cannot occur before the first
 443 .BR p \~command.
 444 .
 445 Absolute positioning (by the
 446 .B H
 447 and
 448 .BR V \~commands)
 449 is done relative to the current page, all other positioning
 450 is done relative to the current location within this page.
 451 .
 452 .
 453 .\" ====================================================================
 454 .SH "COMMAND REFERENCE"
 455 .\" ====================================================================
 456 .
 457 This section describes all
 458 .I intermediate output
 459 commands, the classical commands as well as the
 460 .I groff
 461 extensions.
 462 .
 463 .
 464 .\" ====================================================================
 465 .SS "Comment Command"
 466 .\" ====================================================================
 467 .
 468 .TP
 469 .BI # anything \[la]end-of-line\[ra]
 470 A comment.
 471 .
 472 Ignore any characters from the
 473 .BR # \~\c
 474 character up to the next newline character.
 475 .
 476 .P
 477 This command is the only possibility for commenting in the
 478 .I intermediate
 479 .IR output .
 480 .
 481 Each comment can be preceded by arbitrary
 482 .I syntactical
 483 .IR space ;
 484 every command can be terminated by a comment.
 485 .
 486 .
 487 .\" ====================================================================
 488 .SS "Simple Commands"
 489 .\" ====================================================================
 490 .
 491 The commands in this subsection have a command code consisting of a
 492 single character, taking a fixed number of arguments.
 493 .
 494 Most of them are commands for positioning and text writing.
 495 .
 496 These commands are smart about whitespace.
 497 .
 498 Optionally,
 499 .I syntactical space
 500 can be inserted before, after, and between the command letter and its
 501 arguments.
 502 .
 503 All of these commands are stackable, i.e., they can be preceded by
 504 other simple commands or followed by arbitrary other commands on the
 505 same line.
 506 .
 507 A separating
 508 .I syntactical space
 509 is only necessary when two integer arguments would clash or if the
 510 preceding argument ends with a string argument.
 511 .
 512 .
 513 .if \n[@USE_ENV_STACK]=1 \{\
 514 .TP
 515 .command {
 516 Open a new environment by copying the actual device configuration data
 517 to the environment stack.
 518 .
 519 The current environment is setup by the device specification and
 520 manipulated by the setting commands.
 521 .
 522 .
 523 .TP
 524 .command }
 525 Close the actual environment (opened by a preceding
 526 .BR { \~command)
 527 and restore the previous environment from the environment
 528 stack as the actual device configuration data.
 529 .
 530 .\}              \" endif @USE_ENV_STACK
 531 .
 532 .
 533 .TP
 534 .command C xxx \[la]white-space\[ra]
 535 Print a glyph (special character) named
 536 .IR xxx .
 537 .
 538 The trailing
 539 .I syntactical space
 540 or
 541 .I line break
 542 is necessary to allow glyph names of arbitrary length.
 543 .
 544 The glyph is printed at the current print position; the
 545 glyph's size is read from the font file.
 546 .
 547 The print position is not changed.
 548 .
 549 .
 550 .TP
 551 .command c c
 552 Print glyph with single-letter name\~\c
 553 .I c
 554 at the current print position;
 555 the glyph's size is read from the font file.
 556 .
 557 The print position is not changed.
 558 .
 559 .
 560 .TP
 561 .command f n
 562 Set font to font number\~\c
 563 .I n
 564 (a non-negative integer).
 565 .
 566 .
 567 .TP
 568 .command H n
 569 Move right to the absolute vertical position\~\c
 570 .I n
 571 (a non-negative integer in basic units\~\c
 572 .BR u )
 573 relative to left edge of current page.
 574 .
 575 .
 576 .TP
 577 .command h n
 578 Move
 579 .I n
 580 (a non-negative integer) basic units\~\c
 581 .B u
 582 horizontally to the right.
 583 .
 584 [CSTR\~#54]
 585 allows negative values for
 586 .I n
 587 also, but
 588 .I groff
 589 doesn't use this.
 590 .
 591 .
 592 .TP
 593 .command m "color-scheme \fR[\fPcomponent .\|.\|.\fR]\fP"
 594 Set the color for text (glyphs), line drawing, and the outline of
 595 graphic objects using different color schemes; the analogous command
 596 for the filling color of graphic objects is
 597 .BR DF .
 598 .
 599 The color components are specified as integer arguments between 0 and
 600 \n[@maxcolor].
 601 .
 602 The number of color components and their meaning vary for the
 603 different color schemes.
 604 .
 605 These commands are generated by the
 606 .I groff
 607 escape sequence
 608 .BR \*[@backslash]m .
 609 .
 610 No position changing.
 611 .
 612 These commands are a
 613 .I groff
 614 extension.
 615 .
 616 .
 617 .RS
 618 .
 619 .TP
 620 .command mc "cyan magenta yellow"
 621 Set color using the CMY color scheme, having the 3\~color components
 622 cyan, magenta, and yellow.
 623 .
 624 .
 625 .TP
 626 .command md
 627 Set color to the default color value
 628 (black in most cases).
 629 .
 630 No component arguments.
 631 .
 632 .
 633 .TP
 634 .command mg "gray"
 635 Set color to the shade of gray given by the argument, an integer
 636 between 0 (black) and \n[@maxcolor] (white).
 637 .
 638 .
 639 .TP
 640 .command mk "cyan magenta yellow black"
 641 Set color using the CMYK color scheme, having the 4\~color components
 642 cyan, magenta, yellow, and black.
 643 .
 644 .TP
 645 .command mr "red green blue"
 646 Set color using the RGB color scheme, having the 3\~color components
 647 red, green, and blue.
 648 .
 649 .RE
 650 .
 651 .
 652 .TP
 653 .command N n
 654 Print glyph with index\~\c
 655 .I n
 656 (an integer, normally non-negative) of the current font.
 657 .
 658 The print position is not changed.
 659 .
 660 If
 661 .B \-T\~html
 662 or
 663 .B \-T\~xhtml
 664 is used, negative values are emitted also to indicate an unbreakable
 665 space with given width.
 666 .
 667 For example,
 668 .B N\~\-193
 669 represents an unbreakable space which has a width of 193\|u.
 670 .
 671 This command is a
 672 .I groff
 673 extension.
 674 .
 675 .
 676 .TP
 677 .command n b\ a
 678 Inform the device about a line break, but no positioning is done by
 679 this command.
 680 .
 681 In
 682 .I classical
 683 .IR troff ,
 684 the integer arguments
 685 .I b
 686 and\~\c
 687 .I a
 688 informed about the space before and after the current line to
 689 make the
 690 .I intermediate output
 691 more human readable without performing any action.
 692 .
 693 In
 694 .IR groff ,
 695 they are just ignored, but they must be provided for compatibility
 696 reasons.
 697 .
 698 .
 699 .TP
 700 .command p n
 701 Begin a new page in the outprint.
 702 .
 703 The page number is set to\~\c
 704 .IR n .
 705 .
 706 This page is completely independent of pages formerly processed even
 707 if those have the same page number.
 708 .
 709 The vertical position on the outprint is automatically set to\~0.
 710 .
 711 All positioning, writing, and drawing is always done relative to a
 712 page, so a
 713 .BR p \~command
 714 must be issued before any of these commands.
 715 .
 716 .
 717 .TP
 718 .command s n
 719 Set point size to
 720 .I n
 721 scaled points
 722 (this is unit\~\c
 723 .B z
 724 in GNU
 725 .BR @g@troff ).
 726 .
 727 .I Classical troff
 728 used the unit
 729 .I points
 730 (\c
 731 .BR p )
 732 instead;
 733 see section \[lq]Compatibility\[rq] below.
 734 .
 735 .
 736 .TP
 737 .command t xyz\|.\|.\|. \[la]white-space\[ra]
 738 .TQ
 739 .command t "xyz\|.\|.\|.\& dummy-arg" \[la]white-space\[ra]
 740 Print a word, i.e., a sequence of glyphs with single-letter names
 741 .IR x ,
 742 .IR y ,
 743 .IR z ,
 744 etc., terminated by a space character or a line break; an optional
 745 second integer argument is ignored (this allows the formatter to
 746 generate an even number of arguments).
 747 .
 748 The first glyph should be printed at the current position, the
 749 current horizontal position should then be increased by the width of
 750 the first glyph, and so on for each glyph.
 751 .
 752 The widths of the glyph are read from the font file, scaled for the
 753 current point size, and rounded to a multiple of the horizontal
 754 resolution.
 755 .
 756 Special characters (glyphs with names longer than a single letter)
 757 cannot be printed using this command; use the
 758 .B C
 759 command for those glyphs.
 760 .
 761 This command is a
 762 .I groff
 763 extension; it is only used for devices whose
 764 .I DESC
 765 file contains the
 766 .B tcommand
 767 keyword; see
 768 .BR groff_font (@MAN5EXT@).
 769 .
 770 .
 771 .TP
 772 .command u "n xyz\|.\|.\|." \[la]white-space\[ra]
 773 Print word with track kerning.
 774 .
 775 This is the same as the
 776 .B t
 777 command except that after printing each glyph, the current
 778 horizontal position is increased by the sum of the width of that
 779 glyph and\~\c
 780 .I n
 781 (an integer in
 782 basic units\~\c
 783 .BR u ).
 784 This command is a
 785 .I groff
 786 extension; it is only used for devices whose
 787 .I DESC
 788 file contains the
 789 .B tcommand
 790 keyword; see
 791 .BR groff_font (@MAN5EXT@).
 792 .
 793 .
 794 .TP
 795 .command V n
 796 Move down to the absolute vertical position\~\c
 797 .I n
 798 (a non-negative integer in basic units\~\c
 799 .BR u )
 800 relative to upper edge of current page.
 801 .
 802 .
 803 .TP
 804 .command v n
 805 Move
 806 .I n
 807 basic units\~\c
 808 .B u
 809 down
 810 .RI ( n
 811 is a non-negative integer).
 812 .
 813 [CSTR\~#54]
 814 allows negative values for
 815 .I n
 816 also, but
 817 .I groff
 818 doesn't use this.
 819 .
 820 .
 821 .TP
 822 .command w
 823 Informs about a paddable whitespace to increase readability.
 824 .
 825 The spacing itself must be performed explicitly by a move command.
 826 .
 827 .
 828 .\" ====================================================================
 829 .SS "Graphics Commands"
 830 .\" ====================================================================
 831 .
 832 Each graphics or drawing command in the
 833 .I intermediate output
 834 starts with the letter\~\c
 835 .B D
 836 followed by one or two characters that specify a subcommand; this
 837 is followed by a fixed or variable number of integer arguments that
 838 are separated by a single space character.
 839 .
 840 A
 841 .BR D \~command
 842 may not be followed by another command on the same line (apart from a
 843 comment), so each
 844 .BR D \~command
 845 is terminated by a
 846 .I syntactical line
 847 .IR break .
 848 .
 849 .
 850 .P
 851 .B @g@troff
 852 output follows the classical spacing rules (no space between command
 853 and subcommand, all arguments are preceded by a single space
 854 character), but the parser allows optional space between the command
 855 letters and makes the space before the first argument optional.
 856 .
 857 As usual, each space can be any sequence of tab and space characters.
 858 .
 859 .
 860 .P
 861 Some graphics commands can take a variable number of arguments.
 862 .
 863 In this case, they are integers representing a size measured in basic
 864 units\~\c
 865 .BR u .
 866 .
 867 The
 868 .I h
 869 arguments
 870 stand for horizontal distances where positive means right, negative
 871 left.
 872 .
 873 The
 874 .I v
 875 arguments
 876 stand for vertical distances where positive means down, negative up.
 877 .
 878 All these distances are offsets relative to the current location.
 879 .
 880 .
 881 .P
 882 Unless indicated otherwise, each graphics command directly corresponds
 883 to a similar
 884 .I groff
 885 .B \*[@backslash]D
 886 escape sequence; see
 887 .BR groff (@MAN7EXT@).
 888 .
 889 .
 890 .P
 891 Unknown
 892 .BR D \~commands
 893 are assumed to be device-specific.
 894 .
 895 Its arguments are parsed as strings; the whole information is then
 896 sent to the postprocessor.
 897 .
 898 .
 899 .P
 900 In the following command reference, the syntax element
 901 .I \[la]line-break\[ra]
 902 means a
 903 .I syntactical line break
 904 as defined in subsection \[lq]Separation\[rq] above.
 905 .
 906 .
 907 .TP
 908 .D-multiarg \[ti]
 909 Draw B-spline from current position to offset
 910 .indexed_offset h 1 v 1 ,
 911 then to offset
 912 .indexed_offset h 2 v 2
 913 if given, etc., up to
 914 .indexed_offset h n v n .
 915 This command takes a variable number of argument pairs; the current
 916 position is moved to the terminal point of the drawn curve.
 917 .
 918 .
 919 .TP
 920 .Da-command
 921 Draw arc from current position to
 922 .indexed_offset h 1 v 1 \|+\|\c
 923 .indexed_offset h 2 v 2
 924 with center at
 925 .indexed_offset h 1 v 1 ;
 926 then move the current position to the final point of the arc.
 927 .
 928 .
 929 .TP
 930 .D-command C d
 931 .TQ
 932 .D-command C "d dummy-arg"
 933 Draw a solid circle using the current fill color with diameter\~\c
 934 .I d
 935 (integer in basic units\~\c
 936 .BR u )
 937 with leftmost point at the current position; then move the current
 938 position to the rightmost point of the circle.
 939 .
 940 An optional second integer argument is ignored (this allows the
 941 formatter to generate an even number of arguments).
 942 .
 943 This command is a
 944 .I groff
 945 extension.
 946 .
 947 .
 948 .TP
 949 .D-command c d
 950 Draw circle line with diameter\~\c
 951 .I d
 952 (integer in basic units\~\c
 953 .BR u )
 954 with leftmost point at the current position; then move the current
 955 position to the rightmost point of the circle.
 956 .
 957 .
 958 .TP
 959 .D-command E "h v"
 960 Draw a solid ellipse in the current fill color with a horizontal
 961 diameter of\~\c
 962 .I h
 963 and a vertical diameter of\~\c
 964 .I v
 965 (both integers in basic units\~\c
 966 .BR u )
 967 with the leftmost point at the current position; then move to the
 968 rightmost point of the ellipse.
 969 .
 970 This command is a
 971 .I groff
 972 extension.
 973 .
 974 .
 975 .TP
 976 .D-command e "h v"
 977 Draw an outlined ellipse with a horizontal diameter of\~\c
 978 .I h
 979 and a vertical diameter of\~\c
 980 .I v
 981 (both integers in basic units\~\c
 982 .BR u )
 983 with the leftmost point at current position; then move to the
 984 rightmost point of the ellipse.
 985 .
 986 .
 987 .TP
 988 .D-command F "color-scheme \fR[\fPcomponent .\|.\|.\fR]\fP"
 989 Set fill color for solid drawing objects using different color
 990 schemes; the analogous command for setting the color of text, line
 991 graphics, and the outline of graphic objects is
 992 .BR m .
 993 .
 994 The color components are specified as integer arguments between 0 and
 995 \n[@maxcolor].
 996 .
 997 The number of color components and their meaning vary for the
 998 different color schemes.
 999 .
1000 These commands are generated by the
1001 .I groff
1002 escape sequences
1003 .BR \*[@backslash]D'F\  .\|.\|. '
1004 and
1005 .B \*[@backslash]M
1006 (with no other corresponding graphics commands).
1007 .
1008 No position changing.
1009 .
1010 This command is a
1011 .I groff
1012 extension.
1013 .
1014 .
1015 .RS
1016 .
1017 .TP
1018 .D-command Fc "cyan magenta yellow"
1019 Set fill color for solid drawing objects using the CMY color scheme,
1020 having the 3\~color components cyan, magenta, and yellow.
1021 .
1022 .
1023 .TP
1024 .D-command Fd
1025 Set fill color for solid drawing objects to the default fill color value
1026 (black in most cases).
1027 .
1028 No component arguments.
1029 .
1030 .
1031 .TP
1032 .D-command Fg "gray"
1033 Set fill color for solid drawing objects to the shade of gray given by
1034 the argument, an integer between 0 (black) and \n[@maxcolor] (white).
1035 .
1036 .
1037 .TP
1038 .D-command Fk "cyan magenta yellow black"
1039 Set fill color for solid drawing objects using the CMYK color scheme,
1040 having the 4\~color components cyan, magenta, yellow, and black.
1041 .
1042 .TP
1043 .D-command Fr "red green blue"
1044 Set fill color for solid drawing objects using the RGB color scheme,
1045 having the 3\~color components red, green, and blue.
1046 .
1047 .RE
1048 .
1049 .
1050 .TP
1051 .D-command f n
1052 The argument
1053 .I n
1054 must be an integer in the range \-32767 to 32767.
1055 .
1056 .RS
1057 .TP
1058 .RI 0\|\[<=]\| n \|\[<=]\|1000
1059 Set the color for filling solid drawing objects to a shade of gray,
1060 where 0 corresponds to solid white, 1000 (the default) to solid black,
1061 and values in between to intermediate shades of gray; this is
1062 obsoleted by command
1063 .BR DFg .
1064 .
1065 .TP
1066 .IR n "\|<\|0 or " n \|>\|1000
1067 Set the filling color to the color that is currently being used for
1068 the text and the outline, see command
1069 .BR m .
1070 For example, the command sequence
1071 .
1072 .RS
1073 .IP
1074 .EX
1075 mg 0 0 \n[@maxcolor]
1076 Df \-1
1077 .EE
1078 .RE
1079 .
1080 .IP
1081 sets all colors to blue.
1082 .
1083 .P
1084 No position changing.
1085 .
1086 This command is a
1087 .I groff
1088 extension.
1089 .
1090 .RE
1091 .
1092 .
1093 .TP
1094 .D-command l "h v"
1095 Draw line from current position to offset
1096 .offset h v
1097 (integers in basic units\~\c
1098 .BR u );
1099 then set current position to the end of the drawn line.
1100 .
1101 .
1102 .TP
1103 .D-multiarg p
1104 Draw a polygon line from current position to offset
1105 .indexed_offset h 1 v 1 ,
1106 from there to offset
1107 .indexed_offset h 2 v 2 ,
1108 etc., up to offset
1109 .indexed_offset h n v n ,
1110 and from there back to the starting position.
1111 .
1112 .ie \n[@STUPID_DRAWING_POSITIONING]=1 \{\
1113 For historical reasons, the position is changed by adding the sum of
1114 all arguments with odd index to the actual horizontal position and the
1115 even ones to the vertical position.
1116 .
1117 Although this doesn't make sense it is kept for compatibility.
1118 .
1119 .\}
1120 .el \{\
1121 As the polygon is closed, the end of drawing is the starting point, so
1122 the position doesn't change.
1123 .\}
1124 .
1125 This command is a
1126 .I groff
1127 extension.
1128 .
1129 .
1130 .TP
1131 .D-multiarg P
1132 The same macro as the corresponding
1133 .B Dp
1134 command with the same arguments, but draws a solid polygon in the
1135 current fill color rather than an outlined polygon.
1136 .
1137 .ie \n[@STUPID_DRAWING_POSITIONING]=1 \{\
1138 The position is changed in the same way as with
1139 .BR Dp .
1140 .\}
1141 .el \
1142 No position changing.
1143 .
1144 This command is a
1145 .I groff
1146 extension.
1147 .
1148 .
1149 .TP
1150 .D-command t n
1151 Set the current line thickness to\~\c
1152 .I n
1153 (an integer in basic units\~\c
1154 .BR u )
1155 if
1156 .IR n \|>\|0;
1157 if
1158 .IR n \|=\|0
1159 select the smallest available line thickness; if
1160 .IR n \|<\|0
1161 set the line thickness proportional to the point size (this is the
1162 default before the first
1163 .B Dt
1164 command was specified).
1165 .
1166 .ie \n[@STUPID_DRAWING_POSITIONING]=1 \{\
1167 For historical reasons, the horizontal position is changed by adding
1168 the argument to the actual horizontal position, while the vertical
1169 position is not changed.
1170 .
1171 Although this doesn't make sense it is kept for compatibility.
1172 .
1173 .\}
1174 .el \
1175 No position changing.
1176 .
1177 This command is a
1178 .I groff
1179 extension.
1180 .
1181 .
1182 .\" ====================================================================
1183 .SS "Device Control Commands"
1184 .\" ====================================================================
1185 .
1186 Each device control command starts with the letter
1187 .B x
1188 followed by a space character (optional or arbitrary space/\:tab in
1189 .IR groff )
1190 and a subcommand letter or word; each argument (if any) must be
1191 preceded by a
1192 .I syntactical
1193 .IR space .
1194 .
1195 All
1196 .B x
1197 commands are terminated by a
1198 .IR "syntactical line break" ;
1199 no device control command can be followed by another command on the same
1200 line (except a comment).
1201 .
1202 .P
1203 The subcommand is basically a single letter, but to increase
1204 readability, it can be written as a word, i.e., an arbitrary sequence
1205 of characters terminated by the next tab, space, or newline character.
1206 .
1207 All characters of the subcommand word but the first are simply ignored.
1208 .
1209 For example,
1210 .B @g@troff
1211 outputs the initialization command
1212 .B x\ i
1213 as
1214 .B x\ init
1215 and the resolution command
1216 .B x\ r
1217 as
1218 .BR "x\ res" .
1219 .
1220 But writings like
1221 .B x\ i_like_groff
1222 and
1223 .B x\ roff_is_groff
1224 are accepted as well to mean the same commands.
1225 .
1226 .P
1227 In the following, the syntax element
1228 .I \[la]line-break\[ra]
1229 means a
1230 .I syntactical line break
1231 as defined in subsection \[lq]Separation\[rq] above.
1232 .
1233 .TP
1234 .x-command F name
1235 .xsub Filename
1236 Use
1237 .I name
1238 as the intended name for the current file in error reports.
1239 .
1240 This is useful for remembering the original file name when
1241 .B groff
1242 uses an internal piping mechanism.
1243 .
1244 The input file is not changed by this command.
1245 .
1246 This command is a
1247 .I groff
1248 extension.
1249 .
1250 .
1251 .TP
1252 .x-command f "n\ s"
1253 .xsub font
1254 Mount font position\~\c
1255 .I n
1256 (a non-negative integer) with font named\~\c
1257 .I s
1258 (a text word);
1259 see
1260 .BR groff_font (@MAN5EXT@).
1261 .
1262 .
1263 .TP
1264 .x-command H n
1265 .xsub Height
1266 Set character height to\~\c
1267 .I n
1268 (a positive integer in scaled points\~\c
1269 .BR z ).
1270 .
1271 .I Classical troff
1272 used the unit points (\c
1273 .BR p )
1274 instead;
1275 see section \[lq]Compatibility\[rq] below.
1276 .
1277 .
1278 .TP
1279 .x-command i
1280 .xsub init
1281 Initialize device.
1282 .
1283 This is the third command of the
1284 .IR prologue .
1285 .
1286 .
1287 .TP
1288 .x-command p
1289 .xsub pause
1290 Parsed but ignored.
1291 .
1292 The classical documentation reads
1293 .I pause device, can be
1294 .IR restarted .
1295 .
1296 .
1297 .TP
1298 .x-command r "n\ h\ v"
1299 .xsub resolution
1300 Resolution is\~\c
1301 .IR n ,
1302 while
1303 .I h
1304 is the minimal horizontal motion, and
1305 .I v
1306 the minimal vertical motion possible with this device; all arguments
1307 are positive integers in basic units\~\c
1308 .B u
1309 per inch.
1310 .
1311 This is the second command of the
1312 .IR prologue .
1313 .
1314 .
1315 .TP
1316 .x-command S n
1317 .xsub Slant
1318 Set slant to\~\c
1319 .I n
1320 degrees (an integer in basic units\~\c
1321 .BR u ).
1322 .
1323 .
1324 .TP
1325 .x-command s
1326 .xsub stop
1327 Terminates the processing of the current file; issued as the last
1328 command of any
1329 .I intermediate @g@troff
1330 .IR output .
1331 .
1332 .
1333 .TP
1334 .x-command t
1335 .xsub trailer
1336 Generate trailer information, if any.
1337 .
1338 In
1339 .BR groff ,
1340 this is actually just ignored.
1341 .
1342 .
1343 .TP
1344 .x-command T xxx
1345 .xsub Typesetter
1346 Set name of device to word
1347 .IR xxx ,
1348 a sequence of characters ended by the next whitespace character.
1349 .
1350 The possible device names coincide with those from the groff
1351 .B \-T
1352 option.
1353 .
1354 This is the first command of the
1355 .IR prologue .
1356 .
1357 .
1358 .TP
1359 .x-command u n
1360 .xsub underline
1361 Configure underlining of spaces.
1362 .
1363 If
1364 .I n
1365 is\~1, start underlining of spaces;
1366 if
1367 .I n
1368 is\~0, stop underlining of spaces.
1369 .
1370 This is needed for the
1371 .B cu
1372 request in
1373 .B @g@nroff
1374 mode and is ignored otherwise.
1375 .
1376 This command is a
1377 .I groff
1378 extension.
1379 .
1380 .
1381 .TP
1382 .x-command X anything
1383 .xsub X-escape
1384 Send string
1385 .I anything
1386 uninterpreted to the device.
1387 .
1388 If the line following this command starts with a
1389 .B +
1390 character this line is interpreted as a continuation line in the
1391 following sense.
1392 .
1393 The
1394 .B +
1395 is ignored, but a newline character is sent instead to the device, the
1396 rest of the line is sent uninterpreted.
1397 .
1398 The same applies to all following lines until the first character of a
1399 line is not a
1400 .B +
1401 character.
1402 .
1403 This command is generated by the
1404 .I groff
1405 escape sequence
1406 .BR \*[@backslash]X .
1407 .
1408 The line-continuing feature is a
1409 .I groff
1410 extension.
1411 .
1412 .
1413 .\" ====================================================================
1414 .SS "Obsolete Command"
1415 .\" ====================================================================
1416 .
1417 In
1418 .I classical troff
1419 output, emitting a single glyph was mostly done by a very
1420 strange command that combined a horizontal move and the printing of a
1421 glyph.
1422 .
1423 It didn't have a command code, but is represented by a 3-character
1424 argument consisting of exactly 2\~digits and a character.
1425 .
1426 .TP
1427 .I ddc
1428 Move right
1429 .I dd
1430 (exactly two decimal digits) basic units\~\c
1431 .BR u ,
1432 then print glyph with single-letter name\~\c
1433 .IR c .
1434 .
1435 .
1436 .RS
1437 .P
1438 In
1439 .IR groff ,
1440 arbitrary
1441 .I syntactical space
1442 around and within this command is allowed to be added.
1443 .
1444 Only when a preceding command on the same line ends with an argument
1445 of variable length a separating space is obligatory.
1446 .
1447 In
1448 .I classical
1449 .IR troff ,
1450 large clusters of these and other commands were used, mostly without
1451 spaces; this made such output almost unreadable.
1452 .
1453 .RE
1454 .
1455 .
1456 .P
1457 For modern high-resolution devices, this command does not make sense
1458 because the width of the glyphs can become much larger than two
1459 decimal digits.
1460 .
1461 In
1462 .BR groff ,
1463 this is only used for the devices
1464 .BR X75 ,
1465 .BR X75-12 ,
1466 .BR X100 ,
1467 and
1468 .BR X100-12 .
1469 .
1470 For other devices,
1471 the commands
1472 .B t
1473 and\~\c
1474 .B u
1475 provide a better functionality.
1476 .
1477 .
1478 .\" ====================================================================
1479 .SH "POSTPROCESSING"
1480 .\" ====================================================================
1481 .
1482 The
1483 .I roff
1484 postprocessors are programs that have the task to translate the
1485 .I intermediate output
1486 into actions that are sent to a device.
1487 .
1488 A device can be some piece of hardware such as a printer, or a software
1489 file format suitable for graphical or text processing.
1490 .
1491 The
1492 .I groff
1493 system provides powerful means that make the programming of such
1494 postprocessors an easy task.
1495 .P
1496 There is a library function that parses the
1497 .I intermediate output
1498 and sends the information obtained to the device via methods of a
1499 class with a common interface for each device.
1500 .
1501 So a
1502 .I groff
1503 postprocessor must only redefine the methods of this class.
1504 .
1505 For details,
1506 see the reference in section \[lq]Files\[rq] below.
1507 .
1508 .
1509 .\" ====================================================================
1510 .SH "EXAMPLES"
1511 .\" ====================================================================
1512 .
1513 This section presents the
1514 .I intermediate output
1515 generated from the same input for three different devices.
1516 .
1517 The input is the sentence
1518 .I hell world
1519 fed into
1520 .B groff
1521 on the command line.
1522 .
1523 .
1524 .IP \[bu] 2m
1525 High-resolution device
1526 .I ps
1527 .
1528 .
1529 .RS
1530 .P
1531 .EX
1532 \fBshell>\fP echo "hell world" | groff \-Z \-T ps
1533 .EE
1534 .
1535 .
1536 .P
1537 .nf
1538 .ft CB
1539 x T ps
1540 x res 72000 1 1
1541 x init
1542 p1
1543 x font 5 TR
1544 f5
1545 s10000
1546 V12000
1547 H72000
1548 thell
1549 wh2500
1550 tw
1551 H96620
1552 torld
1553 n12000 0
1554 x trailer
1555 V792000
1556 x stop
1557 .ft P
1558 .fi
1559 .RE
1560 .
1561 .
1562 .P
1563 This output can be fed into the postprocessor
1564 .BR grops (@MAN1EXT@)
1565 to get its representation as a PostScript file, or
1566 .BR gropdf (@MAN1EXT@)
1567 to output directly to PDF.
1568 .
1569 .
1570 .IP \[bu] 2m
1571 Low-resolution device
1572 .I latin1
1573 .
1574 .
1575 .RS
1576 .P
1577 This is similar to the high-resolution device except that the
1578 positioning is done at a minor scale.
1579 .
1580 Some comments (lines starting with
1581 .IR # )
1582 were added for clarification; they were not generated by the
1583 formatter.
1584 .
1585 .
1586 .P
1587 .EX
1588 \fBshell>\fP "hell world" | groff \-Z \-T latin1
1589 .EE
1590 .
1591 .
1592 .P
1593 .nf
1594 .I "# prologue"
1595 .ft CB
1596 x T latin1
1597 x res 240 24 40
1598 x init
1599 .I "# begin a new page"
1600 .ft CB
1601 p1
1602 .I "# font setup"
1603 .ft CB
1604 x font 1 R
1605 f1
1606 s10
1607 .I "# initial positioning on the page"
1608 .ft CB
1609 V40
1610 H0
1611 .I "# write text \[oq]hell\[cq]"
1612 .ft CB
1613 thell
1614 .I "# inform about a space, and do it by a horizontal jump"
1615 .ft CB
1616 wh24
1617 .I "# write text \[oq]world\[cq]"
1618 .ft CB
1619 tworld
1620 .I "# announce line break, but do nothing because ..."
1621 .ft CB
1622 n40 0
1623 .I "# ... the end of the document has been reached"
1624 .ft CB
1625 x trailer
1626 V2640
1627 x stop
1628 .ft P
1629 .fi
1630 .RE
1631 .
1632 .
1633 .P
1634 This output can be fed into the postprocessor
1635 .BR grotty (@MAN1EXT@)
1636 to get a formatted text document.
1637 .
1638 .
1639 .IP \[bu] 2m
1640 Classical style output
1641 .
1642 .
1643 .RS
1644 .P
1645 As a computer monitor has a very low resolution compared to modern
1646 printers the
1647 .I intermediate output
1648 for the X\~devices can use the jump-and-write command with its 2-digit
1649 displacements.
1650 .
1651 .
1652 .P
1653 .EX
1654 \fBshell>\fP "hell world" | groff \-Z \-T X100
1655 .EE
1656 .
1657 .
1658 .P
1659 .nf
1660 .ft CB
1661 x T X100
1662 x res 100 1 1
1663 x init
1664 p1
1665 x font 5 TR
1666 f5
1667 s10
1668 V16
1669 H100
1670 .I "# write text with old-style jump-and-write command"
1671 .ft CB
1672 ch07e07l03lw06w11o07r05l03dh7
1673 n16 0
1674 x trailer
1675 V1100
1676 x stop
1677 .ft P
1678 .fi
1679 .RE
1680 .
1681 .
1682 .P
1683 This output can be fed into the postprocessor
1684 .BR \%xditview (1x)
1685 or
1686 .BR \%gxditview (@MAN1EXT@)
1687 for displaying in\~X.
1688 .
1689 .
1690 .P
1691 Due to the obsolete jump-and-write command, the text clusters in the
1692 classical output are almost unreadable.
1693 .
1694 .
1695 .\" ====================================================================
1696 .SH "COMPATIBILITY"
1697 .\" ====================================================================
1698 .
1699 The
1700 .I intermediate output
1701 language of the
1702 .I classical troff
1703 was first documented in
1704 [CSTR\~#97] .
1705 .
1706 The
1707 .I groff intermediate output
1708 format is compatible with this specification except for the following
1709 features.
1710 .
1711 .
1712 .IP \[bu] 2m
1713 The classical quasi device independence is not yet implemented.
1714 .
1715 .
1716 .IP \[bu] 2m
1717 The old hardware was very different from what we use today.
1718 .
1719 So the
1720 .I groff
1721 devices are also fundamentally different from the ones in
1722 .I classical
1723 .IR troff .
1724 .
1725 For example, the classical PostScript device was called
1726 .I post
1727 and had a resolution of 720 units per inch,
1728 while
1729 .IR groff 's
1730 .I ps
1731 device has a resolution of 72000 units per inch.
1732 .
1733 Maybe, by implementing some rescaling mechanism similar to the
1734 classical quasi device independence, these could be integrated into
1735 modern
1736 .IR groff .
1737 .
1738 .
1739 .IP \[bu] 2m
1740 The B-spline command
1741 .B D\[ti]
1742 is correctly handled by the
1743 .I intermediate output
1744 parser, but the drawing routines aren't implemented in some of the
1745 postprocessor programs.
1746 .
1747 .
1748 .IP \[bu] 2m
1749 The argument of the commands
1750 .B s
1751 and
1752 .B x H
1753 has the implicit unit scaled point\~\c
1754 .B z
1755 in
1756 .IR groff ,
1757 while
1758 .I classical troff
1759 had point (\c
1760 .BR p ).
1761 .
1762 This isn't an incompatibility, but a compatible extension, for both
1763 units coincide for all devices without a
1764 .I sizescale
1765 parameter, including all classical and the
1766 .I groff
1767 text devices.
1768 .
1769 The few
1770 .I groff
1771 devices with a sizescale parameter either did not exist, had a
1772 different name, or seem to have had a different resolution.
1773 .
1774 So conflicts with classical devices are very unlikely.
1775 .
1776 .
1777 .ie \n[@STUPID_DRAWING_POSITIONING]=1 \{\
1778 .IP \[bu] 2m
1779 The position changing after the commands
1780 .BR Dp ,
1781 .BR DP ,
1782 and
1783 .B Dt
1784 is illogical, but as old versions of groff used this feature it is
1785 kept for compatibility reasons.
1786 .\}             \" @STUPID_DRAWING_POSITIONING
1787 .el \{\
1788 .IP \[bu] 2m
1789 Temporarily, there existed some confusion on the positioning after the
1790 .B D
1791 commands that are
1792 .I groff
1793 extensions.
1794 .
1795 This has been clarified by establishing the classical rule for all
1796 groff drawing commands:
1797 .
1798 .
1799 .RS
1800 .P
1801 .ft I
1802 The position after a graphic object has been drawn is at its end;
1803 for circles and ellipses, the "end" is at the right side.
1804 .ft
1805 .RE
1806 .
1807 .
1808 .P
1809 From this, the positionings specified for the drawing commands above
1810 follow quite naturally.
1811 .\}             \" @STUPID_DRAWING_POSITIONING
1812 .
1813 .P
1814 The differences between
1815 .I groff
1816 and
1817 .I classical troff
1818 are documented in
1819 .BR groff_diff (@MAN7EXT@).
1820 .
1821 .
1822 .\" ====================================================================
1823 .SH "FILES"
1824 .\" ====================================================================
1825 .
1826 .TP
1827 .IR @FONTDIR@/dev name /DESC
1828 Device description file for device
1829 .IR name .
1830 .
1831 .TP
1832 .I src/libs/libdriver/input.cpp
1833 Defines the parser and postprocessor for the
1834 .I intermediate
1835 .IR output .
1836 .
1837 It is located relative to the top directory of the
1838 .I groff
1839 source tree.
1840 .
1841 This parser is the definitive specification of the
1842 .I groff intermediate output
1843 format.
1844 .
1845 .
1846 .\" ====================================================================
1847 .SH AUTHORS
1848 .\" ====================================================================
1849 James Clark wrote an early version of this document, which described
1850 only the differences between
1851 .BR ditroff (7)'s
1852 output format and that of GNU
1853 .IR roff .
1854 .
1855 The present version was completely rewritten in 2001 by
1856 .MT groff\-bernd.warken\-72@\:web.de
1857 Bernd Warken
1858 .ME .
1859 .
1860 .
1861 .\" ====================================================================
1862 .SH "SEE ALSO"
1863 .\" ====================================================================
1864 .
1865 A reference like
1866 .BR groff (@MAN7EXT@)
1867 refers to a manual page; here
1868 .B groff
1869 in section\~\c
1870 .I @MAN7EXT@
1871 of the man page documentation system.
1872 .
1873 To read the example, look up section\~@MAN7EXT@ in your desktop help
1874 system or call from the shell prompt
1875 .
1876 .
1877 .RS
1878 .P
1879 .EX
1880 \fBshell>\fP man @MAN7EXT@ groff
1881 .EE
1882 .RE
1883 .
1884 .
1885 .P
1886 For more details, see
1887 .BR man (1).
1888 .
1889 .
1890 .TP
1891 .BR groff (@MAN1EXT@)
1892 option
1893 .B \-Z
1894 and further readings on groff.
1895 .
1896 .
1897 .TP
1898 .BR groff (@MAN7EXT@)
1899 for details of the
1900 .I groff
1901 language such as numerical units and escape sequences.
1902 .
1903 .
1904 .TP
1905 .BR groff_font (@MAN5EXT@)
1906 for details on the device scaling parameters of the
1907 .I DESC
1908 file.
1909 .
1910 .
1911 .TP
1912 .BR @g@troff (@MAN1EXT@)
1913 generates the device-independent intermediate output.
1914 .
1915 .
1916 .TP
1917 .BR roff (@MAN7EXT@)
1918 for historical aspects and the general structure of roff systems.
1919 .
1920 .
1921 .TP
1922 .BR groff_diff (@MAN7EXT@)
1923 The differences between the intermediate output in groff and classical
1924 troff.
1925 .
1926 .
1927 .TP
1928 .BR gxditview (@MAN1EXT@)
1929 Viewer for the
1930 .I intermediate
1931 .IR output .
1932 .
1933 .
1934 .P
1935 .BR \%grodvi (@MAN1EXT@),
1936 .BR \%grohtml (@MAN1EXT@),
1937 .BR \%grolbp (@MAN1EXT@),
1938 .BR \%grolj4 (@MAN1EXT@),
1939 .BR \%grops (@MAN1EXT@),
1940 .BR \%grotty (@MAN1EXT@)
1941 .br
1942 .RS
1943 the groff postprocessor programs.
1944 .RE
1945 .
1946 .
1947 .P
1948 .IR "Groff: The GNU Implementation of troff" ,
1949 by Trent A.\& Fisher and Werner Lemberg,
1950 is the primary
1951 .I groff
1952 manual.
1953 .
1954 You can browse it interactively with \[lq]info groff\[rq].
1955 .
1956 .
1957 .P
1958 The
1959 .I classical troff output language
1960 is described in two AT&T Bell Labs CSTR documents available on-line at
1961 .UR http://\:cm.bell\-labs.com/\:cm/\:cs/\:cstr.html
1962 Bell Labs CSTR site
1963 .UE .
1964 .
1965 .
1966 .TP
1967 [CSTR #97]
1968 .I A Typesetter-independent TROFF
1969 by
1970 .I Brian Kernighan
1971 is the original and most comprehensive documentation on the output
1972 language; see
1973 .UR http://\:cm.bell\-labs.com/\:cm/\:cs/\:cstr/\:97.ps.gz
1974 CSTR\~#97
1975 .UE .
1976 .
1977 .
1978 .TP
1979 [CSTR\~#54]
1980 The 1992 revision of the
1981 .I Nroff/\:Troff User's Manual
1982 by
1983 .I J.\& F.\& Ossanna
1984 and
1985 .I Brian Kernighan
1986 isn't as comprehensive as
1987 [CSTR\~#97]
1988 regarding the output language; see
1989 .UR http://\:cm.bell\-labs.com/\:cm/\:cs/\:cstr/\:54.ps.gz
1990 CSTR\~#54
1991 .UE .
1992 .
1993 .
1994 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
1995 .cp \n[groff_out_C]
1996 .
1997 .
1998 .\" ====================================================================
1999 .\" Editor settings
2000 .\" ====================================================================
2001 .
2002 .\" Local Variables:
2003 .\" mode: nroff
2004 .\" fill-column: 72
2005 .\" End:
2006 .\" vim: set filetype=groff textwidth=72: