PageRenderTime 103ms CodeModel.GetById 75ms app.highlight 16ms RepoModel.GetById 1ms app.codeStats 1ms

/contrib/groff/man/groff.man

https://bitbucket.org/freebsd/freebsd-head/
Unknown | 3564 lines | 3559 code | 5 blank | 0 comment | 0 complexity | 654730c758ce818da6b15e673ea49876 MD5 | raw file

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

   1'\" t
   2.ig
   3groff.man
   4
   5Last update: 17 Feb 2005
   6
   7This file is part of groff, the GNU roff type-setting system.
   8
   9Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005
  10  Free Software Foundation, Inc.
  11written by Bernd Warken <bwarken@mayn.de>
  12maintained by Werner Lemberg <wl@gnu.org>
  13
  14Permission is granted to copy, distribute and/or modify this document
  15under the terms of the GNU Free Documentation License, Version 1.1 or
  16any later version published by the Free Software Foundation; with the
  17Invariant Sections being this .ig-section and AUTHORS, with no
  18Front-Cover Texts, and with no Back-Cover Texts.
  19
  20A copy of the Free Documentation License is included as a file called
  21FDL in the main directory of the groff source package.
  22..
  23.
  24.\" --------------------------------------------------------------------
  25.\" Setup
  26.\" --------------------------------------------------------------------
  27.
  28.do nr groff_C \n[.C]
  29.cp 0
  30.
  31.mso www.tmac
  32.
  33.if n \{\
  34.  mso tty-char.tmac
  35.  ftr CR R
  36.  ftr CI I
  37.  ftr CB B
  38.\}
  39.
  40.if '\*[.T]'dvi' \{\
  41.  ftr CB CW
  42.\}
  43.
  44.
  45.\" --------------------------------------------------------------------
  46.\" start of macro definitions
  47.eo
  48.
  49.de c
  50..
  51.
  52.de TPx
  53.  TP 10n
  54..
  55.c ---------------------------------------------------------------------
  56.c .Text anything ...
  57.c
  58.c All arguments are printed as text.
  59.c
  60.de Text
  61.  nop \)\$*
  62..
  63.c ---------------------------------------------------------------------
  64.c .ExecFF macro font1 font2 text1 text2 text1 text2 ...
  65.c
  66.c Concat text arguments using alternating fonts and feed into macro.
  67.c For a trailing punctuation, terminate the call with \c.
  68.c
  69.de ExecFF
  70.  if (\n[.$] < 4) \
  71.    return
  72.  ds @a\"
  73.  ds @m \$1\"
  74.  ds @f1 \$2\"
  75.  ds @f2 \$3\"
  76.  shift 3
  77.  ds @s\"
  78.  while 1 \{\
  79.    if (\n[.$] = 0) \
  80.      break
  81.    ds @a \$1\"
  82.    as @s \f[\*[@f1]]\*[@a]\f[]\"
  83.    shift
  84.    if (\n[.$] = 0) \
  85.      break
  86.    ds @a \$1\"
  87.    as @s \f[\*[@f2]]\*[@a]\f[]\"
  88.    shift
  89.  \}
  90.  \*[@m] "\*[@s]\f[R]"
  91.  ft P                 \" to make \c happy
  92.  rm @m
  93.  rm @s
  94.  rm @a
  95.  rm @f1
  96.  rm @f2
  97..
  98.
  99.c --------- command line option ---------
 100.
 101.de option
 102.  Text \f[CB]\$*
 103.  ft P
 104..
 105.
 106.c --------- characters ---------
 107.
 108.de character
 109.  ExecFF Text CB R \$*
 110..
 111.de squoted_char
 112.  ds @1 \$1\"
 113.  shift
 114.  ExecFF Text R CB \[oq] \*[@1] "\[cq]\$*"
 115.  rm @1
 116..
 117.de dquoted_char
 118.  ds @1 \$1\"
 119.  shift
 120.  ExecFF Text R CB \[lq] \*[@1] "\[rq]\$*"
 121.  rm @1
 122..
 123.c --------- requests ---------
 124.
 125.c synopsis of a request
 126.de REQ
 127.  if (\n[.$] = 0) \
 128.    return
 129.  ds @1 \$1\"
 130.  shift 1
 131.  ie (\n[.$] = 0) \{\
 132.    TP 10n
 133.    Text \f[CB]\*[@1]\f[]
 134.  \}
 135.  el \{\
 136.    TP 10n
 137.    Text \f[CB]\*[@1]\~\f[]\f[I]\$*\f[]
 138.  \}
 139.  rm @1
 140..
 141.c reference of a request
 142.de request
 143.  BR \$*
 144..
 145.
 146.c --------- numerical elements ---------
 147.
 148.c number with a trailing unit
 149.de scalednumber
 150.  Text \$1\^\f[CB]\$2\f[]\$3\f[R]
 151.  ft P
 152..
 153.
 154.c representation of units within the text
 155.de scaleindicator
 156.  Text \f[CB]\$1\f[]\$2\f[R]
 157.  ft P
 158..
 159.
 160.c representation of mathematical operators within the text
 161.de operator
 162.  squoted_char \$@
 163..
 164.
 165.
 166.c --------- escape sequences ---------
 167.
 168.c ---------------------------------------------------------------------
 169.c .ESC name [arg]
 170.c
 171.c Synopsis of an escape sequence, optionally with argument
 172.c Args   : 1 or 2; `name' obligatory, `arg' optional
 173.c   name : suitable name for an escape sequence (c, (xy, [long])
 174.c   arg  : arbitrary word
 175.c Result : prints \namearg, where `name' is in CB, `arg' in I
 176.c
 177.de ESC
 178.  if (\n[.$] < 1)
 179.    ab .ESC needs 1 or 2 arguments.
 180.  ExecFF IP CB I "\[rs]\$1" "\,\$2\/"
 181..
 182.c ---------------------------------------------------------------------
 183.c .ESC[] name arg
 184.c
 185.c Synopsis for escape sequence with a bracketed long argument
 186.c Args   : 2 obligatory
 187.c   name : suitable name for an escape sequence (c, (xy, [long])
 188.c   arg  : arbitrary text
 189.c Result : prints \name[arg], where `name' is in CB, `arg' in I
 190.c
 191.de ESC[]
 192.  if !(\n[.$] = 2) \
 193.    ab .ESC[] needs exactly 2 arguments.
 194.  ExecFF IP CB I "\[rs]\$1\[lB]" "\h'-0.2m'\$2\h'-0.15m'" \[rB]
 195..
 196.c ---------------------------------------------------------------------
 197.c .ESCq name arg
 198.c
 199.c Synopsis for escape sequence with a bracketed long argument
 200.c Args   : 2 obligatory
 201.c   name : suitable name for an escape sequence (c, (xy, [long])
 202.c   arg  : arbitrary text
 203.c Result : prints \name'arg', where `name' is in CB, `arg' in I
 204.c
 205.de ESCq
 206.  if !(\n[.$] = 2) \
 207.    ab .ESCq needs exactly 2 argument.
 208.  ExecFF IP CB I "\[rs]\$1\[cq]" "\h'-0.3m'\$2" \[cq]
 209..
 210.c ---------------------------------------------------------------------
 211.c .ESC? arg
 212.c
 213.c Synopsis for escape sequence with a bracketed long argument
 214.c Args   : 1 obligatory
 215.c   arg  : arbitrary text
 216.c Result : prints `\?arg?', where the `?' are in CB, `arg' in I
 217.c
 218.de ESC?
 219.  if !(\n[.$] = 1) \
 220.    ab .ESC? needs exactly 1 arguments.
 221.  ExecFF IP CB I \[rs]? "\$1" ?
 222..
 223.c ---------------------------------------------------------------------
 224.c .esc name [punct]
 225.c
 226.c Reference of an escape sequence (no args), possibly punctuation
 227.c Args    : 1 obligatory
 228.c   name  : suitable name for an escape sequence (c, (xy, [long])
 229.c   punct : arbitrary
 230.c Result  : prints \name, where `name' is in B, `punct' in R
 231.c
 232.de esc
 233.  if (\n[.$] < 1) \
 234.    ab .esc needs 1 or 2 arguments.
 235.  BR "\[rs]\$1" \$2
 236..
 237.c ---------------------------------------------------------------------
 238.c .escarg name arg [punct]
 239.c
 240.c Reference of an escape sequence (no args)
 241.c Args    : 1 obligatory, 1 optional
 242.c   name  : suitable name for an escape sequence (c, (xy, [long])
 243.c   arg   : arbitrary word
 244.c Result  : prints \namearg, where
 245.c           `name' is in B, `arg' in I
 246.c
 247.de escarg
 248.  if (\n[.$] < 2) \
 249.    ab .esc needs 2 or 3 arguments.
 250.  Text \f[B]\[rs]\$1\f[]\f[I]\$2\f[]\$3
 251..
 252.c ---------------------------------------------------------------------
 253.c .esc[] name arg [punct]
 254.c
 255.c Reference for escape sequence with a bracketed long argument
 256.c Args   : 2 obligatory
 257.c   name : suitable name for an escape sequence (c, (xy, [long])
 258.c   arg  : arbitrary text
 259.c Result : prints \name[arg], where `name' is in CB, `arg' in CI
 260.c
 261.de esc[]
 262.  if (\n[.$] < 2) \
 263.    ab .esc[] needs 2 or 3 arguments.
 264.  Text \f[B]\[rs]\$1\[lB]\f[]\f[I]\$2\f[]\f[B]\[rB]\f[]\$3
 265..
 266.
 267.c ---------------------------------------------------------------------
 268.c .escq name arg
 269.c
 270.c Reference for escape sequence with a bracketed long argument
 271.c Args   : 2 obligatory
 272.c   name : suitable name for an escape sequence (c, (xy, [long])
 273.c   arg  : arbitrary text
 274.c Result : prints \name'arg', where `name' is in CB, `arg' in CI
 275.c
 276.de escq
 277.  if (\n[.$] < 2) \
 278.    ab .escq needs 2 arguments.
 279.  Text \f[B]\[rs]\$1\[cq]\f[]\f[I]\$2\f[]\f[B]\[cq]\f[]\$3
 280..
 281.
 282.c --------- strings ---------
 283.
 284.c synopsis for string, with \*[]
 285.de STRING
 286.  ds @1 \$1\"
 287.  shift 1
 288.  TP 10n
 289.  ExecFF Text R CB \[rs]*[ \*[@1]\f[]\f[R]] \$*
 290.  rm @1
 291..
 292.c synopsis for a long string
 293.de string
 294.  if (\n[.$] = 0) \
 295.    return
 296.  Text \f[CB]\[rs]*\[lB]\$1\[rB]\f[]\$2
 297..
 298.
 299.
 300.c --------- registers ---------
 301.
 302.c synopsis for registers, with \n[]
 303.de REG
 304.  ds @1 \$1\"
 305.  shift 1
 306.  TP 10n
 307.  ExecFF Text R CB \[rs]n[ \*[@1]\f[]\f[R]] \$*
 308.  rm @1
 309..
 310.c reference of a register, without decoration
 311.de register
 312.  Text register
 313.  BR \$*
 314..
 315.
 316.ec
 317.\" end of macro definitions
 318.
 319.
 320.\" --------------------------------------------------------------------
 321.\" Title
 322.\" --------------------------------------------------------------------
 323.
 324.TH GROFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
 325.SH NAME
 326groff \- a short reference for the GNU roff language
 327.
 328.
 329.\" --------------------------------------------------------------------
 330.SH DESCRIPTION
 331.\" --------------------------------------------------------------------
 332.
 333The name
 334.I groff
 335stands for
 336.I GNU roff
 337and is the free implementation of the roff type-setting system.
 338.
 339See
 340.BR roff (@MAN7EXT@)
 341for a survey and the background of the groff system.
 342.
 343.P
 344This document gives only short descriptions of the predefined roff
 345language elements as used in groff.
 346.
 347Both the classical features and the groff extensions are provided.
 348.
 349.P
 350Historically, the
 351.I roff language
 352was called
 353.IR troff .
 354.I groff
 355is compatible with the classical system and provides proper
 356extensions.
 357.
 358So in GNU, the terms
 359.IR roff ,
 360.IR troff ,
 361and
 362.I groff language
 363could be used as synonyms.
 364.
 365However
 366.I troff
 367slightly tends to refer more to the classical aspects, whereas
 368.I groff
 369emphasizes the GNU extensions, and
 370.I roff
 371is the general term for the language.
 372.
 373.P
 374This file is only a short version of the complete documentation that
 375is found in the
 376.I groff
 377.BR info (1)
 378file, which contains more detailed, actual, and concise information.
 379.
 380.P
 381The general syntax for writing groff documents is relatively easy, but
 382writing extensions to the roff language can be a bit harder.
 383.
 384.P
 385The roff language is line-oriented.
 386.
 387There are only two kinds of lines, control lines and text lines.
 388.
 389The control lines start with a control character, by default a period
 390.dquoted_char .
 391or a single quote
 392.dquoted_char ' ;
 393all other lines are text lines.
 394.
 395.P
 396.B Control lines
 397represent commands, optionally with arguments.
 398.
 399They have the following syntax.
 400.
 401The leading control character can be followed by a command name;
 402arguments, if any, are separated by blanks from the command name and
 403among themselves, for example,
 404.RS
 405.
 406.P
 407.Text .command_name arg1 arg2
 408.RE
 409.
 410.P
 411For indentation, any number of space or tab characters can be inserted
 412between the leading control character and the command name, but the
 413control character must be on the first position of the line.
 414.
 415.P
 416.B Text lines
 417represent the parts that will be printed.
 418They can be modified by escape sequences, which are recognized by a
 419leading backslash
 420.squoted_char \[rs] .
 421These are in-line or even in-word formatting elements or functions.
 422.
 423Some of these take arguments separated by single quotes
 424.dquoted_char ' ,
 425others are regulated by a length encoding introduced by an open
 426parenthesis
 427.squoted_char (
 428or enclosed in brackets
 429.squoted_char [
 430and
 431.squoted_char ] .
 432.
 433.P
 434The roff language provides flexible instruments for writing language
 435extension, such as macros.
 436.
 437When interpreting macro definitions, the roff system enters a special
 438operating mode, called the
 439.BR "copy mode" .
 440.
 441.P
 442The copy mode behavior can be quite tricky, but there are some rules
 443that ensure a safe usage.
 444.
 445.IP 1.
 446Printable backslashes must be denoted as
 447.esc e .
 448To be more precise,
 449.esc e
 450represents the current escape character.
 451.
 452To get a backslash glyph, use
 453.esc (rs
 454or
 455.esc [rs] .
 456.IP 2.
 457Double all backslashes.
 458.IP 3.
 459Begin all text lines with the special non-spacing character
 460.esc & .
 461.
 462.P
 463This does not produce the most efficient code, but it should work as a
 464first measure.
 465.
 466For better strategies, see the groff info file and
 467.BR groff_tmac (@MAN5EXT@).
 468.
 469.P
 470Reading roff source files is easier, just reduce all double backslashes
 471to a single one in all macro definitions.
 472.
 473.
 474.\" --------------------------------------------------------------------
 475.SH "GROFF ELEMENTS"
 476.\" --------------------------------------------------------------------
 477.
 478The roff language elements add formatting information to a text file.
 479.
 480The fundamental elements are predefined commands and variables that
 481make roff a full-blown programming language.
 482.
 483.P
 484There are two kinds of roff commands, possibly with arguments.
 485.B Requests
 486are written on a line of their own starting with a dot
 487.squoted_char .
 488or a
 489.dquoted_char ' ,
 490whereas
 491.B Escape sequences
 492are in-line functions and in-word formatting elements starting with a
 493backslash
 494.squoted_char \[rs] .
 495.
 496.P
 497The user can define her own formatting commands using the
 498.request de
 499request.
 500.
 501These commands are called
 502.BR macros ,
 503but they are used exactly like requests.
 504.
 505Macro packages are pre-defined sets of macros written in the groff
 506language.
 507.
 508A user's possibilities to create escape sequences herself is very
 509limited, only special characters can be mapped.
 510.
 511.P
 512The groff language provides several kinds of variables with
 513different interfaces.
 514.
 515There are pre-defined variables, but the user can define her own
 516variables as well.
 517.
 518.P
 519.B String
 520variables store character sequences.
 521.
 522They are set with the
 523.request ds
 524request and retrieved by the
 525.esc *
 526escape sequences.
 527.
 528Strings can have variables.
 529.
 530.P
 531.B Register
 532variables can store numerical values, numbers with a scale unit, and
 533occasionally string-like objects.
 534.
 535They are set with the
 536.request nr
 537request and retrieved by the
 538.esc n
 539escape sequences.
 540.
 541.P
 542.B Environments
 543allow the user to temporarily store global formatting parameters like
 544line length, font size, etc.\& for later reuse.
 545.
 546This is done by the
 547.request ev
 548request.
 549.
 550.P
 551.B Fonts
 552are identified either by a name or by an internal number.
 553.
 554The current font is chosen by the
 555.request ft
 556request or by the
 557.esc f
 558escape sequences.
 559.
 560Each device has special fonts, but the following fonts are available
 561for all devices.
 562.B R
 563is the standard font Roman.
 564.B B
 565is its
 566.B bold
 567counterpart.
 568.
 569The
 570.I italic
 571font is called
 572.B I
 573and is available everywhere, but on text devices it is displayed as an
 574underlined Roman font.
 575.
 576For the graphical output devices, there exist constant-width pendants
 577of these fonts,
 578.BR CR ,
 579.BR CI ,
 580and
 581.BR CB .
 582On text devices, all characters have a constant width anyway.
 583.
 584.P
 585Moreover, there are some advanced roff elements.
 586.
 587A
 588.B diversion
 589stores information into a macro for later usage.
 590.
 591A
 592.B trap
 593is a positional condition like a certain number of lines from page top
 594or in a diversion or in the input.
 595.
 596Some action can be prescribed to be run automatically when the
 597condition is met.
 598.
 599.P
 600More detailed information and examples can be found in the groff info
 601file.
 602.
 603.
 604.\" --------------------------------------------------------------------
 605.SH "CONTROL CHARACTERS"
 606.\" --------------------------------------------------------------------
 607.
 608There is a small set of characters that have a special controlling
 609task in certain conditions.
 610.
 611.TP
 612.character .
 613A dot is only special at the beginning of a line or after the
 614condition in the requests
 615.request if ,
 616.request ie ,
 617.request el ,
 618and
 619.request while .
 620There it is the control character that introduces a request (or macro).
 621.
 622The special behavior can be delayed by using the
 623.esc .
 624escape.
 625.
 626By using the 
 627.request cc
 628request, the control character can be set to a different character,
 629making the dot
 630.squoted_char .
 631a non-special character.
 632.IP ""
 633In all other positions, it just means a dot character.
 634.
 635In text paragraphs, it is advantageous to start each sentence at a
 636line of its own.
 637.
 638.TP
 639.character '
 640The single quote has two controlling tasks.
 641.
 642At the beginning of a line and in the conditional requests it is the
 643non-breaking control character.
 644.
 645That means that it introduces a request like the dot, but with the
 646additional property that this request doesn't cause a linebreak.
 647.
 648By using the 
 649.request c2
 650request, the non-break control character can be set to a different
 651character.
 652.
 653.IP ""
 654As a second task, it is the most commonly used argument separator in
 655some functional escape sequences (but any pair of characters not part
 656of the argument will work).
 657.
 658In all other positions, it denotes the single quote or apostrophe
 659character.
 660.
 661Groff provides a printable representation with the
 662.esc (cq
 663escape sequence.
 664.
 665.TP
 666.character \[dq]
 667The double quote is used to enclose arguments in requests, macros, and
 668strings.
 669.
 670In the
 671.request ds
 672and
 673.request as
 674requests, a leading double quote in the argument will be stripped off,
 675making everything else afterwards the string to be defined (enabling
 676leading whitespace).
 677.
 678The escaped double quote
 679.esc \[dq]
 680introduces a comment.
 681.
 682Otherwise, it is not special.
 683.
 684Groff provides a printable representation with the
 685.esc (dq
 686escape sequence.
 687.
 688.TP
 689.character \[rs]
 690The backslash usually introduces an escape sequence (this can be
 691changed with the
 692.request ec
 693request).
 694.
 695A printed version of the escape character is the
 696.esc e
 697escape; a backslash glyph can be obtained by
 698.esc (rs .
 699.TP
 700.character (
 701The open parenthesis is only special in escape sequences when
 702introducing an escape name or argument consisting of exactly two
 703characters.
 704.
 705In groff, this behavior can be replaced by the \f[CB][]\f[] construct.
 706.TP
 707.character [
 708The opening bracket is only special in groff escape sequences; there
 709it is used to introduce a long escape name or long escape argument.
 710.
 711Otherwise, it is non-special, e.g.\& in macro calls.
 712.TP
 713.character ]
 714The closing bracket is only special in groff escape sequences; there
 715it terminates a long escape name or long escape argument.
 716.
 717Otherwise, it is non-special.
 718.TP
 719\f[CI]space\f[]
 720Space characters are only functional characters.
 721.
 722They separate the arguments in requests, macros, and strings, and the words
 723in text lines.
 724.
 725They are subject to groff's horizontal spacing calculations.
 726.
 727To get a defined space width, escape sequences like
 728.squoted_char "\[rs]\ "
 729(this is the escape character followed by a space),
 730.esc | ,
 731.esc ^ ,
 732or
 733.esc h
 734should be used.
 735.
 736.IP \f[CI]newline\f[]
 737In text paragraphs, newlines mostly behave like space characters.
 738.
 739Continuation lines can be specified by an escaped newline, i.e., by
 740specifying a backslash
 741.squoted_char \[rs]
 742as the last character of a line.
 743.IP \f[CI]tab\f[]
 744If a tab character occurs during text the interpreter makes a
 745horizontal jump to the next pre-defined tab position.
 746.
 747There is a sophisticated interface for handling tab positions.
 748.
 749.
 750.\" --------------------------------------------------------------------
 751.SH "NUMERICAL EXPRESSIONS"
 752.\" --------------------------------------------------------------------
 753.
 754A
 755.B numerical value
 756is a signed or unsigned integer or float with or without an appended
 757scaling indicator.
 758.
 759A
 760.B scaling indicator
 761is a one-character abbreviation for a unit of measurement.
 762.
 763A number followed by a scaling indicator signifies a size value.
 764.
 765By default, numerical values do not have a scaling indicator, i.e., they
 766are normal numbers.
 767.
 768.P
 769The
 770.I roff
 771language defines the following scaling indicators.
 772.
 773.
 774.P
 775.PD 0
 776.RS
 777.
 778.TPx
 779.B c
 780Centimeter
 781.
 782.TPx
 783.B i
 784Inch
 785.
 786.TPx
 787.B P
 788Pica\ \[eq]\ 1/6\ inch
 789.
 790.TPx
 791.B p
 792Point\ \[eq]\ 1/72\ inch
 793.
 794.TPx
 795.B m
 796Em\ \[eq]\ \f[R]the font size in points (width of letter `\f[CR]m\f[R]')
 797.
 798.TPx
 799.B M
 800100\^th \f[R]of an \f[CR]Em
 801.
 802.TPx
 803.B n
 804En\ \[eq]\ Em/2
 805.
 806.TPx
 807.B u
 808Basic unit for actual output device
 809.
 810.TPx
 811.B v
 812Vertical line space in basic units
 813scaled point\ \[eq]\ 1/\f[CI]sizescale\f[R] of a point (defined in
 814font \f[I]DESC\f[] file)
 815.
 816.TPx
 817.B f
 818Scale by 65536.
 819.RE
 820.PD
 821.
 822.P
 823.B Numerical expressions
 824are combinations of the numerical values defined above with the
 825following arithmetical operators already defined in classical troff.
 826.
 827.P
 828.PD 0
 829.RS
 830.
 831.TPx
 832.B +
 833Addition
 834.
 835.TPx
 836.B \-
 837Subtraction
 838.
 839.TPx
 840.B *
 841Multiplication
 842.
 843.TPx
 844.B /
 845Division
 846.
 847.TPx
 848.B %
 849Modulo
 850.
 851.TPx
 852.B =
 853Equals
 854.
 855.TPx
 856.B ==
 857Equals
 858.
 859.TPx
 860.B <
 861Less than
 862.
 863.TPx
 864.B >
 865Greater than
 866.
 867.TPx
 868.B <=
 869Less or equal
 870.
 871.TPx
 872.B >=
 873Greater or equal
 874.
 875.TPx
 876.B &
 877Logical and
 878.
 879.TPx
 880.B :
 881Logical or
 882.
 883.TPx
 884.B !
 885Logical not
 886.
 887.TPx
 888.B (
 889Grouping of expressions
 890.
 891.TPx
 892.B )
 893Close current grouping
 894.
 895.RE
 896.PD
 897.
 898.P
 899Moreover,
 900.I groff
 901added the following operators for numerical expressions:
 902.
 903.P
 904.PD 0
 905.RS
 906.
 907.TPx
 908.ExecFF Text I CB e1 >? e2
 909The maximum of
 910.I e1
 911and
 912.IR e2 .
 913.
 914.TPx
 915.ExecFF Text I CB e1 <? e2
 916The minimum of
 917.I e1
 918and
 919.IR e2 .
 920.
 921.TPx
 922.ExecFF Text CB I ( c ; e )
 923Evaluate
 924.I e
 925using
 926.I c
 927as the default scaling indicator.
 928.
 929.RE
 930.PD
 931.
 932.P
 933For details see the groff info file.
 934.
 935.
 936.\" --------------------------------------------------------------------
 937.SH CONDITIONS
 938.\" --------------------------------------------------------------------
 939.
 940.B Conditions
 941occur in tests raised by the
 942.request if ,
 943.request ie ,
 944and the
 945.request while
 946requests.
 947.
 948The following table characterizes the different types of conditions.
 949.
 950.P
 951.PD 0
 952.RS
 953.
 954.TPx
 955.I N
 956A numerical expression
 957.I N
 958yields true if its value is greater than\~0.
 959.
 960.TPx
 961.BI ! N
 962True if the value of
 963.I I
 964is\~0.
 965.
 966.TPx
 967.BI ' s1 ' s2 '
 968True if string\~\c
 969.I s1
 970is identical to string\~\c
 971.IR s2 .
 972.
 973.TPx
 974.BI !' s1 ' s2 '
 975True if string\~\c
 976.I s1
 977is not identical to string\~\c
 978.IR s2 .
 979.
 980.TPx
 981.BI c ch
 982True if there is a character\~\c
 983.I ch
 984available.
 985.
 986.TPx
 987.BI d name
 988True if there is a string, macro, diversion, or request called
 989.IR name .
 990.
 991.TPx
 992.B e
 993Current page number is even.
 994.
 995.TPx
 996.B o
 997Current page number is odd.
 998.
 999.TPx
1000.BI m name
1001True if there is a color called
1002.IR name .
1003.
1004.TPx
1005.B n
1006Formatter is
1007.BR nroff .
1008.
1009.TPx
1010.BI r reg
1011True if there is a register named
1012.IR reg .
1013.
1014.TPx
1015.B t
1016Formatter is
1017.BR troff .
1018.
1019.TPx
1020.BI F font
1021True if there exists a font named
1022.IR font .
1023.
1024.TPx
1025.BI S style
1026True if a style named
1027.I style
1028has been registered.
1029.
1030.RE
1031.PD
1032.
1033.
1034.\" --------------------------------------------------------------------
1035.SH REQUESTS
1036.\" --------------------------------------------------------------------
1037.
1038This section provides a short reference for the predefined requests.
1039.
1040In groff, request and macro names can be arbitrarily long.
1041.
1042No bracketing or marking of long names is needed.
1043.
1044.P
1045Most requests take one or more arguments.
1046.
1047The arguments are separated by space characters (no tabs!); there is
1048no inherent limit for their length or number.
1049.
1050An argument can be enclosed by a pair of double quotes.
1051.
1052This is very handy if an argument contains space characters, e.g.,
1053.RI \[dq] "arg with space" \[dq]
1054denotes a single argument.
1055.
1056.P
1057Some requests have optional arguments with a different behaviour.
1058.
1059Not all of these details are outlined here.
1060.
1061Refer to the groff info file and
1062.BR groff_diff (@MAN7EXT@)
1063for all details.
1064.
1065.P
1066In the following request specifications, most argument names were
1067chosen to be descriptive.
1068.
1069Only the following denotations need clarification.
1070.
1071.P
1072.PD 0
1073.RS
1074.
1075.TPx
1076.I c
1077denotes a single character.
1078.
1079.TPx
1080.I font
1081a font either specified as a font name or a font number.
1082.
1083.TPx
1084.I anything
1085all characters up to the end of the line or within
1086.esc {
1087and
1088.esc } .
1089.
1090.TPx
1091.I n
1092is a numerical expression that evaluates to an integer value.
1093.
1094.TPx
1095.I N
1096is an arbitrary numerical expression, signed or unsigned.
1097.
1098.TPx
1099.I \[+-]N
1100has three meanings depending on its sign, described below.
1101.
1102.RE
1103.PD
1104.
1105.P
1106If an expression defined as
1107.I \[+-]N
1108starts with a
1109.squoted_char +
1110sign the resulting value of the expression will be added to an already
1111existing value inherent to the related request, e.g.\& adding to a number
1112register.
1113.
1114If the expression starts with a
1115.squoted_char -
1116the value of the expression will be subtracted from the request value.
1117.
1118.P
1119Without a sign,
1120.I N
1121replaces the existing value directly.
1122.
1123To assign a negative number either prepend\~0 or enclose the negative
1124number in parentheses.
1125.
1126.
1127.\" --------------------------------------------------------------------
1128.SS "Request Short Reference"
1129.\" --------------------------------------------------------------------
1130.
1131.PD 0
1132.
1133.REQ .
1134Empty line, ignored.
1135.
1136Useful for structuring documents.
1137.
1138.REQ .\[rs]\[dq] anything
1139Complete line is a comment.
1140.
1141.REQ .ab string
1142Print
1143.I string
1144on standard error, exit program.
1145.
1146.REQ .ad
1147Begin line adjustment for output lines in current adjust mode.
1148.
1149.REQ .ad c
1150Start line adjustment in mode
1151.I c
1152(\f[CI]c\f[]\f[CR]\|\^\[eq]\|l,r,b,n\f[]).
1153.
1154.REQ .af register c
1155Assign format
1156.I c
1157to
1158.I register
1159(\f[CI]c\f[]\f[CR]\|\^\[eq]\|l,i,I,a,A\f[]).
1160.
1161.REQ .aln alias register
1162Create alias name for
1163.IR register .
1164.
1165.REQ .als alias object
1166Create alias name for request, string, macro, or diversion
1167.IR object .
1168.
1169.REQ .am macro
1170Append to
1171.I macro
1172until
1173.B ..\&
1174is encountered.
1175.
1176.REQ .am macro end
1177Append to
1178.I macro
1179until
1180.request .end
1181is called.
1182.
1183.REQ .am1 macro
1184Same as
1185.request .am
1186but with compatibility mode switched off during macro expansion.
1187.
1188.REQ .am1 macro end
1189Same as
1190.request .am
1191but with compatibility mode switched off during macro expansion.
1192.
1193.REQ .ami macro
1194Append to a macro whose name is contained in the string register
1195.I macro
1196until
1197.B ..\&
1198is encountered.
1199.
1200.REQ .ami macro end
1201Append to a macro indirectly.
1202.I macro
1203and
1204.I end
1205are string registers whose contents are interpolated for the macro name
1206and the end macro, respectively.
1207.
1208.REQ .ami1 macro
1209Same as
1210.request .ami
1211but with compatibility mode switched off during macro expansion.
1212.
1213.REQ .ami1 macro end
1214Same as
1215.request .ami
1216but with compatibility mode switched off during macro expansion.
1217.
1218.REQ .as stringvar anything
1219Append
1220.I anything
1221to
1222.IR stringvar .
1223.
1224.REQ .as1 stringvar anything
1225Same as
1226.request .as
1227but with compatibility mode switched off during string expansion.
1228.
1229.REQ .asciify diversion
1230Unformat ASCII characters, spaces, and some escape sequences in
1231.IR diversion .
1232.
1233.REQ .backtrace
1234Print a backtrace of the input on stderr.
1235.
1236.REQ .bd font N
1237Embolden
1238.I font
1239by
1240.IR N -1
1241units.
1242.
1243.REQ .bd S font N
1244Embolden Special Font
1245.I S
1246when current font is
1247.IR font .
1248.
1249.REQ .blm
1250Unset the blank line macro.
1251.
1252.REQ .blm macro
1253Set the blank line macro to
1254.IR macro .
1255.
1256.REQ .box
1257End current diversion.
1258.
1259.REQ .box macro
1260Divert to
1261.IR macro ,
1262omitting a partially filled line.
1263.
1264.REQ .boxa
1265End current diversion.
1266.
1267.REQ .boxa macro
1268Divert and append to
1269.IR macro ,
1270omitting a partially filled line.
1271.
1272.REQ .bp
1273Eject current page and begin new page.
1274.
1275.REQ .bp \[+-]N
1276Eject current page; next page number
1277.IR \[+-]N .
1278.
1279.REQ .br
1280Line break.
1281.
1282.REQ .brp
1283Break and spread output line.
1284Same as
1285.esc p .
1286.
1287.REQ .break
1288Break out of a while loop.
1289.
1290.REQ .c2
1291Reset no-break control character to
1292.dquoted_char ' .
1293.
1294.REQ .c2 c
1295Set no-break control character to
1296.IR c .
1297.
1298.REQ .cc
1299Reset control character to
1300.squoted_char . .
1301.
1302.REQ .cc c
1303Set control character to
1304.IR c .
1305.
1306.REQ .ce
1307Center the next input line.
1308.
1309.REQ .ce N
1310Center following
1311.I N
1312input lines.
1313.
1314.REQ .cf filename
1315Copy contents of file
1316.I filename
1317unprocessed to stdout or to the diversion.
1318.
1319.REQ .cflags mode c1 c2 .\|.\|.\&
1320Treat characters
1321.IR c1 ,
1322.IR c2 ,
1323.I .\|.\|.\&
1324according to
1325.I mode
1326number.
1327.
1328.REQ .ch trap N
1329Change
1330.I trap
1331location
1332to
1333.I N .
1334.
1335.REQ .char c anything
1336Define character
1337.I c
1338as string
1339.IR anything .
1340.
1341.REQ .chop object
1342Chop the last character off macro, string, or diversion
1343.IR object .
1344.
1345.REQ .close stream
1346Close the
1347.IR stream .
1348.
1349.REQ .color
1350Enable colors.
1351.
1352.REQ .color N
1353If
1354.I N
1355is zero disable colors, otherwise enable them.
1356.
1357.REQ .composite from to
1358Map glyph name
1359.I from
1360to glyph name
1361.I to
1362while constructing a composite glyph name.
1363.
1364.REQ .continue
1365Finish the current iteration of a while loop.
1366.
1367.REQ .cp
1368Enable compatibility mode.
1369.
1370.REQ .cp N
1371If
1372.I N
1373is zero disable compatibility mode, otherwise enable it.
1374.
1375.REQ .cs font N M
1376Set constant character width mode for
1377.I font
1378to
1379.IR N /36
1380ems with em
1381.IR M .
1382.
1383.REQ .cu N
1384Continuous underline in nroff, like
1385.request .ul
1386in troff.
1387.
1388.REQ .da
1389End current diversion.
1390.
1391.REQ .da macro
1392Divert and append to
1393.IR macro .
1394.
1395.REQ .de macro
1396Define or redefine
1397.I macro
1398until
1399.B ..\&
1400is encountered.
1401.
1402.REQ .de macro end
1403Define or redefine
1404.I macro
1405until
1406.request .end
1407is called.
1408.
1409.REQ .de1 macro
1410Same as
1411.request .de
1412but with compatibility mode switched off during macro expansion.
1413.
1414.REQ .de1 macro end
1415Same as
1416.request .de
1417but with compatibility mode switched off during macro expansion.
1418.
1419.REQ .defcolor color scheme component
1420Define or redefine a color with name
1421.IR color .
1422.I scheme
1423can be
1424.BR rgb ,
1425.BR cym ,
1426.BR cymk ,
1427.BR gray ,
1428or
1429.BR grey .
1430.I component
1431can be single components specified as fractions in the range 0 to 1
1432(default scaling indicator\~\c
1433.scaleindicator f ),
1434as a string of two-digit hexadecimal color components with a leading
1435.BR # ,
1436or as a string of four-digit hexadecimal components with two leading
1437.BR # .
1438The color
1439.B default
1440can't be redefined.
1441.
1442.REQ .dei macro
1443Define or redefine a macro whose name is contained in the string register
1444.I macro
1445until
1446.B ..\&
1447is encountered.
1448.
1449.REQ .dei macro end
1450Define or redefine a macro indirectly.
1451.I macro
1452and
1453.I end
1454are string registers whose contents are interpolated for the macro name
1455and the end macro, respectively.
1456.
1457.REQ .dei1 macro
1458Same as
1459.request .dei
1460but with compatibility mode switched off during macro expansion.
1461.
1462.REQ .dei1 macro end
1463Same as
1464.request .dei
1465but with compatibility mode switched off during macro expansion.
1466.
1467.REQ .di
1468End current diversion.
1469.
1470.REQ .di macro
1471Divert to
1472.I macro .
1473.
1474.REQ .do name
1475Interpret
1476.request .name
1477with compatibility mode disabled.
1478.
1479.REQ .ds stringvar anything
1480Set
1481.I stringvar
1482to
1483.IR anything .
1484.
1485.REQ .ds1 stringvar anything
1486Same as
1487.request .ds
1488but with compatibility mode switched off during string expansion.
1489.
1490.REQ .dt N trap
1491Set diversion trap to position
1492.I N
1493(default scaling indicator\~\c
1494.scaleindicator v ).
1495.
1496.REQ .ec
1497Reset escape character to
1498.squoted_char \[rs] .
1499.
1500.REQ .ec c
1501Set escape character to
1502.IR c .
1503.
1504.REQ .ecr
1505Restore escape character saved with
1506.request .ecs .
1507.
1508.REQ .ecs
1509Save current escape character.
1510.
1511.REQ .el anything
1512Else part for if-else (\c
1513.request ie )
1514request.
1515.
1516.REQ .em macro
1517The
1518.I macro
1519will be run after the end of input.
1520.
1521.REQ .eo
1522Turn off escape character mechanism.
1523.
1524.REQ .ev
1525Switch to previous environment.
1526.
1527.REQ .ev env
1528Push down environment number or name
1529.I env
1530and switch to it.
1531.
1532.REQ .evc env
1533Copy the contents of environment
1534.I env
1535to the current environment.
1536No pushing or popping.
1537.
1538.REQ .ex
1539Exit from roff processing.
1540.
1541.REQ .fam
1542Return to previous font family.
1543.
1544.REQ .fam name
1545Set the current font family to
1546.IR name .
1547.
1548.REQ .fc
1549Disable field mechanism.
1550.
1551.REQ .fc a
1552Set field delimiter to
1553.I a
1554and pad character to space.
1555.
1556.REQ .fc a b
1557Set field delimiter to
1558.I a
1559and pad character to
1560.IR b .
1561.
1562.REQ .fchar c anything
1563Define fallback character
1564.I c
1565as string
1566.IR anything .
1567.
1568.REQ .fcolor
1569Set fill color to previous fill color.
1570.
1571.REQ .fcolor c
1572Set fill color to
1573.IR c .
1574.
1575.REQ .fi
1576Fill output lines.
1577.
1578.REQ .fl
1579Flush output buffer.
1580.
1581.REQ .fp n font
1582Mount
1583.I font
1584on position
1585.IR n .
1586.
1587.REQ .fp n internal external
1588Mount font with long
1589.I external
1590name to short
1591.I internal
1592name on position
1593.IR n .
1594.
1595.REQ .fschar f c anything
1596Define fallback character
1597.I c
1598for font
1599.I f
1600as string
1601.IR anything .
1602.
1603.REQ .fspecial font
1604Reset list of special fonts for
1605.I font
1606to be empty.
1607.
1608.REQ .fspecial font s1 s2 .\|.\|.\&
1609When the current font is
1610.IR font ,
1611then the fonts
1612.IR s1 ,
1613.IR s2 ,
1614.I .\|.\|.\&
1615will be special.
1616.
1617.REQ .ft
1618Return to previous font.
1619Same as
1620.request \[rs]f[]
1621or
1622.request \[rs]fP .
1623.
1624.REQ .ft font
1625Change to font name or number
1626.IR font ;
1627same as
1628.esc[] f font
1629escape sequence.
1630.
1631.REQ .ftr font1 font2
1632Translate
1633.I font1
1634to
1635.IR font2 .
1636.
1637.REQ .gcolor
1638Set glyph color to previous glyph color.
1639.
1640.REQ .gcolor c
1641Set glyph color to
1642.IR c .
1643.
1644.REQ .hc
1645Remove additional hyphenation indicator character.
1646.
1647.REQ .hc c
1648Set up additional hyphenation indicator character\~\c
1649.IR c .
1650.
1651.REQ .hcode c1 code1 c2 code2 .\|.\|.\&
1652Set the hyphenation code of character
1653.I c1
1654to
1655.IR code1 ,
1656that of
1657.I c2
1658to
1659.IR code2 ,
1660etc.
1661.
1662.REQ .hla lang
1663Set the current hyphenation language to
1664.IR lang .
1665.
1666.REQ .hlm n
1667Set the maximum number of consecutive hyphenated lines to
1668.IR n .
1669.
1670.REQ .hpf file
1671Read hyphenation patterns from
1672.IR file .
1673.
1674.REQ .hpfa file
1675Append hyphenation patterns from
1676.IR file .
1677.
1678.REQ .hpfcode file
1679Set input mapping for
1680.request .hpf .
1681.
1682.REQ .hw words
1683List of
1684.I words
1685with exceptional hyphenation.
1686.
1687.REQ .hy N
1688Switch to hyphenation mode
1689.IR N .
1690.
1691.REQ .hym n
1692Set the hyphenation margin to
1693.I n
1694(default scaling indicator\~\c
1695.scaleindicator m ).
1696.
1697.REQ .hys n
1698Set the hyphenation space to
1699.IR n .
1700.
1701.REQ .ie cond anything
1702If
1703.I cond
1704then
1705.I anything
1706else goto
1707.request .el .
1708.
1709.REQ .if cond anything
1710If
1711.I cond
1712then
1713.IR anything ;
1714otherwise do nothing.
1715.
1716.REQ .ig
1717Ignore text until
1718.B ..\&
1719is encountered.
1720.
1721.REQ .ig end
1722Ignore text until
1723.request .end .
1724.
1725.REQ .in
1726Change to previous indent value.
1727.
1728.REQ .in \[+-]N
1729Change indent according to
1730.I \[+-]N
1731(default scaling indicator\~\c
1732.scaleindicator m ).
1733.
1734.REQ .it N trap
1735Set an input-line count trap for the next
1736.I N
1737lines.
1738.
1739.REQ .itc N trap
1740Same as
1741.request .it
1742but count lines interrupted with
1743.esc c
1744as one line.
1745.
1746.REQ .kern
1747Enable pairwise kerning.
1748.
1749.REQ .kern n
1750If
1751.I n
1752is zero, disable pairwise kerning, otherwise enable it.
1753.
1754.REQ .lc
1755Remove leader repetition character.
1756.
1757.REQ .lc c
1758Set leader repetition character to\~\c
1759.IR c .
1760.
1761.REQ .length register anything
1762Write the length of the string
1763.I anything
1764in
1765.IR register .
1766.
1767.REQ .linetabs
1768Enable line-tabs mode (i.e., calculate tab positions relative to output
1769line).
1770.
1771.REQ .linetabs n
1772If
1773.I n
1774is zero, disable line-tabs mode, otherwise enable it.
1775.
1776.REQ .lf N
1777Set input line number to
1778.IR N .
1779.
1780.REQ .lf N file
1781Set input line number to
1782.I N
1783and filename to
1784.IR file .
1785.
1786.REQ .lg N
1787Ligature mode on if
1788.IR N >0.
1789.
1790.REQ .ll
1791Change to previous line length.
1792.
1793.REQ .ll \[+-]N
1794Set line length according to
1795.I \[+-]N
1796(default size
1797.scalednumber 6.5 i ,
1798default scaling indicator\~\c
1799.scaleindicator m ).
1800.
1801.REQ .ls
1802Change to the previous value of additional intra-line skip.
1803.
1804.REQ .ls N
1805Set additional intra-line skip value to
1806.IR N ,
1807i.e.,
1808.IR N -1
1809blank lines are inserted after each text output line.
1810.
1811.REQ .lt \[+-]N
1812Length of title (default scaling indicator\~\c
1813.scaleindicator m ).
1814.
1815.REQ .mc
1816Margin character off.
1817.
1818.REQ .mc c
1819Print character
1820.I c
1821after each text line at actual distance from right margin.
1822.
1823.REQ .mc c N
1824Set margin character to
1825.I c
1826and distance to
1827.I N
1828from right margin (default scaling indicator\~\c
1829.scaleindicator m ).
1830.
1831.REQ .mk register
1832Mark current vertical position in
1833.IR register .
1834.
1835.REQ .mso file
1836The same as the .so request except that
1837.I file
1838is searched in the tmac directories.
1839.
1840.REQ .na
1841No output-line adjusting.
1842.
1843.REQ .ne
1844Need a one-line vertical space.
1845.
1846.REQ .ne N
1847Need
1848.I N
1849vertical space (default scaling indicator\~\c
1850.scaleindicator v ).
1851.
1852.REQ .nf
1853No filling or adjusting of output-lines.
1854.
1855.REQ .nh
1856No hyphenation.
1857.
1858.REQ .nm
1859Number mode off.
1860.
1861.REQ .nm \[+-]N \fR[\fPM \fR[\fPS \fR[\fPI\fR]]]\fP
1862In line number mode, set number, multiple, spacing, and indent.
1863.
1864.REQ .nn
1865Do not number next line.
1866.
1867.REQ .nn N
1868Do not number next
1869.I N
1870lines.
1871.
1872.REQ .nop anything
1873Always execute
1874.IR anything .
1875.
1876.REQ .nr register \[+-]N M
1877Define or modify
1878.I register
1879using
1880.I \[+-]N
1881with auto-increment
1882.IR M .
1883.
1884.REQ .nroff
1885Make the built-in condition
1886.B n
1887true and
1888.B t
1889false.
1890.
1891.REQ .ns
1892Turn no-space mode on.
1893.
1894.REQ .nx
1895Immediately jump to end of current file.
1896.
1897.REQ .nx filename
1898Next file.
1899.
1900.REQ .open stream filename
1901Open
1902.register filename
1903for writing and associate the stream named
1904.register stream
1905with it.
1906.
1907.REQ .opena stream filename
1908Like
1909.request .open
1910but append to it.
1911.
1912.REQ .os
1913Output vertical distance that was saved by the
1914.request sv
1915request.
1916.
1917.REQ .output string
1918Emit
1919.I string
1920directly to intermediate output, allowing leading whitespace if
1921.I string
1922starts with
1923.character \[dq]
1924(which will be stripped off).
1925.
1926.REQ .pc
1927Reset page number character to\~\c
1928.squoted_char % .
1929.
1930.REQ .pc c
1931Page number character.
1932.
1933.REQ .pi program
1934Pipe output to
1935.I program
1936(nroff only).
1937.
1938.REQ .pl
1939Set page length to default
1940.scalednumber 11 i .
1941The current page length is stored in
1942.register .p .
1943.
1944.REQ .pl \[+-]N
1945Change page length to
1946.I \[+-]N
1947(default scaling indicator\~\c
1948.scaleindicator v ).
1949.
1950.REQ .pm
1951Print macro names and sizes (number of blocks of 128 bytes).
1952.
1953.REQ ".pm t"
1954Print only total of sizes of macros (number of 128 bytes blocks).
1955.
1956.REQ .pn \[+-]N
1957Next page number
1958.IR N .
1959.
1960.REQ .pnr
1961Print the names and contents of all currently defined number registers
1962on stderr.
1963.
1964.REQ .po
1965Change to previous page offset.
1966.
1967The current page offset is available in
1968.register .o .
1969.
1970.REQ .po \[+-]N
1971Page offset
1972.IR N .
1973.
1974.REQ .ps
1975Return to previous point-size.
1976.REQ .ps \[+-]N
1977Point size; same as
1978.esc[] s \[+-]N .
1979.
1980.REQ .psbb filename
1981Get the bounding box of a PostScript image
1982.IR filename .
1983.
1984.REQ .pso command
1985This behaves like the
1986.request so
1987request except that input comes from the standard output of
1988.IR command .
1989.
1990.REQ .ptr
1991Print the names and positions of all traps (not including input line
1992traps and diversion traps) on stderr.
1993.
1994.REQ .pvs
1995Change to previous post-vertical line spacing.
1996.
1997.REQ .pvs \[+-]N
1998Change post-vertical line spacing according to
1999.I \[+-]N
2000(default scaling indicator\~\c
2001.scaleindicator p ).
2002.
2003.REQ .rchar c1 c2 .\|.\|.\&
2004Remove the definitions of characters
2005.IR c1 ,
2006.IR c2 ,
2007.I .\|.\|.\&
2008.
2009.REQ .rd prompt
2010Read insertion.
2011.
2012.REQ .return
2013Return from a macro.
2014.
2015.REQ .return anything
2016Return twice, namely from the macro at the current level and from the macro
2017one level higher.
2018.
2019.REQ .rfschar f c1 c2 .\|.\|.\&
2020Remove the definitions of characters
2021.IR c1 ,
2022.IR c2 ,
2023.I .\|.\|.\&
2024for font
2025.IR f .
2026.
2027.REQ .rj n
2028Right justify the next
2029.I n
2030input lines.
2031.
2032.REQ .rm name
2033Remove request, macro, or string
2034.IR name .
2035.
2036.REQ .rn old new
2037Rename request, macro, or string
2038.I old
2039to
2040.IR new .
2041.
2042.REQ .rnn reg1 reg2
2043Rename register
2044.I reg1
2045to
2046.IR reg2 .
2047.
2048.REQ .rr register
2049Remove
2050.IR register .
2051.
2052.REQ .rs
2053Restore spacing; turn no-space mode off.
2054.
2055.REQ .rt \[+-]N
2056Return
2057.I (upward only)
2058to marked vertical place (default scaling indicator\~\c
2059.scaleindicator v ).
2060.
2061.REQ .schar c anything
2062Define global fallback character
2063.I c
2064as string
2065.IR anything .
2066.
2067.REQ .shc
2068Reset soft hyphen character to
2069.esc (hy .
2070.
2071.REQ .shc c
2072Set the soft hyphen character to
2073.IR c .
2074.
2075.REQ .shift n
2076In a macro, shift the arguments by
2077.IR n \~\c
2078positions.
2079.
2080.REQ .sizes s1 s2 .\|.\|.\& sn \fB[0]\fP
2081Set available font sizes similar to the
2082.B sizes
2083command in a
2084.B DESC
2085file.
2086.
2087.REQ .so filename
2088Include source file.
2089.
2090.REQ .sp
2091Skip one line vertically.
2092.
2093.REQ .sp N
2094Space vertical distance
2095.I N
2096up or down according to sign of
2097.I N
2098(default scaling indicator\~\c
2099.scaleindicator v ).
2100.
2101.REQ .special
2102Reset global list of special fonts to be empty.
2103.
2104.REQ .special s1 s2 .\|.\|.\&
2105Fonts
2106.IR s1 ,
2107.IR s2 ,
2108etc.\& are special and will be searched for characters not in the
2109current font.
2110.
2111.REQ .spreadwarn
2112Toggle the spread warning on and off without changing its value.
2113.
2114.REQ .spreadwarn limit
2115Emit a warning if each space in an output line is widened by
2116.I limit
2117or more (default scaling indicator\~\c
2118.scaleindicator m ).
2119.
2120.REQ .ss N
2121Space-character size set to
2122.IR N /12
2123of the spacewidth in the current font.
2124.
2125.REQ .ss N M
2126Space-character size set to
2127.IR N /12
2128and sentence space size set to
2129.IR M /12
2130of the spacewidth in the current font (\f[CR]\[eq]1/3 em\f[]).
2131.
2132.REQ .sty n style
2133Associate
2134.I style
2135with font position
2136.IR n .
2137.
2138.REQ .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 .
2145.
2146.REQ .sv
2147Save
2148.scalednumber 1 v
2149of vertical space.
2150.
2151.REQ .sv N
2152Save the vertical distance
2153.I N
2154for later output with
2155.request os
2156request.
2157.
2158.REQ .sy command-line
2159Execute program
2160.IR command-line .
2161.
2162.REQ ".ta T" N
2163Set tabs after every position that is a multiple of
2164.I N
2165(default scaling indicator\~\c
2166.scaleindicator m ).
2167.REQ .ta n1 n2 .\|.\|.\& nn \f[CB]T\f[] r1 r2 .\|.\|.\& rn
2168Set tabs at positions
2169.IR n1 ,
2170.IR n2 ,
2171.Text .\|.\|.,
2172.IR nn ,
2173then set tabs at
2174.IR nn + r1 ,
2175.IR nn + r2 ,
2176.Text .\|.\|.,
2177.IR nn + rn ,
2178then at
2179.IR nn + rn + r1 ,
2180.IR nn + rn + r2 ,
2181.Text .\|.\|.,
2182.IR nn + rn + rn ,
2183and so on.
2184.
2185.\".REQ .tar
2186.\"Restore internally saved tab positions.
2187.\".
2188.\".REQ .tas
2189.\"Save tab positions internally.
2190.
2191.REQ .tc
2192Remove tab repition character.
2193.REQ .tc c
2194Set tab repetition character to\~\c
2195.IR c .
2196.
2197.REQ .ti \[+-]N
2198Temporary indent next line (default scaling indicator\~\c
2199.scaleindicator m ).
2200.
2201.REQ .tkf font s1 n1 s2 n2
2202Enable track kerning for
2203.IR font .
2204.
2205.REQ .tl \f[CB]\[cq]\f[]left\f[CB]\[cq]\f[]center\f[CB]\[cq]\f[]right\f[CB]\[cq]\f[]
2206Three-part title.
2207.
2208.REQ .tm anything
2209Print
2210.I anything
2211on terminal (UNIX standard message output).
2212.
2213.REQ .tm1 anything
2214Print
2215.I anything
2216on terminal (UNIX standard message output), allowing leading
2217whitespace if
2218.I anything
2219starts with
2220.character \[dq]
2221(which will be stripped off).
2222.
2223.REQ .tmc anything
2224Similar to
2225.request .tm1
2226without emitting a final newline.
2227.
2228.REQ .tr abcd.\|.\|.\&
2229Translate
2230.I a
2231to
2232.IR b ,
2233.I c
2234to
2235.IR d ,
2236etc.\& on output.
2237.
2238.REQ .trf filename
2239Transparently output the contents of file
2240.IR filename .
2241.
2242.REQ .trin abcd.\|.\|.\&
2243This is the same as the
2244.request tr
2245request except that the
2246.B asciify
2247request will use the character code (if any) before the character
2248translation.
2249.
2250.REQ .trnt abcd.\|.\|.\&
2251This is the same as the
2252.request tr
2253request except that the translations do not apply to text that is
2254transparently throughput into a diversion with
2255.esc ! .
2256.
2257.REQ .troff
2258Make the built-in condition
2259.B t
2260true and
2261.B n
2262false.
2263.
2264.REQ .uf font
2265Underline font set to
2266.I font
2267(to be switched to by
2268.request .ul ).
2269.
2270.REQ .ul N
2271Underline (italicize in troff)
2272.I N
2273input lines.
2274.
2275.REQ .unformat diversion
2276Unformat space characters and tabs, preserving font information in
2277.IR diversion .
2278.REQ .vpt n
2279Enable vertical position traps if
2280.I n
2281is non-zero, disable them otherwise.
2282.
2283.REQ .vs
2284Change to previous vertical base line spacing.
2285.
2286.REQ .vs \[+-]N
2287Set vertical base line spacing according to
2288.I \[+-]N
2289(default scaling indicator\~\c
2290.scaleindicator p ).
2291Default value is
2292.scalednumber 12 p .
2293.
2294.REQ .warn n
2295Set warnings code to
2296.IR n .
2297.
2298.REQ .warnscale si
2299Set scaling indicator used in warnings to
2300.IR si .
2301.
2302.REQ .wh N
2303Remove (first) trap at position
2304.IR N .
2305.
2306.REQ .wh N trap
2307Set location trap; negative means from page bottom.
2308.
2309.REQ .while cond anything
2310While condition
2311.I cond
2312is true, accept
2313.I anything
2314as input.
2315.
2316.REQ .write stream anything
2317Write
2318.I anything
2319to the stream named
2320.IR stream .
2321.
2322.REQ .writec stream anything
2323Similar to
2324.request .write
2325without emitting a final newline.
2326.
2327.REQ .writem stream xx
2328Write contents of macro or string
2329.I xx
2330to the stream named
2331.IR stream .
2332.
2333.PD
2334.
2335.P
2336Besides these standard groff requests, there might be further macro
2337calls.
2338They can originate from a macro package (see
2339.BR roff (@MAN7EXT@)
2340for an overview) or from a preprocessor.
2341.
2342.P
2343Preprocessor macros are easy to be recognized.
2344.
2345They enclose their code into a pair of characteristic macros.
2346.
2347.P
2348.TS
2349box, center, tab (@);
2350c | c | c
2351CfCB | CfCB | CfCB.
2352preprocessor@start macro@ end macro
2353=
2354eqn@.PS@.PE
2355grap@.G1@.G2
2356grn@.GS@.GE
2357pic@.PS@.PE
2358refer@.R1@.R2
2359soelim@\f[I]none@\f[I]none
2360tbl@.TS@.TE
2361.TE
2362.P
2363.
2364.
2365.\" --------------------------------------------------------------------
2366.SH "ESCAPE SEQUENCES"
2367.\" --------------------------------------------------------------------
2368.
2369Escape sequences are in-line language elements usually introduced by a
2370backslash
2371.squoted_char \[rs]
2372and followed by an escape name and sometimes by a required argument.
2373.
2374Input processing is continued directly after the escaped character or
2375the argument resp.\& without an intervening separation character.
2376.
2377So there must be a way to determine the end of the escape name and the
2378end of the argument.
2379.
2380.P
2381This is done by enclosing names (escape name and arguments consisting
2382of a variable name) by a pair of brackets
2383.BI \[lB] name \[rB] 
2384and constant arguments (number expressions and characters) by
2385apostrophes (ASCII 0x27) like
2386.BI \[cq] constant \[cq] \f[R].
2387.
2388.P
2389There are abbreviations for short names.
2390.
2391Two character escape names can be specified by an opening parenthesis
2392like
2393.esc ( xy
2394without a closing counterpart.
2395.
2396And all one-character names different from the special characters
2397.squoted_char [
2398and
2399.squoted_char (
2400can even be specified without a marker in the form
2401.esc c .
2402.
2403.P
2404Constant arguments of length\~1 can omit the marker apostrophes, too,
2405but there is no two-character analogue.
2406.
2407.P
2408While 1-character escape sequences are mainly used for in-line
2409functions and system related tasks, the 2-letter names following the
2410.esc (
2411construct are used for special characters predefined by the roff system.
2412.
2413Escapes sequences with names of more than two characters
2414.esc[] "" name
2415denote user defined named characters (see the
2416.request char
2417request).
2418.
2419.
2420.\" --------------------------------------------------------------------
2421.SS "Single Character Escapes"
2422.\" --------------------------------------------------------------------
2423.
2424.PD 0
2425.
2426.\" --------- comments ---------
2427.
2428.ESC \[dq]
2429Beginning of a comment.
2430.
2431Everything up to the end of the line is ignored.
2432.
2433.ESC #
2434Everything up to and including the next newline is ignored.
2435.
2436This is interpreted in copy mode.
2437.
2438This is like
2439.esc \[dq]
2440except that the terminating newline is ignored as well.
2441.
2442.\" --------- strings ---------
2443.
2444.ESC *\f[I]s\f[]
2445The string stored in the string variable with 1-character name
2446.IR s .
2447.
2448.ESC *(\f[I]st\f[]
2449The string stored in the string variable with 2-character name
2450.IR st .
2451.
2452.ESC[] * "stringvar arg1 arg2 .\|.\|."
2453The string stored in the string variable with arbitrary length name
2454.IR stringvar ,
2455taking
2456.IR arg1 ,
2457.IR arg2 ,
2458.I .\|.\|.\&
2459as arguments.
2460.
2461.\" --------- macro arguments ---------
2462.
2463.ESC $0
2464The name by which the current macro was invoked.
2465.
2466The
2467.request als
2468request can make a macro have more than one name.
2469.
2470.ESC $ x
2471Macro or string argument with 1-place number
2472.IR x ,
2473where
2474.I x
2475is a digit between 1 and 9.
2476.
2477.ESC $( xy
2478Macro or string argument with 2-digit number
2479.IR xy .
2480.
2481.ESC[] $ nexp
2482Macro or string argument with number
2483.IR nexp ,
2484where
2485.I nexp
2486is a numerical expression evaluating to an integer \[>=]1.
2487.
2488.ESC $*
2489In a macro or string, the concatenation of all the arguments separated
2490by spaces.
2491.
2492.ESC $@
2493In a macro or string, the concatenation of all the arguments with each
2494surrounded by double quotes, and separated by spaces.
2495.
2496.\" --------- escaped characters ---------
2497.
2498.ESC \[rs]
2499reduces to a single backslash; useful to delay its interpretation as
2500escape character in copy mode.
2501.
2502For a printable backslash, use
2503.esc e ,
2504or even better
2505.esc [rs] ,
2506to be independent from the current escape character.
2507.
2508.ESC \[cq]
2509The acute accent \[aa]; same as
2510.esc (aa .
2511Unescaped: apostrophe, right quotation mark, single quote (ASCII 0x27).
2512.
2513.ESC `
2514The grave accent \[ga]; same as
2515.esc (ga .
2516Unescaped: left quote, backquote (ASCII 0x60).
2517.
2518.ESC \-
2519The \- sign in the current font.
2520.
2521.ESC .
2522An uninterpreted dot (period), even at start of line.
2523.
2524.ESC %
2525Default optional hyphenation character.
2526.
2527.ESC !
2528Transparent line indicator.
2529.
2530.ESC? anything
2531In a diversion, this will transparently embed
2532.I anything
2533in the diversion.
2534.I anything
2535is read in copy mode.
2536.
2537See also the escape sequences
2538.esc !
2539and
2540.esc ? .
2541.
2542.
2543.\" --------- spacing ---------
2544.
2545.ESC \& space
2546Unpaddable space-size space character (no line break).
2547.
2548.ESC 0
2549Digit width.
2550.
2551.ESC |
25521/6\ em narrow space character; zero width in nroff.
2553.
2554.ESC ^
25551/12\ em half-narrow space character; zero width in nroff.
2556.
2557.ESC &
2558Non-printable, zero width character.
2559.
2560.ESC )
2561Like
2562.esc &
2563except that it behaves like a character declared with the cflags
2564request to be transparent for the purposes of end of sentence
2565recognition.
2566.
2567.ESC /
2568Increases the width of the preceding character so that the spacing
2569between that character and the following character will be correct if
2570the following character is a roman character.
2571.
2572.ESC ,
2573Modifies the spacing of the following character so that the spacing
2574between that character and the preceding character will correct if the
2575preceding character is a roman character.
2576.
2577.ESC ~
2578Unbreakable space that stretches like a normal inter-word space when a
2579line is adjusted.
2580.
2581.ESC :
2582Inserts a zero-width break point (similar to
2583.esc %
2584but without a soft hyphen character).
2585.
2586.ESC "" newline
2587Ignored newline, for continuation lines.
2588.
2589.\" --------- structuring ---------
2590.
2591.ESC {
2592Begin conditional input.
2593.
2594.ESC }
2595End conditional input.
2596.
2597.\" --------- longer escape names ---------
2598.
2599.ESC ( sc
2600The special character with 2-character name
2601.IR sc ,
2602see section
2603.BR "Special Characters" .
2604.
2605.ESC[] "" name
2606The named character (or rather glyph) with arbitrary length name
2607.IR name .
2608.
2609.ESC[] "" "comp1 comp2 .\|.\|."
2610A composite glyph with components
2611.IR comp1 ,
2612.IR comp2 ,
2613.I .\|.\|.
2614.
2615.\" --------- alphabetical escapes ---------
2616.
2617.ESC a
2618Non-interpreted leader character.
2619.
2620.ESCq A anything
2621If
2622.I anything
2623is acceptable as a name of a string, macro, diversion, register,
2624environment or font it expands to\~1, and to\~0 otherwise.
2625.
2626.ESCq b abc.\|.\|.\&
2627Bracket building function.
2628.
2629.ESCq B anything
2630If
2631.I anything
2632is acceptable as a valid numeric expression it expands to\~1, and
2633to\~0 otherwise.
2634.
2635.ESC c
2636Interrupt text processing.
2637.
2638.ESCq C char
2639The character called
2640.IR char ;
2641same as
2642.esc[] "" char ,
2643but compatible to other roff versions.
2644.
2645.ESC d
2646Forward (down) 1/2 em vertical unit (1/2 line in nroff).
2647.
2648.ESCq D charseq
2649Draw a graphical element defined by the characters in
2650.IR charseq ;
2651see groff info file for details.
2652.
2653.ESC e
2654Printable version of the current escape character.
2655.
2656.ESC E
2657Equivalent to an escape character, but is not interpreted in copy-mode.
2658.
2659.ESC f F
2660Change to font with 1-character name or 1-digit number
2661.IR F .
2662.
2663.ESC fP
2664Switch back to previous font.
2665.
2666.ESC f( fo
2667Change to font with 2-character name or 2-digit number
2668.IR fo .
2669.
2670.ESC[] f font
2671Change to font with arbitrary length name or number expression
2672.IR font .
2673.
2674.ESC[] f ""
2675Switch back to previous font.
2676.
2677.ESC F f
2678Change to font family with 1-character name
2679.IR f .
2680.
2681.ESC F( fm
2682Change to font family with 2-character name
2683.IR fm .
2684.
2685.ESC[] F fam
2686Change to font family with arbitrary length name
2687.IR fam .
2688.
2689.ESC[] F ""
2690Switch back to previous font family.
2691.
2692.ESC[] g reg
2693Return format of register with name
2694.I reg
2695suitable for
2696.request .af .
2697.
2698Alternative forms
2699.escarg g( xy
2700and
2701.escarg g x .
2702.
2703.ESCq h N
2704Local horizontal motion; m

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