contrib/groff/man/groff.man

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