/contrib/groff/man/groff_out.man

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