contrib/groff-1.19/man/groff.man

   1 '\" t
   2 .ig
   3 groff.man
   4
   5 Last update: 17 Feb 2005
   6
   7 This file is part of groff, the GNU roff type-setting system.
   8
   9 Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005
  10   Free Software Foundation, Inc.
  11 written by Bernd Warken <bwarken@mayn.de>
  12 maintained by Werner Lemberg <wl@gnu.org>
  13
  14 Permission is granted to copy, distribute and/or modify this document
  15 under the terms of the GNU Free Documentation License, Version 1.1 or
  16 any later version published by the Free Software Foundation; with the
  17 Invariant Sections being this .ig-section and AUTHORS, with no
  18 Front-Cover Texts, and with no Back-Cover Texts.
  19
  20 A copy of the Free Documentation License is included as a file called
  21 FDL 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
 326 groff \- a short reference for the GNU roff language
 327 .
 328 .
 329 .\" --------------------------------------------------------------------
 330 .SH DESCRIPTION
 331 .\" --------------------------------------------------------------------
 332 .
 333 The name
 334 .I groff
 335 stands for
 336 .I GNU roff
 337 and is the free implementation of the roff type-setting system.
 338 .
 339 See
 340 .BR roff (@MAN7EXT@)
 341 for a survey and the background of the groff system.
 342 .
 343 .P
 344 This document gives only short descriptions of the predefined roff
 345 language elements as used in groff.
 346 .
 347 Both the classical features and the groff extensions are provided.
 348 .
 349 .P
 350 Historically, the
 351 .I roff language
 352 was called
 353 .IR troff .
 354 .I groff
 355 is compatible with the classical system and provides proper
 356 extensions.
 357 .
 358 So in GNU, the terms
 359 .IR roff ,
 360 .IR troff ,
 361 and
 362 .I groff language
 363 could be used as synonyms.
 364 .
 365 However
 366 .I troff
 367 slightly tends to refer more to the classical aspects, whereas
 368 .I groff
 369 emphasizes the GNU extensions, and
 370 .I roff
 371 is the general term for the language.
 372 .
 373 .P
 374 This file is only a short version of the complete documentation that
 375 is found in the
 376 .I groff
 377 .BR info (1)
 378 file, which contains more detailed, actual, and concise information.
 379 .
 380 .P
 381 The general syntax for writing groff documents is relatively easy, but
 382 writing extensions to the roff language can be a bit harder.
 383 .
 384 .P
 385 The roff language is line-oriented.
 386 .
 387 There are only two kinds of lines, control lines and text lines.
 388 .
 389 The control lines start with a control character, by default a period
 390 .dquoted_char .
 391 or a single quote
 392 .dquoted_char ' ;
 393 all other lines are text lines.
 394 .
 395 .P
 396 .B Control lines
 397 represent commands, optionally with arguments.
 398 .
 399 They have the following syntax.
 400 .
 401 The leading control character can be followed by a command name;
 402 arguments, if any, are separated by blanks from the command name and
 403 among themselves, for example,
 404 .RS
 405 .
 406 .P
 407 .Text .command_name arg1 arg2
 408 .RE
 409 .
 410 .P
 411 For indentation, any number of space or tab characters can be inserted
 412 between the leading control character and the command name, but the
 413 control character must be on the first position of the line.
 414 .
 415 .P
 416 .B Text lines
 417 represent the parts that will be printed.
 418 They can be modified by escape sequences, which are recognized by a
 419 leading backslash
 420 .squoted_char \[rs] .
 421 These are in-line or even in-word formatting elements or functions.
 422 .
 423 Some of these take arguments separated by single quotes
 424 .dquoted_char ' ,
 425 others are regulated by a length encoding introduced by an open
 426 parenthesis
 427 .squoted_char (
 428 or enclosed in brackets
 429 .squoted_char [
 430 and
 431 .squoted_char ] .
 432 .
 433 .P
 434 The roff language provides flexible instruments for writing language
 435 extension, such as macros.
 436 .
 437 When interpreting macro definitions, the roff system enters a special
 438 operating mode, called the
 439 .BR "copy mode" .
 440 .
 441 .P
 442 The copy mode behavior can be quite tricky, but there are some rules
 443 that ensure a safe usage.
 444 .
 445 .IP 1.
 446 Printable backslashes must be denoted as
 447 .esc e .
 448 To be more precise,
 449 .esc e
 450 represents the current escape character.
 451 .
 452 To get a backslash glyph, use
 453 .esc (rs
 454 or
 455 .esc [rs] .
 456 .IP 2.
 457 Double all backslashes.
 458 .IP 3.
 459 Begin all text lines with the special non-spacing character
 460 .esc & .
 461 .
 462 .P
 463 This does not produce the most efficient code, but it should work as a
 464 first measure.
 465 .
 466 For better strategies, see the groff info file and
 467 .BR groff_tmac (@MAN5EXT@).
 468 .
 469 .P
 470 Reading roff source files is easier, just reduce all double backslashes
 471 to a single one in all macro definitions.
 472 .
 473 .
 474 .\" --------------------------------------------------------------------
 475 .SH "GROFF ELEMENTS"
 476 .\" --------------------------------------------------------------------
 477 .
 478 The roff language elements add formatting information to a text file.
 479 .
 480 The fundamental elements are predefined commands and variables that
 481 make roff a full-blown programming language.
 482 .
 483 .P
 484 There are two kinds of roff commands, possibly with arguments.
 485 .B Requests
 486 are written on a line of their own starting with a dot
 487 .squoted_char .
 488 or a
 489 .dquoted_char ' ,
 490 whereas
 491 .B Escape sequences
 492 are in-line functions and in-word formatting elements starting with a
 493 backslash
 494 .squoted_char \[rs] .
 495 .
 496 .P
 497 The user can define her own formatting commands using the
 498 .request de
 499 request.
 500 .
 501 These commands are called
 502 .BR macros ,
 503 but they are used exactly like requests.
 504 .
 505 Macro packages are pre-defined sets of macros written in the groff
 506 language.
 507 .
 508 A user's possibilities to create escape sequences herself is very
 509 limited, only special characters can be mapped.
 510 .
 511 .P
 512 The groff language provides several kinds of variables with
 513 different interfaces.
 514 .
 515 There are pre-defined variables, but the user can define her own
 516 variables as well.
 517 .
 518 .P
 519 .B String
 520 variables store character sequences.
 521 .
 522 They are set with the
 523 .request ds
 524 request and retrieved by the
 525 .esc *
 526 escape sequences.
 527 .
 528 Strings can have variables.
 529 .
 530 .P
 531 .B Register
 532 variables can store numerical values, numbers with a scale unit, and
 533 occasionally string-like objects.
 534 .
 535 They are set with the
 536 .request nr
 537 request and retrieved by the
 538 .esc n
 539 escape sequences.
 540 .
 541 .P
 542 .B Environments
 543 allow the user to temporarily store global formatting parameters like
 544 line length, font size, etc.\& for later reuse.
 545 .
 546 This is done by the
 547 .request ev
 548 request.
 549 .
 550 .P
 551 .B Fonts
 552 are identified either by a name or by an internal number.
 553 .
 554 The current font is chosen by the
 555 .request ft
 556 request or by the
 557 .esc f
 558 escape sequences.
 559 .
 560 Each device has special fonts, but the following fonts are available
 561 for all devices.
 562 .B R
 563 is the standard font Roman.
 564 .B B
 565 is its
 566 .B bold
 567 counterpart.
 568 .
 569 The
 570 .I italic
 571 font is called
 572 .B I
 573 and is available everywhere, but on text devices it is displayed as an
 574 underlined Roman font.
 575 .
 576 For the graphical output devices, there exist constant-width pendants
 577 of these fonts,
 578 .BR CR ,
 579 .BR CI ,
 580 and
 581 .BR CB .
 582 On text devices, all characters have a constant width anyway.
 583 .
 584 .P
 585 Moreover, there are some advanced roff elements.
 586 .
 587 A
 588 .B diversion
 589 stores information into a macro for later usage.
 590 .
 591 A
 592 .B trap
 593 is a positional condition like a certain number of lines from page top
 594 or in a diversion or in the input.
 595 .
 596 Some action can be prescribed to be run automatically when the
 597 condition is met.
 598 .
 599 .P
 600 More detailed information and examples can be found in the groff info
 601 file.
 602 .
 603 .
 604 .\" --------------------------------------------------------------------
 605 .SH "CONTROL CHARACTERS"
 606 .\" --------------------------------------------------------------------
 607 .
 608 There is a small set of characters that have a special controlling
 609 task in certain conditions.
 610 .
 611 .TP
 612 .character .
 613 A dot is only special at the beginning of a line or after the
 614 condition in the requests
 615 .request if ,
 616 .request ie ,
 617 .request el ,
 618 and
 619 .request while .
 620 There it is the control character that introduces a request (or macro).
 621 .
 622 The special behavior can be delayed by using the
 623 .esc .
 624 escape.
 625 .
 626 By using the
 627 .request cc
 628 request, the control character can be set to a different character,
 629 making the dot
 630 .squoted_char .
 631 a non-special character.
 632 .IP ""
 633 In all other positions, it just means a dot character.
 634 .
 635 In text paragraphs, it is advantageous to start each sentence at a
 636 line of its own.
 637 .
 638 .TP
 639 .character '
 640 The single quote has two controlling tasks.
 641 .
 642 At the beginning of a line and in the conditional requests it is the
 643 non-breaking control character.
 644 .
 645 That means that it introduces a request like the dot, but with the
 646 additional property that this request doesn't cause a linebreak.
 647 .
 648 By using the
 649 .request c2
 650 request, the non-break control character can be set to a different
 651 character.
 652 .
 653 .IP ""
 654 As a second task, it is the most commonly used argument separator in
 655 some functional escape sequences (but any pair of characters not part
 656 of the argument will work).
 657 .
 658 In all other positions, it denotes the single quote or apostrophe
 659 character.
 660 .
 661 Groff provides a printable representation with the
 662 .esc (cq
 663 escape sequence.
 664 .
 665 .TP
 666 .character \[dq]
 667 The double quote is used to enclose arguments in requests, macros, and
 668 strings.
 669 .
 670 In the
 671 .request ds
 672 and
 673 .request as
 674 requests, a leading double quote in the argument will be stripped off,
 675 making everything else afterwards the string to be defined (enabling
 676 leading whitespace).
 677 .
 678 The escaped double quote
 679 .esc \[dq]
 680 introduces a comment.
 681 .
 682 Otherwise, it is not special.
 683 .
 684 Groff provides a printable representation with the
 685 .esc (dq
 686 escape sequence.
 687 .
 688 .TP
 689 .character \[rs]
 690 The backslash usually introduces an escape sequence (this can be
 691 changed with the
 692 .request ec
 693 request).
 694 .
 695 A printed version of the escape character is the
 696 .esc e
 697 escape; a backslash glyph can be obtained by
 698 .esc (rs .
 699 .TP
 700 .character (
 701 The open parenthesis is only special in escape sequences when
 702 introducing an escape name or argument consisting of exactly two
 703 characters.
 704 .
 705 In groff, this behavior can be replaced by the \f[CB][]\f[] construct.
 706 .TP
 707 .character [
 708 The opening bracket is only special in groff escape sequences; there
 709 it is used to introduce a long escape name or long escape argument.
 710 .
 711 Otherwise, it is non-special, e.g.\& in macro calls.
 712 .TP
 713 .character ]
 714 The closing bracket is only special in groff escape sequences; there
 715 it terminates a long escape name or long escape argument.
 716 .
 717 Otherwise, it is non-special.
 718 .TP
 719 \f[CI]space\f[]
 720 Space characters are only functional characters.
 721 .
 722 They separate the arguments in requests, macros, and strings, and the words
 723 in text lines.
 724 .
 725 They are subject to groff's horizontal spacing calculations.
 726 .
 727 To 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 ^ ,
 732 or
 733 .esc h
 734 should be used.
 735 .
 736 .IP \f[CI]newline\f[]
 737 In text paragraphs, newlines mostly behave like space characters.
 738 .
 739 Continuation lines can be specified by an escaped newline, i.e., by
 740 specifying a backslash
 741 .squoted_char \[rs]
 742 as the last character of a line.
 743 .IP \f[CI]tab\f[]
 744 If a tab character occurs during text the interpreter makes a
 745 horizontal jump to the next pre-defined tab position.
 746 .
 747 There is a sophisticated interface for handling tab positions.
 748 .
 749 .
 750 .\" --------------------------------------------------------------------
 751 .SH "NUMERICAL EXPRESSIONS"
 752 .\" --------------------------------------------------------------------
 753 .
 754 A
 755 .B numerical value
 756 is a signed or unsigned integer or float with or without an appended
 757 scaling indicator.
 758 .
 759 A
 760 .B scaling indicator
 761 is a one-character abbreviation for a unit of measurement.
 762 .
 763 A number followed by a scaling indicator signifies a size value.
 764 .
 765 By default, numerical values do not have a scaling indicator, i.e., they
 766 are normal numbers.
 767 .
 768 .P
 769 The
 770 .I roff
 771 language defines the following scaling indicators.
 772 .
 773 .
 774 .P
 775 .PD 0
 776 .RS
 777 .
 778 .TPx
 779 .B c
 780 Centimeter
 781 .
 782 .TPx
 783 .B i
 784 Inch
 785 .
 786 .TPx
 787 .B P
 788 Pica\ \[eq]\ 1/6\ inch
 789 .
 790 .TPx
 791 .B p
 792 Point\ \[eq]\ 1/72\ inch
 793 .
 794 .TPx
 795 .B m
 796 Em\ \[eq]\ \f[R]the font size in points (width of letter `\f[CR]m\f[R]')
 797 .
 798 .TPx
 799 .B M
 800 100\^th \f[R]of an \f[CR]Em
 801 .
 802 .TPx
 803 .B n
 804 En\ \[eq]\ Em/2
 805 .
 806 .TPx
 807 .B u
 808 Basic unit for actual output device
 809 .
 810 .TPx
 811 .B v
 812 Vertical line space in basic units
 813 scaled point\ \[eq]\ 1/\f[CI]sizescale\f[R] of a point (defined in
 814 font \f[I]DESC\f[] file)
 815 .
 816 .TPx
 817 .B f
 818 Scale by 65536.
 819 .RE
 820 .PD
 821 .
 822 .P
 823 .B Numerical expressions
 824 are combinations of the numerical values defined above with the
 825 following arithmetical operators already defined in classical troff.
 826 .
 827 .P
 828 .PD 0
 829 .RS
 830 .
 831 .TPx
 832 .B +
 833 Addition
 834 .
 835 .TPx
 836 .B \-
 837 Subtraction
 838 .
 839 .TPx
 840 .B *
 841 Multiplication
 842 .
 843 .TPx
 844 .B /
 845 Division
 846 .
 847 .TPx
 848 .B %
 849 Modulo
 850 .
 851 .TPx
 852 .B =
 853 Equals
 854 .
 855 .TPx
 856 .B ==
 857 Equals
 858 .
 859 .TPx
 860 .B <
 861 Less than
 862 .
 863 .TPx
 864 .B >
 865 Greater than
 866 .
 867 .TPx
 868 .B <=
 869 Less or equal
 870 .
 871 .TPx
 872 .B >=
 873 Greater or equal
 874 .
 875 .TPx
 876 .B &
 877 Logical and
 878 .
 879 .TPx
 880 .B :
 881 Logical or
 882 .
 883 .TPx
 884 .B !
 885 Logical not
 886 .
 887 .TPx
 888 .B (
 889 Grouping of expressions
 890 .
 891 .TPx
 892 .B )
 893 Close current grouping
 894 .
 895 .RE
 896 .PD
 897 .
 898 .P
 899 Moreover,
 900 .I groff
 901 added the following operators for numerical expressions:
 902 .
 903 .P
 904 .PD 0
 905 .RS
 906 .
 907 .TPx
 908 .ExecFF Text I CB e1 >? e2
 909 The maximum of
 910 .I e1
 911 and
 912 .IR e2 .
 913 .
 914 .TPx
 915 .ExecFF Text I CB e1 <? e2
 916 The minimum of
 917 .I e1
 918 and
 919 .IR e2 .
 920 .
 921 .TPx
 922 .ExecFF Text CB I ( c ; e )
 923 Evaluate
 924 .I e
 925 using
 926 .I c
 927 as the default scaling indicator.
 928 .
 929 .RE
 930 .PD
 931 .
 932 .P
 933 For details see the groff info file.
 934 .
 935 .
 936 .\" --------------------------------------------------------------------
 937 .SH CONDITIONS
 938 .\" --------------------------------------------------------------------
 939 .
 940 .B Conditions
 941 occur in tests raised by the
 942 .request if ,
 943 .request ie ,
 944 and the
 945 .request while
 946 requests.
 947 .
 948 The following table characterizes the different types of conditions.
 949 .
 950 .P
 951 .PD 0
 952 .RS
 953 .
 954 .TPx
 955 .I N
 956 A numerical expression
 957 .I N
 958 yields true if its value is greater than\~0.
 959 .
 960 .TPx
 961 .BI ! N
 962 True if the value of
 963 .I I
 964 is\~0.
 965 .
 966 .TPx
 967 .BI ' s1 ' s2 '
 968 True if string\~\c
 969 .I s1
 970 is identical to string\~\c
 971 .IR s2 .
 972 .
 973 .TPx
 974 .BI !' s1 ' s2 '
 975 True if string\~\c
 976 .I s1
 977 is not identical to string\~\c
 978 .IR s2 .
 979 .
 980 .TPx
 981 .BI c ch
 982 True if there is a character\~\c
 983 .I ch
 984 available.
 985 .
 986 .TPx
 987 .BI d name
 988 True if there is a string, macro, diversion, or request called
 989 .IR name .
 990 .
 991 .TPx
 992 .B e
 993 Current page number is even.
 994 .
 995 .TPx
 996 .B o
 997 Current page number is odd.
 998 .
 999 .TPx
1000 .BI m name
1001 True if there is a color called
1002 .IR name .
1003 .
1004 .TPx
1005 .B n
1006 Formatter is
1007 .BR nroff .
1008 .
1009 .TPx
1010 .BI r reg
1011 True if there is a register named
1012 .IR reg .
1013 .
1014 .TPx
1015 .B t
1016 Formatter is
1017 .BR troff .
1018 .
1019 .TPx
1020 .BI F font
1021 True if there exists a font named
1022 .IR font .
1023 .
1024 .TPx
1025 .BI S style
1026 True if a style named
1027 .I style
1028 has been registered.
1029 .
1030 .RE
1031 .PD
1032 .
1033 .
1034 .\" --------------------------------------------------------------------
1035 .SH REQUESTS
1036 .\" --------------------------------------------------------------------
1037 .
1038 This section provides a short reference for the predefined requests.
1039 .
1040 In groff, request and macro names can be arbitrarily long.
1041 .
1042 No bracketing or marking of long names is needed.
1043 .
1044 .P
1045 Most requests take one or more arguments.
1046 .
1047 The arguments are separated by space characters (no tabs!); there is
1048 no inherent limit for their length or number.
1049 .
1050 An argument can be enclosed by a pair of double quotes.
1051 .
1052 This is very handy if an argument contains space characters, e.g.,
1053 .RI \[dq] "arg with space" \[dq]
1054 denotes a single argument.
1055 .
1056 .P
1057 Some requests have optional arguments with a different behaviour.
1058 .
1059 Not all of these details are outlined here.
1060 .
1061 Refer to the groff info file and
1062 .BR groff_diff (@MAN7EXT@)
1063 for all details.
1064 .
1065 .P
1066 In the following request specifications, most argument names were
1067 chosen to be descriptive.
1068 .
1069 Only the following denotations need clarification.
1070 .
1071 .P
1072 .PD 0
1073 .RS
1074 .
1075 .TPx
1076 .I c
1077 denotes a single character.
1078 .
1079 .TPx
1080 .I font
1081 a font either specified as a font name or a font number.
1082 .
1083 .TPx
1084 .I anything
1085 all characters up to the end of the line or within
1086 .esc {
1087 and
1088 .esc } .
1089 .
1090 .TPx
1091 .I n
1092 is a numerical expression that evaluates to an integer value.
1093 .
1094 .TPx
1095 .I N
1096 is an arbitrary numerical expression, signed or unsigned.
1097 .
1098 .TPx
1099 .I \[+-]N
1100 has three meanings depending on its sign, described below.
1101 .
1102 .RE
1103 .PD
1104 .
1105 .P
1106 If an expression defined as
1107 .I \[+-]N
1108 starts with a
1109 .squoted_char +
1110 sign the resulting value of the expression will be added to an already
1111 existing value inherent to the related request, e.g.\& adding to a number
1112 register.
1113 .
1114 If the expression starts with a
1115 .squoted_char -
1116 the value of the expression will be subtracted from the request value.
1117 .
1118 .P
1119 Without a sign,
1120 .I N
1121 replaces the existing value directly.
1122 .
1123 To assign a negative number either prepend\~0 or enclose the negative
1124 number in parentheses.
1125 .
1126 .
1127 .\" --------------------------------------------------------------------
1128 .SS "Request Short Reference"
1129 .\" --------------------------------------------------------------------
1130 .
1131 .PD 0
1132 .
1133 .REQ .
1134 Empty line, ignored.
1135 .
1136 Useful for structuring documents.
1137 .
1138 .REQ .\[rs]\[dq] anything
1139 Complete line is a comment.
1140 .
1141 .REQ .ab string
1142 Print
1143 .I string
1144 on standard error, exit program.
1145 .
1146 .REQ .ad
1147 Begin line adjustment for output lines in current adjust mode.
1148 .
1149 .REQ .ad c
1150 Start 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
1155 Assign format
1156 .I c
1157 to
1158 .I register
1159 (\f[CI]c\f[]\f[CR]\|\^\[eq]\|l,i,I,a,A\f[]).
1160 .
1161 .REQ .aln alias register
1162 Create alias name for
1163 .IR register .
1164 .
1165 .REQ .als alias object
1166 Create alias name for request, string, macro, or diversion
1167 .IR object .
1168 .
1169 .REQ .am macro
1170 Append to
1171 .I macro
1172 until
1173 .B ..\&
1174 is encountered.
1175 .
1176 .REQ .am macro end
1177 Append to
1178 .I macro
1179 until
1180 .request .end
1181 is called.
1182 .
1183 .REQ .am1 macro
1184 Same as
1185 .request .am
1186 but with compatibility mode switched off during macro expansion.
1187 .
1188 .REQ .am1 macro end
1189 Same as
1190 .request .am
1191 but with compatibility mode switched off during macro expansion.
1192 .
1193 .REQ .ami macro
1194 Append to a macro whose name is contained in the string register
1195 .I macro
1196 until
1197 .B ..\&
1198 is encountered.
1199 .
1200 .REQ .ami macro end
1201 Append to a macro indirectly.
1202 .I macro
1203 and
1204 .I end
1205 are string registers whose contents are interpolated for the macro name
1206 and the end macro, respectively.
1207 .
1208 .REQ .ami1 macro
1209 Same as
1210 .request .ami
1211 but with compatibility mode switched off during macro expansion.
1212 .
1213 .REQ .ami1 macro end
1214 Same as
1215 .request .ami
1216 but with compatibility mode switched off during macro expansion.
1217 .
1218 .REQ .as stringvar anything
1219 Append
1220 .I anything
1221 to
1222 .IR stringvar .
1223 .
1224 .REQ .as1 stringvar anything
1225 Same as
1226 .request .as
1227 but with compatibility mode switched off during string expansion.
1228 .
1229 .REQ .asciify diversion
1230 Unformat ASCII characters, spaces, and some escape sequences in
1231 .IR diversion .
1232 .
1233 .REQ .backtrace
1234 Print a backtrace of the input on stderr.
1235 .
1236 .REQ .bd font N
1237 Embolden
1238 .I font
1239 by
1240 .IR N -1
1241 units.
1242 .
1243 .REQ .bd S font N
1244 Embolden Special Font
1245 .I S
1246 when current font is
1247 .IR font .
1248 .
1249 .REQ .blm
1250 Unset the blank line macro.
1251 .
1252 .REQ .blm macro
1253 Set the blank line macro to
1254 .IR macro .
1255 .
1256 .REQ .box
1257 End current diversion.
1258 .
1259 .REQ .box macro
1260 Divert to
1261 .IR macro ,
1262 omitting a partially filled line.
1263 .
1264 .REQ .boxa
1265 End current diversion.
1266 .
1267 .REQ .boxa macro
1268 Divert and append to
1269 .IR macro ,
1270 omitting a partially filled line.
1271 .
1272 .REQ .bp
1273 Eject current page and begin new page.
1274 .
1275 .REQ .bp \[+-]N
1276 Eject current page; next page number
1277 .IR \[+-]N .
1278 .
1279 .REQ .br
1280 Line break.
1281 .
1282 .REQ .brp
1283 Break and spread output line.
1284 Same as
1285 .esc p .
1286 .
1287 .REQ .break
1288 Break out of a while loop.
1289 .
1290 .REQ .c2
1291 Reset no-break control character to
1292 .dquoted_char ' .
1293 .
1294 .REQ .c2 c
1295 Set no-break control character to
1296 .IR c .
1297 .
1298 .REQ .cc
1299 Reset control character to
1300 .squoted_char . .
1301 .
1302 .REQ .cc c
1303 Set control character to
1304 .IR c .
1305 .
1306 .REQ .ce
1307 Center the next input line.
1308 .
1309 .REQ .ce N
1310 Center following
1311 .I N
1312 input lines.
1313 .
1314 .REQ .cf filename
1315 Copy contents of file
1316 .I filename
1317 unprocessed to stdout or to the diversion.
1318 .
1319 .REQ .cflags mode c1 c2 .\|.\|.\&
1320 Treat characters
1321 .IR c1 ,
1322 .IR c2 ,
1323 .I .\|.\|.\&
1324 according to
1325 .I mode
1326 number.
1327 .
1328 .REQ .ch trap N
1329 Change
1330 .I trap
1331 location
1332 to
1333 .I N .
1334 .
1335 .REQ .char c anything
1336 Define character
1337 .I c
1338 as string
1339 .IR anything .
1340 .
1341 .REQ .chop object
1342 Chop the last character off macro, string, or diversion
1343 .IR object .
1344 .
1345 .REQ .close stream
1346 Close the
1347 .IR stream .
1348 .
1349 .REQ .color
1350 Enable colors.
1351 .
1352 .REQ .color N
1353 If
1354 .I N
1355 is zero disable colors, otherwise enable them.
1356 .
1357 .REQ .composite from to
1358 Map glyph name
1359 .I from
1360 to glyph name
1361 .I to
1362 while constructing a composite glyph name.
1363 .
1364 .REQ .continue
1365 Finish the current iteration of a while loop.
1366 .
1367 .REQ .cp
1368 Enable compatibility mode.
1369 .
1370 .REQ .cp N
1371 If
1372 .I N
1373 is zero disable compatibility mode, otherwise enable it.
1374 .
1375 .REQ .cs font N M
1376 Set constant character width mode for
1377 .I font
1378 to
1379 .IR N /36
1380 ems with em
1381 .IR M .
1382 .
1383 .REQ .cu N
1384 Continuous underline in nroff, like
1385 .request .ul
1386 in troff.
1387 .
1388 .REQ .da
1389 End current diversion.
1390 .
1391 .REQ .da macro
1392 Divert and append to
1393 .IR macro .
1394 .
1395 .REQ .de macro
1396 Define or redefine
1397 .I macro
1398 until
1399 .B ..\&
1400 is encountered.
1401 .
1402 .REQ .de macro end
1403 Define or redefine
1404 .I macro
1405 until
1406 .request .end
1407 is called.
1408 .
1409 .REQ .de1 macro
1410 Same as
1411 .request .de
1412 but with compatibility mode switched off during macro expansion.
1413 .
1414 .REQ .de1 macro end
1415 Same as
1416 .request .de
1417 but with compatibility mode switched off during macro expansion.
1418 .
1419 .REQ .defcolor color scheme component
1420 Define or redefine a color with name
1421 .IR color .
1422 .I scheme
1423 can be
1424 .BR rgb ,
1425 .BR cym ,
1426 .BR cymk ,
1427 .BR gray ,
1428 or
1429 .BR grey .
1430 .I component
1431 can be single components specified as fractions in the range 0 to 1
1432 (default scaling indicator\~\c
1433 .scaleindicator f ),
1434 as a string of two-digit hexadecimal color components with a leading
1435 .BR # ,
1436 or as a string of four-digit hexadecimal components with two leading
1437 .BR # .
1438 The color
1439 .B default
1440 can't be redefined.
1441 .
1442 .REQ .dei macro
1443 Define or redefine a macro whose name is contained in the string register
1444 .I macro
1445 until
1446 .B ..\&
1447 is encountered.
1448 .
1449 .REQ .dei macro end
1450 Define or redefine a macro indirectly.
1451 .I macro
1452 and
1453 .I end
1454 are string registers whose contents are interpolated for the macro name
1455 and the end macro, respectively.
1456 .
1457 .REQ .dei1 macro
1458 Same as
1459 .request .dei
1460 but with compatibility mode switched off during macro expansion.
1461 .
1462 .REQ .dei1 macro end
1463 Same as
1464 .request .dei
1465 but with compatibility mode switched off during macro expansion.
1466 .
1467 .REQ .di
1468 End current diversion.
1469 .
1470 .REQ .di macro
1471 Divert to
1472 .I macro .
1473 .
1474 .REQ .do name
1475 Interpret
1476 .request .name
1477 with compatibility mode disabled.
1478 .
1479 .REQ .ds stringvar anything
1480 Set
1481 .I stringvar
1482 to
1483 .IR anything .
1484 .
1485 .REQ .ds1 stringvar anything
1486 Same as
1487 .request .ds
1488 but with compatibility mode switched off during string expansion.
1489 .
1490 .REQ .dt N trap
1491 Set diversion trap to position
1492 .I N
1493 (default scaling indicator\~\c
1494 .scaleindicator v ).
1495 .
1496 .REQ .ec
1497 Reset escape character to
1498 .squoted_char \[rs] .
1499 .
1500 .REQ .ec c
1501 Set escape character to
1502 .IR c .
1503 .
1504 .REQ .ecr
1505 Restore escape character saved with
1506 .request .ecs .
1507 .
1508 .REQ .ecs
1509 Save current escape character.
1510 .
1511 .REQ .el anything
1512 Else part for if-else (\c
1513 .request ie )
1514 request.
1515 .
1516 .REQ .em macro
1517 The
1518 .I macro
1519 will be run after the end of input.
1520 .
1521 .REQ .eo
1522 Turn off escape character mechanism.
1523 .
1524 .REQ .ev
1525 Switch to previous environment.
1526 .
1527 .REQ .ev env
1528 Push down environment number or name
1529 .I env
1530 and switch to it.
1531 .
1532 .REQ .evc env
1533 Copy the contents of environment
1534 .I env
1535 to the current environment.
1536 No pushing or popping.
1537 .
1538 .REQ .ex
1539 Exit from roff processing.
1540 .
1541 .REQ .fam
1542 Return to previous font family.
1543 .
1544 .REQ .fam name
1545 Set the current font family to
1546 .IR name .
1547 .
1548 .REQ .fc
1549 Disable field mechanism.
1550 .
1551 .REQ .fc a
1552 Set field delimiter to
1553 .I a
1554 and pad character to space.
1555 .
1556 .REQ .fc a b
1557 Set field delimiter to
1558 .I a
1559 and pad character to
1560 .IR b .
1561 .
1562 .REQ .fchar c anything
1563 Define fallback character
1564 .I c
1565 as string
1566 .IR anything .
1567 .
1568 .REQ .fcolor
1569 Set fill color to previous fill color.
1570 .
1571 .REQ .fcolor c
1572 Set fill color to
1573 .IR c .
1574 .
1575 .REQ .fi
1576 Fill output lines.
1577 .
1578 .REQ .fl
1579 Flush output buffer.
1580 .
1581 .REQ .fp n font
1582 Mount
1583 .I font
1584 on position
1585 .IR n .
1586 .
1587 .REQ .fp n internal external
1588 Mount font with long
1589 .I external
1590 name to short
1591 .I internal
1592 name on position
1593 .IR n .
1594 .
1595 .REQ .fschar f c anything
1596 Define fallback character
1597 .I c
1598 for font
1599 .I f
1600 as string
1601 .IR anything .
1602 .
1603 .REQ .fspecial font
1604 Reset list of special fonts for
1605 .I font
1606 to be empty.
1607 .
1608 .REQ .fspecial font s1 s2 .\|.\|.\&
1609 When the current font is
1610 .IR font ,
1611 then the fonts
1612 .IR s1 ,
1613 .IR s2 ,
1614 .I .\|.\|.\&
1615 will be special.
1616 .
1617 .REQ .ft
1618 Return to previous font.
1619 Same as
1620 .request \[rs]f[]
1621 or
1622 .request \[rs]fP .
1623 .
1624 .REQ .ft font
1625 Change to font name or number
1626 .IR font ;
1627 same as
1628 .esc[] f font
1629 escape sequence.
1630 .
1631 .REQ .ftr font1 font2
1632 Translate
1633 .I font1
1634 to
1635 .IR font2 .
1636 .
1637 .REQ .gcolor
1638 Set glyph color to previous glyph color.
1639 .
1640 .REQ .gcolor c
1641 Set glyph color to
1642 .IR c .
1643 .
1644 .REQ .hc
1645 Remove additional hyphenation indicator character.
1646 .
1647 .REQ .hc c
1648 Set up additional hyphenation indicator character\~\c
1649 .IR c .
1650 .
1651 .REQ .hcode c1 code1 c2 code2 .\|.\|.\&
1652 Set the hyphenation code of character
1653 .I c1
1654 to
1655 .IR code1 ,
1656 that of
1657 .I c2
1658 to
1659 .IR code2 ,
1660 etc.
1661 .
1662 .REQ .hla lang
1663 Set the current hyphenation language to
1664 .IR lang .
1665 .
1666 .REQ .hlm n
1667 Set the maximum number of consecutive hyphenated lines to
1668 .IR n .
1669 .
1670 .REQ .hpf file
1671 Read hyphenation patterns from
1672 .IR file .
1673 .
1674 .REQ .hpfa file
1675 Append hyphenation patterns from
1676 .IR file .
1677 .
1678 .REQ .hpfcode file
1679 Set input mapping for
1680 .request .hpf .
1681 .
1682 .REQ .hw words
1683 List of
1684 .I words
1685 with exceptional hyphenation.
1686 .
1687 .REQ .hy N
1688 Switch to hyphenation mode
1689 .IR N .
1690 .
1691 .REQ .hym n
1692 Set the hyphenation margin to
1693 .I n
1694 (default scaling indicator\~\c
1695 .scaleindicator m ).
1696 .
1697 .REQ .hys n
1698 Set the hyphenation space to
1699 .IR n .
1700 .
1701 .REQ .ie cond anything
1702 If
1703 .I cond
1704 then
1705 .I anything
1706 else goto
1707 .request .el .
1708 .
1709 .REQ .if cond anything
1710 If
1711 .I cond
1712 then
1713 .IR anything ;
1714 otherwise do nothing.
1715 .
1716 .REQ .ig
1717 Ignore text until
1718 .B ..\&
1719 is encountered.
1720 .
1721 .REQ .ig end
1722 Ignore text until
1723 .request .end .
1724 .
1725 .REQ .in
1726 Change to previous indent value.
1727 .
1728 .REQ .in \[+-]N
1729 Change indent according to
1730 .I \[+-]N
1731 (default scaling indicator\~\c
1732 .scaleindicator m ).
1733 .
1734 .REQ .it N trap
1735 Set an input-line count trap for the next
1736 .I N
1737 lines.
1738 .
1739 .REQ .itc N trap
1740 Same as
1741 .request .it
1742 but count lines interrupted with
1743 .esc c
1744 as one line.
1745 .
1746 .REQ .kern
1747 Enable pairwise kerning.
1748 .
1749 .REQ .kern n
1750 If
1751 .I n
1752 is zero, disable pairwise kerning, otherwise enable it.
1753 .
1754 .REQ .lc
1755 Remove leader repetition character.
1756 .
1757 .REQ .lc c
1758 Set leader repetition character to\~\c
1759 .IR c .
1760 .
1761 .REQ .length register anything
1762 Write the length of the string
1763 .I anything
1764 in
1765 .IR register .
1766 .
1767 .REQ .linetabs
1768 Enable line-tabs mode (i.e., calculate tab positions relative to output
1769 line).
1770 .
1771 .REQ .linetabs n
1772 If
1773 .I n
1774 is zero, disable line-tabs mode, otherwise enable it.
1775 .
1776 .REQ .lf N
1777 Set input line number to
1778 .IR N .
1779 .
1780 .REQ .lf N file
1781 Set input line number to
1782 .I N
1783 and filename to
1784 .IR file .
1785 .
1786 .REQ .lg N
1787 Ligature mode on if
1788 .IR N >0.
1789 .
1790 .REQ .ll
1791 Change to previous line length.
1792 .
1793 .REQ .ll \[+-]N
1794 Set line length according to
1795 .I \[+-]N
1796 (default size
1797 .scalednumber 6.5 i ,
1798 default scaling indicator\~\c
1799 .scaleindicator m ).
1800 .
1801 .REQ .ls
1802 Change to the previous value of additional intra-line skip.
1803 .
1804 .REQ .ls N
1805 Set additional intra-line skip value to
1806 .IR N ,
1807 i.e.,
1808 .IR N -1
1809 blank lines are inserted after each text output line.
1810 .
1811 .REQ .lt \[+-]N
1812 Length of title (default scaling indicator\~\c
1813 .scaleindicator m ).
1814 .
1815 .REQ .mc
1816 Margin character off.
1817 .
1818 .REQ .mc c
1819 Print character
1820 .I c
1821 after each text line at actual distance from right margin.
1822 .
1823 .REQ .mc c N
1824 Set margin character to
1825 .I c
1826 and distance to
1827 .I N
1828 from right margin (default scaling indicator\~\c
1829 .scaleindicator m ).
1830 .
1831 .REQ .mk register
1832 Mark current vertical position in
1833 .IR register .
1834 .
1835 .REQ .mso file
1836 The same as the .so request except that
1837 .I file
1838 is searched in the tmac directories.
1839 .
1840 .REQ .na
1841 No output-line adjusting.
1842 .
1843 .REQ .ne
1844 Need a one-line vertical space.
1845 .
1846 .REQ .ne N
1847 Need
1848 .I N
1849 vertical space (default scaling indicator\~\c
1850 .scaleindicator v ).
1851 .
1852 .REQ .nf
1853 No filling or adjusting of output-lines.
1854 .
1855 .REQ .nh
1856 No hyphenation.
1857 .
1858 .REQ .nm
1859 Number mode off.
1860 .
1861 .REQ .nm \[+-]N \fR[\fPM \fR[\fPS \fR[\fPI\fR]]]\fP
1862 In line number mode, set number, multiple, spacing, and indent.
1863 .
1864 .REQ .nn
1865 Do not number next line.
1866 .
1867 .REQ .nn N
1868 Do not number next
1869 .I N
1870 lines.
1871 .
1872 .REQ .nop anything
1873 Always execute
1874 .IR anything .
1875 .
1876 .REQ .nr register \[+-]N M
1877 Define or modify
1878 .I register
1879 using
1880 .I \[+-]N
1881 with auto-increment
1882 .IR M .
1883 .
1884 .REQ .nroff
1885 Make the built-in condition
1886 .B n
1887 true and
1888 .B t
1889 false.
1890 .
1891 .REQ .ns
1892 Turn no-space mode on.
1893 .
1894 .REQ .nx
1895 Immediately jump to end of current file.
1896 .
1897 .REQ .nx filename
1898 Next file.
1899 .
1900 .REQ .open stream filename
1901 Open
1902 .register filename
1903 for writing and associate the stream named
1904 .register stream
1905 with it.
1906 .
1907 .REQ .opena stream filename
1908 Like
1909 .request .open
1910 but append to it.
1911 .
1912 .REQ .os
1913 Output vertical distance that was saved by the
1914 .request sv
1915 request.
1916 .
1917 .REQ .output string
1918 Emit
1919 .I string
1920 directly to intermediate output, allowing leading whitespace if
1921 .I string
1922 starts with
1923 .character \[dq]
1924 (which will be stripped off).
1925 .
1926 .REQ .pc
1927 Reset page number character to\~\c
1928 .squoted_char % .
1929 .
1930 .REQ .pc c
1931 Page number character.
1932 .
1933 .REQ .pi program
1934 Pipe output to
1935 .I program
1936 (nroff only).
1937 .
1938 .REQ .pl
1939 Set page length to default
1940 .scalednumber 11 i .
1941 The current page length is stored in
1942 .register .p .
1943 .
1944 .REQ .pl \[+-]N
1945 Change page length to
1946 .I \[+-]N
1947 (default scaling indicator\~\c
1948 .scaleindicator v ).
1949 .
1950 .REQ .pm
1951 Print macro names and sizes (number of blocks of 128 bytes).
1952 .
1953 .REQ ".pm t"
1954 Print only total of sizes of macros (number of 128 bytes blocks).
1955 .
1956 .REQ .pn \[+-]N
1957 Next page number
1958 .IR N .
1959 .
1960 .REQ .pnr
1961 Print the names and contents of all currently defined number registers
1962 on stderr.
1963 .
1964 .REQ .po
1965 Change to previous page offset.
1966 .
1967 The current page offset is available in
1968 .register .o .
1969 .
1970 .REQ .po \[+-]N
1971 Page offset
1972 .IR N .
1973 .
1974 .REQ .ps
1975 Return to previous point-size.
1976 .REQ .ps \[+-]N
1977 Point size; same as
1978 .esc[] s \[+-]N .
1979 .
1980 .REQ .psbb filename
1981 Get the bounding box of a PostScript image
1982 .IR filename .
1983 .
1984 .REQ .pso command
1985 This behaves like the
1986 .request so
1987 request except that input comes from the standard output of
1988 .IR command .
1989 .
1990 .REQ .ptr
1991 Print the names and positions of all traps (not including input line
1992 traps and diversion traps) on stderr.
1993 .
1994 .REQ .pvs
1995 Change to previous post-vertical line spacing.
1996 .
1997 .REQ .pvs \[+-]N
1998 Change post-vertical line spacing according to
1999 .I \[+-]N
2000 (default scaling indicator\~\c
2001 .scaleindicator p ).
2002 .
2003 .REQ .rchar c1 c2 .\|.\|.\&
2004 Remove the definitions of characters
2005 .IR c1 ,
2006 .IR c2 ,
2007 .I .\|.\|.\&
2008 .
2009 .REQ .rd prompt
2010 Read insertion.
2011 .
2012 .REQ .return
2013 Return from a macro.
2014 .
2015 .REQ .return anything
2016 Return twice, namely from the macro at the current level and from the macro
2017 one level higher.
2018 .
2019 .REQ .rfschar f c1 c2 .\|.\|.\&
2020 Remove the definitions of characters
2021 .IR c1 ,
2022 .IR c2 ,
2023 .I .\|.\|.\&
2024 for font
2025 .IR f .
2026 .
2027 .REQ .rj n
2028 Right justify the next
2029 .I n
2030 input lines.
2031 .
2032 .REQ .rm name
2033 Remove request, macro, or string
2034 .IR name .
2035 .
2036 .REQ .rn old new
2037 Rename request, macro, or string
2038 .I old
2039 to
2040 .IR new .
2041 .
2042 .REQ .rnn reg1 reg2
2043 Rename register
2044 .I reg1
2045 to
2046 .IR reg2 .
2047 .
2048 .REQ .rr register
2049 Remove
2050 .IR register .
2051 .
2052 .REQ .rs
2053 Restore spacing; turn no-space mode off.
2054 .
2055 .REQ .rt \[+-]N
2056 Return
2057 .I (upward only)
2058 to marked vertical place (default scaling indicator\~\c
2059 .scaleindicator v ).
2060 .
2061 .REQ .schar c anything
2062 Define global fallback character
2063 .I c
2064 as string
2065 .IR anything .
2066 .
2067 .REQ .shc
2068 Reset soft hyphen character to
2069 .esc (hy .
2070 .
2071 .REQ .shc c
2072 Set the soft hyphen character to
2073 .IR c .
2074 .
2075 .REQ .shift n
2076 In a macro, shift the arguments by
2077 .IR n \~\c
2078 positions.
2079 .
2080 .REQ .sizes s1 s2 .\|.\|.\& sn \fB[0]\fP
2081 Set available font sizes similar to the
2082 .B sizes
2083 command in a
2084 .B DESC
2085 file.
2086 .
2087 .REQ .so filename
2088 Include source file.
2089 .
2090 .REQ .sp
2091 Skip one line vertically.
2092 .
2093 .REQ .sp N
2094 Space vertical distance
2095 .I N
2096 up or down according to sign of
2097 .I N
2098 (default scaling indicator\~\c
2099 .scaleindicator v ).
2100 .
2101 .REQ .special
2102 Reset global list of special fonts to be empty.
2103 .
2104 .REQ .special s1 s2 .\|.\|.\&
2105 Fonts
2106 .IR s1 ,
2107 .IR s2 ,
2108 etc.\& are special and will be searched for characters not in the
2109 current font.
2110 .
2111 .REQ .spreadwarn
2112 Toggle the spread warning on and off without changing its value.
2113 .
2114 .REQ .spreadwarn limit
2115 Emit a warning if each space in an output line is widened by
2116 .I limit
2117 or more (default scaling indicator\~\c
2118 .scaleindicator m ).
2119 .
2120 .REQ .ss N
2121 Space-character size set to
2122 .IR N /12
2123 of the spacewidth in the current font.
2124 .
2125 .REQ .ss N M
2126 Space-character size set to
2127 .IR N /12
2128 and sentence space size set to
2129 .IR M /12
2130 of the spacewidth in the current font (\f[CR]\[eq]1/3 em\f[]).
2131 .
2132 .REQ .sty n style
2133 Associate
2134 .I style
2135 with font position
2136 .IR n .
2137 .
2138 .REQ .substring xx n1 n2
2139 Replace the string named
2140 .I xx
2141 with the substring defined by the indices
2142 .I n1
2143 and
2144 .IR n2 .
2145 .
2146 .REQ .sv
2147 Save
2148 .scalednumber 1 v
2149 of vertical space.
2150 .
2151 .REQ .sv N
2152 Save the vertical distance
2153 .I N
2154 for later output with
2155 .request os
2156 request.
2157 .
2158 .REQ .sy command-line
2159 Execute program
2160 .IR command-line .
2161 .
2162 .REQ ".ta T" N
2163 Set 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
2168 Set tabs at positions
2169 .IR n1 ,
2170 .IR n2 ,
2171 .Text .\|.\|.,
2172 .IR nn ,
2173 then set tabs at
2174 .IR nn + r1 ,
2175 .IR nn + r2 ,
2176 .Text .\|.\|.,
2177 .IR nn + rn ,
2178 then at
2179 .IR nn + rn + r1 ,
2180 .IR nn + rn + r2 ,
2181 .Text .\|.\|.,
2182 .IR nn + rn + rn ,
2183 and 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
2192 Remove tab repition character.
2193 .REQ .tc c
2194 Set tab repetition character to\~\c
2195 .IR c .
2196 .
2197 .REQ .ti \[+-]N
2198 Temporary indent next line (default scaling indicator\~\c
2199 .scaleindicator m ).
2200 .
2201 .REQ .tkf font s1 n1 s2 n2
2202 Enable 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[]
2206 Three-part title.
2207 .
2208 .REQ .tm anything
2209 Print
2210 .I anything
2211 on terminal (UNIX standard message output).
2212 .
2213 .REQ .tm1 anything
2214 Print
2215 .I anything
2216 on terminal (UNIX standard message output), allowing leading
2217 whitespace if
2218 .I anything
2219 starts with
2220 .character \[dq]
2221 (which will be stripped off).
2222 .
2223 .REQ .tmc anything
2224 Similar to
2225 .request .tm1
2226 without emitting a final newline.
2227 .
2228 .REQ .tr abcd.\|.\|.\&
2229 Translate
2230 .I a
2231 to
2232 .IR b ,
2233 .I c
2234 to
2235 .IR d ,
2236 etc.\& on output.
2237 .
2238 .REQ .trf filename
2239 Transparently output the contents of file
2240 .IR filename .
2241 .
2242 .REQ .trin abcd.\|.\|.\&
2243 This is the same as the
2244 .request tr
2245 request except that the
2246 .B asciify
2247 request will use the character code (if any) before the character
2248 translation.
2249 .
2250 .REQ .trnt abcd.\|.\|.\&
2251 This is the same as the
2252 .request tr
2253 request except that the translations do not apply to text that is
2254 transparently throughput into a diversion with
2255 .esc ! .
2256 .
2257 .REQ .troff
2258 Make the built-in condition
2259 .B t
2260 true and
2261 .B n
2262 false.
2263 .
2264 .REQ .uf font
2265 Underline font set to
2266 .I font
2267 (to be switched to by
2268 .request .ul ).
2269 .
2270 .REQ .ul N
2271 Underline (italicize in troff)
2272 .I N
2273 input lines.
2274 .
2275 .REQ .unformat diversion
2276 Unformat space characters and tabs, preserving font information in
2277 .IR diversion .
2278 .REQ .vpt n
2279 Enable vertical position traps if
2280 .I n
2281 is non-zero, disable them otherwise.
2282 .
2283 .REQ .vs
2284 Change to previous vertical base line spacing.
2285 .
2286 .REQ .vs \[+-]N
2287 Set vertical base line spacing according to
2288 .I \[+-]N
2289 (default scaling indicator\~\c
2290 .scaleindicator p ).
2291 Default value is
2292 .scalednumber 12 p .
2293 .
2294 .REQ .warn n
2295 Set warnings code to
2296 .IR n .
2297 .
2298 .REQ .warnscale si
2299 Set scaling indicator used in warnings to
2300 .IR si .
2301 .
2302 .REQ .wh N
2303 Remove (first) trap at position
2304 .IR N .
2305 .
2306 .REQ .wh N trap
2307 Set location trap; negative means from page bottom.
2308 .
2309 .REQ .while cond anything
2310 While condition
2311 .I cond
2312 is true, accept
2313 .I anything
2314 as input.
2315 .
2316 .REQ .write stream anything
2317 Write
2318 .I anything
2319 to the stream named
2320 .IR stream .
2321 .
2322 .REQ .writec stream anything
2323 Similar to
2324 .request .write
2325 without emitting a final newline.
2326 .
2327 .REQ .writem stream xx
2328 Write contents of macro or string
2329 .I xx
2330 to the stream named
2331 .IR stream .
2332 .
2333 .PD
2334 .
2335 .P
2336 Besides these standard groff requests, there might be further macro
2337 calls.
2338 They can originate from a macro package (see
2339 .BR roff (@MAN7EXT@)
2340 for an overview) or from a preprocessor.
2341 .
2342 .P
2343 Preprocessor macros are easy to be recognized.
2344 .
2345 They enclose their code into a pair of characteristic macros.
2346 .
2347 .P
2348 .TS
2349 box, center, tab (@);
2350 c | c | c
2351 CfCB | CfCB | CfCB.
2352 preprocessor@start macro@ end macro
2353 =
2354 eqn@.PS@.PE
2355 grap@.G1@.G2
2356 grn@.GS@.GE
2357 pic@.PS@.PE
2358 refer@.R1@.R2
2359 soelim@\f[I]none@\f[I]none
2360 tbl@.TS@.TE
2361 .TE
2362 .P
2363 .
2364 .
2365 .\" --------------------------------------------------------------------
2366 .SH "ESCAPE SEQUENCES"
2367 .\" --------------------------------------------------------------------
2368 .
2369 Escape sequences are in-line language elements usually introduced by a
2370 backslash
2371 .squoted_char \[rs]
2372 and followed by an escape name and sometimes by a required argument.
2373 .
2374 Input processing is continued directly after the escaped character or
2375 the argument resp.\& without an intervening separation character.
2376 .
2377 So there must be a way to determine the end of the escape name and the
2378 end of the argument.
2379 .
2380 .P
2381 This is done by enclosing names (escape name and arguments consisting
2382 of a variable name) by a pair of brackets
2383 .BI \[lB] name \[rB]
2384 and constant arguments (number expressions and characters) by
2385 apostrophes (ASCII 0x27) like
2386 .BI \[cq] constant \[cq] \f[R].
2387 .
2388 .P
2389 There are abbreviations for short names.
2390 .
2391 Two character escape names can be specified by an opening parenthesis
2392 like
2393 .esc ( xy
2394 without a closing counterpart.
2395 .
2396 And all one-character names different from the special characters
2397 .squoted_char [
2398 and
2399 .squoted_char (
2400 can even be specified without a marker in the form
2401 .esc c .
2402 .
2403 .P
2404 Constant arguments of length\~1 can omit the marker apostrophes, too,
2405 but there is no two-character analogue.
2406 .
2407 .P
2408 While 1-character escape sequences are mainly used for in-line
2409 functions and system related tasks, the 2-letter names following the
2410 .esc (
2411 construct are used for special characters predefined by the roff system.
2412 .
2413 Escapes sequences with names of more than two characters
2414 .esc[] "" name
2415 denote user defined named characters (see the
2416 .request char
2417 request).
2418 .
2419 .
2420 .\" --------------------------------------------------------------------
2421 .SS "Single Character Escapes"
2422 .\" --------------------------------------------------------------------
2423 .
2424 .PD 0
2425 .
2426 .\" --------- comments ---------
2427 .
2428 .ESC \[dq]
2429 Beginning of a comment.
2430 .
2431 Everything up to the end of the line is ignored.
2432 .
2433 .ESC #
2434 Everything up to and including the next newline is ignored.
2435 .
2436 This is interpreted in copy mode.
2437 .
2438 This is like
2439 .esc \[dq]
2440 except that the terminating newline is ignored as well.
2441 .
2442 .\" --------- strings ---------
2443 .
2444 .ESC *\f[I]s\f[]
2445 The string stored in the string variable with 1-character name
2446 .IR s .
2447 .
2448 .ESC *(\f[I]st\f[]
2449 The string stored in the string variable with 2-character name
2450 .IR st .
2451 .
2452 .ESC[] * "stringvar arg1 arg2 .\|.\|."
2453 The string stored in the string variable with arbitrary length name
2454 .IR stringvar ,
2455 taking
2456 .IR arg1 ,
2457 .IR arg2 ,
2458 .I .\|.\|.\&
2459 as arguments.
2460 .
2461 .\" --------- macro arguments ---------
2462 .
2463 .ESC $0
2464 The name by which the current macro was invoked.
2465 .
2466 The
2467 .request als
2468 request can make a macro have more than one name.
2469 .
2470 .ESC $ x
2471 Macro or string argument with 1-place number
2472 .IR x ,
2473 where
2474 .I x
2475 is a digit between 1 and 9.
2476 .
2477 .ESC $( xy
2478 Macro or string argument with 2-digit number
2479 .IR xy .
2480 .
2481 .ESC[] $ nexp
2482 Macro or string argument with number
2483 .IR nexp ,
2484 where
2485 .I nexp
2486 is a numerical expression evaluating to an integer \[>=]1.
2487 .
2488 .ESC $*
2489 In a macro or string, the concatenation of all the arguments separated
2490 by spaces.
2491 .
2492 .ESC $@
2493 In a macro or string, the concatenation of all the arguments with each
2494 surrounded by double quotes, and separated by spaces.
2495 .
2496 .\" --------- escaped characters ---------
2497 .
2498 .ESC \[rs]
2499 reduces to a single backslash; useful to delay its interpretation as
2500 escape character in copy mode.
2501 .
2502 For a printable backslash, use
2503 .esc e ,
2504 or even better
2505 .esc [rs] ,
2506 to be independent from the current escape character.
2507 .
2508 .ESC \[cq]
2509 The acute accent \[aa]; same as
2510 .esc (aa .
2511 Unescaped: apostrophe, right quotation mark, single quote (ASCII 0x27).
2512 .
2513 .ESC `
2514 The grave accent \[ga]; same as
2515 .esc (ga .
2516 Unescaped: left quote, backquote (ASCII 0x60).
2517 .
2518 .ESC \-
2519 The \- sign in the current font.
2520 .
2521 .ESC .
2522 An uninterpreted dot (period), even at start of line.
2523 .
2524 .ESC %
2525 Default optional hyphenation character.
2526 .
2527 .ESC !
2528 Transparent line indicator.
2529 .
2530 .ESC? anything
2531 In a diversion, this will transparently embed
2532 .I anything
2533 in the diversion.
2534 .I anything
2535 is read in copy mode.
2536 .
2537 See also the escape sequences
2538 .esc !
2539 and
2540 .esc ? .
2541 .
2542 .
2543 .\" --------- spacing ---------
2544 .
2545 .ESC \& space
2546 Unpaddable space-size space character (no line break).
2547 .
2548 .ESC 0
2549 Digit width.
2550 .
2551 .ESC |
2552 1/6\ em narrow space character; zero width in nroff.
2553 .
2554 .ESC ^
2555 1/12\ em half-narrow space character; zero width in nroff.
2556 .
2557 .ESC &
2558 Non-printable, zero width character.
2559 .
2560 .ESC )
2561 Like
2562 .esc &
2563 except that it behaves like a character declared with the cflags
2564 request to be transparent for the purposes of end of sentence
2565 recognition.
2566 .
2567 .ESC /
2568 Increases the width of the preceding character so that the spacing
2569 between that character and the following character will be correct if
2570 the following character is a roman character.
2571 .
2572 .ESC ,
2573 Modifies the spacing of the following character so that the spacing
2574 between that character and the preceding character will correct if the
2575 preceding character is a roman character.
2576 .
2577 .ESC ~
2578 Unbreakable space that stretches like a normal inter-word space when a
2579 line is adjusted.
2580 .
2581 .ESC :
2582 Inserts a zero-width break point (similar to
2583 .esc %
2584 but without a soft hyphen character).
2585 .
2586 .ESC "" newline
2587 Ignored newline, for continuation lines.
2588 .
2589 .\" --------- structuring ---------
2590 .
2591 .ESC {
2592 Begin conditional input.
2593 .
2594 .ESC }
2595 End conditional input.
2596 .
2597 .\" --------- longer escape names ---------
2598 .
2599 .ESC ( sc
2600 The special character with 2-character name
2601 .IR sc ,
2602 see section
2603 .BR "Special Characters" .
2604 .
2605 .ESC[] "" name
2606 The named character (or rather glyph) with arbitrary length name
2607 .IR name .
2608 .
2609 .ESC[] "" "comp1 comp2 .\|.\|."
2610 A composite glyph with components
2611 .IR comp1 ,
2612 .IR comp2 ,
2613 .I .\|.\|.
2614 .
2615 .\" --------- alphabetical escapes ---------
2616 .
2617 .ESC a
2618 Non-interpreted leader character.
2619 .
2620 .ESCq A anything
2621 If
2622 .I anything
2623 is acceptable as a name of a string, macro, diversion, register,
2624 environment or font it expands to\~1, and to\~0 otherwise.
2625 .
2626 .ESCq b abc.\|.\|.\&
2627 Bracket building function.
2628 .
2629 .ESCq B anything
2630 If
2631 .I anything
2632 is acceptable as a valid numeric expression it expands to\~1, and
2633 to\~0 otherwise.
2634 .
2635 .ESC c
2636 Interrupt text processing.
2637 .
2638 .ESCq C char
2639 The character called
2640 .IR char ;
2641 same as
2642 .esc[] "" char ,
2643 but compatible to other roff versions.
2644 .
2645 .ESC d
2646 Forward (down) 1/2 em vertical unit (1/2 line in nroff).
2647 .
2648 .ESCq D charseq
2649 Draw a graphical element defined by the characters in
2650 .IR charseq ;
2651 see groff info file for details.
2652 .
2653 .ESC e
2654 Printable version of the current escape character.
2655 .
2656 .ESC E
2657 Equivalent to an escape character, but is not interpreted in copy-mode.
2658 .
2659 .ESC f F
2660 Change to font with 1-character name or 1-digit number
2661 .IR F .
2662 .
2663 .ESC fP
2664 Switch back to previous font.
2665 .
2666 .ESC f( fo
2667 Change to font with 2-character name or 2-digit number
2668 .IR fo .
2669 .
2670 .ESC[] f font
2671 Change to font with arbitrary length name or number expression
2672 .IR font .
2673 .
2674 .ESC[] f ""
2675 Switch back to previous font.
2676 .
2677 .ESC F f
2678 Change to font family with 1-character name
2679 .IR f .
2680 .
2681 .ESC F( fm
2682 Change to font family with 2-character name
2683 .IR fm .
2684 .
2685 .ESC[] F fam
2686 Change to font family with arbitrary length name
2687 .IR fam .
2688 .
2689 .ESC[] F ""
2690 Switch back to previous font family.
2691 .
2692 .ESC[] g reg
2693 Return format of register with name
2694 .I reg
2695 suitable for
2696 .request .af .
2697 .
2698 Alternative forms
2699 .escarg g( xy
2700 and
2701 .escarg g x .
2702 .
2703 .ESCq h N
2704 Local horizontal motion; move right
2705 .I N
2706 (left if negative).
2707 .
2708 .ESCq H N
2709 Set height of current font to
2710 .IR N .
2711 .
2712 .ESC[] k reg
2713 Mark horizontal input place in register with arbitrary length name
2714 .IR reg .
2715 Alternative forms
2716 .escarg k( xy
2717 and
2718 .escarg k x .
2719 .
2720 .ESCq l Nc
2721 Horizontal line drawing function (optionally using character
2722 .IR c ).
2723 .
2724 .ESCq L Nc
2725 Vertical line drawing function (optionally using character
2726 .IR c ).
2727 .
2728 .ESC[] m color
2729 Change to color
2730 .IR color .
2731 .
2732 Alternative forms
2733 .escarg m( co
2734 and
2735 .escarg m c .
2736 .
2737 .ESC[] m ""
2738 Switch back to previous color.
2739 .
2740 .ESC[] M color
2741 Change filling color for closed drawn objects to color
2742 .IR color .
2743 .
2744 Alternative forms
2745 .escarg M( co
2746 and
2747 .escarg M c .
2748 .
2749 .ESC[] M ""
2750 Switch to previous fill color.
2751 .
2752 .ESC n r
2753 The numerical value stored in the register variable with the
2754 1-character name
2755 .IR r .
2756 .
2757 .ESC n( re
2758 The numerical value stored in the register variable with the
2759 2-character name
2760 .IR re .
2761 .
2762 .ESC[] n reg
2763 The numerical value stored in the register variable with arbitrary
2764 length name
2765 .IR reg .
2766 .
2767 .ESCq N n
2768 Typeset the character with code
2769 .I n
2770 in the current font, no special fonts are searched.
2771 .
2772 Useful for adding characters to a font using the
2773 .request char
2774 request.
2775 .
2776 .ESCq o abc.\|.\|.\&
2777 Overstrike characters
2778 .IR a ,
2779 .IR b ,
2780 .IR c ,
2781 etc.
2782 .
2783 .ESC O 0
2784 Disable glyph output.
2785 .
2786 Mainly for internal use.
2787 .
2788 .ESC O 1
2789 Enable glyph output.
2790 .
2791 Mainly for internal use.
2792 .
2793 .ESC p
2794 Break and spread output line.
2795 .
2796 .ESC r
2797 Reverse 1\ em vertical motion (reverse line in nroff).
2798 .
2799 .ESCq R "name\~\[+-]n"
2800 The same as
2801 .request .nr
2802 .I name
2803 .IR \[+-]n .
2804 .
2805 .ESC[] s \[+-]N
2806 Set the point size to
2807 .I N
2808 scaled points.
2809 .
2810 Note the alternative forms
2811 .BI \[rs]s \[+-] [ N ]\c
2812 ,
2813 .BI \[rs]s' \[+-]N '\c
2814 .Text ,
2815 .BI \[rs]s \[+-] ' N '\c
2816 .Text ,
2817 .escarg s( \[+-]xy\c
2818 .Text ,
2819 .BI \[rs]s \[+-] ( xy\c
2820 .Text ,
2821 .escarg s \[+-]x .
2822 Same as
2823 .request ps
2824 request.
2825 .
2826 .ESCq S N
2827 Slant output
2828 .I N
2829 degrees.
2830 .
2831 .ESC t
2832 Non-interpreted horizontal tab.
2833 .
2834 .ESC u
2835 Reverse (up) 1/2 em vertical motion (1/2 line in nroff).
2836 .
2837 .ESCq v N
2838 Local vertical motion; move down
2839 .I N
2840 (up if negative).
2841 .
2842 .ESC[] V env
2843 The contents of the environment variable
2844 .IR env .
2845 .
2846 Alternative forms
2847 .escarg V( xy
2848 and
2849 .escarg V x .
2850 .
2851 .ESCq w string
2852 The width of the character sequence
2853 .IR string .
2854 .
2855 .ESCq x N
2856 Extra line-space function (negative before, positive after).
2857 .
2858 .ESCq X string
2859 Output
2860 .I string
2861 as device control function.
2862 .
2863 .ESC[] Y name
2864 Output string variable or macro
2865 .I name
2866 uninterpreted as device control function.
2867 .
2868 Alternative forms
2869 .escarg Y( xy
2870 and
2871 .escarg Y x .
2872 .
2873 .ESC z c
2874 Print
2875 .I c
2876 with zero width (without spacing).
2877 .
2878 .ESCq Z anything
2879 Print
2880 .I anything
2881 and then restore the horizontal and vertical position;
2882 .I anything
2883 may not contain tabs or leaders.
2884 .
2885 .PD
2886 .P
2887 The escape sequences
2888 .esc e ,
2889 .esc . ,
2890 .esc \[dq] ,
2891 .esc $ ,
2892 .esc * ,
2893 .esc a ,
2894 .esc n ,
2895 .esc t ,
2896 .esc g ,
2897 and
2898 .escarg \& newline
2899 are interpreted in copy mode.
2900 .
2901 .P
2902 Escape sequences starting with
2903 .esc (
2904 or
2905 .esc [
2906 do not represent single character escape sequences, but introduce escape
2907 names with two or more characters.
2908 .
2909 .P
2910 If a backslash is followed by a character that does not constitute a
2911 defined escape sequence the backslash is silently ignored and the
2912 character maps to itself.
2913 .
2914 .
2915 .\" --------------------------------------------------------------------
2916 .SS "Special Characters"
2917 .\" --------------------------------------------------------------------
2918 .
2919 Common special characters are predefined by escape sequences of the
2920 form
2921 .BI \[rs]( xy
2922 with characters
2923 .I x
2924 and
2925 .IR y .
2926 .
2927 Some of these exist in the usual font while most of them are only
2928 available in the special font.
2929 .
2930 Below you'll find a selection of the most important glyphs; a complete
2931 list can be found in
2932 .BR groff_char (@MAN7EXT@).
2933 .RS
2934 .P
2935 .PD 0
2936 .
2937 .ESC (bu
2938 Bullet sign
2939 .ESC (co
2940 Copyright
2941 .ESC (ct
2942 Cent
2943 .ESC (dd
2944 Double dagger
2945 .ESC (de
2946 Degree
2947 .ESC (dg
2948 Dagger
2949 .ESC (rs
2950 Printable double quote
2951 .ESC (em
2952 Em-dash
2953 .ESC (hy
2954 Hyphen
2955 .ESC (rg
2956 Registered sign
2957 .ESC (rs
2958 Printable backslash character
2959 .ESC (sc
2960 Section sign
2961 .ESC (ul
2962 Underline character
2963 .ESC (==
2964 Identical
2965 .ESC (>=
2966 Larger or equal
2967 .ESC (<=
2968 Less or equal
2969 .ESC (!=
2970 Not equal
2971 .ESC (->
2972 Right arrow
2973 .ESC (<-
2974 Left arrow
2975 .ESC (+-
2976 Plus-minus sign
2977 .PD
2978 .RE
2979 .
2980 .
2981 .\" --------------------------------------------------------------------
2982 .SS "Strings"
2983 .\" --------------------------------------------------------------------
2984 .
2985 Strings are defined by the
2986 .request ds
2987 request and can be retrieved by the
2988 .esc *
2989 escape sequence.
2990 .
2991 .P
2992 Strings share their name space with macros.
2993 .
2994 So strings and macros without arguments are roughly equivalent; it is
2995 possible to call a string like a macro and vice-versa, but this often
2996 leads to unpredictable results.
2997 .
2998 The following strings are predefined in groff.
2999 .
3000 .STRING .T
3001 The name of the current output device as specified by the
3002 .option -T
3003 command line option.
3004 .
3005 .
3006 .\" --------------------------------------------------------------------
3007 .SH REGISTERS
3008 .\" --------------------------------------------------------------------
3009 .
3010 Registers are variables that store a value.
3011 In groff, most registers store numerical values (see section
3012 .B NUMERICAL EXPRESSIONS
3013 above), but some can also hold a string value.
3014 .
3015 .P
3016 Each register is given a name.
3017 Arbitrary registers can be defined and set with the request
3018 .request nr
3019 .IR register .
3020 .
3021 .P
3022 The value stored in a register can be retrieved by the escape sequences
3023 introduced by
3024 .esc n .
3025 .
3026 .P
3027 Most useful are predefined registers.
3028 .
3029 In the following the notation
3030 .I name
3031 is used to refer to a register called
3032 .register name
3033 to make clear that we speak about registers.
3034 .
3035 Please keep in mind that the
3036 .esc[] n ""
3037 decoration is not part of the register name.
3038 .
3039 .
3040 .\" --------------------------------------------------------------------
3041 .SS "Read-only Registers"
3042 .\" --------------------------------------------------------------------
3043 .
3044 The following registers have predefined values that should not be
3045 modified by the user (usually, registers starting with a dot a
3046 read-only).
3047 .
3048 Mostly, they provide information on the current settings or store
3049 results from request calls.
3050 .
3051 .P
3052 .PD 0
3053 .
3054 .REG .$
3055 Number of arguments in the current macro or string.
3056 .
3057 .REG .a
3058 Post-line extra line-space most recently utilized using
3059 .escq x N .
3060 .
3061 .REG .A
3062 Set to\~1 in
3063 .B troff
3064 if option
3065 .B \-A
3066 is used; always\~1 in
3067 .BR nroff .
3068 .
3069 .REG .c
3070 Current input line number.
3071 .
3072 .REG .C
3073 1\~if compatibility mode is in effect, 0\~otherwise.
3074 .
3075 .REG .cdp
3076 The depth of the last character added to the current environment.
3077 It is positive if the character extends below the baseline.
3078 .
3079 .REG .ce
3080 The number of lines remaining to be centered, as set by the
3081 .request ce
3082 request.
3083 .
3084 .REG .cht
3085 The height of the last character added to the current environment.
3086 It is positive if the character extends above the baseline.
3087 .
3088 .REG .color
3089 1\~if colors are enabled, 0\~otherwise.
3090 .
3091 .REG .csk
3092 The skew of the last character added to the current environment.
3093 The skew of a character is how far to the right of the center of a character
3094 the center of an accent over that character should be placed.
3095 .
3096 .REG .d
3097 Current vertical place in current diversion; equal to
3098 .register nl .
3099 .
3100 .REG .ev
3101 The name or number of the current environment (string-valued).
3102 .
3103 .REG .f
3104 Current font number.
3105 .
3106 .REG .fam
3107 The current font family (string-valued).
3108 .
3109 .REG .fn
3110 The current (internal) real font name (string-valued).
3111 .
3112 .REG .fp
3113 The number of the next free font position.
3114 .
3115 .REG .g
3116 Always 1 in GNU troff.
3117 .
3118 Macros should use it to test if running under groff.
3119 .
3120 .REG .h
3121 Text base-line high-water mark on current page or diversion.
3122 .
3123 .REG .H
3124 Available horizontal resolution in basic units.
3125 .
3126 .REG .height
3127 The current font height as set with
3128 .request \[rs]H .
3129 .
3130 .REG .hla
3131 The current hyphenation language as set by the
3132 .B .hla
3133 request.
3134 .
3135 .REG .hlc
3136 The number of immediately preceding consecutive hyphenated lines.
3137 .
3138 .REG .hlm
3139 The maximum allowed number of consecutive hyphenated lines, as set by
3140 the
3141 .request hlm
3142 request.
3143 .
3144 .REG .hy
3145 The current hyphenation flags (as set by the
3146 .request hy
3147 request).
3148 .
3149 .REG .hym
3150 The current hyphenation margin (as set by the
3151 .request hym
3152 request).
3153 .
3154 .REG .hys
3155 The current hyphenation space (as set by the
3156 .request hys
3157 request).
3158 .
3159 .REG .i
3160 Current ident.
3161 .
3162 .REG .in
3163 The indent that applies to the current output line.
3164 .
3165 .REG .int
3166 Positive if last output line contains
3167 .esc c .
3168 .
3169 .REG .kern
3170 1\~if pairwise kerning is enabled, 0\~otherwise.
3171 .
3172 .REG .l
3173 Current line length.
3174 .
3175 .REG .lg
3176 The current ligature mode (as set by the
3177 .request lg
3178 request).
3179 .
3180 .REG .linetabs
3181 The current line-tabs mode (as set by the
3182 .request linetabs
3183 request).
3184 .
3185 .REG .ll
3186 The line length that applies to the current output line.
3187 .
3188 .REG .lt
3189 The title length (as set by the
3190 .request lt
3191 request).
3192 .
3193 .REG .m
3194 The current drawing color (string-valued).
3195 .
3196 .REG .M
3197 The current background color (string-valued).
3198 .
3199 .REG .n
3200 Length of text portion on previous output line.
3201 .
3202 .REG .ne
3203 The amount of space that was needed in the last
3204 .request ne
3205 request that caused a trap to be sprung.
3206 .
3207 Useful in conjunction with
3208 .register .trunc .
3209 .
3210 .REG .ns
3211 1\~if in no-space mode, 0\~otherwise.
3212 .
3213 .REG .o
3214 Current page offset.
3215 .
3216 .REG .p
3217 Current page length.
3218 .
3219 .REG .pe
3220 1\~during page ejection, 0\~otherwise.
3221 .
3222 .REG .pn
3223 The number of the next page: either the value set by a
3224 .request pn
3225 request, or the number of the current page plus\ 1.
3226 .
3227 .REG .ps
3228 The current pointsize in scaled points.
3229 .
3230 .REG .psr
3231 The last-requested pointsize in scaled points.
3232 .
3233 .REG .pvs
3234 The current post-vertical line spacing.
3235 .
3236 .REG .rj
3237 The number of lines to be right-justified as set by the rj request.
3238 .
3239 .REG .s
3240 Current point size as a decimal fraction.
3241 .
3242 .REG .slant
3243 The slant of the current font as set with
3244 .request \[rs]S .
3245 .
3246 .REG .sr
3247 The last requested pointsize in points as a decimal fraction
3248 (string-valued).
3249 .
3250 .REG .ss
3251 The value of the parameters set by the first argument of the
3252 .request ss
3253 request.
3254 .
3255 .REG .sss
3256 The value of the parameters set by the second argument of the
3257 .request ss
3258 request.
3259 .
3260 .REG .sty
3261 The current font style (string-valued).
3262 .
3263 .REG .t
3264 Distance to the next trap.
3265 .
3266 .REG .T
3267 Set to\~1
3268 if option
3269 .B \-T
3270 is used.
3271 .
3272 .REG .tabs
3273 A string representation of the current tab settings suitable for use
3274 as an argument to the
3275 .request ta
3276 request.
3277 .
3278 .REG .trunc
3279 The amount of vertical space truncated by the most recently sprung
3280 vertical position trap, or, if the trap was sprung by a
3281 .request ne
3282 request, minus the amount of vertical motion produced by
3283 .request .ne .
3284 .
3285 In other words, at the point a trap is sprung, it represents
3286 the difference of what the vertical position would have been but for
3287 the trap, and what the vertical position actually is.
3288 .
3289 Useful in conjunction with the
3290 .register .ne .
3291 .
3292 .REG .u
3293 Equal to 1 in fill mode and 0 in nofill mode.
3294 .
3295 .REG .U
3296 Equal to 1 in safer mode and 0 in unsafe mode.
3297 .
3298 .REG .v
3299 Current vertical line spacing.
3300 .
3301 .REG .V
3302 Available vertical resolution in basic units.
3303 .
3304 .REG .vpt
3305 1\~ if vertical position traps are enabled, 0\~otherwise.
3306 .
3307 .REG .w
3308 Width of previous character.
3309 .
3310 .REG .warn
3311 The sum of the number codes of the currently enabled warnings.
3312 .
3313 .REG .x
3314 The major version number.
3315 .
3316 .REG .y
3317 The minor version number.
3318 .
3319 .REG .Y
3320 The revision number of groff.
3321 .
3322 .REG .z
3323 Name of current diversion.
3324 .PD
3325 .
3326 .
3327 .\" --------------------------------------------------------------------
3328 .SS "Writable Registers"
3329 .\" --------------------------------------------------------------------
3330 .
3331 The following registers can be read and written by the user.
3332 They have predefined default values, but these can be modified for
3333 customizing a document.
3334 .
3335 .P
3336 .PD 0
3337 .REG %
3338 Current page number.
3339 .
3340 .REG c.
3341 Current input line number.
3342 .
3343 .REG ct
3344 Character type (set by width function
3345 .esc w ).
3346 .
3347 .REG dl
3348 Maximal width of last completed diversion.
3349 .
3350 .REG dn
3351 Height of last completed diversion.
3352 .
3353 .REG dw
3354 Current day of week (1-7).
3355 .
3356 .REG dy
3357 Current day of month (1-31).
3358 .
3359 .REG hours
3360 The number of hours past midnight.
3361 .
3362 Initialized at start-up.
3363 .
3364 .REG hp
3365 Current horizontal position at input line.
3366 .
3367 .REG llx
3368 Lower left x-coordinate (in PostScript units) of a given PostScript
3369 image (set by
3370 .request .psbb ).
3371 .
3372 .REG lly
3373 Lower left y-coordinate (in PostScript units) of a given PostScript
3374 image (set by
3375 .request .psbb ).
3376 .
3377 .REG ln
3378 Output line number.
3379 .
3380 .REG minutes
3381 The number of minutes after the hour.
3382 .
3383 Initialized at start-up.
3384 .
3385 .REG mo
3386 Current month (1-12).
3387 .
3388 .REG nl
3389 Vertical position of last printed text base-line.
3390 .
3391 .REG rsb
3392 Like
3393 .register sb ,
3394 but takes account of the heights and depths of characters.
3395 .
3396 .REG rst
3397 Like
3398 .register st ,
3399 but takes account of the heights and depths of characters.
3400 .
3401 .REG sb
3402 Depth of string below base line (generated by width function
3403 .esc w ).
3404 .
3405 .REG seconds
3406 The number of seconds after the minute.
3407 .
3408 Initialized at start-up.
3409 .
3410 .REG skw
3411 Right skip width from the center of the last character in the
3412 .esc w
3413 argument.
3414 .
3415 .REG slimit
3416 If greater than 0, the maximum number of objects on the input stack.
3417 .
3418 If \[<=]0 there is no limit, i.e., recursion can continue until virtual
3419 memory is exhausted.
3420 .
3421 .REG ssc
3422 The amount of horizontal space (possibly negative) that should be
3423 added to the last character before a subscript (generated by width
3424 function
3425 .esc w ).
3426 .
3427 .REG st
3428 Height of string above base line (generated by width function
3429 .esc w ).
3430 .
3431 .REG systat
3432 The return value of the
3433 .I system()
3434 function executed by the last
3435 .request sy
3436 request.
3437 .
3438 .REG urx
3439 Upper right x-coordinate (in PostScript units) of a given PostScript
3440 image (set by
3441 .request .psbb ).
3442 .
3443 .REG ury
3444 Upper right y-coordinate (in PostScript units) of a given PostScript
3445 image (set by
3446 .request .psbb ).
3447 .
3448 .REG year
3449 The current year (year 2000 compliant).
3450 .
3451 .REG yr
3452 Current year minus 1900.
3453 .
3454 For Y2K compliance use
3455 .register year
3456 instead.
3457 .
3458 .PD
3459 .
3460 .
3461 .\" --------------------------------------------------------------------
3462 .SH COMPATIBILITY
3463 .\" --------------------------------------------------------------------
3464 .
3465 The differences of the groff language in comparison to classical troff
3466 as defined by
3467 .I [CSTR\~#54]
3468 are documented in
3469 .BR groff_diff (@MAN7EXT@).
3470 .
3471 .P
3472 The groff system provides a compatibility mode, see
3473 .BR groff (@MAN1EXT@)
3474 on how to invoke this.
3475 .
3476 .
3477 .\" --------------------------------------------------------------------
3478 .SH BUGS
3479 .\" --------------------------------------------------------------------
3480 .
3481 Report bugs to the
3482 .MTO bug-groff@gnu.org "groff bug mailing list" .
3483 Include a complete, self-contained example that will allow the bug to
3484 be reproduced, and say which version of groff you are using.
3485 .
3486 .
3487 .\" --------------------------------------------------------------------
3488 .SH AUTHORS
3489 .\" --------------------------------------------------------------------
3490 .
3491 Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005
3492 Free Software Foundation, Inc.
3493 .
3494 .P
3495 This document is distributed under the terms of the FDL (GNU Free
3496 Documentation License) version 1.1 or later.
3497 .
3498 You should have received a copy of the FDL on your system, it is also
3499 available on-line at the
3500 .URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" .
3501 .
3502 .P
3503 This document is part of
3504 .IR groff ,
3505 the GNU roff distribution.
3506 .
3507 It was written by
3508 .MTO bwarken@mayn.de "Bernd Warken" ;
3509 it is maintained by
3510 .MTO wl@gnu.org "Werner Lemberg" .
3511 .
3512 .
3513 .\" --------------------------------------------------------------------
3514 .SH "SEE ALSO"
3515 .\" --------------------------------------------------------------------
3516 .
3517 .P
3518 The main source of information for the groff language is the
3519 .B groff
3520 .BR info (1)
3521 file.
3522 .
3523 Besides the gory details, it contains many examples.
3524 .
3525 .TP
3526 .BR groff (@MAN1EXT@)
3527 the usage of the groff program and pointers to the documentation and
3528 availability of the groff system.
3529 .
3530 .TP
3531 .BR groff_diff (@MAN7EXT@)
3532 the differences of the groff language as compared to classical roff.
3533 .
3534 This is the authoritative document for the predefined language
3535 elements that are specific to groff.
3536 .
3537 .TP
3538 .BR groff_char (@MAN7EXT@)
3539 the predefined groff characters (glyphs).
3540 .
3541 .TP
3542 .BR groff_font (@MAN5EXT@)
3543 the specification of fonts and the DESC file.
3544 .
3545 .TP
3546 .BR roff (@MAN7EXT@)
3547 the history of roff, the common parts shared by all roff systems, and
3548 pointers to further documentation.
3549 .
3550 .TP
3551 .I [CSTR\~#54]
3552 .URL http://\:cm.bell-labs.com/\:cm/\:cs/\:54.ps \
3553      "Nroff/\:Troff User's Manual by Osanna & Kernighan"
3554 \[em] the bible for classical troff.
3555 .
3556 .cp \n[groff_C]
3557 .
3558 .\" --------------------------------------------------------------------
3559 .\" Emacs Setup
3560 .\" --------------------------------------------------------------------
3561 .
3562 .\" Local Variables:
3563 .\" mode: nroff
3564 .\" End: