man/groff.man

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