/contrib/groff/man/groff_diff.man

Large files files are truncated, but you can click here to view the full 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]
2628…

Large files files are truncated, but you can click here to view the full file