man/groff.man

   1 '\" t
   2 .ig
   3 groff.man
   4
   5 Last update: 6 Jan 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 .request ..
1155 is called.
1156 .
1157 .REQ .am macro end
1158 Append to
1159 .I macro
1160 until
1161 .request .end
1162 is called.
1163 .
1164 .REQ .am1 macro
1165 Same as
1166 .request .am
1167 but with compatibility mode switched off during macro expansion.
1168 .
1169 .REQ .am1 macro end
1170 Same as
1171 .request .am
1172 but with compatibility mode switched off during macro expansion.
1173 .
1174 .REQ .as stringvar anything
1175 Append
1176 .I anything
1177 to
1178 .IR stringvar .
1179 .
1180 .REQ .asciify diversion
1181 Unformat ASCII characters, spaces, and some escape sequences in
1182 .IR diversion .
1183 .
1184 .REQ .backtrace
1185 Print a backtrace of the input on stderr.
1186 .
1187 .REQ .bd font N
1188 Embolden
1189 .I font
1190 by
1191 .IR N -1
1192 units.
1193 .
1194 .REQ .bd S font N
1195 Embolden Special Font
1196 .I S
1197 when current font is
1198 .IR font .
1199 .
1200 .REQ .blm
1201 Unset the blank line macro.
1202 .
1203 .REQ .blm macro
1204 Set the blank line macro to
1205 .IR macro .
1206 .
1207 .REQ .box
1208 End current diversion.
1209 .
1210 .REQ .box macro
1211 Divert to
1212 .IR macro ,
1213 omitting a partially filled line.
1214 .
1215 .REQ .boxa
1216 End current diversion.
1217 .
1218 .REQ .boxa macro
1219 Divert and append to
1220 .IR macro ,
1221 omitting a partially filled line.
1222 .
1223 .REQ .bp
1224 Eject current page and begin new page.
1225 .
1226 .REQ .bp \[+-]N
1227 Eject current page; next page number
1228 .IR \[+-]N .
1229 .
1230 .REQ .br
1231 Line break.
1232 .
1233 .REQ .brp
1234 Break and spread output line.
1235 Same as
1236 .esc p .
1237 .
1238 .REQ .break
1239 Break out of a while loop.
1240 .
1241 .REQ .c2
1242 Reset no-break control character to
1243 .dquoted_char ' .
1244 .
1245 .REQ .c2 c
1246 Set no-break control character to
1247 .IR c .
1248 .
1249 .REQ .cc
1250 Reset control character to
1251 .squoted_char . .
1252 .
1253 .REQ .cc c
1254 Set control character to
1255 .IR c .
1256 .
1257 .REQ .ce
1258 Center the next input line.
1259 .
1260 .REQ .ce N
1261 Center following
1262 .I N
1263 input lines.
1264 .
1265 .REQ .cf filename
1266 Copy contents of file
1267 .I filename
1268 unprocessed to stdout or to the diversion.
1269 .
1270 .REQ .cflags mode c1 c2 .\|.\|.\&
1271 Treat characters
1272 .IR c1 ,
1273 .IR c2 ,
1274 .I .\|.\|.\&
1275 according to
1276 .I mode
1277 number.
1278 .
1279 .REQ .ch trap N
1280 Change
1281 .I trap
1282 location
1283 to
1284 .I N .
1285 .
1286 .REQ .char c anything
1287 Define character
1288 .I c
1289 as string
1290 .IR anything .
1291 .
1292 .REQ .chop object
1293 Chop the last character off macro, string, or diversion
1294 .IR object .
1295 .
1296 .REQ .close stream
1297 Close the
1298 .IR stream .
1299 .
1300 .REQ .continue
1301 Finish the current iteration of a while loop.
1302 .
1303 .REQ .cp
1304 Enable compatibility mode.
1305 .
1306 .REQ .cp N
1307 If
1308 .I N
1309 is zero disable compatibility mode, otherwise enable it.
1310 .
1311 .REQ .cs font N M
1312 Set constant character width mode for
1313 .I font
1314 to
1315 .IR N /36
1316 ems with em
1317 .IR M .
1318 .
1319 .REQ .cu N
1320 Continuous underline in nroff, like
1321 .request .ul
1322 in troff.
1323 .
1324 .REQ .da
1325 End current diversion.
1326 .
1327 .REQ .da macro
1328 Divert and append to
1329 .IR macro .
1330 .
1331 .REQ .de macro
1332 Define or redefine
1333 .I macro
1334 until
1335 .request ..
1336 is called.
1337 .
1338 .REQ .de macro end
1339 Define or redefine
1340 .I macro
1341 until
1342 .request .end
1343 is called.
1344 .
1345 .REQ .de1 macro
1346 Same as
1347 .request .de
1348 but with compatibility mode switched off during macro expansion.
1349 .
1350 .REQ .de1 macro end
1351 Same as
1352 .request .de
1353 but with compatibility mode switched off during macro expansion.
1354 .
1355 .REQ .defcolor color scheme component
1356 Define or redefine a color with name
1357 .IR color .
1358 .I scheme
1359 can be
1360 .BR rgb ,
1361 .BR cym ,
1362 .BR cymk ,
1363 .BR gray ,
1364 or
1365 .BR grey .
1366 .I component
1367 can be single components specified as fractions in the range 0 to 1
1368 (default scale indicator\~\c
1369 .scaleindicator f ),
1370 as a string of two-digit hexadecimal color components with a leading
1371 .BR # ,
1372 or as a string of four-digit hexadecimal components with two leading
1373 .BR # .
1374 .
1375 .REQ .dei macro
1376 Define or redefine a macro whose name is contained in the string register
1377 .I macro
1378 until
1379 .request ..
1380 is called.
1381 .
1382 .REQ .dei macro end
1383 Define or redefine a macro indirectly.
1384 .I macro
1385 and
1386 .I end
1387 are string registers whose contents are interpolated for the macro name
1388 and the end macro, respectively.
1389 .
1390 .REQ .di
1391 End current diversion.
1392 .
1393 .REQ .di macro
1394 Divert to
1395 .I macro .
1396 .
1397 .REQ .do name
1398 Interpret
1399 .request .name
1400 with compatibility mode disabled.
1401 .
1402 .REQ .ds stringvar anything
1403 Set
1404 .I stringvar
1405 to
1406 .IR anything .
1407 .
1408 .REQ .dt N trap
1409 Set diversion trap to position
1410 .I N
1411 (default scale indicator\~\c
1412 .scaleindicator v ).
1413 .
1414 .REQ .ec
1415 Reset escape character to
1416 .squoted_char \[rs] .
1417 .
1418 .REQ .ec c
1419 Set escape character to
1420 .IR c .
1421 .
1422 .REQ .ecr
1423 Restore escape character saved with
1424 .request .ecs .
1425 .
1426 .REQ .ecs
1427 Save current escape character.
1428 .
1429 .REQ .el anything
1430 Else part for if-else (\c
1431 .request .ie )
1432 request.
1433 .
1434 .REQ .em macro
1435 The
1436 .I macro
1437 will be run after the end of input.
1438 .
1439 .REQ .eo
1440 Turn off escape character mechanism.
1441 .
1442 .REQ .ev
1443 Switch to previous environment.
1444 .
1445 .REQ .ev env
1446 Push down environment number or name
1447 .I env
1448 and switch to it.
1449 .
1450 .REQ .evc env
1451 Copy the contents of environment
1452 .I env
1453 to the current environment.
1454 No pushing or popping.
1455 .
1456 .REQ .ex
1457 Exit from roff processing.
1458 .
1459 .REQ .fam
1460 Return to previous font family.
1461 .
1462 .REQ .fam name
1463 Set the current font family to
1464 .IR name .
1465 .
1466 .REQ .fc
1467 Disable field mechanism.
1468 .
1469 .REQ .fc a
1470 Set field delimiter to
1471 .I a
1472 and pad character to space.
1473 .
1474 .REQ .fc a b
1475 Set field delimiter to
1476 .I a
1477 and pad character to
1478 .IR b .
1479 .
1480 .REQ .fchar c anything
1481 Define fallback character
1482 .I c
1483 as string
1484 .IR anything .
1485 .
1486 .REQ .fi
1487 Fill output lines.
1488 .
1489 .REQ .fl
1490 Flush output buffer.
1491 .
1492 .REQ .fp n font
1493 Mount
1494 .I font
1495 on position
1496 .IR n .
1497 .
1498 .REQ .fp n internal external
1499 Mount font with long
1500 .I external
1501 name to short
1502 .I internal
1503 name on position
1504 .IR n .
1505 .
1506 .REQ .fspecial font s1 s2 .\|.\|.\&
1507 When the current font is
1508 .IR font ,
1509 then the fonts
1510 .IR s1 ,
1511 .IR s2 ,
1512 .I .\|.\|.\&
1513 will be special.
1514 .
1515 .REQ .ft
1516 Return to previous font.
1517 Same as
1518 .request \[rs]fP .
1519 .REQ .ft font
1520 Change to font name or number
1521 .IR font ;
1522 same as
1523 .esc[] f font
1524 escape sequence.
1525 .
1526 .REQ .ftr font1 font2
1527 Translate
1528 .I font1
1529 to
1530 .IR font2 .
1531 .
1532 .REQ .hc
1533 Remove additional hyphenation indicator character.
1534 .
1535 .REQ .hc c
1536 Set up additional hyphenation indicator character\~\c
1537 .IR c .
1538 .
1539 .REQ .hcode c1 code1 c2 code2 .\|.\|.\&
1540 Set the hyphenation code of character
1541 .I c1
1542 to
1543 .IR code1 ,
1544 that of
1545 .I c2
1546 to
1547 .IR code2 ,
1548 etc.
1549 .
1550 .REQ .hla lang
1551 Set the current hyphenation language to
1552 .IR lang .
1553 .
1554 .REQ .hlm n
1555 Set the maximum number of consecutive hyphenated lines to
1556 .IR n .
1557 .
1558 .REQ .hpf file
1559 Read hyphenation patterns from
1560 .IR file .
1561 .
1562 .REQ .hw words
1563 List of
1564 .I words
1565 with exceptional hyphenation.
1566 .
1567 .REQ .hy N
1568 Switch to hyphenation mode
1569 .IR N .
1570 .
1571 .REQ .hym n
1572 Set the hyphenation margin to
1573 .I n
1574 (default scale indicator\~\c
1575 .scaleindicator m ).
1576 .
1577 .REQ .hys n
1578 Set the hyphenation space to
1579 .IR n .
1580 .
1581 .REQ .ie cond anything
1582 If
1583 .I cond
1584 then
1585 .I anything
1586 else goto
1587 .request .el .
1588 .
1589 .REQ .if cond anything
1590 If
1591 .I cond
1592 then
1593 .IR anything ;
1594 otherwise do nothing.
1595 .
1596 .REQ .ig
1597 Ignore text until
1598 .request ..
1599 is called.
1600 .
1601 .REQ .ig end
1602 Ignore text until
1603 .request .end .
1604 .
1605 .REQ .in
1606 Change to previous indent value.
1607 .
1608 .REQ .in \[+-]N
1609 Change indent according to
1610 .I \[+-]N
1611 (default scale indicator\~\c
1612 .scaleindicator m ).
1613 .
1614 .REQ .it N trap
1615 Set an input-line count trap for the next
1616 .I N
1617 lines.
1618 .
1619 .REQ .itc N trap
1620 Same as
1621 .request .it
1622 but count lines interrupted with
1623 .esc c
1624 as one line.
1625 .
1626 .REQ .kern
1627 Enable pairwise kerning.
1628 .
1629 .REQ .kern n
1630 If
1631 .I n
1632 is zero, disable pairwise kerning, otherwise enable it.
1633 .
1634 .REQ .lc
1635 Remove leader repetition character.
1636 .
1637 .REQ .lc c
1638 Set leader repetition character to\~\c
1639 .IR c .
1640 .
1641 .REQ .length register anything
1642 Write the length of the string
1643 .I anything
1644 in
1645 .IR register .
1646 .
1647 .REQ .linetabs
1648 Enable line-tabs mode (i.e., calculate tab positions relative to output
1649 line).
1650 .
1651 .REQ .linetabs n
1652 If
1653 .I n
1654 is zero, disable line-tabs mode, otherwise enable it.
1655 .
1656 .REQ .lf N file
1657 Set input line number to
1658 .I N
1659 and filename to
1660 .IR file .
1661 .
1662 .REQ .lg N
1663 Ligature mode on if
1664 .IR N >0.
1665 .
1666 .REQ .ll
1667 Change to previous line length.
1668 .
1669 .REQ .ll \[+-]N
1670 Set line length according to
1671 .I \[+-]N
1672 (default size
1673 .scalednumber 6.5 i ,
1674 default scale indicator\~\c
1675 .scaleindicator m ).
1676 .
1677 .REQ .ls
1678 Change to the previous value of additional intra-line skip.
1679 .
1680 .REQ .ls N
1681 Set additional intra-line skip value to
1682 .IR N ,
1683 i.e.,
1684 .IR N -1
1685 blank lines are inserted after each text output line.
1686 .
1687 .REQ .lt \[+-]N
1688 Length of title (default scale indicator\~\c
1689 .scaleindicator m ).
1690 .
1691 .REQ .mc
1692 Margin character off.
1693 .
1694 .REQ .mc c
1695 Print character
1696 .I c
1697 after each text line at actual distance from right margin.
1698 .
1699 .REQ .mc c N
1700 Set margin character to
1701 .I c
1702 and distance to
1703 .I N
1704 from right margin (default scale indicator\~\c
1705 .scaleindicator m ).
1706 .
1707 .REQ .mk register
1708 Mark current vertical position in
1709 .IR register .
1710 .
1711 .REQ .mso file
1712 The same as the .so request except that
1713 .I file
1714 is searched in the tmac directories.
1715 .
1716 .REQ .na
1717 No output-line adjusting.
1718 .
1719 .REQ .ne
1720 Need a one-line vertical space.
1721 .
1722 .REQ .ne N
1723 Need
1724 .I N
1725 vertical space (default scale indicator\~\c
1726 .scaleindicator v ).
1727 .
1728 .REQ .nf
1729 No filling or adjusting of output-lines.
1730 .
1731 .REQ .nh
1732 No hyphenation.
1733 .
1734 .REQ .nm
1735 Number mode off.
1736 .
1737 .REQ .nm \[+-]N M S I
1738 In line number mode, set number, multiple, spacing, and indent.
1739 .
1740 .REQ .nn
1741 Do not number next line.
1742 .
1743 .REQ .nn N
1744 Do not number next
1745 .I N
1746 lines.
1747 .
1748 .REQ .nop anything
1749 Always execute
1750 .IR anything .
1751 .
1752 .REQ .nr register \[+-]N M
1753 Define or modify
1754 .I register
1755 using
1756 .I \[+-]N
1757 with auto-increment
1758 .IR M .
1759 .
1760 .REQ .nroff
1761 Make the built-in condition
1762 .B n
1763 true and
1764 .B t
1765 false.
1766 .
1767 .REQ .ns
1768 Turn no-space mode on.
1769 .
1770 .REQ .nx filename
1771 Next file.
1772 .
1773 .REQ .open stream filename
1774 Open
1775 .register filename
1776 for writing and associate the stream named
1777 .register stream
1778 with it.
1779 .
1780 .REQ .opena stream filename
1781 Like
1782 .request .open
1783 but append to it.
1784 .
1785 .REQ .os
1786 Output vertical distance that was saved by the
1787 .request .sv
1788 request.
1789 .
1790 .REQ .pc
1791 Reset page number character to\~\c
1792 .squoted_char % .
1793 .
1794 .REQ .pc c
1795 Page number character.
1796 .
1797 .REQ .pi program
1798 Pipe output to
1799 .I program
1800 (nroff only).
1801 .
1802 .REQ .pl
1803 Set page length to default
1804 .scalednumber 11 i .
1805 The current page length is stored in
1806 .register .p .
1807 .
1808 .REQ .pl \[+-]N
1809 Change page length to
1810 .I \[+-]N
1811 (default scale indicator\~\c
1812 .scaleindicator v ).
1813 .
1814 .REQ .pm
1815 Print macro names and sizes (number of blocks of 128 bytes).
1816 .
1817 .REQ ".pm t"
1818 Print only total of sizes of macros (number of 128 bytes blocks).
1819 .
1820 .REQ .pn \[+-]N
1821 Next page number
1822 .IR N .
1823 .
1824 .REQ .pnr
1825 Print the names and contents of all currently defined number registers
1826 on stderr.
1827 .
1828 .REQ .po
1829 Change to previous page offset.
1830 .
1831 The current page offset is available in
1832 .register .o .
1833 .
1834 .REQ .po \[+-]N
1835 Page offset
1836 .IR N .
1837 .
1838 .REQ .ps
1839 Return to previous point-size.
1840 .REQ .ps \[+-]N
1841 Point size; same as
1842 .esc[] s \[+-]N .
1843 .
1844 .REQ .psbb filename
1845 Get the bounding box of a PostScript image
1846 .IR filename .
1847 .
1848 .REQ .pso command
1849 This behaves like the
1850 .request .so
1851 request except that input comes from the standard output of
1852 .IR command .
1853 .
1854 .REQ .ptr
1855 Print the names and positions of all traps (not including input line
1856 traps and diversion traps) on stderr.
1857 .
1858 .REQ .rchar c1 c2 .\|.\|.\&
1859 Remove the definitions of characters
1860 .IR c1 ,
1861 .IR c2 ,
1862 .I .\|.\|.\&
1863 .
1864 .REQ .rd prompt
1865 Read insertion.
1866 .
1867 .REQ .return
1868 Return from a macro.
1869 .
1870 .REQ .rj n
1871 Right justify the next
1872 .I n
1873 input lines.
1874 .
1875 .REQ .rm name
1876 Remove request, macro, or string
1877 .IR name .
1878 .
1879 .REQ .rn old new
1880 Rename request, macro, or string
1881 .I old
1882 to
1883 .IR new .
1884 .
1885 .REQ .rnn reg1 reg2
1886 Rename register
1887 .I reg1
1888 to
1889 .IR reg2 .
1890 .
1891 .REQ .rr register
1892 Remove
1893 .IR register .
1894 .
1895 .REQ .rs
1896 Restore spacing; turn no-space mode off.
1897 .
1898 .REQ .rt \[+-]N
1899 Return
1900 .I (upward only)
1901 to marked vertical place (default scale indicator\~\c
1902 .scaleindicator v ).
1903 .
1904 .REQ .shc
1905 Reset soft hyphen character to
1906 .esc (hy .
1907 .
1908 .REQ .shc c
1909 Set the soft hyphen character to
1910 .IR c .
1911 .
1912 .REQ .shift n
1913 In a macro, shift the arguments by
1914 .IR n \~\c
1915 positions.
1916 .
1917 .REQ .so filename
1918 Include source file.
1919 .
1920 .REQ .sp
1921 Skip one line vertically.
1922 .
1923 .REQ .sp N
1924 Space vertical distance
1925 .I N
1926 up or down according to sign of
1927 .I N
1928 (default scaling indicator\~\c
1929 .scaleindicator v ).
1930 .
1931 .REQ .special s1 s2 .\|.\|.\&
1932 Fonts
1933 .IR s1 ,
1934 .IR s2 ,
1935 etc.\& are special and will be searched for characters not in the
1936 current font.
1937 .
1938 .REQ .ss N
1939 Space-character size set to
1940 .IR N /12
1941 of the spacewidth in the current font.
1942 .
1943 .REQ .ss N M
1944 Space-character size set to
1945 .IR N /12
1946 and sentence space size set to
1947 .IR M /12
1948 of the spacewidth in the current font (\f[CR]\[eq]1/3 em\f[P]).
1949 .
1950 .REQ .sty n style
1951 Associate
1952 .I style
1953 with font position
1954 .IR n .
1955 .
1956 .REQ .substring register n1 n2
1957 Replace the string in
1958 .I register
1959 with the substring defined by the indices
1960 .I n1
1961 and
1962 .IR n2 .
1963 .
1964 .REQ .sv
1965 Save
1966 .scalednumber 1 v
1967 of vertical space.
1968 .
1969 .REQ .sv N
1970 Save the vertical distance
1971 .I N
1972 for later output with
1973 .request .os
1974 request.
1975 .
1976 .REQ .sy command-line
1977 Execute program
1978 .IR command-line .
1979 .
1980 .REQ ".ta T" N
1981 Set tabs after every position that is a multiple of
1982 .I N
1983 (default scaling indicator\~\c
1984 .scaleindicator m ).
1985 .REQ .ta n1 n2 .\|.\|.\& nn \f[CB]T\f[P] r1 r2 .\|.\|.\& rn
1986 Set tabs at positions
1987 .IR n1 ,
1988 .IR n2 ,
1989 .Text .\|.\|.,
1990 .IR nn ,
1991 then set tabs at
1992 .IR nn + r1 ,
1993 .IR nn + r2 ,
1994 .Text .\|.\|.,
1995 .IR nn + rn ,
1996 then at
1997 .IR nn + rn + r1 ,
1998 .IR nn + rn + r2 ,
1999 .Text .\|.\|.,
2000 .IR nn + rn + rn ,
2001 and so on.
2002 .
2003 .\".REQ .tar
2004 .\"Restore internally saved tab positions.
2005 .\".
2006 .\".REQ .tas
2007 .\"Save tab positions internally.
2008 .
2009 .REQ .tc
2010 Remove tab repition character.
2011 .REQ .tc c
2012 Set tab repetition character to\~\c
2013 .IR c .
2014 .
2015 .REQ .ti \[+-]N
2016 Temporary indent next line (default scaling indicator\~\c
2017 .scaleindicator m ).
2018 .
2019 .REQ .tkf font s1 n1 s2 n2
2020 Enable track kerning for
2021 .IR font .
2022 .
2023 .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]
2024 Three-part title.
2025 .
2026 .REQ .tm anything
2027 Print
2028 .I anything
2029 on terminal (UNIX standard message output).
2030 .
2031 .REQ .tm1 anything
2032 Print
2033 .I anything
2034 on terminal (UNIX standard message output), allowing leading
2035 whitespace if
2036 .I anything
2037 starts with
2038 .character \[dq]
2039 (which will be stripped off).
2040 .
2041 .REQ .tmc anything
2042 Similar to
2043 .request .tm1
2044 without emitting a final newline.
2045 .
2046 .REQ .tr abcd.\|.\|.\&
2047 Translate
2048 .I a
2049 to
2050 .IR b ,
2051 .I c
2052 to
2053 .IR d ,
2054 etc.\& on output.
2055 .
2056 .REQ .trf filename
2057 Transparently output the contents of file
2058 .IR filename .
2059 .
2060 .REQ .trnt abcd.\|.\|.\&
2061 This is the same as the
2062 .request .tr
2063 request except that the translations do not apply to text that is
2064 transparently throughput into a diversion with
2065 .esc ! .
2066 .
2067 .REQ .troff
2068 Make the built-in condition
2069 .B t
2070 true and
2071 .B n
2072 false.
2073 .
2074 .REQ .uf font
2075 Underline font set to
2076 .I font
2077 (to be switched to by
2078 .request .ul ).
2079 .
2080 .REQ .ul N
2081 Underline (italicize in troff)
2082 .I N
2083 input lines.
2084 .
2085 .REQ .unformat diversion
2086 Unformat space characters and tabs, preserving font information in
2087 .IR diversion .
2088 .REQ .vpt n
2089 Enable vertical position traps if
2090 .I n
2091 is non-zero, disable them otherwise.
2092 .
2093 .REQ .vs
2094 Change to previous vertical base line spacing.
2095 .
2096 .REQ .vs N
2097 Set vertical base line spacing to
2098 .IR N .
2099 Default value is
2100 .scalednumber 12 p .
2101 .
2102 .REQ .warn n
2103 Set warnings code to
2104 .IR n .
2105 .
2106 .REQ .wh N trap
2107 Set location trap; negative means from page bottom.
2108 .
2109 .REQ .while cond anything
2110 While condition
2111 .I cond
2112 is true, accept
2113 .I anything
2114 as input.
2115 .
2116 .REQ .write stream anything
2117 Write
2118 .I anything
2119 to the stream named
2120 .IR stream .
2121 .
2122 .PD
2123 .
2124 .P
2125 Besides these standard groff requests, there might be further macro
2126 calls.
2127 They can originate from a macro package (see
2128 .BR roff (@MAN7EXT@)
2129 for an overview) or from a preprocessor.
2130 .
2131 .P
2132 Preprocessor macros are easy to be recognized.
2133 .
2134 They enclose their code into a pair of characteristic macros.
2135 .
2136 .P
2137 .TS
2138 box, center, tab (@);
2139 c | c | c
2140 CfCB | CfCB | CfCB.
2141 preprocessor@start macro@ end macro
2142 =
2143 eqn@.PS@.PE
2144 grap@.G1@.G2
2145 grn@.GS@.GE
2146 pic@.PS@.PE
2147 refer@.R1@.R2
2148 soelim@\f[I]none@\f[I]none
2149 tbl@.TS@.TE
2150 .TE
2151 .P
2152 .
2153 .
2154 .\" --------------------------------------------------------------------
2155 .SH "ESCAPE SEQUENCES"
2156 .\" --------------------------------------------------------------------
2157 .
2158 Escape sequences are in-line language elements usually introduced by a
2159 backslash
2160 .squoted_char \[rs]
2161 and followed by an escape name and sometimes by a required argument.
2162 .
2163 Input processing is continued directly after the escaped character or
2164 the argument resp.\& without an intervening separation character.
2165 .
2166 So there must be a way to determine the end of the escape name and the
2167 end of the argument.
2168 .
2169 .P
2170 This is done by enclosing names (escape name and arguments consisting
2171 of a variable name) by a pair of brackets
2172 .BI \[lB] name \[rB]
2173 and constant arguments (number expressions and characters) by
2174 apostrophes (ASCII 0x27) like
2175 .BI \[cq] constant \[cq] \f[R].
2176 .
2177 .P
2178 There are abbreviations for short names.
2179 .
2180 Two character escape names can be specified by an opening parenthesis
2181 like
2182 .esc ( xy
2183 without a closing counterpart.
2184 .
2185 And all one-character names different from the special characters
2186 .squoted_char [
2187 and
2188 .squoted_char (
2189 can even be specified without a marker in the form
2190 .esc c .
2191 .
2192 .P
2193 Constant arguments of length\~1 can omit the marker apostrophes, too,
2194 but there is no two-character analogue.
2195 .
2196 .P
2197 While 1-character escape sequences are mainly used for in-line
2198 functions and system related tasks, the 2-letter names following the
2199 .esc (
2200 construct are used for special characters predefined by the roff system.
2201 .
2202 Escapes sequences with names of more than two characters
2203 .esc[] "" name
2204 denote user defined named characters (see the
2205 .request .char
2206 request).
2207 .
2208 .
2209 .\" --------------------------------------------------------------------
2210 .SS "Single Character Escapes"
2211 .\" --------------------------------------------------------------------
2212 .
2213 .PD 0
2214 .
2215 .\" --------- comments ---------
2216 .
2217 .ESC \[dq]
2218 Beginning of a comment.
2219 .
2220 Everything up to the end of the line is ignored.
2221 .
2222 .ESC #
2223 Everything up to and including the next newline is ignored.
2224 .
2225 This is interpreted in copy mode.
2226 .
2227 This is like
2228 .esc \[dq]
2229 except that the terminating newline is ignored as well.
2230 .
2231 .\" --------- strings ---------
2232 .
2233 .ESC *\f[I]s\f[P]
2234 The string stored in the string variable with 1-character name
2235 .IR s .
2236 .
2237 .ESC *(\f[I]st\f[P]
2238 The string stored in the string variable with 2-character name
2239 .IR st .
2240 .
2241 .ESC[] * stringvar
2242 The string stored in the string variable with arbitrary length name
2243 .IR stringvar .
2244 .
2245 .\" --------- macro arguments ---------
2246 .
2247 .ESC $0
2248 The name by which the current macro was invoked.
2249 .
2250 The
2251 .request .als
2252 request can make a macro have more than one name.
2253 .
2254 .ESC $ x
2255 Macro argument with 1-place number
2256 .IR x ,
2257 where
2258 .I x
2259 is a digit between 1 and 9.
2260 .
2261 .ESC $( xy
2262 Macro argument with 2-digit number
2263 .IR xy .
2264 .
2265 .ESC[] $ nexp
2266 Macro argument with number
2267 .IR nexp ,
2268 where
2269 .I nexp
2270 is a numerical expression evaluating to an integer \[>=]1.
2271 .
2272 .ESC $*
2273 In a macro, the concatenation of all the arguments separated by spaces.
2274 .
2275 .ESC $@
2276 In a macro, the concatenation of all the arguments with each surrounded
2277 by double quotes, and separated by spaces.
2278 .
2279 .\" --------- escaped characters ---------
2280 .
2281 .ESC \[rs]
2282 reduces to a single backslash; useful to delay its interpretation as
2283 escape character in copy mode.
2284 .
2285 For a printable backslash, use
2286 .esc e .
2287 .
2288 .ESC \[cq]
2289 The acute accent \[aa]; same as
2290 .esc (aa .
2291 Unescaped: apostrophe, right quotation mark, single quote (ASCII 0x27).
2292 .
2293 .ESC `
2294 The grave accent \[ga]; same as
2295 .esc (ga .
2296 Unescaped: left quote, backquote (ASCII 0x60).
2297 .
2298 .ESC \-
2299 The \- sign in the current font.
2300 .
2301 .ESC .
2302 An uninterpreted dot (period), even at start of line.
2303 .
2304 .ESC %
2305 Default optional hyphenation character.
2306 .
2307 .ESC !
2308 Transparent line indicator.
2309 .
2310 .ESC? anything
2311 In a diversion, this will transparently embed
2312 .I anything
2313 in the diversion.
2314 .I anything
2315 is read in copy mode.
2316 .
2317 See also the escape sequences
2318 .esc !
2319 and
2320 .esc ? .
2321 .
2322 .
2323 .\" --------- spacing ---------
2324 .
2325 .ESC \& space
2326 Unpaddable space-size space character (no line break).
2327 .
2328 .ESC 0
2329 Digit width.
2330 .
2331 .ESC |
2332 1/6\ em narrow space character; zero width in nroff.
2333 .
2334 .ESC ^
2335 1/12\ em half-narrow space character; zero width in nroff.
2336 .
2337 .ESC &
2338 Non-printable, zero width character.
2339 .
2340 .ESC )
2341 Like
2342 .esc &
2343 except that it behaves like a character declared with the cflags
2344 request to be transparent for the purposes of end of sentence
2345 recognition.
2346 .
2347 .ESC /
2348 Increases the width of the preceding character so that the spacing
2349 between that character and the following character will be correct if
2350 the following character is a roman character.
2351 .
2352 .ESC ,
2353 Modifies the spacing of the following character so that the spacing
2354 between that character and the preceding character will correct if the
2355 preceding character is a roman character.
2356 .
2357 .ESC ~
2358 Unbreakable space that stretches like a normal inter-word space when a
2359 line is adjusted.
2360 .
2361 .ESC :
2362 Inserts a zero-width break point (similar to
2363 .esc %
2364 but without a soft hyphen character).
2365 .
2366 .ESC "" newline
2367 Ignored newline, for continuation lines.
2368 .
2369 .\" --------- structuring ---------
2370 .
2371 .ESC {
2372 Begin conditional input.
2373 .
2374 .ESC }
2375 End conditional input.
2376 .
2377 .\" --------- longer escape names ---------
2378 .
2379 .ESC ( sc
2380 The special character with 2-character name
2381 .IR sc ,
2382 see section
2383 .BR "Special Characters" .
2384 .
2385 .ESC[] "" name
2386 The named character with arbitrary length name
2387 .IR name .
2388 .
2389 .\" --------- alphabetical escapes ---------
2390 .
2391 .ESC a
2392 Non-interpreted leader character.
2393 .
2394 .ESCq A anything
2395 If
2396 .I anything
2397 is acceptable as a name of a string, macro, diversion, register,
2398 environment or font it expands to\~1, and to\~0 otherwise.
2399 .
2400 .ESCq b abc.\|.\|.\&
2401 Bracket building function.
2402 .
2403 .ESCq B anything
2404 If
2405 .I anything
2406 is acceptable as a valid numeric expression it expands to\~1, and
2407 to\~0 otherwise.
2408 .
2409 .ESC c
2410 Interrupt text processing.
2411 .
2412 .ESCq C char
2413 The character called
2414 .IR char ;
2415 same as
2416 .esc[] "" char ,
2417 but compatible to other roff versions.
2418 .
2419 .ESC d
2420 Forward (down) 1/2 em vertical unit (1/2 line in nroff).
2421 .
2422 .ESCq D charseq
2423 Draw a graphical element defined by the characters in
2424 .IR charseq ;
2425 see groff info file for details.
2426 .
2427 .ESC e
2428 Printable version of the current escape character.
2429 .
2430 .ESC E
2431 Equivalent to an escape character, but is not interpreted in copy-mode.
2432 .
2433 .ESC f F
2434 Change to font with 1-character name or 1-digit number
2435 .IR F .
2436 .
2437 .ESC f( fo
2438 Change to font with 2-characer name or 2-digit number
2439 .IR fo .
2440 .
2441 .ESC[] f font
2442 Change to font with arbitrary length name or number expression
2443 .IR font .
2444 .
2445 .ESC[] g reg
2446 Return format of register with name
2447 .I reg
2448 suitable for
2449 .request .af .
2450 Alternative forms
2451 .escarg g( xy
2452 and
2453 .escarg g x .
2454 .
2455 .ESCq h N
2456 Local horizontal motion; move right
2457 .I N
2458 (left if negative).
2459 .
2460 .ESCq H N
2461 Set height of current font to
2462 .IR N .
2463 .
2464 .ESC[] k reg
2465 Mark horizontal input place in register with arbitrary length name
2466 .IR reg .
2467 Alternative forms
2468 .escarg k( xy
2469 and
2470 .escarg k x .
2471 .
2472 .ESCq l Nc
2473 Horizontal line drawing function (optionally using character
2474 .IR c ).
2475 .
2476 .ESCq L Nc
2477 Vertical line drawing function (optionally using character
2478 .IR c ).
2479 .
2480 .ESC[] m color
2481 Change to color
2482 .IR color .
2483 .
2484 Alternative forms
2485 .escarg m( co
2486 and
2487 .escarg m c .
2488 .
2489 .ESC[] M color
2490 Change filling color for closed drawn objects to color
2491 .IR color .
2492 .
2493 Alternative forms
2494 .escarg M( co
2495 and
2496 .escarg M c .
2497 .
2498 .ESC n r
2499 The numerical value stored in the register variable with the
2500 1-character name
2501 .IR r .
2502 .
2503 .ESC n( re
2504 The numerical value stored in the register variable with the
2505 2-character name
2506 .IR re .
2507 .
2508 .ESC[] n reg
2509 The numerical value stored in the register variable with arbitrary
2510 length name
2511 .IR reg .
2512 .
2513 .ESCq N n
2514 Typeset the character with code
2515 .I n
2516 in the current font, no special fonts are searched.
2517 .
2518 Useful for adding characters to a font using the
2519 .request .char
2520 request.
2521 .
2522 .ESCq o abc.\|.\|.\&
2523 Overstrike characters
2524 .IR a ,
2525 .IR b ,
2526 .IR c ,
2527 etc.
2528 .
2529 .ESC O 0
2530 Disable glyph output.
2531 .
2532 Mainly for internal use.
2533 .
2534 .ESC O 1
2535 Enable glyph output.
2536 .
2537 Mainly for internal use.
2538 .
2539 .ESC p
2540 Break and spread output line.
2541 .
2542 .ESC r
2543 Reverse 1\ em vertical motion (reverse line in nroff).
2544 .
2545 .ESCq R "name\~\[+-]n"
2546 The same as
2547 .request .nr
2548 .I name
2549 .IR \[+-]n .
2550 .
2551 .ESC[] s \[+-]N
2552 Set the point size to
2553 .I N
2554 scaled points.
2555 .
2556 Note the alternative forms
2557 .BI \[rs]s \[+-] [ N ]\c
2558 ,
2559 .BI \[rs]s' \[+-]N '\c
2560 .Text ,
2561 .BI \[rs]s \[+-] ' N '\c
2562 .Text ,
2563 .escarg s( \[+-]xy\c
2564 .Text ,
2565 .BI \[rs]s \[+-] ( xy\c
2566 .Text ,
2567 .escarg s \[+-]x .
2568 Same as
2569 .request .ps
2570 request.
2571 .
2572 .ESCq S N
2573 Slant output
2574 .I N
2575 degrees.
2576 .
2577 .ESC t
2578 Non-interpreted horizontal tab.
2579 .
2580 .ESC u
2581 Reverse (up) 1/2 em vertical motion (1/2 line in nroff).
2582 .
2583 .ESCq v N
2584 Local vertical motion; move down
2585 .I N
2586 (up if negative).
2587 .
2588 .ESC[] V env
2589 The contents of the environment variable
2590 .IR env .
2591 .
2592 Alternative forms
2593 .escarg V( xy
2594 and
2595 .escarg V x .
2596 .
2597 .ESCq w string
2598 The width of the character sequence
2599 .IR string .
2600 .
2601 .ESCq x N
2602 Extra line-space function (negative before, positive after).
2603 .
2604 .ESCq X string
2605 Output
2606 .I string
2607 as device control function.
2608 .
2609 .ESC[] Y name
2610 Output string variable or macro
2611 .I name
2612 uninterpreted as device control function.
2613 .
2614 Alternative forms
2615 .escarg Y( xy
2616 and
2617 .escarg Y x .
2618 .
2619 .ESC z c
2620 Print
2621 .I c
2622 with zero width (without spacing).
2623 .
2624 .ESCq Z anything
2625 Print
2626 .I anything
2627 and then restore the horizontal and vertical position;
2628 .I anything
2629 may not contain tabs or leaders.
2630 .
2631 .PD
2632 .P
2633 The escape sequences
2634 .esc e ,
2635 .esc . ,
2636 .esc \[dq] ,
2637 .esc $ ,
2638 .esc * ,
2639 .esc a ,
2640 .esc n ,
2641 .esc t ,
2642 .esc g ,
2643 and
2644 .escarg \& newline
2645 are interpreted in copy mode.
2646 .
2647 .P
2648 Escape sequences starting with
2649 .esc (
2650 or
2651 .esc [
2652 do not represent single character escape sequences, but introduce escape
2653 names with two or more characters.
2654 .
2655 .P
2656 If a backslash is followed by a character that does not constitute a
2657 defined escape sequence the backslash is silently ignored and the
2658 character maps to itself.
2659 .
2660 .
2661 .\" --------------------------------------------------------------------
2662 .SS "Special Characters"
2663 .\" --------------------------------------------------------------------
2664 .
2665 Common special characters are predefined by escape sequences of the
2666 form
2667 .BI \[rs]( xy
2668 with characters
2669 .I x
2670 and
2671 .IR y .
2672 .
2673 Some of these exist in the usual font while most of them are only
2674 available in the special font.
2675 .
2676 Below you'll find a selection of the most important glyphs; a complete
2677 list can be found in
2678 .BR groff_char (@MAN7EXT@).
2679 .RS
2680 .P
2681 .PD 0
2682 .
2683 .ESC (bu
2684 Bullet sign
2685 .ESC (co
2686 Copyright
2687 .ESC (ct
2688 Cent
2689 .ESC (dd
2690 Double dagger
2691 .ESC (de
2692 Degree
2693 .ESC (dg
2694 Dagger
2695 .ESC (rs
2696 Printable double quote
2697 .ESC (em
2698 Em-dash
2699 .ESC (hy
2700 Hyphen
2701 .ESC (rg
2702 Registered sign
2703 .ESC (rs
2704 Printable backslash character
2705 .ESC (sc
2706 Section sign
2707 .ESC (ul
2708 Underline character
2709 .ESC (==
2710 Identical
2711 .ESC (>=
2712 Larger or equal
2713 .ESC (<=
2714 Less or equal
2715 .ESC (!=
2716 Not equal
2717 .ESC (->
2718 Right arrow
2719 .ESC (<-
2720 Left arrow
2721 .ESC (+-
2722 Plus-minus sign
2723 .PD
2724 .RE
2725 .
2726 .
2727 .\" --------------------------------------------------------------------
2728 .SS "Strings"
2729 .\" --------------------------------------------------------------------
2730 .
2731 Strings are defined by the
2732 .request .ds
2733 request and can be retrieved by the
2734 .esc *
2735 escape sequence.
2736 .
2737 .P
2738 Strings share their name space with macros.
2739 .
2740 So strings and macros without arguments are roughly equivalent, though
2741 calling a string like a macro and vice-versa is not stably implemented
2742 so far.
2743 .
2744 The following strings are predefined in groff.
2745 .
2746 .STRING .T
2747 The name of the current output device as specified by the
2748 .option -T
2749 command line option.
2750 .
2751 .
2752 .\" --------------------------------------------------------------------
2753 .SH REGISTERS
2754 .\" --------------------------------------------------------------------
2755 .
2756 Registers are variables that store a value.
2757 In groff, most registers store numerical values (see section
2758 .B NUMERICAL EXPRESSIONS
2759 above), but some can also hold a string value.
2760 .
2761 .P
2762 Each register is given a name.
2763 Arbitrary registers can be defined and set with the request
2764 .request .nr
2765 .IR register .
2766 .
2767 .P
2768 The value stored in a register can be retrieved by the escape sequences
2769 introduced by
2770 .esc n .
2771 .
2772 .P
2773 Most useful are predefined registers.
2774 .
2775 In the following the notation
2776 .I name
2777 is used to refer to a register called
2778 .register name
2779 to make clear that we speak about registers.
2780 .
2781 Please keep in mind that the
2782 .esc[] n ""
2783 decoration is not part of the register name.
2784 .
2785 .
2786 .\" --------------------------------------------------------------------
2787 .SS "Read-only Registers"
2788 .\" --------------------------------------------------------------------
2789 .
2790 The following registers have predefined values that should not be
2791 modified by the user (usually, registers starting with a dot a
2792 read-only).
2793 .
2794 Mostly, they provide information on the current settings or store
2795 results from request calls.
2796 .
2797 .P
2798 .PD 0
2799 .
2800 .REG .$
2801 Number of arguments in the current macro.
2802 .
2803 .REG .a
2804 Post-line extra line-space most recently utilized using
2805 .escq x N .
2806 .
2807 .REG .A
2808 Set to\~1 in
2809 .B troff
2810 if option
2811 .B \-A
2812 is used; always\~1 in
2813 .BR nroff .
2814 .
2815 .REG .c
2816 Current input line number.
2817 .
2818 .REG .C
2819 1\~if compatibility mode is in effect, 0\~otherwise.
2820 .
2821 .REG .cdp
2822 The depth of the last character added to the current environment.
2823 It is positive if the character extends below the baseline.
2824 .
2825 .REG .ce
2826 The number of lines remaining to be centered, as set by the
2827 .request .ce
2828 request.
2829 .
2830 .REG .cht
2831 The height of the last character added to the current environment.
2832 It is positive if the character extends above the baseline.
2833 .
2834 .REG .csk
2835 The skew of the last character added to the current environment.
2836 The skew of a character is how far to the right of the center of a character
2837 the center of an accent over that character should be placed.
2838 .
2839 .REG .d
2840 Current vertical place in current diversion; equal to register
2841 .register nl .
2842 .
2843 .REG .ev
2844 The name or number of the current environment (string-valued).
2845 .
2846 .REG .f
2847 Current font number.
2848 .
2849 .REG .fam
2850 The current font family (string-valued).
2851 .
2852 .REG .fn
2853 The current (internal) real font name (string-valued).
2854 .
2855 .REG .fp
2856 The number of the next free font position.
2857 .
2858 .REG .g
2859 Always 1 in GNU troff.
2860 .
2861 Macros should use it to test if running under groff.
2862 .
2863 .REG .h
2864 Text base-line high-water mark on current page or diversion.
2865 .
2866 .REG .H
2867 Available horizontal resolution in basic units.
2868 .
2869 .REG .hla
2870 The current hyphenation language as set by the
2871 .B .hla
2872 request.
2873 .
2874 .REG .hlc
2875 The number of immediately preceding consecutive hyphenated lines.
2876 .
2877 .REG .hlm
2878 The maximum allowed number of consecutive hyphenated lines, as set by
2879 the
2880 .request .hlm
2881 request.
2882 .
2883 .REG .hy
2884 The current hyphenation flags (as set by the
2885 .request .hy
2886 request).
2887 .
2888 .REG .hym
2889 The current hyphenation margin (as set by the
2890 .request .hym
2891 request).
2892 .
2893 .REG .hys
2894 The current hyphenation space (as set by the
2895 .request .hys
2896 request).
2897 .
2898 .REG .i
2899 Current ident.
2900 .
2901 .REG .in
2902 The indent that applies to the current output line.
2903 .
2904 .REG .int
2905 Positive if last output line contains
2906 .esc c .
2907 .
2908 .REG .kern
2909 1\~if pairwise kerning is enabled, 0\~otherwise.
2910 .
2911 .REG .l
2912 Current line length.
2913 .
2914 .REG .lg
2915 The current ligature mode (as set by the
2916 .request .lg
2917 request).
2918 .
2919 .REG .linetabs
2920 The current line-tabs mode (as set by the
2921 .request .linetabs
2922 request).
2923 .
2924 .REG .ll
2925 The line length that applies to the current output line.
2926 .
2927 .REG .lt
2928 The title length (as set by the
2929 .request .lt
2930 request).
2931 .
2932 .REG .n
2933 Length of text portion on previous output line.
2934 .
2935 .REG .ne
2936 The amount of space that was needed in the last
2937 .request .ne
2938 request that caused a trap to be sprung.
2939 .
2940 Useful in conjunction with
2941 .register .trunc .
2942 .
2943 .REG .ns
2944 1\~if in no-space mode, 0\~otherwise.
2945 .
2946 .REG .o
2947 Current page offset.
2948 .
2949 .REG .p
2950 Current page length.
2951 .
2952 .REG .pn
2953 The number of the next page: either the value set by a
2954 .request .pn
2955 request, or the number of the current page plus\ 1.
2956 .
2957 .REG .ps
2958 The current pointsize in scaled points.
2959 .
2960 .REG .psr
2961 The last-requested pointsize in scaled points.
2962 .
2963 .REG .rj
2964 The number of lines to be right-justified as set by the rj request.
2965 .
2966 .REG .s
2967 Current point size as a decimal fraction.
2968 .
2969 .REG .sr
2970 The last requested pointsize in points as a decimal fraction
2971 (string-valued).
2972 .
2973 .REG .t
2974 Distance to the next trap.
2975 .
2976 .REG .T
2977 Set to\~1
2978 if option
2979 .B \-T
2980 is used.
2981 .
2982 .REG .tabs
2983 A string representation of the current tab settings suitable for use
2984 as an argument to the
2985 .request .ta
2986 request.
2987 .
2988 .REG .trunc
2989 The amount of vertical space truncated by the most recently sprung
2990 vertical position trap, or, if the trap was sprung by a
2991 .request .ne
2992 request, minus the amount of vertical motion produced by
2993 .request .ne .
2994 .
2995 In other words, at the point a trap is sprung, it represents
2996 the difference of what the vertical position would have been but for
2997 the trap, and what the vertical position actually is.
2998 .
2999 Useful in conjunction with the
3000 .register .ne
3001 register.
3002 .
3003 .REG .ss
3004 The value of the parameters set by the first argument of the
3005 .request .ss
3006 request.
3007 .
3008 .REG .sss
3009 The value of the parameters set by the second argument of the
3010 .request .ss
3011 request.
3012 .
3013 .REG .u
3014 Equal to 1 bin fill mode and 0 in nofill mode.
3015 .
3016 .REG .v
3017 Current vertical line spacing.
3018 .
3019 .REG .V
3020 Available vertical resolution in basic units.
3021 .
3022 .REG .vpt
3023 1\~ if vertical position traps are enabled, 0\~otherwise.
3024 .
3025 .REG .w
3026 Width of previous character.
3027 .
3028 .REG .warn
3029 The sum of the number codes of the currently enabled warnings.
3030 .
3031 .REG .x
3032 The major version number.
3033 .
3034 .REG .y
3035 The minor version number.
3036 .
3037 .REG .Y
3038 The revision number of groff.
3039 .
3040 .REG .z
3041 Name of current diversion.
3042 .PD
3043 .
3044 .
3045 .\" --------------------------------------------------------------------
3046 .SS "Writable Registers"
3047 .\" --------------------------------------------------------------------
3048 .
3049 The following registers can be read and written by the user.
3050 They have predefined default values, but these can be modified for
3051 customizing a document.
3052 .
3053 .P
3054 .PD 0
3055 .REG %
3056 Current page number.
3057 .
3058 .REG c.
3059 Current input line number.
3060 .
3061 .REG ct
3062 Character type (set by width function
3063 .esc w ).
3064 .
3065 .REG dl
3066 Maximal width of last completed diversion.
3067 .
3068 .REG dn
3069 Height of last completed diversion.
3070 .
3071 .REG dw
3072 Current day of week (1-7).
3073 .
3074 .REG dy
3075 Current day of month (1-31).
3076 .
3077 .REG hp
3078 Current horizontal position at input line.
3079 .
3080 .REG llx
3081 Lower left x-coordinate (in PostScript units) of a given PostScript
3082 image (set by
3083 .request .psbb ).
3084 .
3085 .REG lly
3086 Lower left y-coordinate (in PostScript units) of a given PostScript
3087 image (set by
3088 .request .psbb ).
3089 .
3090 .REG ln
3091 Output line number.
3092 .
3093 .REG mo
3094 Current month (1-12).
3095 .
3096 .REG nl
3097 Vertical position of last printed text base-line.
3098 .
3099 .REG rsb
3100 Like
3101 .register sb ,
3102 but takes account of the heights and depths of characters.
3103 .
3104 .REG rst
3105 Like
3106 .register st ,
3107 but takes account of the heights and depths of characters.
3108 .
3109 .REG sb
3110 Depth of string below base line (generated by width function
3111 .esc w ).
3112 .
3113 .REG skw
3114 Right skip width from the center of the last character in the
3115 .esc w
3116 argument.
3117 .
3118 .REG slimit
3119 If greater than 0, the maximum number of objects on the input stack.
3120 .
3121 If \[<=]0 there is no limit, i.e., recursion can continue until virtual
3122 memory is exhausted.
3123 .
3124 .REG ssc
3125 The amount of horizontal space (possibly negative) that should be
3126 added to the last character before a subscript (generated by width
3127 function
3128 .esc w ).
3129 .
3130 .REG st
3131 Height of string above base line (generated by width function
3132 .esc w ).
3133 .
3134 .REG systat
3135 The return value of the
3136 .I system()
3137 function executed by the last
3138 .request .sy
3139 request.
3140 .
3141 .REG urx
3142 Upper right x-coordinate (in PostScript units) of a given PostScript
3143 image (set by
3144 .request .psbb ).
3145 .
3146 .REG ury
3147 Upper right y-coordinate (in PostScript units) of a given PostScript
3148 image (set by
3149 .request .psbb ).
3150 .
3151 .REG year
3152 The current year (year 2000 compliant).
3153 .
3154 .REG yr
3155 Current year minus 1900.
3156 .
3157 For Y2K compliance use register
3158 .register year
3159 instead.
3160 .
3161 .PD
3162 .
3163 .
3164 .\" --------------------------------------------------------------------
3165 .SH COMPATIBILITY
3166 .\" --------------------------------------------------------------------
3167 .
3168 The differences of the groff language in comparison to classical troff
3169 as defined by
3170 .I [CSTR\~#54]
3171 are documented in
3172 .BR groff_diff (@MAN7EXT@).
3173 .
3174 .P
3175 The groff system provides a compatibility mode, see
3176 .BR groff (@MAN1EXT@)
3177 on how to invoke this.
3178 .
3179 .
3180 .\" --------------------------------------------------------------------
3181 .SH BUGS
3182 .\" --------------------------------------------------------------------
3183 .
3184 Report bugs to the
3185 .URL "groff bug mailing list" mailto:\:bug-groff@gnu.org .
3186 Include a complete, self-contained example that will allow the bug to
3187 be reproduced, and say which version of groff you are using.
3188 .
3189 .
3190 .\" --------------------------------------------------------------------
3191 .SH AUTHORS
3192 .\" --------------------------------------------------------------------
3193 .
3194 Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc.
3195 .
3196 .P
3197 This document is distributed under the terms of the FDL (GNU Free
3198 Documentation License) version 1.1 or later.
3199 .
3200 You should have received a copy of the FDL on your system, it is also
3201 available on-line at the
3202 .URL "GNU copyleft site" http://\:www.gnu.org/\:copyleft/\:fdl.html .
3203 .
3204 .P
3205 This document is part of
3206 .IR groff ,
3207 the GNU roff distribution.
3208 .
3209 It was written by
3210 .URL "Bernd Warken" mailto:\:bwarken@mayn.de ;
3211 it is maintained by
3212 .URL "Werner Lemberg" mailto:\:wl@gnu.org .
3213 .
3214 .
3215 .\" --------------------------------------------------------------------
3216 .SH "SEE ALSO"
3217 .\" --------------------------------------------------------------------
3218 .
3219 .P
3220 The main source of information for the groff language is the
3221 .B groff
3222 .BR info (1)
3223 file.
3224 .
3225 Besides the gory details, it contains many examples.
3226 .
3227 .TP
3228 .BR groff (@MAN1EXT@)
3229 the usage of the groff program and pointers to the documentation and
3230 availability of the groff system.
3231 .
3232 .TP
3233 .BR groff_diff (@MAN7EXT@)
3234 the differences of the groff language as compared to classical roff.
3235 .
3236 This is the authoritative document for the predefined language
3237 elements that are specific to groff.
3238 .
3239 .TP
3240 .BR groff_char (@MAN7EXT@)
3241 the predefined groff characters (glyphs).
3242 .
3243 .TP
3244 .BR groff_font (@MAN5EXT@)
3245 the specification of fonts and the DESC file.
3246 .
3247 .TP
3248 .BR roff (@MAN7EXT@)
3249 the history of roff, the common parts shared by all roff systems, and
3250 pointers to further documentation.
3251 .
3252 .TP
3253 .I [CSTR\~#54]
3254 .URL "Nroff/\:Troff User's Manual by Osanna & Kernighan" \
3255 http://\:cm.bell-labs.com/\:cm/\:cs/\:54.ps
3256 \[em] the bible for classical troff.
3257 .
3258 .
3259 .\" --------------------------------------------------------------------
3260 .\" Emacs Setup
3261 .\" --------------------------------------------------------------------
3262 .
3263 .\" Local Variables:
3264 .\" mode: nroff
3265 .\" End: