man/groff_out.man

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