PageRenderTime 58ms CodeModel.GetById 25ms app.highlight 17ms RepoModel.GetById 2ms app.codeStats 0ms

/contrib/groff/man/groff_diff.man

https://bitbucket.org/freebsd/freebsd-head/
Unknown | 3848 lines | 3842 code | 6 blank | 0 comment | 0 complexity | cbc9dff3c7997ddca4916803cc304d3c MD5 | raw file
   1'\" e
   2.\" The above line should force the use of eqn as a preprocessor
   3.ig
   4groff_diff.man
   5
   6Last update : 26 Jul 2004
   7
   8This file is part of groff, the GNU roff type-setting system.
   9It is the source of the man-page groff_diff(7).
  10
  11Copyright (C) 1989, 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
  12written by James Clark
  13
  14modified by Werner Lemberg <wl@gnu.org>
  15            Bernd Warken <bwarken@mayn.de>
  16
  17Permission is granted to copy, distribute and/or modify this document
  18under the terms of the GNU Free Documentation License, Version 1.1 or
  19any later version published by the Free Software Foundation; with the
  20Invariant Sections being this .ig-section and AUTHORS, with no
  21Front-Cover Texts, and with no Back-Cover Texts.
  22
  23A copy of the Free Documentation License is included as a file called
  24FDL in the main directory of the groff source package.
  25..
  26.
  27.\" --------------------------------------------------------------------
  28.\" Setup
  29.\" --------------------------------------------------------------------
  30.
  31.do nr groff_diff_C \n[.C]
  32.cp 0
  33.
  34.mso www.tmac
  35.
  36.if n \{\
  37.  mso tty-char.tmac
  38.  ftr CR R
  39.  ftr CI I
  40.  ftr CB B
  41.\}
  42.
  43.if '\*[.T]'dvi' \
  44.  ftr CB CW
  45.
  46.\" define a string tx for the TeX logo
  47.ie t .ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
  48.el   .ds tx TeX
  49.
  50.
  51.\" --------------------------------------------------------------------
  52.\" start of macro definitions
  53.
  54.eo
  55.
  56.de c
  57..
  58.
  59.de TQ
  60.  br
  61.  ns
  62.  TP \$1
  63..
  64.de Text
  65.  RI "\$*"
  66..
  67.de Topic
  68.  TP 2m
  69.  Text \[bu]
  70..
  71.de squoted
  72.  ds @arg1 \$1
  73.  shift
  74.\"  Text \[oq]\f[CB]\*[@arg1]\f[]\[cq]\$*
  75.  Text \[oq]\f[B]\*[@arg1]\f[]\[cq]\$*
  76.  rm @arg1
  77..
  78.c A shell command line
  79.de ShellCommand
  80.  br
  81.  IR "shell#" "\h'1m'\f[CB]\$*\f[]\/"
  82..
  83.c reference of a request or macro
  84.de request
  85.  ds @arg1 \$1
  86.  shift 1
  87.\"  Text \f[CB]\*[@arg1]\f[]\$*
  88.  Text \f[B]\*[@arg1]\f[]\$*
  89.  rm @arg1
  90..
  91.als option request
  92.
  93.c representation of an escape sequence
  94.de esc
  95.  ds @arg1 \$1
  96.  shift
  97.\"  Text \f[CB]\[rs]\*[@arg1]\f[]\$*
  98.  Text \f[B]\[rs]\*[@arg1]\&\f[]\$*
  99.  rm @arg1
 100..
 101.ec
 102.\" end of macro definitions
 103.
 104.\" from old groff_out.man
 105.ie \n(.g \
 106.  ds ic \/
 107.el \
 108.  ds ic \^
 109.
 110.
 111.\" --------------------------------------------------------------------
 112.\" Title
 113.\" --------------------------------------------------------------------
 114.
 115.TH GROFF_DIFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
 116.SH NAME
 117groff_diff \- differences between GNU troff and classical troff
 118.
 119.
 120.\" --------------------------------------------------------------------
 121.SH DESCRIPTION
 122.\" --------------------------------------------------------------------
 123.
 124This manual page describes the language differences between
 125.IR groff ,
 126the GNU
 127.I roff
 128text processing system and the classical
 129.I roff
 130formatter of the freely available Unix\~7 of the 1970s, documented in
 131the
 132.I Troff User's Manual
 133by
 134.I Osanna
 135and
 136.IR Kernighan .
 137This inludes the roff language as well as the intermediate output
 138format (troff output).
 139.
 140.P
 141The section
 142.I SEE ALSO
 143gives pointers to both the classical
 144.I roff
 145and the modern
 146.I groff
 147documentation.
 148.
 149.
 150.\" --------------------------------------------------------------------
 151.SH "GROFF LANGUAGE"
 152.\" --------------------------------------------------------------------
 153.
 154In this section, all additional features of
 155.I groff
 156compared to the classical Unix\~7
 157.I troff
 158are described in detail.
 159.
 160.
 161.\" --------------------------------------------------------------------
 162.SS "Long names"
 163.\" --------------------------------------------------------------------
 164.
 165The names of number registers, fonts, strings/\:macros/\:diversions,
 166special characters (glyphs), and colors can be of any length.
 167.
 168In escape sequences, additionally to the classical
 169.BI ( xx
 170construction for a two-character name, you can use
 171.BI [ xxx ]
 172for a name of arbitrary length.
 173.
 174.TP
 175.BI \[rs][ xxx ]
 176Print the special character (glyph) called
 177.IR xxx .
 178.
 179.TP
 180.BI \[rs][ "comp1 comp2 .\|.\|." ]
 181Print composite glyph consisting of multiple components.
 182.
 183Example: `\[rs][A\~ho]' is capital letter A with ogonek which finally maps
 184to glyph name `u0041_0328'.
 185.
 186See the
 187.I groff info file
 188for details how a glyph name for a composite glyph is constructed, and
 189.BR groff_char (@MAN7EXT@)
 190for list of glyph name components used composite glyph names.
 191.
 192.TP
 193.BI \[rs]f[ xxx ]
 194Set font
 195.IR xxx .
 196.
 197Additionally,
 198.B \[rs]f[]
 199is a new syntax equal to
 200.BR \[rs]fP ,
 201i.e., to return to the previous font.
 202.
 203.TP
 204.BI \[rs]*[ "xxx arg1 arg2 .\|.\|." ]
 205Interpolate string
 206.IR xxx ,
 207taking
 208.IR arg1 ,
 209.IR arg2 ,
 210.I .\|.\|.\&
 211as arguments.
 212.
 213.TP
 214.BI \[rs]n[ xxx ]
 215Interpolate number register
 216.IR xxx .
 217.
 218.
 219.\" --------------------------------------------------------------------
 220.SS "Fractional pointsizes"
 221.\" --------------------------------------------------------------------
 222.
 223A
 224.I scaled point
 225is equal to
 226.B 1/sizescale
 227points, where
 228.B sizescale
 229is specified in the
 230.B DESC
 231file (1 by default).
 232.
 233There is a new scale indicator
 234.B z
 235that has the effect of multiplying by sizescale.
 236.
 237Requests and escape sequences in troff interpret arguments that
 238represent a pointsize as being in units of scaled points, but they
 239evaluate each such argument using a default scale indicator of
 240.BR z .
 241Arguments treated in this way are the argument to the
 242.B ps
 243request, the third argument to the
 244.B cs
 245request, the second and fourth arguments to the
 246.B tkf
 247request, the argument to the
 248.B \[rs]H
 249escape sequence, and those variants of the
 250.B \[rs]s
 251escape sequence that take a numeric expression as their argument.
 252.
 253.P
 254For example, suppose sizescale is 1000; then a scaled point will be
 255equivalent to a millipoint; the call
 256.B .ps\ 10.25
 257is equivalent to
 258.B .ps\ 10.25z
 259and so sets the pointsize to 10250 scaled points, which is equal to
 26010.25 points.
 261.
 262.P
 263The number register
 264.B \[rs]n[.s]
 265returns the pointsize in points as decimal fraction.
 266.
 267There is also a new number register
 268.B \[rs]n[.ps]
 269that returns the pointsize in scaled points.
 270.
 271.P
 272It would make no sense to use the
 273.B z
 274scale indicator in a numeric expression whose default scale indicator
 275was neither
 276.B u
 277nor
 278.BR z ,
 279and so
 280.B troff
 281disallows this.
 282.
 283Similarly it would make no sense to use a scaling indicator other than
 284.B z
 285or
 286.B u
 287in a numeric expression whose default scale indicator was
 288.BR z ,
 289and so
 290.B troff
 291disallows this as well.
 292.
 293.P
 294There is also new scale indicator\~\c
 295.B s
 296which multiplies by the number of units in a scaled point.
 297.
 298So, for example,
 299.B \[rs]n[.ps]s
 300is equal to
 301.BR 1m .
 302Be sure not to confuse the
 303.B s
 304and
 305.B z
 306scale indicators.
 307.
 308.
 309.\" --------------------------------------------------------------------
 310.SS "Numeric expressions"
 311.\" --------------------------------------------------------------------
 312.
 313Spaces are permitted in a number expression within parentheses.
 314.
 315.P
 316.B M
 317indicates a scale of 100ths of an em.
 318.B f
 319indicates a scale of 65536 units, providing fractions for color
 320definitions with the
 321.B defcolor
 322request.
 323.
 324For example, 0.5f = 32768u.
 325.
 326.TP
 327.IB e1 >? e2
 328The maximum of
 329.I e1
 330and
 331.IR e2 .
 332.
 333.TP
 334.IB e1 <? e2
 335The minimum of
 336.I e1
 337and
 338.IR e2 .
 339.
 340.TP
 341.BI ( c ; e )
 342Evaluate
 343.I e
 344using
 345.I c
 346as the default scaling indicator.
 347.
 348If
 349.I c
 350is missing, ignore scaling indicators in the evaluation of
 351.IR e .
 352.
 353.
 354.\" --------------------------------------------------------------------
 355.SS "New escape sequences"
 356.\" --------------------------------------------------------------------
 357.
 358.TP
 359.BI \[rs]A' anything '
 360This expands to
 361.B 1
 362or
 363.B 0
 364resp., depending on whether
 365.I anything
 366is or is not acceptable as the name of a string, macro, diversion, number
 367register, environment, font, or color.
 368It will return\~\c
 369.B 0
 370if
 371.I anything
 372is empty.
 373.
 374This is useful if you want to lookup user input in some sort of
 375associative table.
 376.
 377.TP
 378.BI \[rs]B' anything '
 379This expands to
 380.B 1
 381or
 382.B 0
 383resp., depending on whether
 384.I anything
 385is or is not a valid numeric expression.
 386.
 387It will return\~\c
 388.B 0
 389if
 390.I anything
 391is empty.
 392.
 393.TP
 394.BI \[rs]C' xxx '
 395Typeset glyph named
 396.IR xxx .
 397Normally it is more convenient to use
 398.BI \[rs][ xxx ]\f[R].
 399But
 400.B \[rs]C
 401has the advantage that it is compatible with recent versions of
 402.SM UNIX
 403and is available in compatibility mode.
 404.
 405.TP
 406.B \[rs]E
 407This is equivalent to an escape character, but it is not interpreted in
 408copy-mode.
 409.
 410For example, strings to start and end superscripting could be defined
 411like this
 412.
 413.RS
 414.IP
 415.ft CB
 416.Text .ds { \[rs]v'\-.3m'\[rs]s'\[rs]En[.s]*6u/10u'
 417.br
 418.Text .ds } \[rs]s0\[rs]v'.3m'
 419.ft
 420.
 421.P
 422The use of
 423.B \[rs]E
 424ensures that these definitions will work even if
 425.B \[rs]*{
 426gets interpreted in copy-mode (for example, by being used in a macro
 427argument).
 428.RE
 429.
 430.TP
 431.BI \[rs]F f
 432.TQ
 433.BI \[rs]F( fm
 434.TQ
 435.BI \[rs]F[ fam ]
 436Change font family.
 437.
 438This is the same as the
 439.B fam
 440request.
 441.
 442.B \[rs]F[]
 443switches back to the previous color (note that
 444.B \[rs]FP
 445won't work; it selects font family `P' instead).
 446.
 447.TP
 448.BI \[rs]m x
 449.TQ
 450.BI \[rs]m( xx
 451.TQ
 452.BI \[rs]m[ xxx ]
 453Set drawing color.
 454.B \[rs]m[]
 455switches back to the previous color.
 456.
 457.TP
 458.BI \[rs]M x
 459.TQ
 460.BI \[rs]M( xx
 461.TQ
 462.BI \[rs]M[ xxx ]
 463Set background color for filled objects drawn with the
 464.BI \[rs]D' .\|.\|. '
 465commands.
 466.B \[rs]M[]
 467switches back to the previous color.
 468.
 469.TP
 470.BI \[rs]N' n '
 471Typeset the glyph with index
 472.I n
 473in the current font.
 474.I n
 475can be any integer.
 476.
 477Most devices only have glyphs with indices between 0 and 255.
 478.
 479If the current font does not contain a glyph with that code,
 480special fonts will
 481.I not
 482be searched.
 483.
 484The
 485.B \[rs]N
 486escape sequence can be conveniently used in conjunction with the
 487.B char
 488request, for example
 489.
 490.RS
 491.ft CB
 492.IP
 493.Text .char \[rs][phone] \[rs]f(ZD\[rs]N'37'
 494.ft
 495.RE
 496.
 497.IP
 498The index of each glyph is given in the fourth column in the font
 499description file after the
 500.B charset
 501command.
 502.
 503It is possible to include unnamed glyphs in the font description
 504file by using a name of
 505.BR \-\-\- ;
 506the
 507.B \[rs]N
 508escape sequence is the only way to use these.
 509.
 510.TP
 511.BI \[rs]O n
 512.TQ
 513.BI \[rs]O[ n ]
 514Suppressing troff output.
 515.
 516The escapes
 517.BR \[rs]02 ,
 518.BR \[rs]O3 ,
 519.BR \[rs]O4 ,
 520and
 521.B \[rs]O5
 522are intended for internal use by
 523.BR \%grohtml .
 524.
 525.RS
 526.TP
 527.B \[rs]O0
 528Disable any ditroff glyphs from being emitted to the device driver,
 529provided that the escape occurs at the outer level (see
 530.B \[rs]O3
 531and
 532.BR \[rs]O4 ).
 533.
 534.TP
 535.B \[rs]O1
 536Enable output of glyphs, provided that the escape occurs at the outer
 537level.
 538.IP
 539.B \[rs]O0
 540and
 541.B \[rs]O1
 542also reset the registers
 543.BR \[rs]n[opminx] ,
 544.BR \[rs]n[opminy] ,
 545.BR \[rs]n[opmaxx] ,
 546and
 547.B \[rs]n[opmaxy]
 548to\~-1.
 549.
 550These four registers mark the top left and bottom right hand corners
 551of a box which encompasses all written glyphs.
 552.
 553.TP
 554.B \[rs]O2
 555Provided that the escape occurs at the outer level, enable output of
 556glyphs and also write out to stderr the page number and four registers
 557encompassing the glyphs previously written since the last call to
 558.BR \[rs]O .
 559.
 560.TP
 561.B \[rs]O3
 562Begin a nesting level.
 563.
 564At start-up,
 565.B troff
 566is at outer level.
 567.
 568This is really an internal mechanism for
 569.B \%grohtml
 570while producing images.
 571.
 572They are generated by running the troff source through
 573.B troff
 574to the postscript device and
 575.B ghostscript
 576to produce images in PNG format.
 577.
 578The
 579.B \[rs]O3
 580escape will start a new page if the device is not html (to reduce the
 581possibility of images crossing a page boundary).
 582.
 583.TP
 584.B \[rs]O4
 585End a nesting level.
 586.
 587.TP
 588.BI \[rs]O5[ Pfilename ]
 589This escape is
 590.B \%grohtml
 591specific.
 592.
 593Provided that this escape occurs at the outer nesting level, write
 594.I filename
 595to stderr.
 596.
 597The position of the image,
 598.IR P ,
 599must be specified and must be one of l, r, c, or i (left, right,
 600centered, inline).
 601.
 602.I filename
 603will be associated with the production of the next inline image.
 604.RE
 605.
 606.TP
 607.BI \[rs]R' name\ \[+-]n '
 608This has the same effect as
 609.
 610.RS
 611.IP
 612.BI .nr\  name\ \[+-]n
 613.RE
 614.
 615.TP
 616.BI \[rs]s( nn
 617.TQ
 618.BI \[rs]s\[+-]( nn
 619Set the point size to
 620.I nn
 621points;
 622.I nn
 623must be exactly two digits.
 624.
 625.TP
 626.BI \[rs]s[\[+-] n ]
 627.TQ
 628.BI \[rs]s\[+-][ n ]
 629.TQ
 630.BI \[rs]s'\[+-] n '
 631.TQ
 632.BI \[rs]s\[+-]' n '
 633Set the point size to
 634.I n
 635scaled points;
 636.I n
 637is a numeric expression with a default scale indicator of\~\c
 638.BR z .
 639.
 640.TP
 641.BI \[rs]V x
 642.TQ
 643.BI \[rs]V( xx
 644.TQ
 645.BI \[rs]V[ xxx ]
 646Interpolate the contents of the environment variable
 647.IR xxx ,
 648as returned by
 649.BR getenv (3).
 650.B \[rs]V
 651is interpreted in copy-mode.
 652.
 653.TP
 654.BI \[rs]Y x
 655.TQ
 656.BI \[rs]Y( xx
 657.TQ
 658.BI \[rs]Y[ xxx ]
 659This is approximately equivalent to
 660.BI \[rs]X'\[rs]*[ xxx ]'\f[R].
 661However the contents of the string or macro
 662.I xxx
 663are not interpreted; also it is permitted for
 664.I xxx
 665to have been defined as a macro and thus contain newlines (it is not
 666permitted for the argument to
 667.B \[rs]X
 668to contain newlines).
 669.
 670The inclusion of newlines requires an extension to the UNIX troff
 671output format, and will confuse drivers that do not know about this
 672extension.
 673.
 674.TP
 675.BI \[rs]Z' anything '
 676Print anything and then restore the horizontal and vertical position;
 677.I anything
 678may not contain tabs or leaders.
 679.
 680.TP
 681.B \[rs]$0
 682The name by which the current macro was invoked.
 683.
 684The
 685.B als
 686request can make a macro have more than one name.
 687.
 688.TP
 689.B \[rs]$*
 690In a macro or string, the concatenation of all the arguments separated
 691by spaces.
 692.
 693.TP
 694.B \[rs]$@
 695In a macro or string, the concatenation of all the arguments with each
 696surrounded by double quotes, and separated by spaces.
 697.
 698.TP
 699.BI \[rs]$( nn
 700.TQ
 701.BI \[rs]$[ nnn ]
 702In a macro or string, this gives the
 703.IR nn -th
 704or
 705.IR nnn -th
 706argument.
 707.
 708Macros and strings can have an unlimited number of arguments.
 709.
 710.TP
 711.BI \[rs]? anything \[rs]?
 712When used in a diversion, this will transparently embed
 713.I anything
 714in the diversion.
 715.I anything
 716is read in copy mode.
 717.
 718When the diversion is reread,
 719.I anything
 720will be interpreted.
 721.I anything
 722may not contain newlines; use
 723.B \[rs]!\&
 724if you want to embed newlines in a diversion.
 725.
 726The escape sequence
 727.B \[rs]?\&
 728is also recognised in copy mode and turned into a single internal
 729code; it is this code that terminates
 730.IR anything .
 731Thus
 732.
 733.RS
 734.IP
 735.ne 14v+\n(.Vu
 736.ft CB
 737.nf
 738.Text .nr x 1
 739.Text .nf
 740.Text .di d
 741.Text \[rs]?\[rs]\[rs]?\[rs]\[rs]\[rs]\[rs]?\[rs]\[rs]\[rs]\[rs]\[rs]\[rs]\[rs]\c
 742.Text \[rs]nx\[rs]\[rs]\[rs]\[rs]?\[rs]\[rs]?\[rs]?
 743.Text .di
 744.Text .nr x 2
 745.Text .di e
 746.Text .d
 747.Text .di
 748.Text .nr x 3
 749.Text .di f
 750.Text .e
 751.Text .di
 752.Text .nr x 4
 753.Text .f
 754.fi
 755.ft
 756.RE
 757.
 758.IP
 759will print\~\c
 760.BR 4 .
 761.
 762.TP
 763.B \[rs]/
 764This increases the width of the preceding glyph so that the
 765spacing between that glyph and the following glyph will be
 766correct if the following glyph is a roman glyph.
 767.
 768.if t \{\
 769.  nop For example, if an italic f is immediately followed by a roman
 770.  nop right parenthesis, then in many fonts the top right portion of
 771.  nop the f will overlap the top left of the right parenthesis
 772.  nop producing \f[I]f\f[R])\f[R], which is ugly.
 773.  nop Inserting
 774.  B \[rs]/
 775.  nop produces
 776.  ie \n(.g \f[I]f\/\f[R])\f[R]
 777.  el       \f[I]f\|\f[R])\f[R]
 778.  nop and avoids this problem.
 779.\}
 780It is a good idea to use this escape sequence whenever an italic
 781glyph is immediately followed by a roman glyph without any
 782intervening space.
 783.
 784.TP
 785.B \[rs],
 786This modifies the spacing of the following glyph so that the
 787spacing between that glyph and the preceding glyph will
 788correct if the preceding glyph is a roman glyph.
 789.
 790.if t \{\
 791.  nop For example, inserting
 792.  B \[rs],
 793.  nop between the parenthesis and the f changes
 794.  nop \f[R](\f[I]f\f[R] to
 795.  ie \n(.g \f[R](\,\f[I]f\f[R].
 796.  el       \f[R](\^\f[I]f\f[R].
 797.\}
 798It is a good idea to use this escape sequence whenever a roman
 799glyph is immediately followed by an italic glyph without any
 800intervening space.
 801.
 802.TP
 803.B \[rs])
 804Like
 805.B \[rs]&
 806except that it behaves like a character declared with the
 807.B cflags
 808request to be transparent for the purposes of end-of-sentence
 809recognition.
 810.
 811.TP
 812.B \[rs]~
 813This produces an unbreakable space that stretches like a normal
 814inter-word space when a line is adjusted.
 815.
 816.TP
 817.B \[rs]:
 818This causes the insertion of a zero-width break point.
 819.
 820It is equal to
 821.B \[rs]%
 822within a word but without insertion of a soft hyphen character.
 823.
 824.TP
 825.B \[rs]#
 826Everything up to and including the next newline is ignored.
 827.
 828This is interpreted in copy mode.
 829.
 830It is like
 831.B \[rs]"
 832except that
 833.B \[rs]"
 834does not ignore the terminating newline.
 835.
 836.
 837.\" --------------------------------------------------------------------
 838.SS "New requests"
 839.\" --------------------------------------------------------------------
 840.
 841.TP
 842.BI .aln\  xx\ yy
 843Create an alias
 844.I xx
 845for number register object named
 846.IR yy .
 847The new name and the old name will be exactly equivalent.
 848.
 849If
 850.I yy
 851is undefined, a warning of type
 852.B reg
 853will be generated, and the request will be ignored.
 854.
 855.TP
 856.BI .als\  xx\ yy
 857Create an alias
 858.I xx
 859for request, string, macro, or diversion object named
 860.IR yy .
 861.
 862The new name and the old name will be exactly equivalent (it is
 863similar to a hard rather than a soft link).
 864.
 865If
 866.I yy
 867is undefined, a warning of type
 868.B mac
 869will be generated, and the request will be ignored.
 870.
 871The
 872.BR de ,
 873.BR am ,
 874.BR di ,
 875.BR da ,
 876.BR ds ,
 877and
 878.B as
 879requests only create a new object if the name of the macro, diversion
 880or string diversion is currently undefined or if it is defined to be a
 881request; normally they modify the value of an existing object.
 882.
 883.TP
 884.BI .am1\  xx\ yy
 885Similar to
 886.BR .am , 
 887but compatibility mode is switched off during execution.
 888.
 889To be more precise, a `compatibility save' token is inserted at the
 890beginning of the macro addition, and a `compatibility restore' token at
 891the end.
 892.
 893As a consequence, the requests
 894.BR am ,
 895.BR am1 ,
 896.BR de ,
 897and
 898.B de1
 899can be intermixed freely since the compatibility save/\:restore tokens
 900only affect the macro parts defined by
 901.B .am1
 902and
 903.BR .ds1 .
 904.
 905.TP
 906.BI .ami\  xx\ yy
 907Append to macro indirectly.
 908.
 909See the
 910.B dei
 911request below for more information.
 912.
 913.TP
 914.BI .ami1\  xx\ yy
 915Same as the
 916.B ami
 917request but compatibility mode is switched off during execution.
 918.
 919.TP
 920.BI .as1\  xx\ yy
 921Similar to
 922.BR .as , 
 923but compatibility mode is switched off during expansion.
 924.
 925To be more precise, a `compatibility save' token is inserted at the
 926beginning of the string, and a `compatibility restore' token at the end.
 927.
 928As a consequence, the requests
 929.BR as ,
 930.BR as1 ,
 931.BR ds ,
 932and
 933.B ds1
 934can be intermixed freely since the compatibility save/\:restore tokens
 935only affect the (sub)strings defined by
 936.B as1
 937and
 938.BR ds1 .
 939.
 940.TP
 941.BI .asciify\  xx
 942This request `unformats' the diversion
 943.I xx
 944in such a way that
 945.SM ASCII
 946and space characters (and some escape sequences) that were formatted
 947and diverted into
 948.I xx
 949will be treated like ordinary input characters when
 950.I xx
 951is reread.
 952Useful for diversions in conjunction with the
 953.B .writem
 954request.
 955.
 956It can be also used for gross hacks; for example, this
 957.
 958.RS
 959.IP
 960.ne 7v+\n(.Vu
 961.ft CB
 962.nf
 963.Text .tr @.
 964.Text .di x
 965.Text @nr n 1
 966.Text .br
 967.Text .di
 968.Text .tr @@
 969.Text .asciify x
 970.Text .x
 971.fi
 972.ft
 973.RE
 974.
 975.IP
 976will set register\~\c
 977.B n
 978to\~1.
 979.
 980Note that glyph information (font, font size, etc.) is not preserved;
 981use
 982.B .unformat
 983instead.
 984.
 985.TP
 986.B .backtrace
 987Print a backtrace of the input stack on stderr.
 988.
 989.TP
 990.BI .blm\  xx
 991Set the blank line macro to
 992.IR xx .
 993If there is a blank line macro, it will be invoked when a blank line
 994is encountered instead of the usual troff behaviour.
 995.
 996.TP
 997.BI .box\  xx
 998.TQ
 999.BI .boxa\  xx
1000These requests are similar to the
1001.B di
1002and
1003.B da
1004requests with the exception that a partially filled line will not
1005become part of the diversion (i.e., the diversion always starts with a
1006new line) but restored after ending the diversion, discarding the
1007partially filled line which possibly comes from the diversion.
1008.
1009.TP
1010.B .break
1011Break out of a while loop.
1012.
1013See also the
1014.B while
1015and
1016.B continue
1017requests.
1018.
1019Be sure not to confuse this with the
1020.B br
1021request.
1022.
1023.TP
1024.B .brp
1025This is the same as
1026.BR \[rs]p .
1027.
1028.TP
1029.BI .cflags\  n\ c1\ c2\|.\|.\|.\&
1030Characters
1031.IR c1 ,
1032.IR c2 ,\|.\|.\|.\&
1033have properties determined by
1034.IR n ,
1035which is ORed from the following:
1036.
1037.RS
1038.IP 1
1039The character ends sentences (initially characters
1040.B .?!\&
1041have this property).
1042.
1043.IP 2
1044Lines can be broken before the character (initially no characters have
1045this property); a line will not be broken at a character with this
1046property unless the characters on each side both have non-zero
1047hyphenation codes.
1048.
1049.IP 4
1050Lines can be broken after the character (initially characters
1051.B \-\[rs][hy]\[rs][em]
1052have this property); a line will not be broken at a character with
1053this property unless the characters on each side both have non-zero
1054hyphenation codes.
1055.
1056.IP 8
1057The character overlaps horizontally (initially characters
1058.B \[rs][ul]\[rs][rn]\[rs][ru]\[rs][radicalex]\[rs][sqrtex]
1059have this property).
1060.
1061.IP 16
1062The character overlaps vertically (initially character
1063.B \[rs][br]
1064has this property).
1065.
1066.IP 32
1067An end-of-sentence character followed by any number of characters with
1068this property will be treated as the end of a sentence if followed by
1069a newline or two spaces; in other words the character is transparent
1070for the purposes of end-of-sentence recognition; this is the same as
1071having a zero space factor in \*[tx] (initially characters
1072.B \[dq]')]*\[rs](dg\[rs](rq
1073have this property).
1074.RE
1075.
1076.TP
1077.BI .char\  c\ string
1078Define glyph
1079.I c
1080to be
1081.IR string .
1082Every time glyph
1083.I c
1084needs to be printed,
1085.I string
1086will be processed in a temporary environment and the result will be
1087wrapped up into a single object.
1088.
1089Compatibility mode will be turned off and the escape character will be
1090set to
1091.B \[rs]
1092while
1093.I string
1094is being processed.
1095.
1096Any emboldening, constant spacing or track kerning will be applied to
1097this object rather than to individual glyphs in
1098.IR string .
1099.
1100.IP
1101A glyph defined by this request can be used just like a normal
1102glyph provided by the output device.
1103.
1104In particular other characters can be translated to it with the
1105.B tr
1106request; it can be made the leader character by the
1107.B lc
1108request; repeated patterns can be drawn with the character using the
1109.B \[rs]l
1110and
1111.B \[rs]L
1112escape sequences; words containing the character can be hyphenated
1113correctly, if the
1114.B hcode
1115request is used to give the character a hyphenation code.
1116.
1117.IP
1118There is a special anti-recursion feature: Use of glyph within the
1119glyph's definition will be handled like normal glyphs not
1120defined with
1121.BR char .
1122.IP
1123A glyph definition can be removed with the
1124.B rchar
1125request.
1126.
1127.TP
1128.BI .chop\  xx
1129Chop the last element off macro, string, or diversion
1130.IR xx .
1131This is useful for removing the newline from the end of diversions
1132that are to be interpolated as strings.
1133.
1134.TP
1135.BI .close\  stream
1136Close the stream named
1137.IR stream ;
1138.I stream
1139will no longer be an acceptable argument to the
1140.B write
1141request.
1142.
1143See the
1144.B open
1145request.
1146.
1147.TP
1148.BI .composite\  glyph1\ glyph2
1149Map glyph name
1150.I glyph1
1151to glyph name
1152.I glyph2
1153if it is used in
1154.BI \[rs][ ... ]
1155with more than one component.
1156.
1157.TP
1158.B .continue
1159Finish the current iteration of a while loop.
1160.
1161See also the
1162.B while
1163and
1164.B break
1165requests.
1166.
1167.TP
1168.BI .color\  n
1169If
1170.I n
1171is non-zero or missing, enable colors (this is the default), otherwise
1172disable them.
1173.
1174.TP
1175.BI .cp\  n
1176If
1177.I n
1178is non-zero or missing, enable compatibility mode, otherwise disable
1179it.
1180.
1181In compatibility mode, long names are not recognised, and the
1182incompatibilities caused by long names do not arise.
1183.
1184.TP
1185.BI .defcolor\  xxx\ scheme\ color_components
1186Define color.
1187.I scheme
1188can be one of the following values:
1189.B rgb
1190(three components),
1191.B cym
1192(three components),
1193.B cmyk
1194(four components), and
1195.B gray
1196or
1197.B grey
1198(one component).
1199.
1200Color components can be given either as a hexadecimal string or as
1201positive decimal integers in the range 0-65535.
1202.
1203A hexadecimal string contains all color components concatenated; it
1204must start with either
1205.B #
1206or
1207.BR ## .
1208The former specifies hex values in the range 0-255 (which are
1209internally multiplied by\~257), the latter in the range 0-65535.
1210.
1211Examples: #FFC0CB (pink), ##ffff0000ffff (magenta).
1212.
1213A new scaling indicator\~\c
1214.B f
1215has been introduced which multiplies its value by\~65536; this makes
1216it convenient to specify color components as fractions in the range 0
1217to\~1.
1218.
1219Example:
1220.
1221.RS
1222.IP
1223.ft CB
1224.Text .defcolor darkgreen rgb 0.1f 0.5f 0.2f
1225.br
1226.ft
1227.RE
1228.
1229.IP
1230Note that
1231.B f
1232is the default scaling indicator for the
1233.B defcolor
1234request, thus the above statement is equivalent to
1235.
1236.RS
1237.IP
1238.ft CB
1239.Text .defcolor darkgreen rgb 0.1 0.5 0.2
1240.br
1241.ft
1242.RE
1243.
1244.IP
1245The color named
1246.B default
1247(which is device-specific) can't be redefined.
1248.
1249It is possible that the default color for
1250.esc M
1251and
1252.esc m
1253is not the same.
1254.
1255.TP
1256.BI .de1\  xx\ yy
1257Similar to
1258.BR .de , 
1259but compatibility mode is switched off during execution.
1260.
1261On entry, the current compatibility mode is saved and restored at exit.
1262.
1263.TP
1264.BI .dei\  xx\ yy
1265Define macro indirectly.
1266.
1267The following example
1268.
1269.RS
1270.IP
1271.ne 2v+\n(.Vu
1272.ft CB
1273.nf
1274.Text .ds xx aa
1275.Text .ds yy bb
1276.Text .dei xx yy
1277.fi
1278.ft
1279.RE
1280.
1281.IP
1282is equivalent to
1283.
1284.RS
1285.IP
1286.ft CB
1287.Text .de aa bb
1288.br
1289.ft
1290.RE
1291.
1292.TP
1293.BI .dei1\  xx\ yy
1294Similar to the
1295.B dei
1296request but compatibility mode is switched off during execution.
1297.
1298.TP
1299.BI .do\  xxx
1300Interpret
1301.I .xxx
1302with compatibility mode disabled.
1303.
1304For example,
1305.
1306.RS
1307.
1308.IP
1309.ft CB
1310.Text .do fam T
1311.br
1312.ft
1313.
1314.P
1315would have the same effect as
1316.
1317.IP
1318.ft CB
1319.Text .fam T
1320.br
1321.ft
1322.
1323.P
1324except that it would work even if compatibility mode had been enabled.
1325.
1326Note that the previous compatibility mode is restored before any files
1327sourced by
1328.I xxx
1329are interpreted.
1330.
1331.RE
1332.
1333.TP
1334.BI .ds1\  xx\ yy
1335Similar to
1336.BR .ds , 
1337but compatibility mode is switched off during expansion.
1338.
1339To be more precise, a `compatibility save' token is inserted at the
1340beginning of the string, and a `compatibility restore' token at the end.
1341.
1342.TP
1343.B .ecs
1344Save current escape character.
1345.
1346.TP
1347.B .ecr
1348Restore escape character saved with
1349.BR ecs .
1350Without a previous call to
1351.BR ecs ,
1352.RB ` \[rs] '
1353will be the new escape character.
1354.
1355.TP
1356.BI .evc\  xx
1357Copy the contents of environment
1358.I xx
1359to the current environment.
1360.
1361No pushing or popping of environments will be done.
1362.
1363.TP
1364.BI .fam\  xx
1365Set the current font family to
1366.IR xx .
1367The current font family is part of the current environment.
1368If
1369.I xx
1370is missing, switch back to previous font family.
1371.
1372The value at start-up is `T'.
1373.
1374See the description of the
1375.B sty
1376request for more information on font families.
1377.
1378.TP
1379.BI .fchar\  c\ string
1380Define fallback glyph
1381.I c
1382to be
1383.IR string .
1384.
1385The syntax of this request is the same as the
1386.B char
1387request; the only difference is that a glyph defined with
1388.B char
1389hides the glyph with the same name in the current font, whereas a
1390glyph defined with
1391.B fchar
1392is checked only if the particular glyph isn't found in the current font.
1393.
1394This test happens before checking special fonts.
1395.
1396.TP
1397.BI .fcolor\  c
1398Set the fill color to
1399.IR c .
1400If
1401.I c
1402is missing,
1403switch to the previous fill color.
1404.
1405.TP
1406.BI .fschar\  f\ c\ string
1407Define fallback glyph
1408.I c
1409for font
1410.I f
1411to be
1412.IR string .
1413.
1414The syntax of this request is the same as the
1415.B char
1416request (with an additional argument to specify the font); a glyph
1417defined with
1418.B fschar
1419is searched after the list of fonts declared with the
1420.B fspecial
1421request but before the list of fonts declared with
1422.BR special .
1423.
1424.TP
1425.BI .fspecial\  f\ s1\ s2\|.\|.\|.\&
1426When the current font is
1427.IR f ,
1428fonts
1429.IR s1 ,
1430.IR s2 ,\|.\|.\|.\&
1431will be special, that is, they will searched for glyphs not in
1432the current font.
1433.
1434Any fonts specified in the
1435.B special
1436request will be searched after fonts specified in the
1437.B fspecial
1438request.
1439.
1440Without argument, reset the list of global special fonts to be empty.
1441.
1442.TP
1443.BI .ftr\  f\ g
1444Translate font
1445.I f
1446to
1447.IR g .
1448Whenever a font named
1449.I f
1450is referred to in an
1451.B \[rs]f
1452escape sequence, in the
1453.B F
1454and
1455.B S
1456conditional operators, or in the
1457.BR ft ,
1458.BR ul ,
1459.BR bd ,
1460.BR cs ,
1461.BR tkf ,
1462.BR special ,
1463.BR fspecial ,
1464.BR fp ,
1465or
1466.BR sty
1467requests, font
1468.I g
1469will be used.
1470If
1471.I g
1472is missing, or equal to
1473.I f
1474then font
1475.I f
1476will not be translated.
1477.
1478.TP
1479.BI .gcolor\  c
1480Set the glyph color to
1481.IR c .
1482If
1483.I c
1484is missing,
1485switch to the previous glyph color.
1486.
1487.TP
1488.BI .hcode \ c1\ code1\ c2\ code2\|.\|.\|.\&
1489Set the hyphenation code of character
1490.I c1
1491to
1492.I code1
1493and that of
1494.I c2
1495to
1496.IR code2 .
1497A hyphenation code must be a single input character (not a special
1498character) other than a digit or a space.
1499.
1500Initially each lower-case letter \%a-z has a hyphenation code, which is
1501itself, and each upper-case letter \%A-Z has a hyphenation code which is
1502the lower-case version of itself.
1503.
1504See also the
1505.B hpf
1506request.
1507.
1508.TP
1509.BI .hla\  lang
1510Set the current hyphenation language to
1511.IR lang .
1512Hyphenation exceptions specified with the
1513.B hw
1514request and hyphenation patterns specified with the
1515.B hpf
1516request are both associated with the current hyphenation language.
1517.
1518The
1519.B hla
1520request is usually invoked by the
1521.B troffrc
1522file.
1523.
1524.TP
1525.BI .hlm\  n
1526Set the maximum number of consecutive hyphenated lines to\~\c
1527.IR n .
1528If
1529.I n
1530is negative, there is no maximum.
1531.
1532The default value is\~\-1.
1533.
1534This value is associated with the current environment.
1535.
1536Only lines output from an environment count towards the maximum
1537associated with that environment.
1538.
1539Hyphens resulting from
1540.B \[rs]%
1541are counted; explicit hyphens are not.
1542.
1543.TP
1544.BI .hpf\  file
1545Read hyphenation patterns from
1546.IR file ;
1547this will be searched for in the same way that
1548.IB name .tmac
1549is searched for when the
1550.BI \-m name
1551option is specified.
1552.
1553It should have the same format as (simple) \*[tx] patterns files.
1554.
1555More specifically, the following scanning rules are implemented.
1556.
1557.RS
1558.IP \[bu]
1559A percent sign starts a comment (up to the end of the line) even if
1560preceded by a backslash.
1561.
1562.IP \[bu]
1563No support for `digraphs' like
1564.BR \[rs]$ .
1565.
1566.IP \[bu]
1567.BI ^^ xx
1568.RI ( x
1569is 0-9 or a-f) and
1570.BI ^^ x
1571(character code of\~\c
1572.I x
1573in the range 0-127) are recognized; other use of
1574.B ^
1575causes an error.
1576.
1577.IP \[bu]
1578No macro expansion.
1579.
1580.IP \[bu]
1581.B hpf
1582checks for the expression
1583.B \[rs]patterns{.\|.\|.}
1584(possibly with whitespace before and after the braces).
1585.
1586Everything between the braces is taken as hyphenation patterns.
1587.
1588Consequently,
1589.B {
1590and
1591.B }
1592are not allowed in patterns.
1593.
1594.IP \[bu]
1595Similarly,
1596.B \[rs]hyphenation{.\|.\|.}
1597gives a list of hyphenation exceptions.
1598.
1599.IP \[bu]
1600.B \[rs]endinput
1601is recognized also.
1602.
1603.IP \[bu]
1604For backwards compatibility, if
1605.B \[rs]patterns
1606is missing, the whole file is treated as a list of hyphenation patterns
1607(only recognizing the
1608.BR % \~\c
1609character as the start of a comment).
1610.RE
1611.
1612.IP
1613Use the
1614.B hpfcode
1615request to map the encoding used in hyphenation patterns files to
1616.BR groff 's
1617input encoding.
1618.IP
1619The set of hyphenation patterns is associated with the current language
1620set by the
1621.B hla
1622request.
1623.
1624The
1625.B hpf
1626request is usually invoked by the
1627.B troffrc
1628file; a second call replaces the old patterns with the new ones.
1629.
1630.TP
1631.BI .hpfa\  file
1632The same as
1633.B hpf
1634except that the hyphenation patterns from
1635.I file
1636are appended to the patterns already loaded in the current language.
1637.
1638.TP
1639.BI .hpfcode\  a\ b\ c\ d\ .\|.\|.
1640After reading a hyphenation patterns file with the
1641.B hpf
1642or
1643.B hpfa
1644request, convert all characters with character code\~\c
1645.I a
1646in the recently read patterns to character code\~\c
1647.IR b ,
1648character code\~\c
1649.I c
1650to\~\c
1651.IR d ,
1652etc.
1653.
1654Initially, all character codes map to themselves.
1655.
1656The arguments of
1657.B hpfcode
1658must be integers in the range 0 to\~255.
1659.
1660Note that it is even possible to use character codes which are invalid in
1661.B groff
1662otherwise.
1663.
1664.TP
1665.BI .hym\  n
1666Set the
1667.I hyphenation margin
1668to\~\c
1669.IR n :
1670when the current adjustment mode is not\~\c
1671.BR b ,
1672the line will not be hyphenated if the line is no more than
1673.I n
1674short.
1675.
1676The default hyphenation margin is\~0.
1677.
1678The default scaling indicator for this request is\~\c
1679.IR m .
1680The hyphenation margin is associated with the current environment.
1681.
1682The current hyphenation margin is available in the
1683.B \[rs]n[.hym]
1684register.
1685.
1686.TP
1687.BI .hys\  n
1688Set the
1689.I hyphenation space
1690to\~\c
1691.IR n :
1692when the current adjustment mode is\~\c
1693.B b
1694don't hyphenate the line if the line can be justified by adding no
1695more than
1696.I n
1697extra space to each word space.
1698.
1699The default hyphenation space is\~0.
1700.
1701The default scaling indicator for this request is\~\c
1702.BR m .
1703The hyphenation space is associated with the current environment.
1704.
1705The current hyphenation space is available in the
1706.B \[rs]n[.hys]
1707register.
1708.
1709.TP
1710.BI .itc\  n\ macro
1711Variant of
1712.B .it
1713for which a line interrupted with
1714.B \[rs]c
1715counts as one input line.
1716.
1717.TP
1718.BI .kern\  n
1719If
1720.I n
1721is non-zero or missing, enable pairwise kerning, otherwise disable it.
1722.
1723.TP
1724.BI .length\  xx\ string
1725Compute the length of
1726.I string
1727and return it in the number register
1728.I xx
1729(which is not necessarily defined before).
1730.
1731.TP
1732.BI .linetabs\  n
1733If
1734.I n
1735is non-zero or missing, enable line-tabs mode, otherwise disable it
1736(which is the default).
1737.
1738In line-tabs mode, tab distances are computed relative to the
1739(current) output line.
1740.
1741Otherwise they are taken relative to the input line.
1742.
1743For example, the following
1744.
1745.RS
1746.IP
1747.ne 6v+\n(.Vu
1748.ft CB
1749.nf
1750.Text .ds x a\[rs]t\[rs]c
1751.Text .ds y b\[rs]t\[rs]c
1752.Text .ds z c
1753.Text .ta 1i 3i
1754.Text \[rs]*x
1755.Text \[rs]*y
1756.Text \[rs]*z
1757.fi
1758.ft
1759.RE
1760.
1761.IP
1762yields
1763.
1764.RS
1765.IP
1766a         b         c
1767.RE
1768.
1769.IP
1770In line-tabs mode, the same code gives
1771.
1772.RS
1773.IP
1774a         b                   c
1775.RE
1776.
1777.IP
1778Line-tabs mode is associated with the current environment; the
1779read-only number register
1780.B \\[rs]n[.linetabs]
1781is set to\~1 if in line-tabs mode, and 0 otherwise.
1782.
1783.TP
1784.BI .mso\  file
1785The same as the
1786.B so
1787request except that
1788.I file
1789is searched for in the same directories as macro files for the the
1790.B \-m
1791command line option.
1792.
1793If the file name to be included has the form
1794.IB name .tmac
1795and it isn't found,
1796.B mso
1797tries to include
1798.BI tmac. name
1799instead and vice versa.
1800.
1801.TP
1802.BI .nop \ anything
1803Execute
1804.IR anything .
1805This is similar to `.if\ 1'.
1806.
1807.TP
1808.B .nroff
1809Make the
1810.B n
1811built-in condition true and the
1812.B t
1813built-in condition false.
1814.
1815This can be reversed using the
1816.B troff
1817request.
1818.
1819.TP
1820.BI .open\  stream\ filename
1821Open
1822.I filename
1823for writing and associate the stream named
1824.I stream
1825with it.
1826.
1827See also the
1828.B close
1829and
1830.B write
1831requests.
1832.
1833.TP 
1834.BI .opena\  stream\ filename
1835Like
1836.BR open ,
1837but if
1838.I filename
1839exists, append to it instead of truncating it.
1840.
1841.TP
1842.BI .output\  string
1843Emit
1844.I string
1845directly to the intermediate output (subject to copy-mode interpretation);
1846this is similar to
1847.B \[rs]!
1848used at the top level.
1849.
1850An initial double quote in
1851.I string
1852is stripped off to allow initial blanks.
1853.
1854.TP
1855.B .pnr
1856Print the names and contents of all currently defined number registers
1857on stderr.
1858.
1859.TP
1860.BI .psbb \ filename
1861Get the bounding box of a PostScript image
1862.IR filename .
1863This file must conform to Adobe's Document Structuring Conventions;
1864the command looks for a
1865.B \%%%BoundingBox
1866comment to extract the bounding box values.
1867.
1868After a successful call, the coordinates (in PostScript units) of the
1869lower left and upper right corner can be found in the registers
1870.BR \[rs]n[llx] ,
1871.BR \[rs]n[lly] ,
1872.BR \[rs]n[urx] ,
1873and
1874.BR \[rs]n[ury] ,
1875respectively.
1876.
1877If some error has occurred, the four registers are set to zero.
1878.
1879.TP
1880.BI .pso \ command
1881This behaves like the
1882.B so
1883request except that input comes from the standard output of
1884.IR command .
1885.
1886.TP
1887.B .ptr
1888Print the names and positions of all traps (not including input line
1889traps and diversion traps) on stderr.
1890.
1891Empty slots in the page trap list are printed as well, because they
1892can affect the priority of subsequently planted traps.
1893.
1894.TP
1895.BI .pvs \ \[+-]n
1896Set the post-vertical line space to
1897.IR n ;
1898default scale indicator is\~\c
1899.BR p .
1900.
1901This value will be added to each line after it has been output.
1902.
1903With no argument, the post-vertical line space is set to its previous
1904value.
1905.
1906.IP
1907The total vertical line spacing consists of four components:
1908.B .vs
1909and
1910.B \[rs]x
1911with a negative value which are applied before the line is output, and
1912.B .pvs
1913and
1914.B \[rs]x
1915with a positive value which are applied after the line is output.
1916.
1917.TP
1918.BI .rchar\  c1\ c2\|.\|.\|.\&
1919Remove the definitions of glyphs
1920.IR c1 ,
1921.IR c2 ,\|.\|.\|.
1922This undoes the effect of a
1923.B char
1924request.
1925.
1926.TP
1927.B .return
1928Within a macro, return immediately.
1929.
1930If called with an argument, return twice, namely from the current macro and
1931from the macro one level higher.
1932.
1933No effect otherwise.
1934.
1935.TP
1936.BI .rfschar\  c1\ c2\|.\|.\|.\&
1937Remove the font-specific definitions of glyphs
1938.IR c1 ,
1939.IR c2 ,\|.\|.\|.
1940This undoes the effect of a
1941.B fschar
1942request.
1943.
1944.TP
1945.B .rj
1946.TQ
1947.BI .rj \~n
1948Right justify the next
1949.IR n \~\c
1950input lines.
1951.
1952Without an argument right justify the next input line.
1953.
1954The number of lines to be right justified is available in the
1955.B \[rs]n[.rj]
1956register.
1957.
1958This implicitly does
1959.BR .ce \~0 .
1960The
1961.B ce
1962request implicitly does
1963.BR .rj \~0 .
1964.
1965.TP
1966.BI .rnn \ xx\ yy
1967Rename number register
1968.I xx
1969to
1970.IR yy .
1971.
1972.TP
1973.BI .schar\  c\ string
1974Define global fallback glyph
1975.I c
1976to be
1977.IR string .
1978.
1979The syntax of this request is the same as the
1980.B char
1981request; a glyph defined with
1982.B schar
1983is searched after the list of fonts declared with the
1984.B special
1985request but before the mounted special fonts.
1986.
1987.TP
1988.BI .shc\  c
1989Set the soft hyphen character to
1990.IR c .
1991If
1992.I c
1993is omitted, the soft hyphen character will be set to the default
1994.BR \[rs](hy .
1995The soft hyphen character is the glyph which will be inserted when
1996a word is hyphenated at a line break.
1997.
1998If the soft hyphen character does not exist in the font of the
1999glyph immediately preceding a potential break point, then the line
2000will not be broken at that point.
2001.
2002Neither definitions (specified with the
2003.B char
2004request) nor translations (specified with the
2005.B tr
2006request) are considered when finding the soft hyphen character.
2007.
2008.TP
2009.BI .shift\  n
2010In a macro, shift the arguments by
2011.I n
2012positions: argument\~\c
2013.I i
2014becomes argument
2015.IR i \- n ;
2016arguments 1 to\~\c
2017.I n
2018will no longer be available.
2019.
2020If
2021.I n
2022is missing, arguments will be shifted by\~1.
2023.
2024Shifting by negative amounts is currently undefined.
2025.
2026.TP
2027.BI .sizes\  s1\ s2\|.\|.\|.\|sn\  [0]
2028This command is similar to the
2029.B sizes
2030command of a
2031.B DESC
2032file.
2033.
2034It sets the available font sizes for the current font to
2035.IR s1 ,
2036.IR s2 ,\|.\|.\|.\|,\~ sn
2037scaled points.
2038.
2039The list of sizes can be terminated by an optional\~\c
2040.BR 0 .
2041.
2042Each
2043.I si
2044can also be a range of sizes
2045.IR m - n .
2046.
2047Contrary to the font file command, the list can't extend over more
2048than a single line.
2049.
2050.TP
2051.BI .special\  s1\ s2\|.\|.\|.\&
2052Fonts
2053.IR s1 ,
2054.IR s2 ,
2055are special and will be searched for glyphs not in the current
2056font.
2057.
2058Without arguments, reset the list of special fonts to be empty.
2059.
2060.TP
2061.BI .spreadwarn\  limit
2062Make
2063.B troff
2064emit a warning if the additional space inserted for each space between
2065words in an output line is larger or equal to
2066.IR limit .
2067.
2068A negative value is changed to zero; no argument toggles the warning on
2069and off without changing
2070.IR limit .
2071.
2072The default scaling indicator is\~\c
2073.BR m .
2074.
2075At startup,
2076.B spreadwarn
2077is deactivated, and
2078.I limit
2079is set to 3m.
2080.
2081For example,
2082.B .spreadwarn\ 0.2m
2083will cause a warning if
2084.B troff
2085must add 0.2m or more for each interword space in a line.
2086.
2087This request is active only if text is justified to both margins (using
2088.BR .ad\ b ).
2089.
2090.TP
2091.BI .sty\  n\ f
2092Associate style\~\c
2093.I f
2094with font position\~\c
2095.IR n .
2096A font position can be associated either with a font or with a style.
2097.
2098The current font is the index of a font position and so is also either
2099a font or a style.
2100.
2101When it is a style, the font that is actually used is the font the
2102name of which is the concatenation of the name of the current family
2103and the name of the current style.
2104.
2105For example, if the current font is\~1 and font position\~1 is
2106associated with style\~\c
2107.B R
2108and the current font family is\~\c
2109.BR T ,
2110then font
2111.BR TR
2112will be used.
2113.
2114If the current font is not a style, then the current family is ignored.
2115.
2116When the requests
2117.BR cs ,
2118.BR bd ,
2119.BR tkf ,
2120.BR uf ,
2121or
2122.B fspecial
2123are applied to a style, then they will instead be applied to the
2124member of the current family corresponding to that style.
2125.
2126The default family can be set with the
2127.B \-f
2128option.
2129.
2130The
2131.B styles
2132command in the
2133.SM DESC
2134file controls which font positions (if any) are initially associated
2135with styles rather than fonts.
2136.
2137.TP
2138.BI .substring\  xx\ n1\  [ n2 ]
2139Replace the string named
2140.I xx
2141with the substring defined by the indices
2142.I n1
2143and
2144.IR n2 .
2145The first character in the string has index\~0.
2146.
2147If
2148.I n2
2149is omitted, it is taken to be equal to the string's length.
2150.
2151If the index value
2152.I n1
2153or
2154.I n2
2155is negative, it will be counted from the end of the string,
2156going backwards:
2157.
2158The last character has index\~-1, the character before the last
2159character has index\~-2, etc.
2160.
2161.TP
2162.BI .tkf\  f\ s1\ n1\ s2\ n2
2163Enable track kerning for font
2164.IR f .
2165When the current font is
2166.I f
2167the width of every glyph will be increased by an amount between
2168.I n1
2169and
2170.IR n2 ;
2171when the current point size is less than or equal to
2172.I s1
2173the width will be increased by
2174.IR n1 ;
2175when it is greater than or equal to
2176.I s2
2177the width will be increased by
2178.IR n2 ;
2179when the point size is greater than or equal to
2180.I s1
2181and less than or equal to
2182.I s2
2183the increase in width is a linear function of the point size.
2184.
2185.TP
2186.BI .tm1\  string
2187Similar to the
2188.B tm
2189request,
2190.I string
2191is read in copy mode and written on the standard error, but an initial
2192double quote in
2193.I string
2194is stripped off to allow initial blanks.
2195.
2196.TP
2197.BI .tmc\  string
2198Similar to
2199.B tm1
2200but without writing a final newline.
2201.
2202.TP
2203.BI .trf\  filename
2204Transparently output the contents of file
2205.IR filename .
2206Each line is output as if preceded by
2207.BR \[rs]! ;
2208however, the lines are not subject to copy-mode interpretation.
2209.
2210If the file does not end with a newline, then a newline will be added.
2211.
2212For example, you can define a macro\~\c
2213.I x
2214containing the contents of file\~\c
2215.IR f ,
2216using
2217.
2218.RS
2219.IP
2220.ne 2v+\n(.Vu
2221.ft CB
2222.nf
2223.Text .di x
2224.Text .trf f
2225.Text .di
2226.fi
2227.ft
2228.RE
2229.
2230.IP
2231Unlike with the
2232.B cf
2233request, the file cannot contain characters such as
2234.SM NUL
2235that are not legal troff input characters.
2236.
2237.TP
2238.BI .trin\  abcd
2239This is the same as the
2240.B tr
2241request except that the
2242.B asciify
2243request will use the character code (if any) before the character
2244translation.
2245.
2246Example:
2247.
2248.RS
2249.IP
2250.nf
2251.ft CB
2252.Text .trin ax
2253.Text .di xxx
2254.Text a
2255.Text .br
2256.Text .di
2257.Text .xxx
2258.Text .trin aa
2259.Text .asciify xxx
2260.Text .xxx
2261.fi
2262.ft
2263.RE
2264.
2265.IP
2266The result is
2267.BR x\ a .
2268.
2269Using
2270.BR tr ,
2271the result would be
2272.BR x\ x .
2273.
2274.TP
2275.BI .trnt\  abcd
2276This is the same as the
2277.B tr
2278request except that the translations do not apply to text that is
2279transparently throughput into a diversion with
2280.BR \[rs]! .
2281For example,
2282.
2283.RS
2284.IP
2285.nf
2286.ft CB
2287.Text .tr ab
2288.Text .di x
2289.Text \[rs]!.tm a
2290.Text .di
2291.Text .x
2292.fi
2293.ft
2294.RE
2295.
2296.IP
2297will print\~\c
2298.BR b ;
2299if
2300.B trnt
2301is used instead of
2302.B tr
2303it will print\~\c
2304.BR a .
2305.RE
2306.
2307.TP
2308.B .troff
2309Make the
2310.B n
2311built-in condition false, and the
2312.B t
2313built-in condition true.
2314.
2315This undoes the effect of the
2316.B nroff
2317request.
2318.
2319.TP
2320.BI .unformat\  xx
2321This request `unformats' the diversion
2322.IR xx .
2323Contrary to the
2324.B .asciify
2325request, which tries to convert formatted elements of the diversion
2326back to input tokens as much as possible,
2327.B .unformat
2328will only handle tabs and spaces between words (usually caused by
2329spaces or newlines in the input) specially.
2330.
2331The former are treated as if they were input tokens, and the latter
2332are stretchable again.
2333.
2334Note that the vertical size of lines is not preserved.
2335.
2336Glyph information (font, font size, space width, etc.) is retained.
2337.
2338Useful in conjunction with the
2339.B .box
2340and
2341.B .boxa
2342requests.
2343.
2344.TP
2345.BI .vpt\  n
2346Enable vertical position traps if
2347.I n
2348is non-zero, disable them otherwise.
2349.
2350Vertical position traps are traps set by the
2351.B wh
2352or
2353.B dt
2354requests.
2355.
2356Traps set by the
2357.B it
2358request are not vertical position traps.
2359.
2360The parameter that controls whether vertical position traps are
2361enabled is global.
2362.
2363Initially vertical position traps are enabled.
2364.
2365.TP
2366.BI .warn\  n
2367Control warnings.
2368.I n
2369is the sum of the numbers associated with each warning that is to be
2370enabled; all other warnings will be disabled.
2371.
2372The number associated with each warning is listed in
2373.BR @g@troff (@MAN1EXT@).
2374.
2375For example,
2376.B .warn\~0
2377will disable all warnings, and
2378.B .warn\~1
2379will disable all warnings except that about missing glyphs.
2380.
2381If
2382.I n
2383is not given, all warnings will be enabled.
2384.
2385.TP
2386.BI .warnscale\  si
2387Set the scaling indicator used in warnings to
2388.IR si .
2389.
2390Valid values for
2391.I si
2392are
2393.BR u ,
2394.BR i ,
2395.BR c ,
2396.BR p ,
2397and
2398.BR P .
2399.
2400At startup, it is set to\~\c
2401.BR i .
2402.
2403.TP
2404.BI .while \ c\ anything
2405While condition\~\c
2406.I c
2407is true, accept
2408.I anything
2409as input;
2410.IR c \~\c
2411can be any condition acceptable to an
2412.B if
2413request;
2414.I anything
2415can comprise multiple lines if the first line starts with
2416.B \[rs]{
2417and the last line ends with
2418.BR \[rs]} .
2419See also the
2420.B break
2421and
2422.B continue
2423requests.
2424.
2425.TP
2426.BI .write\  stream\ anything
2427Write
2428.I anything
2429to the stream named
2430.IR stream .
2431.I stream
2432must previously have been the subject of an
2433.B open
2434request.
2435.I anything
2436is read in copy mode;
2437a leading\~\c
2438.B \[dq]
2439will be stripped.
2440.
2441.TP
2442.BI .writec\  stream\ anything
2443Similar to
2444.B write
2445but without writing a final newline.
2446.
2447.TP
2448.BI .writem\  stream\ xx
2449Write the contents of the macro or string
2450.I xx
2451to the stream named
2452.IR stream .
2453.I stream
2454must previously have been the subject of an
2455.B open
2456request.
2457.I xx
2458is read in copy mode.
2459.
2460.
2461.\" --------------------------------------------------------------------
2462.SS "Extended escape sequences"
2463.\" --------------------------------------------------------------------
2464.
2465.TP
2466.BI \[rs]D' .\|.\|. '
2467All drawing commands of groff's intermediate output are accepted.
2468.
2469See subsection
2470.B "Drawing Commands"
2471below for more information.
2472.
2473.
2474.\" --------------------------------------------------------------------
2475.SS "Extended requests"
2476.\" --------------------------------------------------------------------
2477.
2478.TP
2479.BI .cf\  filename
2480When used in a diversion, this will embed in the diversion an object
2481which, when reread, will cause the contents of
2482.I filename
2483to be transparently copied through to the output.
2484.
2485In UNIX troff, the contents of
2486.I filename
2487is immediately copied through to the output regardless of whether
2488there is a current diversion; this behaviour is so anomalous that it
2489must be considered a bug.
2490.
2491.TP
2492.BI .de\  xx\ yy
2493.TQ
2494.BI .am\  xx\ yy
2495.TQ
2496.BI .ds\  xx\ yy
2497.TQ
2498.BI .as\  xx\ yy
2499In compatibility mode, these requests behaves similar to
2500.BR .de1 ,
2501.BR .am1 ,
2502.BR .ds1 ,
2503and
2504.BR .as1 ,
2505respectively: A `compatibility save' token is inserted at the
2506beginning, and a `compatibility restore' token at the end, with
2507compatibility mode switched on during execution.
2508.
2509.TP
2510.BI .ev\  xx
2511If
2512.I xx
2513is not a number, this will switch to a named environment called
2514.IR xx .
2515The environment should be popped with a matching
2516.B ev
2517request without any arguments, just as for numbered environments.
2518.
2519There is no limit on the number of named environments; they will be
2520created the first time that they are referenced.
2521.
2522.TP
2523.BI .ss\  m\ n
2524When two arguments are given to the
2525.B ss
2526request, the second argument gives the
2527.IR "sentence space size" .
2528If the second argument is not given, the sentence space size
2529will be the same as the word space size.
2530.
2531Like the word space size, the sentence space is in units of
2532one twelfth of the spacewidth parameter for the current font.
2533.
2534Initially both the word space size and the sentence
2535space size are\~12.
2536.
2537Contrary to UNIX troff, GNU troff handles this request in nroff mode
2538also; a given value is then rounded down to the nearest multiple
2539of\~12.
2540.
2541The sentence space size is used in two circumstances.
2542.
2543If the end of a sentence occurs at the end of a line in fill mode,
2544then both an inter-word space and a sentence space will be added; if
2545two spaces follow the end of a sentence in the middle of a line, then
2546the second space will be a sentence space.
2547.
2548Note that the behaviour of UNIX troff will be exactly that exhibited
2549by GNU troff if a second argument is never given to the
2550.B ss
2551request.
2552.
2553In GNU troff, as in UNIX troff, you should always follow a sentence
2554with either a newline or two spaces.
2555.
2556.TP
2557.BI .ta\  n1\ n2\|.\|.\|.nn \ T\  r1\ r2\|.\|.\|.\|rn
2558Set tabs at positions
2559.IR n1 ,
2560.IR n2 ,\|.\|.\|.\|,
2561.I nn
2562and then set tabs at
2563.IR nn + r1 ,
2564.IR nn + r2 ,\|.\|.\|.\|,
2565.IR nn + rn
2566and then at
2567.IR nn + rn + r1 ,
2568.IR nn + rn + r2 ,\|.\|.\|.\|,
2569.IR nn + rn + rn ,
2570and so on.
2571For example,
2572.
2573.RS
2574.IP
2575.ft CB
2576.Text .ta T .5i
2577.br
2578.ft
2579.
2580.P
2581will set tabs every half an inch.
2582.RE
2583.
2584.
2585.\" --------------------------------------------------------------------
2586.SS "New number registers"
2587.\" --------------------------------------------------------------------
2588.
2589The following read-only registers are available:
2590.
2591.TP
2592.B \[rs]n[.C]
25931\~if compatibility mode is in effect, 0\~otherwise.
2594.
2595.TP
2596.B \[rs]n[.cdp]
2597The depth of the last glyph added to the current environment.
2598.
2599It is positive if the glyph extends below the baseline.
2600.
2601.TP
2602.B \[rs]n[.ce]
2603The number of lines remaining to be centered, as set by the
2604.B ce
2605request.
2606.
2607.TP
2608.B \[rs]n[.cht]
2609The height of the last glyph added to the current environment.
2610.
2611It is positive if the glyph extends above the baseline.
2612.
2613.TP
2614.B \[rs]n[.color]
26151\~if colors are enabled, 0\~otherwise.
2616.
2617.TP
2618.B \[rs]n[.csk]
2619The skew of the last glyph added to the current environment.
2620.
2621The
2622.I skew
2623of a glyph is how far to the right of the center of a glyph
2624the center of an accent over that glyph should be placed.
2625.
2626.TP
2627.B \[rs]n[.ev]
2628The name or number of the current environment.
2629.
2630This is a string-valued register.
2631.
2632.TP
2633.B \[rs]n[.fam]
2634The current font family.
2635.
2636This is a string-valued register.
2637.
2638.TP
2639.B \[rs]n[.fn]
2640The current (internal) real font name.
2641.
2642This is a string-valued register.
2643.
2644If the current font is a style, the value of
2645.B \[rs]n[.fn]
2646is the proper concatenation of family and style name.
2647.
2648.TP
2649.B \[rs]n[.fp]
2650The number of the next free font position.
2651.
2652.TP
2653.B \[rs]n[.g]
2654Always\~1.
2655.
2656Macros should use this to determine whether they are running under GNU
2657troff.
2658.
2659.TP
2660.B \[rs]n[.height]
2661The current height of the font as set with
2662.BR \[rs]H .
2663.
2664.TP
2665.B \[rs]n[.hla]
2666The current hyphenation language as set by the
2667.B hla
2668request.
2669.
2670.TP
2671.B \[rs]n[.hlc]
2672The number of immediately preceding consecutive hyphenated lines.
2673.
2674.TP
2675.B \[rs]n[.hlm]
2676The maximum allowed number of consecutive hyphenated lines, as set by
2677the
2678.B hlm
2679request.
2680.
2681.TP
2682.B \[rs]n[.hy]
2683The current hyphenation flags (as set by the
2684.B hy
2685request).
2686.
2687.TP
2688.B \[rs]n[.hym]
2689The current hyphenation margin (as set by the
2690.B hym
2691request).
2692.
2693.TP
2694.B \[rs]n[.hys]
2695The current hyphenation space (as set by the
2696.B hys
2697request).
2698.
2699.TP
2700.B \[rs]n[.in]
2701The indent that applies to the current output line.
2702.
2703.TP
2704.B \[rs]n[.int]
2705Set to a positive value if last output line is interrupted (i.e., if
2706it contains
2707.IR \[rs]c ).
2708.
2709.TP
2710.B \[rs]n[.kern]
27111\~if pairwise kerning is enabled, 0\~otherwise.
2712.
2713.TP
2714.B \[rs]n[.lg]
2715The current ligature mode (as set by the
2716.B lg
2717request).
2718.
2719.TP
2720.B \[rs]n[.linetabs]
2721The current line-tabs mode (as set by the
2722.B linetabs
2723request).
2724.
2725.TP
2726.B \[rs]n[.ll]
2727The line length that applies to the current output line.
2728.
2729.TP
2730.B \[rs]n[.lt]
2731The title length as set by the
2732.B lt
2733request.
2734.
2735.TP
2736.B \[rs]n[.m]
2737The name of the current drawing color.
2738.
2739This is a string-valued register.
2740.
2741.TP
2742.B \[rs]n[.M]
2743The name of the current background color.
2744.
2745This is a string-valued register.
2746.
2747.TP
2748.B \[rs]n[.ne]
2749The amount of space that was needed in the last
2750.B ne
2751request that caused a trap to be sprung.
2752.
2753Useful in conjunction with the
2754.B \[rs]n[.trunc]
2755register.
2756.
2757.TP
2758.B \[rs]n[.ns]
27591\~if no-space mode is active, 0\~otherwise.
2760.
2761.TP
2762.B \[rs]n[.pe]
27631\~during a page ejection caused by the
2764.B bp
2765request, 0\~otherwise.
2766.
2767.TP
2768.B \[rs]n[.pn]
2769The number of the next page, either the value set by a
2770.B pn
2771request, or the number of the current page plus\~1.
2772.
2773.TP
2774.B \[rs]n[.ps]
2775The current pointsize in scaled points.
2776.
2777.TP
2778.B \[rs]n[.psr]
2779The last-requested pointsize in scaled points.
2780.
2781.TP
2782.B \[rs]n[.pvs]
2783The current post-vertical line space as set with the
2784.B pvs
2785request.
2786.
2787.TP
2788.B \[rs]n[.rj]
2789The number of lines to be right-justified as set by the
2790.B rj
2791request.
2792.
2793.TP
2794.B \[rs]n[.slant]
2795The slant of the current font as set with
2796.BR \[rs]S .
2797.
2798.TP
2799.B \[rs]n[.sr]
2800The last requested pointsize in points as a decimal fraction.
2801.
2802This is a string-valued register.
2803.
2804.TP
2805.B \[rs]n[.ss]
2806.TQ
2807.B \[rs]n[.sss]
2808These give the values of the parameters set by the first and second
2809arguments of the
2810.B ss
2811request.
2812.
2813.TP
2814.B \[rs]n[.sty]
2815The current font style.
2816.
2817This is a string-valued register.
2818.
2819.TP
2820.B \[rs]n[.tabs]
2821A string representation of the current tab settings suitable for use
2822as an argument to the
2823.B ta
2824request.
2825.
2826.TP
2827.B \[rs]n[.trunc]
2828The amount of vertical space truncated by the most recently sprung
2829vertical position trap, or, if the trap was sprung by a
2830.B ne
2831request, minus the amount of vertical motion produced by the
2832.B ne
2833request.
2834.
2835In  other  words, at the point  a  trap is  sprung,  it represents the
2836difference of  what the vertical position  would have been but for the
2837trap, and what the vertical position actually is.
2838.
2839Useful in conjunction with the
2840.B \[rs]n[.ne]
2841register.
2842.
2843.TP
2844.B \[rs]n[.U]
2845Set to 1 if in safer mode and to 0 if in unsafe mode (as given with the
2846.B \-U
2847command line option).
2848.
2849.TP
2850.B \[rs]n[.vpt]
28511\~if vertical position traps are enabled, 0\~otherwise.
2852.
2853.TP
2854.B \[rs]n[.warn]
2855The sum of the numbers associated with each of the currently enabled
2856warnings.
2857.
2858The number associated with each warning is listed in
2859.BR @g@troff (@MAN1EXT@).
2860.
2861.TP
2862.B \[rs]n[.x]
2863The major version number.
2864.
2865For example, if the version number is 1.03, then
2866.B \[rs]n[.x]
2867will contain\~1.
2868.
2869.TP
2870.B \[rs]n[.y]
2871The minor version number.
2872.
2873For example, if the version number is 1.03, then
2874.B \[rs]n[.y]
2875will contain\~03.
2876.
2877.TP
2878.B \[rs]n[.Y]
2879The revision number of groff.
2880.
2881.TP
2882.B \[rs]n[llx]
2883.TQ
2884.B \[rs]n[lly]
2885.TQ
2886.B \[rs]n[urx]
2887.TQ
2888.B \[rs]n[ury]
2889These four registers are set by the
2890.B .psbb
2891request and contain the bounding box values (in PostScript units) of a
2892given PostScript image.
2893.
2894.P
2895The following read/write registers are set by the
2896.B \[rs]w
2897escape sequence:
2898.
2899.TP
2900.B \[rs]n[rst]
2901.TQ
2902.B \[rs]n[rsb]
2903Like the
2904.B st
2905and
2906.B sb
2907registers, but take account of the heights and depths of glyphs.
2908.
2909.TP
2910.B \[rs]n[ssc]
2911The amount of horizontal space (possibly negative) that should be
2912added to the last glyph before a subscript.
2913.
2914.TP
2915.B \[rs]n[skw]
2916How far to right of the center of the last glyph in the
2917.B \[rs]w
2918argument, the center of an accent from a roman font should be placed
2919over that glyph.
2920.
2921.P
2922Other available read/write number registers are:
2923.
2924.TP
2925.B \[rs]n[c.]
2926The current input line number.
2927.B \[rs]n[.c]
2928is a read-only alias to this register.
2929.
2930.TP
2931.B \[rs]n[hours]
2932The number of hours past midnight.
2933.
2934Initialized at start-up.
2935.
2936.TP
2937.B \[rs]n[hp]
2938The current horizontal position at input line.
2939.
2940.TP
2941.B \[rs]n[minutes]
2942The number of minutes after the hour.
2943.
2944Initialized at start-up.
2945.
2946.TP
2947.B \[rs]n[seconds]
2948The number of seconds after the minute.
2949.
2950Initialized at start-up.
2951.
2952.TP
2953.B \[rs]n[systat]
2954The return value of the system() function executed by the last
2955.B sy
2956request.
2957.
2958.TP
2959.B \[rs]n[slimit]
2960If greater than\~0, the maximum number of objects on the input stack.
2961.
2962If less than or equal to\~0, there is no limit on the number of
2963objects on the input stack.
2964.
2965With no limit, recursion can continue until virtual memory is
2966exhausted.
2967.
2968.TP
2969.B \[rs]n[year]
2970The current year.
2971.
2972Note that the traditional
2973.B troff
2974number register
2975.B \[rs]n[yr]
2976is the current year minus 1900.
2977.
2978.
2979.\" --------------------------------------------------------------------
2980.SS Miscellaneous
2981.\" --------------------------------------------------------------------
2982.
2983.B @g@troff
2984predefines a single (read/write) string-based register,
2985.BR \[rs]*(.T ,
2986which contains the argument given to the
2987.B \-T
2988command line option, namely the current output device (for example,
2989.I latin1
2990or
2991.IR ascii ).
2992Note that this is not the same as the (read-only) number register
2993.B \[rs]n[.T]
2994which is defined to be\~1 if
2995.B troff
2996is called with the
2997.B \-T
2998command line option, and zero otherwise.
2999.
3000This behaviour is different to UNIX troff.
3001.
3002.P
3003Fonts not listed in the
3004.SM DESC
3005file are automatically mounted on the next available font position
3006when they are referenced.
3007.
3008If a font is to be mounted explicitly with the
3009.B fp
3010request on an unused font position, it should be mounted on the first
3011unused font position, which can be found in the
3012.B \[rs]n[.fp]
3013register; although
3014.B troff
3015does not enforce this strictly, it will not allow a font to be mounted
3016at a position whose number is much greater than that of any currently
3017used position.
3018.
3019.P
3020Interpolating a string does not hide existing macro arguments.
3021.
3022Thus in a macro, a more efficient way of doing
3023.
3024.IP
3025.BI . xx\  \[rs]\[rs]$@
3026.P
3027is
3028.
3029.IP
3030.BI \[rs]\[rs]*[ xx ]\[rs]\[rs]  
3031.
3032.P
3033If the font description file contains pairwise kerning information,
3034glyphs from that font will be kerned.
3035.
3036Kerning between two glyphs can be inhibited by placing a
3037.B \[rs]&
3038between them.
3039.
3040.P
3041In a string comparison in a condition, characters that appear at
3042different input levels to the first delimiter character will not be
3043recognised as the second or third delimiters.
3044.
3045This applies also to the
3046.B tl
3047request.
3048.
3049In a
3050.B \[rs]w
3051escape sequence, a character that appears at a different input level
3052to the starting delimiter character will not be recognised as the
3053closing delimiter character.
3054.
3055The same is true for
3056.BR \[rs]A ,
3057.BR \[rs]b ,
3058.BR \[rs]B ,
3059.BR \[rs]C ,
3060.BR \[rs]l ,
3061.BR \[rs]L ,
3062.BR \[rs]o ,
3063.BR \[rs]X ,
3064and
3065.BR \[rs]Z .
3066.
3067When decoding a macro or string argument that is delimited by double
3068quotes, a character that appears at a different input level to the starting
3069delimiter character will not be recognised as the closing delimiter
3070character.
3071.
3072The implementation of
3073.B \[rs]$@
3074ensures that the double quotes surrounding an argument will appear the
3075same input level, which will be different to the input level of the
3076argument itself.
3077.
3078In a long escape name
3079.B ]
3080will not be recognized as a closing delimiter except when it occurs at
3081the same input level as the opening
3082.BR ] .
3083.
3084In compatibility mode, no attention is paid to the input-level.
3085.
3086.P
3087There are some new types of condition:
3088.
3089.TP
3090.BI .if\ r xxx
3091True if there is a number register named
3092.IR xxx .
3093.
3094.TP
3095.BI .if\ d xxx
3096True if there is a string, macro, diversion, or request named
3097.IR xxx .
3098.
3099.TP
3100.BI .if\ m xxx
3101True if there is a color named
3102.IR xxx .
3103.
3104.TP
3105.BI .if\ c ch
3106True if there is a glyph
3107.IR ch
3108available;
3109.I ch
3110is either an
3111.SM ASCII
3112character or a glyph (special character)
3113.BI \[rs]( xx
3114or
3115.BI \[rs][ xxx ]\f[R];
3116the condition will also be true if
3117.I ch
3118has been defined by the
3119.B char
3120request.
3121.
3122.TP
3123.BI .if\ F f
3124True if font
3125.I f
3126exists.
3127.
3128.B f
3129is handled as if it was opened with the
3130.B ft
3131request (this is, font translation and styles are applied), without
3132actually mounting it.
3133.
3134.TP
3135.BI .if\ S s
3136True if style
3137.I s
3138has been registered.
3139.
3140Font translation is applied.
3141.
3142.P
3143The
3144.B tr
3145request can now map characters onto
3146.BR \[rs]~ .
3147.
3148.P
3149It is now possible to have whitespace between the first and second dot
3150(or the name of the ending macro) to end a macro definition.
3151.
3152Example:
3153.
3154.IP
3155.ne 6v+\n(.Vu
3156.ft CB
3157.nf
3158.Text .if t \[rs]{\[rs]
3159.Text .  de bar
3160.Text .    nop Hello, I'm `bar'.
3161.Text .  .
3162.Text .\[rs]}
3163.fi
3164.
3165.
3166.\" --------------------------------------------------------------------
3167.SH "INTERMEDIATE OUTPUT FORMAT"
3168.\" --------------------------------------------------------------------
3169.
3170This section describes the format output by GNU troff.
3171.
3172The output format used by GNU troff is very similar to that used
3173by Unix device-independent troff.
3174.
3175Only the differences are documented here.
3176.
3177.
3178.\" --------------------------------------------------------------------
3179.SS "Units"
3180.\" --------------------------------------------------------------------
3181.
3182The argument to the
3183.B s
3184command is in scaled points (units of
3185.RI points/ n ,
3186where
3187.I n
3188is the argument to the
3189.B sizescale
3190command  in the DESC file).
3191.
3192The argument to the
3193.B x\ Height
3194command is also in scaled points.
3195.
3196.
3197.\" --------------------------------------------------------------------
3198.SS "Text Commands"
3199.\" --------------------------------------------------------------------
3200.
3201.TP
3202.BI N n
3203Print glyph with index\~\c
3204.I n
3205(a non-negative integer) of the current font.
3206.
3207.P
3208If the
3209.B tcommand
3210line is present in the DESC file, troff will use the following two
3211commands.
3212.
3213.TP
3214.BI t xxx
3215.I xxx
3216is any sequence of characters terminated by a space or a newline (to
3217be more precise, it is a sequence of glyphs which are accessed with
3218the corresponding characters); the first character should be printed at
3219the current position, the current horizontal position should be increased
3220by the width of the first character, and so on for each character.
3221.
3222The width of the glyph is that given in the font file,
3223appropriately scaled for the current point size, and rounded so that
3224it is a multiple of the horizontal resolution.
3225.
3226Special characters cannot be printed using this command.
3227.
3228.TP
3229.BI u n\ xxx
3230This is same as the
3231.B t
3232command except that after printing each character, the current
3233horizontal position is increased by the sum of the width of that
3234character and
3235.IR n .
3236.
3237.P
3238Note that single characters can have the eighth bit set, as can the
3239names of fonts and special characters.
3240.
3241.P
3242The names of glyphs and fonts can be of arbitrary length; drivers
3243should not assume that they will be only two characters long.
3244.
3245.P
3246When a glyph is to be printed, that glyph will always be
3247in the current font.
3248.
3249Unlike device-independent troff, it is not necessary for drivers to
3250search special fonts to find a glyph.
3251.
3252.P
3253For color support, some new commands have been added:
3254.
3255.TP
3256.Text \f[B]mc \f[I]cyan magenta yellow\f[R]
3257.TQ
3258.Text \f[B]md\f[R]
3259.TQ
3260.Text \f[B]mg \f[I]gray\f[R]
3261.TQ
3262.Text \f[B]mk \f[I]cyan magenta yellow black\f[R]
3263.TQ
3264.Text \f[B]mr \f[I]red green blue\f[R]
3265Set the color components of the current drawing color, using various
3266color schemes.
3267.
3268.B md
3269resets the drawing color to the default value.
3270.
3271The arguments are integers in the range 0 to 65536.
3272.
3273.P
3274The
3275.B x
3276device control command has been extended.
3277.
3278.TP
3279.Text \f[B]x u \f[I]n\f[R]
3280If
3281.I n
3282is\~1, start underlining of spaces.
3283.
3284If
3285.I n
3286is\~0, stop underlining of spaces.
3287.
3288This is needed for the
3289.B cu
3290request in nroff mode and is ignored otherwise.
3291.
3292.
3293.\" --------------------------------------------------------------------
3294.SS "Drawing Commands"
3295.\" --------------------------------------------------------------------
3296.
3297The
3298.B D
3299drawing command has been extended.
3300.
3301These extensions will not be used by GNU pic if the
3302.B \-n
3303option is given.
3304.
3305.TP
3306.Text \f[B]Df \f[I]n\f[R]\*[ic]\[rs]n
3307Set the shade of gray to be used for filling solid objects to
3308.IR n ;
3309.I n
3310must be an integer between 0 and 1000, where 0 corresponds solid white
3311and 1000 to solid black, and values in between correspond to
3312intermediate shades of gray.
3313.
3314This applies only to solid circles, solid ellipses and solid
3315polygons.
3316.
3317By default, a level of 1000 will be used.
3318.
3319Whatever color a solid object has, it should completely obscure
3320everything beneath it.
3321.
3322A value greater than 1000 or less than 0 can also be used: this means
3323fill with the shade of gray that is currently being used for lines and
3324text.
3325.
3326Normally this will be black, but some drivers may provide a way of
3327changing this.
3328.
3329.IP
3330The corresponding
3331.BI \[rs]D'f .\|.\|. '
3332command shouldn't be used since its argument is always rounded to an
3333integer multiple of the horizontal resolution which can lead to
3334surprising results.
3335.
3336.TP
3337.Text \f[B]DC \f[I]d\f[R]\*[ic]\[rs]n
3338Draw a solid circle with a diameter of
3339.I d
3340with the leftmost point at the current position.
3341.
3342.TP
3343.Text \f[B]DE \f[I]dx dy\f[R]\*[ic]\[rs]n
3344Draw a solid ellipse with a horizontal diameter of
3345.I dx
3346and a vertical diameter of
3347.I dy
3348with the leftmost point at the current position.
3349.EQ
3350delim $$
3351.EN
3352.
3353.TP
3354.Text \f[B]Dp\f[R] $dx sub 1$ $dy sub 1$ $dx sub 2$ $dy sub 2$ $...$ $dx sub n$ $dy sub n$\[rs]n
3355Draw a polygon with, for $i = 1 ,..., n+1$, the
3356.IR i -th
3357vertex at the current position 
3358.
3359$+ sum from j=1 to i-1 ( dx sub j , dy sub j )$.
3360.
3361At the moment, GNU pic only uses this command to generate triangles
3362and rectangles.
3363.
3364.TP
3365.Text \f[B]DP\f[R] $dx sub 1$ $dy sub 1$ $dx sub 2$ $dy sub 2$ $...$ $dx sub n$ $dy sub n$\[rs]n
3366.
3367Like
3368.B Dp
3369but draw a solid rather than outlined polygon.
3370.
3371.TP
3372.Text \f[B]Dt \f[I]n\f[R]\*[ic]\[rs]n
3373Set the current line thickness to
3374.I n
3375machine units.
3376.
3377Traditionally Unix troff drivers use a line thickness proportional to
3378the current point size; drivers should continue to do this if no
3379.B Dt
3380command has been given, or if a
3381.B Dt
3382command has been given with a negative value of
3383.IR n .
3384A zero value of
3385.I n
3386selects the smallest available line thickness.
3387.
3388.P
3389A difficulty arises in how the current position should be changed after
3390the execution of these commands.
3391.
3392This is not of great importance since the code generated by GNU pic
3393does not depend on this.
3394.
3395Given a drawing command of the form
3396.IP
3397\f[B]\[rs]D\[fm]\f[I]c\f[R] $x sub 1$ $y sub 1$ $x sub 2$ $y sub 2$ $...$ $x sub n$ $y sub n$\[fm]
3398.
3399.P
3400where
3401.I c
3402is not one of
3403.BR c ,
3404.BR e ,
3405.BR l ,
3406.BR a ,
3407or
3408.BR ~ ,
3409Unix troff will treat each of the $x sub i$ as a horizontal quantity,
3410and each of the $y sub i$ as a vertical quantity and will assume that
3411the width of the drawn object is $sum from i=1 to n x sub i$,
3412and that the height is $sum from i=1 to n y sub i$.
3413.
3414(The assumption about the height can be seen by examining the
3415.B st
3416and
3417.B sb
3418registers after using such a
3419.B D
3420command in a \[rs]w escape sequence).
3421.
3422This rule also holds for all the original drawing commands with the
3423exception of
3424.BR De .
3425For the sake of compatibility GNU troff also follows this rule, even
3426though it produces an ugly result in the case of the
3427.B Dt
3428and
3429.BR Df ,
3430and, to a lesser extent,
3431.B DE
3432commands.
3433.
3434Thus after executing a
3435.B D
3436command of the form
3437.IP
3438\f[B]D\f[I]c\f[R] $x sub 1$ $y sub 1$ $x sub 2$ $y sub 2$ $...$ \c
3439$x sub n$ $y sub n$\[rs]n
3440.
3441.P
3442the current position should be increased by
3443.
3444$( sum from i=1 to n x sub i , sum from i=1 to n y sub i )$.
3445.
3446.P
3447Another set of extensions is
3448.
3449.TP
3450.Text \f[B]DFc \f[I]cyan magenta yellow\f[R]\*[ic]\[rs]n
3451.TQ
3452.Text \f[B]DFd\f[R]\*[ic]\[rs]n
3453.TQ
3454.Text \f[B]DFg \f[I]gray\f[R]\*[ic]\[rs]n
3455.TQ
3456.Text \f[B]DFk \f[I]cyan magenta yellow black\f[R]\*[ic]\[rs]n
3457.TQ
3458.Text \f[B]DFr \f[I]red green blue\f[R]\*[ic]\[rs]n
3459Set the color components of the filling color similar to the
3460.B m
3461commands above.
3462.
3463.P
3464The current position isn't changed by those colour commands (contrary to
3465.BR Df ).
3466.
3467.
3468.\" --------------------------------------------------------------------
3469.SS "Device Control Commands"
3470.\" --------------------------------------------------------------------
3471.
3472There is a continuation convention which permits the argument to the
3473.B x\ X
3474command to contain newlines: when outputting the argument to the
3475.B x\ X
3476command, GNU troff will follow each newline in the argument with a
3477.B +
3478character (as usual, it will terminate the entire argument with a
3479newline); thus if the line after the line containing the
3480.B x\ X
3481command starts with
3482.BR + ,
3483then the newline ending the line containing the
3484.B x\ X
3485command should be treated as part of the argument to the
3486.B x\ X
3487command, the
3488.B +
3489should be ignored, and the part of the line following the
3490.B +
3491should be treated like the part of the line following the
3492.B x\ X
3493command.
3494.
3495.P
3496The first three output commands are guaranteed to be:
3497.IP
3498.BI x\ T\  device
3499.br
3500.BI x\ res\  n\ h\ v
3501.br
3502.B x init
3503.
3504.
3505.\" --------------------------------------------------------------------
3506.SH INCOMPATIBILITIES
3507.\" --------------------------------------------------------------------
3508.
3509In spite of the many extensions, groff has retained compatibility to
3510classical troff to a large degree.
3511.
3512For the cases where the extensions lead to collisions, a special
3513compatibility mode with the restricted, old functionality was created
3514for groff.
3515.
3516.
3517.\" --------------------------------------------------------------------
3518.SS "Groff Language"
3519.\" --------------------------------------------------------------------
3520.
3521.I groff
3522provides a
3523.B compatibility mode
3524that allows to process roff code written for classical
3525.B troff
3526or for other implementations of roff in a consistent way.
3527.
3528.P
3529Compatibility mode can be turned on with the
3530.option \-C
3531command line option, and turned on or off with the
3532.request .cp
3533request.
3534.
3535The number register
3536.esc n(.C
3537is\~1 if compatibility mode is on, 0\~otherwise.
3538.
3539.P
3540This became necessary because the GNU concept for long names causes
3541some incompatibilities.
3542.I Classical troff
3543interprets
3544.IP
3545.request .dsabcd
3546.
3547.P
3548as defining a string
3549.B ab
3550with contents
3551.BR cd .
3552In
3553.IR groff
3554mode, this will be considered as a call of a macro named
3555.request dsabcd .
3556.
3557.P
3558Also
3559.I classical troff
3560interprets
3561.esc *[
3562or
3563.esc n[
3564as references to a string or number register called
3565.request [
3566while
3567.I groff
3568takes this as the start of a long name.
3569.
3570.P
3571In
3572.IR "compatibility mode" ,
3573groff interprets these things in the traditional way; so long
3574names are not recognized.
3575.
3576.P
3577On the other hand, groff in
3578.I GNU native mode
3579does not allow to use the single-character escapes
3580.esc \[rs]
3581(backslash),
3582.esc |
3583(vertical bar),
3584.esc ^
3585(caret),
3586.esc &
3587(ampersand),
3588.esc {
3589(opening brace),
3590.esc }
3591(closing brace),
3592.squoted "\[rs]\ "
3593(space),
3594.esc '
3595(single quote),
3596.esc `
3597(backquote),
3598.esc \-
3599(minus),
3600.esc _
3601(underline),
3602.esc !
3603(bang),
3604.esc %
3605(percent),
3606and
3607.esc c
3608(character c) in names of strings, macros, diversions, number
3609registers, fonts or environments, whereas
3610.I classical troff
3611does.
3612.
3613.P
3614The
3615.esc A
3616escape sequence can be helpful in avoiding these escape sequences in
3617names.
3618.
3619.P
3620Fractional pointsizes cause one noteworthy incompatibility.
3621.
3622In
3623.I classical
3624.IR troff ,
3625the
3626.request ps
3627request ignores scale indicators and so
3628.RS
3629.P
3630.B .ps\~10u
3631.RE
3632.
3633.P
3634will set the pointsize to 10\~points, whereas in groff native mode the
3635pointsize will be set to 10\~scaled points.
3636.
3637.P
3638In
3639.IR groff ,
3640there is a fundamental difference between unformatted input
3641characters, and formatted output characters (glyphs).
3642.
3643Everything that affects how a glyph will be output is
3644stored with the glyph; once a glyph has been
3645constructed it is unaffected by any subsequent requests that are
3646executed, including the
3647.request bd ,
3648.request cs ,
3649.request tkf ,
3650.request tr ,
3651or
3652.request fp
3653requests.
3654.
3655.P
3656Normally glyphs are constructed from input characters at
3657the moment immediately before the glyph is added to the current
3658output line.
3659.
3660Macros, diversions and strings are all, in fact, the same type of
3661object; they contain lists of input characters and glyphs
3662in any combination.
3663.
3664.P
3665Special characters can be both; before being added to the output, they
3666act as input entities, afterwards they denote glyphs.
3667.
3668.P
3669A glyph does not behave like an input character for the
3670purposes of macro processing; it does not inherit any of the special
3671properties that the input character from which it was constructed
3672might have had.
3673.
3674The following example will make things clearer.
3675.
3676.P
3677.RS
3678.nf
3679.ft CB
3680.Text .di x
3681.Text \[rs]\[rs]\[rs]\[rs]
3682.Text .br
3683.Text .di
3684.Text .x
3685.ft
3686.fi
3687.RE
3688.
3689.P
3690With
3691.I GNU troff
3692this will be printed as
3693.esc \[rs] .
3694So each pair of input backslashes
3695.squoted \[rs]\[rs]
3696is turned into a single output backslash glyph
3697.squoted \[rs]
3698and the resulting output backslashes are not interpreted as escape
3699characters when they are reread.
3700.
3701.P
3702.I Classical troff
3703would interpret them as escape characters when they were reread and
3704would end up printing a single backslash
3705.squoted \[rs] .
3706.
3707.P
3708In GNU, the correct way to get a printable version of the backslash
3709character
3710.squoted \[rs]
3711is the
3712.esc (rs
3713escape sequence, but classical troff does not provide a clean feature
3714for getting a non-syntactical backslash.
3715.
3716A close method is the printable version of the current escape
3717character using the
3718.esc e
3719escape sequence; this works if the current escape character is not
3720redefined.
3721.
3722It works in both GNU mode and compatibility mode, while dirty tricks
3723like specifying a sequence of multiple backslashes do not work
3724reliably; for the different handling in diversions, macro definitions,
3725or text mode quickly leads to a confusion about the necessary number of
3726backslashes.
3727.
3728.P
3729To store an escape sequence in a diversion that will be interpreted
3730when the diversion is reread, either the traditional
3731.esc !
3732transparent output facility or the
3733new
3734.esc ?
3735escape sequence can be used.
3736.
3737.
3738.\" --------------------------------------------------------------------
3739.SS "Intermediate Output"
3740.\" --------------------------------------------------------------------
3741.
3742The groff intermediate output format is in a state of evolution.
3743.
3744So far it has some incompatibilities, but it is intended to establish
3745a full compatibility to the classical troff output format.
3746.
3747Actually the following incompatibilities exist:
3748.
3749.Topic
3750The positioning after the drawing of the polygons conflicts with the
3751classical definition.
3752.
3753.Topic
3754The intermediate output cannot be rescaled to other devices as
3755classical "device-independent" troff did.
3756.
3757.
3758.\" --------------------------------------------------------------------
3759.SH AUTHORS
3760.\" --------------------------------------------------------------------
3761.
3762Copyright (C) 1989, 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
3763.
3764.P
3765This document is distributed under the terms of the FDL (GNU Free
3766Documentation License) version 1.1 or later.
3767.
3768You should have received a copy of the FDL on your system, it is also
3769available on-line at the
3770.URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" .
3771.
3772This document was written by James Clark, with modifications by
3773.MTO wl@gnu.org "Werner Lemberg"
3774and
3775.MTO bwarken@mayn.de "Bernd Warken" .
3776.
3777.P
3778This document is part of
3779.IR groff ,
3780the GNU roff distribution.
3781.
3782Formerly, the contents of this document was kept in the manual
3783page
3784.BR @g@troff (@MAN1EXT@).
3785Only the parts dealing with the language aspects of the different
3786.I roff
3787systems were carried over into this document.
3788.
3789The
3790.I troff
3791command line options and warnings are still documented in
3792.BR @g@troff (@MAN1EXT@).
3793.
3794.\" --------------------------------------------------------------------
3795.SH "SEE ALSO"
3796.\" --------------------------------------------------------------------
3797.
3798The
3799.I groff info
3800.IR file ,
3801cf.\&
3802.BR info (1)
3803presents all groff documentation within a single document.
3804.
3805.TP
3806.BR groff (@MAN1EXT@)
3807A list of all documentation around
3808.IR groff .
3809.
3810.TP
3811.BR groff (@MAN7EXT@)
3812A description of the
3813.I groff
3814language, including a short, but complete reference of all predefined
3815requests, registers, and escapes of plain
3816.IR groff .
3817From the command line, this is called using
3818.
3819.IP
3820.ShellCommand man\~7\~groff
3821.
3822.TP
3823.BR roff (@MAN7EXT@)
3824A survey of
3825.I roff
3826systems, including pointers to further historical documentation.
3827.
3828.TP
3829.RI [ CSTR\~#54\/ ]
3830The
3831.I Nroff/\:Troff User's Manual
3832by
3833.I J.\& F.\& Osanna
3834of 1976 in the revision of
3835.I Brian Kernighan
3836of 1992, being the
3837.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:54.ps.gz \
3838     "classical troff documentation" .
3839.
3840.cp \n[groff_diff_C]
3841.
3842.\" --------------------------------------------------------------------
3843.\" Emacs variables
3844.\" --------------------------------------------------------------------
3845.
3846.\" Local Variables:
3847.\" mode: nroff
3848.\" End: