man/groff.man

   1 '\" t
   2 .TH GROFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
   3 .SH NAME
   4 groff \- a short reference for the GNU roff language
   5 .
   6 .\" Before installation: <top-groff-source>/man/groff.man
   7 .\" After installation:  </usr or /usr/local>/share/man/man7/groff.7
   8 .
   9 .\" --------------------------------------------------------------------
  10 .\" Legalese
  11 .\" --------------------------------------------------------------------
  12 .
  13 .de co
  14 This file is part of groff, the GNU roff type-setting system.
  15
  16 Copyright \[co] 2000-2014 Free Software Foundation, Inc.
  17
  18 Permission is granted to copy, distribute and/or modify this document
  19 under the terms of the GNU Free Documentation License, Version 1.3 or
  20 any later version published by the Free Software Foundation; with no
  21 Front-Cover Texts, and with no Back-Cover Texts.
  22
  23 A copy of the Free Documentation License is included as a file called
  24 FDL in the main directory of the groff source package.  It is also
  25 available in the internet at
  26 .UR http://\:www.gnu.org/\:copyleft/\:fdl.html
  27 .UE .
  28 ..
  29 .
  30 .de au
  31 This documentation was written by
  32 .MT groff-bernd.warken-72@web.de
  33 Bernd Warken
  34 .ME
  35 and is appended and maintained by
  36 .MT wl@gnu.org
  37 Werner Lemberg
  38 .ME .
  39 ..
  40 .
  41 .\" --------------------------------------------------------------------
  42 .\" Setup
  43 .\" --------------------------------------------------------------------
  44 .
  45 .do nr groff_C \n[.C]
  46 .cp 0
  47 .
  48 .\" --------------------------------------------------------------------
  49 .\" start of macro definitions
  50 .
  51 .de TPx
  52 .  TP 10n
  53 ..
  54 .\" ---------------------------------------------------------------------
  55 .\" .Text anything ...
  56 .\"
  57 .\" All arguments are printed as text.
  58 .\"
  59 .de Text
  60 .  nop \)\\$*
  61 ..
  62 .
  63 .\" --------- command line option ---------
  64 .
  65 .de option
  66 .  Text \f[CB]\\$*
  67 .  ft P
  68 ..
  69 .
  70 .\" --------- characters ---------
  71 .
  72 .de squoted_char
  73 .  Text \[oq]\f[CB]\\$1\f[]\[cq]\\$2
  74 ..
  75 .de dquoted_char
  76 .  Text \[lq]\f[CB]\\$1\f[]\[rq]\\$2
  77 ..
  78 .\" --------- requests ---------
  79 .
  80 .\" synopsis of a request
  81 .de REQ
  82 .  ie \n[.$]=1 \{\
  83 .    Text \f[CB]\\$1\f[]
  84 .  \}
  85 .  el \{\
  86 .    Text \f[CB]\\$1\~\f[]\f[I]\\$2\f[]
  87 .  \}
  88 ..
  89 .
  90 .\" reference of a request
  91 .de request
  92 .  BR \\$*
  93 ..
  94 .
  95 .\" --------- numerical elements ---------
  96 .
  97 .\" number with a trailing unit
  98 .de scalednumber
  99 .  Text \\$1\^\f[CB]\\$2\f[]\\$3\f[R]
 100 .  ft P
 101 ..
 102 .
 103 .\" representation of units within the text
 104 .de scaleindicator
 105 .  Text \f[CB]\\$1\f[]\\$2\f[R]
 106 .  ft P
 107 ..
 108 .
 109 .\" representation of mathematical operators within the text
 110 .de operator
 111 .  squoted_char \\$@
 112 ..
 113 .
 114 .
 115 .\" --------- escape sequences ---------
 116 .
 117 .\" ---------------------------------------------------------------------
 118 .\" .ESC name [arg]
 119 .\"
 120 .\" Synopsis of an escape sequence, optionally with argument
 121 .\" Args   : 1 or 2; `name' obligatory, `arg' optional
 122 .\"   name : suitable name for an escape sequence (c, (xy, [long])
 123 .\"   arg  : arbitrary word
 124 .\" Result : prints \namearg, where `name' is in CB, `arg' in I
 125 .\"
 126 .de ESC
 127 .  Text "\f[CB]\e\\$1\,\f[I]\\$2\/\fR"
 128 ..
 129 .\" ---------------------------------------------------------------------
 130 .\" .ESC[] name arg
 131 .\"
 132 .\" Synopsis for escape sequence with a bracketed long argument
 133 .\" Args   : 2 obligatory
 134 .\"   name : suitable name for an escape sequence (c, (xy, [long])
 135 .\"   arg  : arbitrary text
 136 .\" Result : prints \name[arg], where `name' is in CB, `arg' in I
 137 .\"
 138 .de ESC[]
 139 .  Text "\f[CB]\e\\$1\[lB]\f[]\,\f[I]\\$2\/\f[]\f[CB]\[rB]\f[]"
 140 ..
 141 .\" ---------------------------------------------------------------------
 142 .\" .ESCq name arg
 143 .\"
 144 .\" Synopsis for escape sequence with a bracketed long argument
 145 .\" Args   : 2 obligatory
 146 .\"   name : suitable name for an escape sequence (c, (xy, [long])
 147 .\"   arg  : arbitrary text
 148 .\" Result : prints \name'arg', where `name' is in CB, `arg' in I
 149 .\"
 150 .de ESCq
 151 .  Text "\f[CB]\e\\$1\[cq]\f[]\,\f[I]\\$2\/\f[]\f[CB]\[cq]\f[]"
 152 ..
 153 .\" ---------------------------------------------------------------------
 154 .\" .ESC? arg
 155 .\"
 156 .\" Synopsis for escape sequence with a bracketed long argument
 157 .\" Args   : 1 obligatory
 158 .\"   arg  : arbitrary text
 159 .\" Result : prints `\?arg?', where the `?' are in CB, `arg' in I
 160 .\"
 161 .de ESC?
 162 .  Text "\f[CB]\e?\,\f[I]\\$1\/\f[CB]?\f[R]"
 163 ..
 164 .\" ---------------------------------------------------------------------
 165 .\" .esc name [punct]
 166 .\"
 167 .\" Reference of an escape sequence (no args), possibly punctuation
 168 .\" Args    : 1 obligatory
 169 .\"   name  : suitable name for an escape sequence (c, (xy, [long])
 170 .\"   punct : arbitrary
 171 .\" Result  : prints \name, where `name' is in B, `punct' in R
 172 .\"
 173 .de esc
 174 .  BR "\e\\$1" \\$2
 175 ..
 176 .\" ---------------------------------------------------------------------
 177 .\" .escarg name arg [punct]
 178 .\"
 179 .\" Reference of an escape sequence (no args)
 180 .\" Args    : 1 obligatory, 1 optional
 181 .\"   name  : suitable name for an escape sequence (c, (xy, [long])
 182 .\"   arg   : arbitrary word
 183 .\" Result  : prints \namearg, where
 184 .\"           `name' is in B, `arg' in I
 185 .\"
 186 .de escarg
 187 .  Text \f[B]\e\\$1\f[]\,\f[I]\\$2\/\f[]\\$3
 188 ..
 189 .\" ---------------------------------------------------------------------
 190 .\" .esc[] name arg [punct]
 191 .\"
 192 .\" Reference for escape sequence with a bracketed long argument
 193 .\" Args   : 2 obligatory
 194 .\"   name : suitable name for an escape sequence (c, (xy, [long])
 195 .\"   arg  : arbitrary text
 196 .\" Result : prints \name[arg], where `name' is in CB, `arg' in CI
 197 .\"
 198 .de esc[]
 199 .  Text \f[CB]\e\\$1\[lB]\f[]\,\f[CI]\\$2\/\f[]\f[CB]\[rB]\f[]\\$3
 200 ..
 201 .
 202 .\" ---------------------------------------------------------------------
 203 .\" .escq name arg
 204 .\"
 205 .\" Reference for escape sequence with a bracketed long argument
 206 .\" Args   : 2 obligatory
 207 .\"   name : suitable name for an escape sequence (c, (xy, [long])
 208 .\"   arg  : arbitrary text
 209 .\" Result : prints \name'arg', where `name' is in CB, `arg' in CI
 210 .\"
 211 .de escq
 212 .  Text \f[CB]\e\\$1\[cq]\f[]\,\f[CI]\\$2\/\f[]\f[CB]\[cq]\f[]\\$3
 213 ..
 214 .
 215 .\" --------- strings ---------
 216 .
 217 .\" synopsis for string, with \*[]
 218 .de STRING
 219 .  Text \[rs]*[\f[CB]\\$1\f[]] \\$2
 220 ..
 221 .\" synopsis for a long string
 222 .de string
 223 .  if \n[.$]=0 \
 224 .    return
 225 .  Text \f[CB]\[rs]*\[lB]\\$1\[rB]\f[]\\$2
 226 ..
 227 .
 228 .\" --------- registers ---------
 229 .
 230 .\" synopsis for registers, with \n[]
 231 .de REG
 232 .  Text \[rs]n[\f[CB]\\$1\f[]]
 233 ..
 234 .\" reference of a register, without decoration
 235 .de register
 236 .  Text register
 237 .  BR \\$*
 238 ..
 239 .
 240 .\" end of macro definitions
 241 .
 242 .
 243 .\" --------------------------------------------------------------------
 244 .SH DESCRIPTION
 245 .\" --------------------------------------------------------------------
 246 .
 247 The name
 248 .I groff
 249 stands for
 250 .I GNU roff
 251 and is the free implementation of the roff type-setting system.
 252 .
 253 See
 254 .BR roff (@MAN7EXT@)
 255 for a survey and the background of the groff system.
 256 .
 257 .
 258 .P
 259 This document gives only short descriptions of the predefined roff
 260 language elements as used in groff.
 261 .
 262 Both the classical features and the groff extensions are provided.
 263 .
 264 .
 265 .P
 266 Historically, the
 267 .I roff language
 268 was called
 269 .IR troff .
 270 .I groff
 271 is compatible with the classical system and provides proper
 272 extensions.
 273 .
 274 So in GNU, the terms
 275 .IR roff ,
 276 .IR troff ,
 277 and
 278 .I groff language
 279 could be used as synonyms.
 280 .
 281 However
 282 .I troff
 283 slightly tends to refer more to the classical aspects, whereas
 284 .I groff
 285 emphasizes the GNU extensions, and
 286 .I roff
 287 is the general term for the language.
 288 .
 289 .
 290 .P
 291 This file is only a short version of the complete documentation that
 292 is found in the
 293 .I groff
 294 .BR info (1)
 295 file, which contains more detailed, actual, and concise information.
 296 .
 297 .P
 298 The general syntax for writing groff documents is relatively easy, but
 299 writing extensions to the roff language can be a bit harder.
 300 .
 301 .
 302 .P
 303 The roff language is line-oriented.
 304 .
 305 There are only two kinds of lines, control lines and text lines.
 306 .
 307 The control lines start with a control character, by default a period
 308 .dquoted_char .
 309 or a single quote
 310 .dquoted_char \[aq] ;
 311 all other lines are text lines.
 312 .
 313 .
 314 .P
 315 .B Control lines
 316 represent commands, optionally with arguments.
 317 .
 318 They have the following syntax.
 319 .
 320 The leading control character can be followed by a command name;
 321 arguments, if any, are separated by spaces (but not tab characters)
 322 from the command name and among themselves, for example,
 323 .RS
 324 .P
 325 .Text .command_name arg1 arg2
 326 .RE
 327 .
 328 .
 329 .P
 330 For indentation, any number of space or tab characters can be inserted
 331 between the leading control character and the command name, but the
 332 control character must be on the first position of the line.
 333 .
 334 .
 335 .P
 336 .B Text lines
 337 represent the parts that is printed.
 338 They can be modified by escape sequences, which are recognized by a
 339 leading backslash
 340 .squoted_char \[rs] .
 341 These are in-line or even in-word formatting elements or functions.
 342 .
 343 Some of these take arguments separated by single quotes
 344 .dquoted_char \[aq] ,
 345 others are regulated by a length encoding introduced by an open
 346 parenthesis
 347 .squoted_char (
 348 or enclosed in brackets
 349 .squoted_char [
 350 and
 351 .squoted_char ] .
 352 .
 353 .
 354 .P
 355 The roff language provides flexible instruments for writing language
 356 extension, such as macros.
 357 .
 358 When interpreting macro definitions, the roff system enters a special
 359 operating mode, called the
 360 .BR "copy mode" .
 361 .
 362 .
 363 .P
 364 The copy mode behaviour can be quite tricky, but there are some rules
 365 that ensure a safe usage.
 366 .
 367 .IP 1.
 368 Printable backslashes must be denoted as
 369 .esc e .
 370 To be more precise,
 371 .esc e
 372 represents the current escape character.
 373 .
 374 To get a backslash glyph, use
 375 .esc (rs
 376 or
 377 .esc [rs] .
 378 .IP 2.
 379 Double all backslashes.
 380 .IP 3.
 381 Begin all text lines with the special non-spacing character
 382 .esc & .
 383 .
 384 .
 385 .P
 386 This does not produce the most efficient code, but it should work as a
 387 first measure.
 388 .
 389 For better strategies, see the groff info file and
 390 .BR groff_tmac (@MAN5EXT@).
 391 .
 392 .
 393 .P
 394 Reading roff source files is easier, just reduce all double backslashes
 395 to a single one in all macro definitions.
 396 .
 397 .
 398 .\" --------------------------------------------------------------------
 399 .SH "GROFF ELEMENTS"
 400 .\" --------------------------------------------------------------------
 401 .
 402 The roff language elements add formatting information to a text file.
 403 .
 404 The fundamental elements are predefined commands and variables that
 405 make roff a full-blown programming language.
 406 .
 407 .
 408 .P
 409 There are two kinds of roff commands, possibly with arguments.
 410 .B Requests
 411 are written on a line of their own starting with a dot
 412 .squoted_char .
 413 or a
 414 .dquoted_char \[aq] ,
 415 whereas
 416 .B Escape sequences
 417 are in-line functions and in-word formatting elements starting with a
 418 backslash
 419 .squoted_char \[rs] .
 420 .
 421 .
 422 .P
 423 The user can define her own formatting commands using the
 424 .request de
 425 request.
 426 .
 427 These commands are called
 428 .BR macros ,
 429 but they are used exactly like requests.
 430 .
 431 Macro packages are pre-defined sets of macros written in the groff
 432 language.
 433 .
 434 A user\[aq]s possibilities to create escape sequences herself is very
 435 limited, only special characters can be mapped.
 436 .
 437 .
 438 .P
 439 The groff language provides several kinds of variables with
 440 different interfaces.
 441 .
 442 There are pre-defined variables, but the user can define her own
 443 variables as well.
 444 .
 445 .
 446 .P
 447 .B String
 448 variables store character sequences.
 449 .
 450 They are set with the
 451 .request ds
 452 request and retrieved by the
 453 .esc *
 454 escape sequences.
 455 .
 456 Strings can have variables.
 457 .
 458 .
 459 .P
 460 .B Register
 461 variables can store numerical values, numbers with a scale unit, and
 462 occasionally string-like objects.
 463 .
 464 They are set with the
 465 .request nr
 466 request and retrieved by the
 467 .esc n
 468 escape sequences.
 469 .
 470 .
 471 .P
 472 .B Environments
 473 allow the user to temporarily store global formatting parameters like
 474 line length, font size, etc.\& for later reuse.
 475 .
 476 This is done by the
 477 .request ev
 478 request.
 479 .
 480 .
 481 .P
 482 .B Fonts
 483 are identified either by a name or by an internal number.
 484 .
 485 The current font is chosen by the
 486 .request ft
 487 request or by the
 488 .esc f
 489 escape sequences.
 490 .
 491 Each device has special fonts, but the following fonts are available
 492 for all devices.
 493 .B R
 494 is the standard font Roman.
 495 .B B
 496 is its
 497 .B bold
 498 counterpart.
 499 .
 500 The
 501 .I italic
 502 font is called
 503 .B I
 504 and is available everywhere, but on text devices it is displayed as an
 505 underlined Roman font.
 506 .
 507 For the graphical output devices, there exist constant-width pendants
 508 of these fonts,
 509 .BR CR ,
 510 .BR CI ,
 511 and
 512 .BR CB .
 513 On text devices, all glyphs have a constant width anyway.
 514 .
 515 .
 516 .P
 517 .B Glyphs
 518 are visual representation forms of
 519 .BR characters .
 520 In groff, the distinction between those two elements is not always
 521 obvious (and a full discussion is beyond the scope of this man page).
 522 .
 523 A first approximation is that glyphs have a specific size and
 524 colour and are taken from a specific font; they can\[aq]t be modified any
 525 more \[en] characters are the input, and glyphs are the output.
 526 .
 527 As soon as an output line has been generated, it no longer contains
 528 characters but glyphs.
 529 .
 530 In this man page, we use either \[oq]glyph\[cq] or
 531 \[oq]character\[cq], whatever is more appropriate.
 532 .
 533 .
 534 .P
 535 Moreover, there are some advanced roff elements.
 536 .
 537 A
 538 .B diversion
 539 stores (formatted) information into a macro for later usage.
 540 .
 541 A
 542 .B trap
 543 is a positional condition like a certain number of lines from page top
 544 or in a diversion or in the input.
 545 .
 546 Some action can be prescribed to be run automatically when the
 547 condition is met.
 548 .
 549 .
 550 .P
 551 More detailed information and examples can be found in the groff info
 552 file.
 553 .
 554 .
 555 .\" --------------------------------------------------------------------
 556 .SH "CONTROL CHARACTERS"
 557 .\" --------------------------------------------------------------------
 558 .
 559 There is a small set of characters that have a special controlling
 560 task in certain conditions.
 561 .
 562 .TP
 563 \&\f[CB].\f[]
 564 A dot is only special at the beginning of a line or after the
 565 condition in the requests
 566 .request if ,
 567 .request ie ,
 568 .request el ,
 569 and
 570 .request while .
 571 There it is the control character that introduces a request (or macro).
 572 .
 573 By using the
 574 .request cc
 575 request, the control character can be set to a different character,
 576 making the dot
 577 .squoted_char .
 578 a non-special character.
 579 .
 580 .IP ""
 581 In all other positions, it just means a dot character.
 582 .
 583 In text paragraphs, it is advantageous to start each sentence at a
 584 line of its own.
 585 .
 586 .TP
 587 \&\f[CB]\[aq]\f[]
 588 The single quote has two controlling tasks.
 589 .
 590 At the beginning of a line and in the conditional requests it is the
 591 non-breaking control character.
 592 .
 593 That means that it introduces a request like the dot, but with the
 594 additional property that this request doesn\[aq]t cause a linebreak.
 595 .
 596 By using the
 597 .request c2
 598 request, the non-break control character can be set to a different
 599 character.
 600 .
 601 .IP ""
 602 As a second task, it is the most commonly used argument separator in
 603 some functional escape sequences (but any pair of characters not part
 604 of the argument do work).
 605 .
 606 In all other positions, it denotes the single quote or apostrophe
 607 character.
 608 .
 609 Groff provides a printable representation with the
 610 .esc (cq
 611 escape sequence.
 612 .
 613 .TP
 614 \&\f[CB]\[dq]\f[]
 615 The double quote is used to enclose arguments in macros (but not in
 616 requests and strings).
 617 .
 618 In the
 619 .request ds
 620 and
 621 .request as
 622 requests, a leading double quote in the argument is stripped off,
 623 making everything else afterwards the string to be defined (enabling
 624 leading whitespace).
 625 .
 626 The escaped double quote
 627 .esc \[dq]
 628 introduces a comment.
 629 .
 630 Otherwise, it is not special.
 631 .
 632 Groff provides a printable representation with the
 633 .esc (dq
 634 escape sequence.
 635 .
 636 .TP
 637 \&\f[CB]\e\f[]
 638 The backslash usually introduces an escape sequence (this can be
 639 changed with the
 640 .request ec
 641 request).
 642 .
 643 A printed version of the escape character is the
 644 .esc e
 645 escape; a backslash glyph can be obtained by
 646 .esc (rs .
 647 .
 648 .TP
 649 \&\f[CB](\f[]
 650 The open parenthesis is only special in escape sequences when
 651 introducing an escape name or argument consisting of exactly two
 652 characters.
 653 .
 654 In groff, this behaviour can be replaced by the \f[CB][]\f[] construct.
 655 .
 656 .TP
 657 \&\f[CB][\f[]
 658 The opening bracket is only special in groff escape sequences; there
 659 it is used to introduce a long escape name or long escape argument.
 660 .
 661 Otherwise, it is non-special, e.g.\& in macro calls.
 662 .
 663 .TP
 664 \&\f[CB]]\f[]
 665 The closing bracket is only special in groff escape sequences; there
 666 it terminates a long escape name or long escape argument.
 667 .
 668 Otherwise, it is non-special.
 669 .
 670 .TP
 671 \f[CI]space\f[]
 672 Space characters are only functional characters.
 673 .
 674 They separate the arguments in requests, macros, and strings, and the words
 675 in text lines.
 676 .
 677 They are subject to groff\[aq]s horizontal spacing calculations.
 678 .
 679 To get a defined space width, escape sequences like
 680 .squoted_char "\[rs]\ "
 681 (this is the escape character followed by a space),
 682 .esc | ,
 683 .esc ^ ,
 684 or
 685 .esc h
 686 should be used.
 687 .
 688 .IP \f[CI]newline\f[]
 689 In text paragraphs, newlines mostly behave like space characters.
 690 .
 691 Continuation lines can be specified by an escaped newline, i.e., by
 692 specifying a backslash
 693 .squoted_char \[rs]
 694 as the last character of a line.
 695 .
 696 .IP \f[CI]tab\f[]
 697 If a tab character occurs during text the interpreter makes a
 698 horizontal jump to the next pre-defined tab position.
 699 .
 700 There is a sophisticated interface for handling tab positions.
 701 .
 702 .
 703 .\" --------------------------------------------------------------------
 704 .SH "NUMERICAL EXPRESSIONS"
 705 .\" --------------------------------------------------------------------
 706 .
 707 A
 708 .B numerical value
 709 is a signed or unsigned integer or float with or without an appended
 710 scaling indicator.
 711 .
 712 A
 713 .B scaling indicator
 714 is a one-character abbreviation for a unit of measurement.
 715 .
 716 A number followed by a scaling indicator signifies a size value.
 717 .
 718 By default, numerical values do not have a scaling indicator, i.e., they
 719 are normal numbers.
 720 .
 721 .
 722 .P
 723 The
 724 .I roff
 725 language defines the following scaling indicators.
 726 .
 727 .
 728 .P
 729 .PD 0
 730 .RS
 731 .
 732 .TPx
 733 .B c
 734 Centimeter
 735 .
 736 .TPx
 737 .B i
 738 Inch
 739 .
 740 .TPx
 741 .B P
 742 Pica\ \[eq]\ 1/6\ inch
 743 .
 744 .TPx
 745 .B p
 746 Point\ \[eq]\ 1/72\ inch
 747 .
 748 .TPx
 749 .B m
 750 Em\ \[eq]\ \f[R]the font size in points (approx.\& width of letter
 751 \[oq]\f[CR]m\f[R]\[cq])
 752 .
 753 .TPx
 754 .B M
 755 100\^th \f[R]of an \f[CR]Em
 756 .
 757 .TPx
 758 .B n
 759 En\ \[eq]\ Em/2
 760 .
 761 .TPx
 762 .B u
 763 Basic unit for actual output device
 764 .
 765 .TPx
 766 .B v
 767 Vertical line space in basic units
 768 scaled point\ \[eq]\ 1/\f[CI]sizescale\f[R] of a point (defined in
 769 font \f[I]DESC\f[] file)
 770 .
 771 .TPx
 772 .B f
 773 Scale by 65536.
 774 .RE
 775 .PD
 776 .
 777 .
 778 .P
 779 .B Numerical expressions
 780 are combinations of the numerical values defined above with the
 781 following arithmetical operators already defined in classical troff.
 782 .
 783 .
 784 .P
 785 .PD 0
 786 .RS
 787 .
 788 .TPx
 789 .B +
 790 Addition
 791 .
 792 .TPx
 793 .B \-
 794 Subtraction
 795 .
 796 .TPx
 797 .B *
 798 Multiplication
 799 .
 800 .TPx
 801 .B /
 802 Division
 803 .
 804 .TPx
 805 .B %
 806 Modulo
 807 .
 808 .TPx
 809 .B =
 810 Equals
 811 .
 812 .TPx
 813 .B ==
 814 Equals
 815 .
 816 .TPx
 817 .B <
 818 Less than
 819 .
 820 .TPx
 821 .B >
 822 Greater than
 823 .
 824 .TPx
 825 .B <=
 826 Less or equal
 827 .
 828 .TPx
 829 .B >=
 830 Greater or equal
 831 .
 832 .TPx
 833 .B &
 834 Logical and
 835 .
 836 .TPx
 837 .B :
 838 Logical or
 839 .
 840 .TPx
 841 .B !
 842 Logical not
 843 .
 844 .TPx
 845 .B (
 846 Grouping of expressions
 847 .
 848 .TPx
 849 .B )
 850 Close current grouping
 851 .
 852 .RE
 853 .PD
 854 .
 855 .
 856 .P
 857 Moreover,
 858 .I groff
 859 added the following operators for numerical expressions:
 860 .
 861 .
 862 .P
 863 .PD 0
 864 .RS
 865 .
 866 .TPx
 867 \f[I]e1\/\f[CB]>?\,\f[I]e2\f[R]
 868 The maximum of
 869 .I e1
 870 and
 871 .IR e2 .
 872 .
 873 .TPx
 874 \f[I]e1\/\f[CB]<?\,\f[I]e2\f[R]
 875 The minimum of
 876 .I e1
 877 and
 878 .IR e2 .
 879 .
 880 .TPx
 881 \f[CB](\,\f[I]c\/\f[CB];\,\f[I]e\/\f[CB])\f[R]
 882 Evaluate
 883 .I e
 884 using
 885 .I c
 886 as the default scaling indicator.
 887 .
 888 .RE
 889 .PD
 890 .
 891 .
 892 .P
 893 For details see the groff info file.
 894 .
 895 .
 896 .\" --------------------------------------------------------------------
 897 .SH CONDITIONS
 898 .\" --------------------------------------------------------------------
 899 .
 900 .B Conditions
 901 occur in tests raised by the
 902 .request if ,
 903 .request ie ,
 904 and the
 905 .request while
 906 requests.
 907 .
 908 The following table characterizes the different types of conditions.
 909 .
 910 .P
 911 .
 912 .PD 0
 913 .RS
 914 .
 915 .TPx
 916 .I N
 917 A numerical expression
 918 .I N
 919 yields true if its value is greater than\~0.
 920 .
 921 .TPx
 922 .BI ! N
 923 True if the value of
 924 .I N
 925 is\~0 (see below).
 926 .
 927 .TPx
 928 .BI \[aq] s1 \[aq] s2 \[aq]
 929 True if string\~\c
 930 .I s1
 931 is identical to string\~\c
 932 .IR s2 .
 933 .
 934 .TPx
 935 .BI !\[aq] s1 \[aq] s2 \[aq]
 936 True if string\~\c
 937 .I s1
 938 is not identical to string\~\c
 939 .I s2
 940 (see below).
 941 .
 942 .TPx
 943 .BI c ch
 944 True if there is a glyph\~\c
 945 .I ch
 946 available.
 947 .
 948 .TPx
 949 .BI d name
 950 True if there is a string, macro, diversion, or request called
 951 .IR name .
 952 .
 953 .TPx
 954 .B e
 955 Current page number is even.
 956 .
 957 .TPx
 958 .B o
 959 Current page number is odd.
 960 .
 961 .TPx
 962 .BI m name
 963 True if there is a color called
 964 .IR name .
 965 .
 966 .TPx
 967 .B n
 968 Formatter is
 969 .BR nroff .
 970 .
 971 .TPx
 972 .BI r reg
 973 True if there is a register named
 974 .IR reg .
 975 .
 976 .TPx
 977 .B t
 978 Formatter is
 979 .BR troff .
 980 .
 981 .TPx
 982 .BI F font
 983 True if there exists a font named
 984 .IR font .
 985 .
 986 .TPx
 987 .BI S style
 988 True if a style named
 989 .I style
 990 has been registered.
 991 .
 992 .RE
 993 .PD
 994 .
 995 .
 996 .P
 997 Note that the
 998 .B !
 999 operator may only appear at the beginning of an expression,
1000 and negates the entire expression.
1001 This maintains bug-compatibility with AT&T
1002 .IR troff .
1003 .
1004 .
1005 .\" --------------------------------------------------------------------
1006 .SH REQUESTS
1007 .\" --------------------------------------------------------------------
1008 .
1009 This section provides a short reference for the predefined requests.
1010 .
1011 In groff, request, macro, and string names can be arbitrarily long.
1012 .
1013 No bracketing or marking of long names is needed.
1014 .
1015 .
1016 .P
1017 Most requests take one or more arguments.
1018 .
1019 The arguments are separated by space characters (no tabs!); there is
1020 no inherent limit for their length or number.
1021 .
1022 .
1023 .P
1024 Some requests have optional arguments with a different behaviour.
1025 .
1026 Not all of these details are outlined here.
1027 .
1028 Refer to the groff info file and
1029 .BR groff_diff (@MAN7EXT@)
1030 for all details.
1031 .
1032 .
1033 .P
1034 In the following request specifications, most argument names were
1035 chosen to be descriptive.
1036 .
1037 Only the following denotations need clarification.
1038 .
1039 .
1040 .P
1041 .PD 0
1042 .RS
1043 .
1044 .TPx
1045 .I c
1046 denotes a single character.
1047 .
1048 .TPx
1049 .I font
1050 a font either specified as a font name or a font number.
1051 .
1052 .TPx
1053 .I anything
1054 all characters up to the end of the line or within
1055 .esc {
1056 and
1057 .esc } .
1058 .
1059 .TPx
1060 .I n
1061 is a numerical expression that evaluates to an integer value.
1062 .
1063 .TPx
1064 .I N
1065 is an arbitrary numerical expression, signed or unsigned.
1066 .
1067 .TPx
1068 .I \[+-]N
1069 has three meanings depending on its sign, described below.
1070 .
1071 .RE
1072 .PD
1073 .
1074 .
1075 .P
1076 If an expression defined as
1077 .I \[+-]N
1078 starts with a
1079 .squoted_char +
1080 sign the resulting value of the expression is added to an already
1081 existing value inherent to the related request, e.g.\& adding to a number
1082 register.
1083 .
1084 If the expression starts with a
1085 .squoted_char -
1086 the value of the expression is subtracted from the request value.
1087 .
1088 .
1089 .P
1090 Without a sign,
1091 .I N
1092 replaces the existing value directly.
1093 .
1094 To assign a negative number either prepend\~0 or enclose the negative
1095 number in parentheses.
1096 .
1097 .
1098 .\" --------------------------------------------------------------------
1099 .SS "Request Short Reference"
1100 .\" --------------------------------------------------------------------
1101 .
1102 .PD 0
1103 .
1104 .TPx
1105 .REQ .
1106 Empty line, ignored.
1107 .
1108 Useful for structuring documents.
1109 .
1110 .TPx
1111 .REQ .\e\[dq] "anything"
1112 Complete line is a comment.
1113 .
1114 .TPx
1115 .REQ .ab "string"
1116 Print
1117 .I string
1118 on standard error, exit program.
1119 .
1120 .TPx
1121 .REQ .ad
1122 Begin line adjustment for output lines in current adjust mode.
1123 .
1124 .TPx
1125 .REQ .ad "c"
1126 Start line adjustment in mode
1127 .I c
1128 (\f[CI]c\/\f[]\f[CR]\|\^\[eq]\|l,r,c,b,n\f[]).
1129 .
1130 .TPx
1131 .REQ .af "register c"
1132 Assign format
1133 .I c
1134 to
1135 .I register
1136 (\f[CI]c\/\f[]\f[CR]\|\^\[eq]\|l,i,I,a,A\f[]).
1137 .
1138 .TPx
1139 .REQ .aln "alias register"
1140 Create alias name for
1141 .IR register .
1142 .
1143 .TPx
1144 .REQ .als "alias object"
1145 Create alias name for request, string, macro, or diversion
1146 .IR object .
1147 .
1148 .TPx
1149 .REQ .am "macro"
1150 Append to
1151 .I macro
1152 until
1153 .B ..\&
1154 is encountered.
1155 .
1156 .TPx
1157 .REQ .am "macro end"
1158 Append to
1159 .I macro
1160 until
1161 .BI . end
1162 is called.
1163 .
1164 .TPx
1165 .REQ .am1 "macro"
1166 Same as
1167 .request .am
1168 but with compatibility mode switched off during macro expansion.
1169 .
1170 .TPx
1171 .REQ .am1 "macro end"
1172 Same as
1173 .request .am
1174 but with compatibility mode switched off during macro expansion.
1175 .
1176 .TPx
1177 .REQ .ami "macro"
1178 Append to a macro whose name is contained in the string register
1179 .I macro
1180 until
1181 .B ..\&
1182 is encountered.
1183 .
1184 .TPx
1185 .REQ .ami "macro end"
1186 Append to a macro indirectly.
1187 .I macro
1188 and
1189 .I end
1190 are string registers whose contents are interpolated for the macro name
1191 and the end macro, respectively.
1192 .
1193 .TPx
1194 .REQ .ami1 "macro"
1195 Same as
1196 .request .ami
1197 but with compatibility mode switched off during macro expansion.
1198 .
1199 .TPx
1200 .REQ .ami1 "macro end"
1201 Same as
1202 .request .ami
1203 but with compatibility mode switched off during macro expansion.
1204 .
1205 .TPx
1206 .REQ .as "stringvar anything"
1207 Append
1208 .I anything
1209 to
1210 .IR stringvar .
1211 .
1212 .TPx
1213 .REQ .as1 "stringvar anything"
1214 Same as
1215 .request .as
1216 but with compatibility mode switched off during string expansion.
1217 .
1218 .TPx
1219 .REQ .asciify "diversion"
1220 Unformat ASCII characters, spaces, and some escape sequences in
1221 .IR diversion .
1222 .
1223 .TPx
1224 .REQ .backtrace
1225 Print a backtrace of the input on stderr.
1226 .
1227 .TPx
1228 .REQ .bd "font N"
1229 Embolden
1230 .I font
1231 by
1232 .IR N \\-1
1233 units.
1234 .
1235 .TPx
1236 .REQ .bd "S font N"
1237 Embolden Special Font
1238 .I S
1239 when current font is
1240 .IR font .
1241 .
1242 .TPx
1243 .REQ .blm
1244 Unset the blank line macro.
1245 .
1246 .TPx
1247 .REQ .blm "macro"
1248 Set the blank line macro to
1249 .IR macro .
1250 .
1251 .TPx
1252 .REQ .box
1253 End current diversion.
1254 .
1255 .TPx
1256 .REQ .box "macro"
1257 Divert to
1258 .IR macro ,
1259 omitting a partially filled line.
1260 .
1261 .TPx
1262 .REQ .boxa
1263 End current diversion.
1264 .
1265 .TPx
1266 .REQ .boxa "macro"
1267 Divert and append to
1268 .IR macro ,
1269 omitting a partially filled line.
1270 .
1271 .TPx
1272 .REQ .bp
1273 Eject current page and begin new page.
1274 .
1275 .TPx
1276 .REQ .bp "\[+-]N"
1277 Eject current page; next page number
1278 .IR \[+-]N .
1279 .
1280 .TPx
1281 .REQ .br
1282 Line break.
1283 .
1284 .TPx
1285 .REQ .brp
1286 Break and spread output line.
1287 Same as
1288 .esc p .
1289 .
1290 .TPx
1291 .REQ .break
1292 Break out of a while loop.
1293 .
1294 .TPx
1295 .REQ .c2
1296 Reset no-break control character to
1297 .dquoted_char \[aq] .
1298 .
1299 .TPx
1300 .REQ .c2 "c"
1301 Set no-break control character to
1302 .IR c .
1303 .
1304 .TPx
1305 .REQ .cc
1306 Reset control character to
1307 .squoted_char . .
1308 .
1309 .TPx
1310 .REQ .cc "c"
1311 Set control character to
1312 .IR c .
1313 .
1314 .TPx
1315 .REQ .ce
1316 Center the next input line.
1317 .
1318 .TPx
1319 .REQ .ce "N"
1320 Center following
1321 .I N
1322 input lines.
1323 .
1324 .TPx
1325 .REQ .cf "filename"
1326 Copy contents of file
1327 .I filename
1328 unprocessed to stdout or to the diversion.
1329 .
1330 .TPx
1331 .REQ .cflags "mode c1 c2 .\|.\|.\&"
1332 Treat characters
1333 .IR c1 ,
1334 .IR c2 ,
1335 .I .\|.\|.\&
1336 according to
1337 .I mode
1338 number.
1339 .
1340 .TPx
1341 .REQ .ch "trap N"
1342 Change
1343 .I trap
1344 location
1345 to
1346 .IR N .
1347 .
1348 .TPx
1349 .REQ .char "c anything"
1350 Define entity
1351 .I c
1352 as string
1353 .IR anything .
1354 .
1355 .TPx
1356 .REQ .chop "object"
1357 Chop the last character off macro, string, or diversion
1358 .IR object .
1359 .
1360 .TPx
1361 .REQ .class "name c1 c2 .\|.\|.\&"
1362 Assign a set of characters, character ranges, or classes
1363 .IR c1 ,
1364 .IR c2 ,
1365 .I .\|.\|.\&
1366 to
1367 .IR name .
1368 .
1369 .TPx
1370 .REQ .close "stream"
1371 Close the
1372 .IR stream .
1373 .
1374 .TPx
1375 .REQ .color
1376 Enable colors.
1377 .
1378 .TPx
1379 .REQ .color "N"
1380 If
1381 .I N
1382 is zero disable colors, otherwise enable them.
1383 .
1384 .TPx
1385 .REQ .composite "from to"
1386 Map glyph name
1387 .I from
1388 to glyph name
1389 .I to
1390 while constructing a composite glyph name.
1391 .
1392 .TPx
1393 .REQ .continue
1394 Finish the current iteration of a while loop.
1395 .
1396 .TPx
1397 .REQ .cp
1398 Enable compatibility mode.
1399 .
1400 .TPx
1401 .REQ .cp "N"
1402 If
1403 .I N
1404 is zero disable compatibility mode, otherwise enable it.
1405 .
1406 .TPx
1407 .REQ .cs "font N M"
1408 Set constant character width mode for
1409 .I font
1410 to
1411 .IR N /36
1412 ems with em
1413 .IR M .
1414 .
1415 .TPx
1416 .REQ .cu "N"
1417 Continuous underline in nroff, like
1418 .request .ul
1419 in troff.
1420 .
1421 .TPx
1422 .REQ .da
1423 End current diversion.
1424 .
1425 .TPx
1426 .REQ .da "macro"
1427 Divert and append to
1428 .IR macro .
1429 .
1430 .TPx
1431 .REQ .de "macro"
1432 Define or redefine
1433 .I macro
1434 until
1435 .B ..\&
1436 is encountered.
1437 .
1438 .TPx
1439 .REQ .de "macro end"
1440 Define or redefine
1441 .I macro
1442 until
1443 .BI . end
1444 is called.
1445 .
1446 .TPx
1447 .REQ .de1 "macro"
1448 Same as
1449 .request .de
1450 but with compatibility mode switched off during macro expansion.
1451 .
1452 .TPx
1453 .REQ .de1 "macro end"
1454 Same as
1455 .request .de
1456 but with compatibility mode switched off during macro expansion.
1457 .
1458 .TPx
1459 .REQ .defcolor "color scheme component"
1460 Define or redefine a color with name
1461 .IR color .
1462 .I scheme
1463 can be
1464 .BR rgb ,
1465 .BR cym ,
1466 .BR cymk ,
1467 .BR gray ,
1468 or
1469 .BR grey .
1470 .I component
1471 can be single components specified as fractions in the range 0 to 1
1472 (default scaling indicator\~\c
1473 .scaleindicator f ),
1474 as a string of two-digit hexadecimal color components with a leading
1475 .BR # ,
1476 or as a string of four-digit hexadecimal components with two leading
1477 .BR # .
1478 The color
1479 .B default
1480 can\[aq]t be redefined.
1481 .
1482 .TPx
1483 .REQ .dei "macro"
1484 Define or redefine a macro whose name is contained in the string register
1485 .I macro
1486 until
1487 .B ..\&
1488 is encountered.
1489 .
1490 .TPx
1491 .REQ .dei "macro end"
1492 Define or redefine a macro indirectly.
1493 .I macro
1494 and
1495 .I end
1496 are string registers whose contents are interpolated for the macro name
1497 and the end macro, respectively.
1498 .
1499 .TPx
1500 .REQ .dei1 "macro"
1501 Same as
1502 .request .dei
1503 but with compatibility mode switched off during macro expansion.
1504 .
1505 .TPx
1506 .REQ .dei1 "macro end"
1507 Same as
1508 .request .dei
1509 but with compatibility mode switched off during macro expansion.
1510 .
1511 .TPx
1512 .REQ .device "anything"
1513 Write
1514 .I anything
1515 to the intermediate output as a device control function.
1516 .
1517 .TPx
1518 .REQ .devicem "name"
1519 Write contents of macro or string
1520 .I name
1521 uninterpreted to the intermediate output as a device control function.
1522 .
1523 .TPx
1524 .REQ .di
1525 End current diversion.
1526 .
1527 .TPx
1528 .REQ .di "macro"
1529 Divert to
1530 .IR macro .
1531 .
1532 .TPx
1533 .REQ .do "name"
1534 Interpret
1535 .BI . name
1536 with compatibility mode disabled.
1537 .
1538 .TPx
1539 .REQ .ds "stringvar anything"
1540 Set
1541 .I stringvar
1542 to
1543 .IR anything .
1544 .
1545 .TPx
1546 .REQ .ds1 "stringvar anything"
1547 Same as
1548 .request .ds
1549 but with compatibility mode switched off during string expansion.
1550 .
1551 .TPx
1552 .REQ .dt "N trap"
1553 Set diversion trap to position
1554 .I N
1555 (default scaling indicator\~\c
1556 .scaleindicator v ).
1557 .
1558 .TPx
1559 .REQ .ec
1560 Reset escape character to
1561 .squoted_char \[rs] .
1562 .
1563 .TPx
1564 .REQ .ec "c"
1565 Set escape character to
1566 .IR c .
1567 .
1568 .TPx
1569 .REQ .ecr
1570 Restore escape character saved with
1571 .request .ecs .
1572 .
1573 .TPx
1574 .REQ .ecs
1575 Save current escape character.
1576 .
1577 .TPx
1578 .REQ .el "anything"
1579 Else part for if-else (\c
1580 .request ie )
1581 request.
1582 .
1583 .TPx
1584 .REQ .em "macro"
1585 The
1586 .I macro
1587 is run after the end of input.
1588 .
1589 .TPx
1590 .REQ .eo
1591 Turn off escape character mechanism.
1592 .
1593 .TPx
1594 .REQ .ev
1595 Switch to previous environment and pop it off the stack.
1596 .
1597 .TPx
1598 .REQ .ev "env"
1599 Push down environment number or name
1600 .I env
1601 to the stack and switch to it.
1602 .
1603 .TPx
1604 .REQ .evc "env"
1605 Copy the contents of environment
1606 .I env
1607 to the current environment.
1608 No pushing or popping.
1609 .
1610 .TPx
1611 .REQ .ex
1612 Exit from roff processing.
1613 .
1614 .TPx
1615 .REQ .fam
1616 Return to previous font family.
1617 .
1618 .TPx
1619 .REQ .fam "name"
1620 Set the current font family to
1621 .IR name .
1622 .
1623 .TPx
1624 .REQ .fc
1625 Disable field mechanism.
1626 .
1627 .TPx
1628 .REQ .fc "a"
1629 Set field delimiter to\~\c
1630 .I a
1631 and pad glyph to space.
1632 .
1633 .TPx
1634 .REQ .fc "a b"
1635 Set field delimiter to\~\c
1636 .I a
1637 and pad glyph to\~\c
1638 .IR b .
1639 .
1640 .TPx
1641 .REQ .fchar "c anything"
1642 Define fallback character (or glyph)
1643 .I c
1644 as string
1645 .IR anything .
1646 .
1647 .TPx
1648 .REQ .fcolor
1649 Set fill color to previous fill color.
1650 .
1651 .TPx
1652 .REQ .fcolor "c"
1653 Set fill color to
1654 .IR c .
1655 .
1656 .TPx
1657 .REQ .fi
1658 Fill output lines.
1659 .
1660 .TPx
1661 .REQ .fl
1662 Flush output buffer.
1663 .
1664 .TPx
1665 .REQ .fp "n font"
1666 Mount
1667 .I font
1668 on position
1669 .IR n .
1670 .
1671 .TPx
1672 .REQ .fp "n internal external"
1673 Mount font with long
1674 .I external
1675 name to short
1676 .I internal
1677 name on position
1678 .IR n .
1679 .
1680 .TPx
1681 .REQ .fschar "f c anything"
1682 Define fallback character (or glyph)
1683 .I c
1684 for font
1685 .I f
1686 as string
1687 .IR anything .
1688 .
1689 .TPx
1690 .REQ .fspecial "font"
1691 Reset list of special fonts for
1692 .I font
1693 to be empty.
1694 .
1695 .TPx
1696 .REQ .fspecial "font s1 s2 .\|.\|.\&"
1697 When the current font is
1698 .IR font ,
1699 then the fonts
1700 .IR s1 ,
1701 .IR s2 ,
1702 .I .\|.\|.\&
1703 are special.
1704 .
1705 .TPx
1706 .REQ .ft
1707 Return to previous font.
1708 Same as
1709 .request \[rs]f[]
1710 or
1711 .request \[rs]fP .
1712 .
1713 .TPx
1714 .REQ .ft "font"
1715 Change to font name or number
1716 .IR font ;
1717 same as
1718 .esc[] f font
1719 escape sequence.
1720 .
1721 .TPx
1722 .REQ .ftr "font1 font2"
1723 Translate
1724 .I font1
1725 to
1726 .IR font2 .
1727 .
1728 .TPx
1729 .REQ .fzoom "font"
1730 Don\[aq]t magnify
1731 .IR font .
1732 .
1733 .TPx
1734 .REQ .fzoom "font zoom"
1735 Set zoom factor for
1736 .I font
1737 (in multiples of 1/1000th).
1738 .
1739 .TPx
1740 .REQ .gcolor
1741 Set glyph color to previous glyph color.
1742 .
1743 .TPx
1744 .REQ .gcolor "c"
1745 Set glyph color to
1746 .IR c .
1747 .
1748 .TPx
1749 .REQ .hc
1750 Remove additional hyphenation indicator character.
1751 .
1752 .TPx
1753 .REQ .hc "c"
1754 Set up additional hyphenation indicator character\~\c
1755 .IR c .
1756 .
1757 .TPx
1758 .REQ .hcode "c1 code1 c2 code2 .\|.\|.\&"
1759 Set the hyphenation code of character
1760 .I c1
1761 to
1762 .IR code1 ,
1763 that of
1764 .I c2
1765 to
1766 .IR code2 ,
1767 etc.
1768 .
1769 .TPx
1770 .REQ .hla "lang"
1771 Set the current hyphenation language to
1772 .IR lang .
1773 .
1774 .TPx
1775 .REQ .hlm "n"
1776 Set the maximum number of consecutive hyphenated lines to
1777 .IR n .
1778 .
1779 .TPx
1780 .REQ .hpf "file"
1781 Read hyphenation patterns from
1782 .IR file .
1783 .
1784 .TPx
1785 .REQ .hpfa "file"
1786 Append hyphenation patterns from
1787 .IR file .
1788 .
1789 .TPx
1790 .REQ .hpfcode "a b c d .\|.\|.\&"
1791 Set input mapping for
1792 .request .hpf .
1793 .
1794 .TPx
1795 .REQ .hw "words"
1796 List of
1797 .I words
1798 with exceptional hyphenation.
1799 .
1800 .TPx
1801 .REQ .hy "N"
1802 Switch to hyphenation mode
1803 .IR N .
1804 .
1805 .TPx
1806 .REQ .hym "n"
1807 Set the hyphenation margin to
1808 .I n
1809 (default scaling indicator\~\c
1810 .scaleindicator m ).
1811 .
1812 .TPx
1813 .REQ .hys "n"
1814 Set the hyphenation space to
1815 .IR n .
1816 .
1817 .TPx
1818 .REQ .ie "cond anything"
1819 If
1820 .I cond
1821 then
1822 .I anything
1823 else goto
1824 .request .el .
1825 .
1826 .TPx
1827 .REQ .if "cond anything"
1828 If
1829 .I cond
1830 then
1831 .IR anything ;
1832 otherwise do nothing.
1833 .
1834 .TPx
1835 .REQ .ig
1836 Ignore text until
1837 .B ..\&
1838 is encountered.
1839 .
1840 .TPx
1841 .REQ .ig "end"
1842 Ignore text until
1843 .BI . end
1844 is called.
1845 .
1846 .TPx
1847 .REQ .in
1848 Change to previous indentation value.
1849 .
1850 .TPx
1851 .REQ .in "\[+-]N"
1852 Change indentation according to
1853 .I \[+-]N
1854 (default scaling indicator\~\c
1855 .scaleindicator m ).
1856 .
1857 .TPx
1858 .REQ .it "N trap"
1859 Set an input-line count trap for the next
1860 .I N
1861 lines.
1862 .
1863 .TPx
1864 .REQ .itc "N trap"
1865 Same as
1866 .request .it
1867 but count lines interrupted with
1868 .esc c
1869 as one line.
1870 .
1871 .TPx
1872 .REQ .kern
1873 Enable pairwise kerning.
1874 .
1875 .TPx
1876 .REQ .kern "n"
1877 If
1878 .I n
1879 is zero, disable pairwise kerning, otherwise enable it.
1880 .
1881 .TPx
1882 .REQ .lc
1883 Remove leader repetition glyph.
1884 .
1885 .TPx
1886 .REQ .lc "c"
1887 Set leader repetition glyph to\~\c
1888 .IR c .
1889 .
1890 .TPx
1891 .REQ .length "register anything"
1892 Write the length of the string
1893 .I anything
1894 to
1895 .IR register .
1896 .
1897 .TPx
1898 .REQ .linetabs
1899 Enable line-tabs mode (i.e., calculate tab positions relative to output
1900 line).
1901 .
1902 .TPx
1903 .REQ .linetabs "n"
1904 If
1905 .I n
1906 is zero, disable line-tabs mode, otherwise enable it.
1907 .
1908 .TPx
1909 .REQ .lf "N"
1910 Set input line number to
1911 .IR N .
1912 .
1913 .TPx
1914 .REQ .lf "N file"
1915 Set input line number to
1916 .I N
1917 and filename to
1918 .IR file .
1919 .
1920 .TPx
1921 .REQ .lg "N"
1922 Ligature mode on if
1923 .IR N >0.
1924 .
1925 .TPx
1926 .REQ .ll
1927 Change to previous line length.
1928 .
1929 .TPx
1930 .REQ .ll "\[+-]N"
1931 Set line length according to
1932 .I \[+-]N
1933 (default length
1934 .scalednumber 6.5 i ,
1935 default scaling indicator\~\c
1936 .scaleindicator m ).
1937 .
1938 .TPx
1939 .REQ .lsm
1940 Unset the leading spaces macro.
1941 .
1942 .TPx
1943 .REQ .lsm "macro"
1944 Set the leading spaces macro to
1945 .IR macro .
1946 .
1947 .TPx
1948 .REQ .ls
1949 Change to the previous value of additional intra-line skip.
1950 .
1951 .TPx
1952 .REQ .ls "N"
1953 Set additional intra-line skip value to
1954 .IR N ,
1955 i.e.,
1956 .IR N \\-1
1957 blank lines are inserted after each text output line.
1958 .
1959 .TPx
1960 .REQ .lt "\[+-]N"
1961 Length of title (default scaling indicator\~\c
1962 .scaleindicator m ).
1963 .
1964 .TPx
1965 .REQ .mc
1966 Margin glyph off.
1967 .
1968 .TPx
1969 .REQ .mc "c"
1970 Print glyph\~\c
1971 .I c
1972 after each text line at actual distance from right margin.
1973 .
1974 .TPx
1975 .REQ .mc "c N"
1976 Set margin glyph to\~\c
1977 .I c
1978 and distance to\~\c
1979 .I N
1980 from right margin (default scaling indicator\~\c
1981 .scaleindicator m ).
1982 .
1983 .TPx
1984 .REQ .mk "register"
1985 Mark current vertical position in
1986 .IR register .
1987 .
1988 .TPx
1989 .REQ .mso "file"
1990 The same as
1991 .request .so
1992 except that
1993 .I file
1994 is searched in the tmac directories.
1995 .
1996 .TPx
1997 .REQ .na
1998 No output-line adjusting.
1999 .
2000 .TPx
2001 .REQ .ne
2002 Need a one-line vertical space.
2003 .
2004 .TPx
2005 .REQ .ne "N"
2006 Need
2007 .I N
2008 vertical space (default scaling indicator\~\c
2009 .scaleindicator v ).
2010 .
2011 .TPx
2012 .REQ .nf
2013 No filling or adjusting of output-lines.
2014 .
2015 .TPx
2016 .REQ .nh
2017 No hyphenation.
2018 .
2019 .TPx
2020 .REQ .nm
2021 Number mode off.
2022 .
2023 .TPx
2024 .REQ .nm "\[+-]N \fR[\fPM \fR[\fPS \fR[\fPI\fR]]]\fP"
2025 In line number mode, set number, multiple, spacing, and indentation.
2026 .
2027 .TPx
2028 .REQ .nn
2029 Do not number next line.
2030 .
2031 .TPx
2032 .REQ .nn "N"
2033 Do not number next
2034 .I N
2035 lines.
2036 .
2037 .TPx
2038 .REQ .nop "anything"
2039 Always process
2040 .IR anything .
2041 .
2042 .TPx
2043 .REQ .nr "register \[+-]N \fR[\fPM\fR]\fP"
2044 Define or modify
2045 .I register
2046 using
2047 .I \[+-]N
2048 with auto-increment
2049 .IR M .
2050 .
2051 .TPx
2052 .REQ .nroff
2053 Make the built-in conditions
2054 .B n
2055 true and
2056 .B t
2057 false.
2058 .
2059 .TPx
2060 .REQ .ns
2061 Turn on no-space mode.
2062 .
2063 .TPx
2064 .REQ .nx
2065 Immediately jump to end of current file.
2066 .
2067 .TPx
2068 .REQ .nx "filename"
2069 Immediately continue processing with file
2070 .IR file .
2071 .
2072 .TPx
2073 .REQ .open "stream filename"
2074 Open
2075 .I filename
2076 for writing and associate the stream named
2077 .I stream
2078 with it.
2079 .
2080 .TPx
2081 .REQ .opena "stream filename"
2082 Like
2083 .request .open
2084 but append to it.
2085 .
2086 .TPx
2087 .REQ .os
2088 Output vertical distance that was saved by the
2089 .request sv
2090 request.
2091 .
2092 .TPx
2093 .REQ .output "string"
2094 Emit
2095 .I string
2096 directly to intermediate output, allowing leading whitespace if
2097 .I string
2098 starts with
2099 \&\f[CB]\[dq]\f[]
2100 (which is stripped off).
2101 .
2102 .TPx
2103 .REQ .pc
2104 Reset page number character to\~\c
2105 .squoted_char % .
2106 .
2107 .TPx
2108 .REQ .pc "c"
2109 Page number character.
2110 .
2111 .TPx
2112 .REQ .pev
2113 Print the current environment and each defined environment
2114 state to stderr.
2115 .
2116 .TPx
2117 .REQ .pi "program"
2118 Pipe output to
2119 .I program
2120 (nroff only).
2121 .
2122 .TPx
2123 .REQ .pl
2124 Set page length to default
2125 .scalednumber 11 i .
2126 The current page length is stored in
2127 .register .p .
2128 .
2129 .TPx
2130 .REQ .pl "\[+-]N"
2131 Change page length to
2132 .I \[+-]N
2133 (default scaling indicator\~\c
2134 .scaleindicator v ).
2135 .
2136 .TPx
2137 .REQ .pm
2138 Print macro names and sizes (number of blocks of 128 bytes).
2139 .
2140 .TPx
2141 .REQ .pm "t"
2142 Print only total of sizes of macros (number of 128 bytes blocks).
2143 .
2144 .TPx
2145 .REQ .pn "\[+-]N"
2146 Next page number
2147 .IR N .
2148 .
2149 .TPx
2150 .REQ .pnr
2151 Print the names and contents of all currently defined number registers
2152 on stderr.
2153 .
2154 .TPx
2155 .REQ .po
2156 Change to previous page offset.
2157 .
2158 The current page offset is available in
2159 .register .o .
2160 .
2161 .TPx
2162 .REQ .po "\[+-]N"
2163 Page offset
2164 .IR N .
2165 .
2166 .TPx
2167 .REQ .ps
2168 Return to previous point size.
2169 .TPx
2170 .REQ .ps "\[+-]N"
2171 Point size; same as
2172 .esc[] s \[+-]N .
2173 .
2174 .TPx
2175 .REQ .psbb "filename"
2176 Get the bounding box of a PostScript image
2177 .IR filename .
2178 .
2179 .TPx
2180 .REQ .pso "command"
2181 This behaves like the
2182 .request so
2183 request except that input comes from the standard output of
2184 .IR command .
2185 .
2186 .TPx
2187 .REQ .ptr
2188 Print the names and positions of all traps (not including input line
2189 traps and diversion traps) on stderr.
2190 .
2191 .TPx
2192 .REQ .pvs
2193 Change to previous post-vertical line spacing.
2194 .
2195 .TPx
2196 .REQ .pvs "\[+-]N"
2197 Change post-vertical line spacing according to
2198 .I \[+-]N
2199 (default scaling indicator\~\c
2200 .scaleindicator p ).
2201 .
2202 .TPx
2203 .REQ .rchar "c1 c2 .\|.\|.\&"
2204 Remove the definitions of entities
2205 .IR c1 ,
2206 .IR c2 ,
2207 .I .\|.\|.\&
2208 .
2209 .TPx
2210 .REQ .rd "prompt"
2211 Read insertion.
2212 .
2213 .TPx
2214 .REQ .return
2215 Return from a macro.
2216 .
2217 .TPx
2218 .REQ .return "anything"
2219 Return twice, namely from the macro at the current level and from the macro
2220 one level higher.
2221 .
2222 .TPx
2223 .REQ .rfschar "f c1 c2 .\|.\|.\&"
2224 Remove the definitions of entities
2225 .IR c1 ,
2226 .IR c2 ,
2227 .I .\|.\|.\&
2228 for font
2229 .IR f .
2230 .
2231 .TPx
2232 .REQ .rj "n"
2233 Right justify the next
2234 .I n
2235 input lines.
2236 .
2237 .TPx
2238 .REQ .rm "name"
2239 Remove request, macro, or string
2240 .IR name .
2241 .
2242 .TPx
2243 .REQ .rn "old new"
2244 Rename request, macro, or string
2245 .I old
2246 to
2247 .IR new .
2248 .
2249 .TPx
2250 .REQ .rnn "reg1 reg2"
2251 Rename register
2252 .I reg1
2253 to
2254 .IR reg2 .
2255 .
2256 .TPx
2257 .REQ .rr "register"
2258 Remove
2259 .IR register .
2260 .
2261 .TPx
2262 .REQ .rs
2263 Restore spacing; turn no-space mode off.
2264 .
2265 .TPx
2266 .REQ .rt "\[+-]N"
2267 Return
2268 .I (upward only)
2269 to marked vertical place (default scaling indicator\~\c
2270 .scaleindicator v ).
2271 .
2272 .TPx
2273 .REQ .schar "c anything"
2274 Define global fallback character (or glyph)\~\c
2275 .I c
2276 as string
2277 .IR anything .
2278 .
2279 .TPx
2280 .REQ .shc
2281 Reset soft hyphen glyph to
2282 .esc (hy .
2283 .
2284 .TPx
2285 .REQ .shc "c"
2286 Set the soft hyphen glyph to\~\c
2287 .IR c .
2288 .
2289 .TPx
2290 .REQ .shift "n"
2291 In a macro, shift the arguments by
2292 .IR n \~\c
2293 positions.
2294 .
2295 .TPx
2296 .REQ .sizes "s1 s2 .\|.\|.\& sn \fB[0]\fP"
2297 Set available font sizes similar to the
2298 .B sizes
2299 command in a
2300 .B DESC
2301 file.
2302 .
2303 .TPx
2304 .REQ .so "filename"
2305 Include source file.
2306 .
2307 .TPx
2308 .REQ .sp
2309 Skip one line vertically.
2310 .
2311 .TPx
2312 .REQ .sp "N"
2313 Space vertical distance
2314 .I N
2315 up or down according to sign of
2316 .I N
2317 (default scaling indicator\~\c
2318 .scaleindicator v ).
2319 .
2320 .TPx
2321 .REQ .special
2322 Reset global list of special fonts to be empty.
2323 .
2324 .TPx
2325 .REQ .special "s1 s2 .\|.\|.\&"
2326 Fonts
2327 .IR s1 ,
2328 .IR s2 ,
2329 etc.\& are special and are searched for glyphs not in the
2330 current font.
2331 .
2332 .TPx
2333 .REQ .spreadwarn
2334 Toggle the spread warning on and off without changing its value.
2335 .
2336 .TPx
2337 .REQ .spreadwarn "limit"
2338 Emit a warning if each space in an output line is widened by
2339 .I limit
2340 or more (default scaling indicator\~\c
2341 .scaleindicator m ).
2342 .
2343 .TPx
2344 .REQ .ss "N"
2345 Set space glyph size to
2346 .IR N /12
2347 of the space width in the current font.
2348 .
2349 .TPx
2350 .REQ .ss "N M"
2351 Set space glyph size to
2352 .IR N /12
2353 and sentence space size set to
2354 .IR M /12
2355 of the space width in the current font.
2356 .
2357 .TPx
2358 .REQ .sty "n style"
2359 Associate
2360 .I style
2361 with font position
2362 .IR n .
2363 .
2364 .TPx
2365 .REQ .substring "xx n1 n2"
2366 Replace the string named
2367 .I xx
2368 with the substring defined by the indices
2369 .I n1
2370 and
2371 .IR n2 .
2372 .
2373 .TPx
2374 .REQ .sv
2375 Save
2376 .scalednumber "1 v"
2377 of vertical space.
2378 .TPx
2379 .REQ .sv "N"
2380 Save the vertical distance
2381 .I N
2382 for later output with
2383 .request os
2384 request (default scaling indicator\~\c
2385 .scaleindicator v ).
2386 .
2387 .TPx
2388 .REQ .sy "command-line"
2389 Execute program
2390 .IR command-line .
2391 .
2392 .TPx
2393 .REQ .ta "T N"
2394 Set tabs after every position that is a multiple of
2395 .I N
2396 (default scaling indicator\~\c
2397 .scaleindicator m ).
2398 .TPx
2399 .REQ .ta "n1 n2 .\|.\|.\& nn \f[CB]T\f[] r1 r2 .\|.\|.\& rn"
2400 Set tabs at positions
2401 .IR n1 ,
2402 .IR n2 ,
2403 .Text .\|.\|.,
2404 .IR nn ,
2405 then set tabs at
2406 .IR nn + r1 ,
2407 .IR nn + r2 ,
2408 .Text .\|.\|.,
2409 .IR nn + rn ,
2410 then at
2411 .IR nn + rn + r1 ,
2412 .IR nn + rn + r2 ,
2413 .Text .\|.\|.,
2414 .IR nn + rn + rn ,
2415 and so on.
2416 .
2417 .\".TPx
2418 .\".REQ .tar
2419 .\"Restore internally saved tab positions.
2420 .\".
2421 .\".TPx
2422 .\".REQ .tas
2423 .\"Save tab positions internally.
2424 .
2425 .TPx
2426 .REQ .tc
2427 Remove tab repetition glyph.
2428 .TPx
2429 .REQ .tc "c"
2430 Set tab repetition glyph to\~\c
2431 .IR c .
2432 .
2433 .TPx
2434 .REQ .ti "\[+-]N"
2435 Temporary indent next line (default scaling indicator\~\c
2436 .scaleindicator m ).
2437 .
2438 .TPx
2439 .REQ .tkf "font s1 n1 s2 n2"
2440 Enable track kerning for
2441 .IR font .
2442 .
2443 .TPx
2444 .REQ .tl "\f[CB]\[cq]\f[]left\f[CB]\[cq]\f[]center\f[CB]\[cq]\f[]right\f[CB]\[cq]\f[]"
2445 Three-part title.
2446 .
2447 .TPx
2448 .REQ .tm "anything"
2449 Print
2450 .I anything
2451 on stdout.
2452 .
2453 .TPx
2454 .REQ .tm1 "anything"
2455 Print
2456 .I anything
2457 on stdout, allowing leading whitespace if
2458 .I anything
2459 starts with
2460 \&\f[CB]\[dq]\f[]
2461 (which is stripped off).
2462 .
2463 .TPx
2464 .REQ .tmc "anything"
2465 Similar to
2466 .request .tm1
2467 without emitting a final newline.
2468 .
2469 .TPx
2470 .REQ .tr "abcd.\|.\|.\&"
2471 Translate
2472 .I a
2473 to
2474 .IR b ,
2475 .I c
2476 to
2477 .IR d ,
2478 etc.\& on output.
2479 .
2480 .TPx
2481 .REQ .trf "filename"
2482 Transparently output the contents of file
2483 .IR filename .
2484 .
2485 .TPx
2486 .REQ .trin "abcd.\|.\|.\&"
2487 This is the same as the
2488 .request tr
2489 request except that the
2490 .B asciify
2491 request uses the character code (if any) before the character
2492 translation.
2493 .
2494 .TPx
2495 .REQ .trnt "abcd.\|.\|.\&"
2496 This is the same as the
2497 .request tr
2498 request except that the translations do not apply to text that is
2499 transparently throughput into a diversion with
2500 .esc ! .
2501 .
2502 .TPx
2503 .REQ .troff
2504 Make the built-in conditions
2505 .B t
2506 true and
2507 .B n
2508 false.
2509 .
2510 .TPx
2511 .REQ .uf "font"
2512 Set underline font to
2513 .I font
2514 (to be switched to by
2515 .request .ul ).
2516 .
2517 .TPx
2518 .REQ .ul "N"
2519 Underline (italicize in troff)
2520 .I N
2521 input lines.
2522 .
2523 .TPx
2524 .REQ .unformat "diversion"
2525 Unformat space characters and tabs in
2526 .IR diversion ,
2527 preserving font information.
2528 .TPx
2529 .REQ .vpt "n"
2530 Enable vertical position traps if
2531 .I n
2532 is non-zero, disable them otherwise.
2533 .
2534 .TPx
2535 .REQ .vs
2536 Change to previous vertical base line spacing.
2537 .
2538 .TPx
2539 .REQ .vs "\[+-]N"
2540 Set vertical base line spacing to
2541 .I \[+-]N
2542 (default scaling indicator\~\c
2543 .scaleindicator p ).
2544 .
2545 .TPx
2546 .REQ .warn "n"
2547 Set warnings code to
2548 .IR n .
2549 .
2550 .TPx
2551 .REQ .warnscale "si"
2552 Set scaling indicator used in warnings to
2553 .IR si .
2554 .
2555 .TPx
2556 .REQ .wh "N"
2557 Remove (first) trap at position
2558 .IR N .
2559 .
2560 .TPx
2561 .REQ .wh "N trap"
2562 Set location trap; negative means from page bottom.
2563 .
2564 .TPx
2565 .REQ .while "cond anything"
2566 While condition
2567 .I cond
2568 is true, accept
2569 .I anything
2570 as input.
2571 .
2572 .TPx
2573 .REQ .write "stream anything"
2574 Write
2575 .I anything
2576 to the stream named
2577 .IR stream .
2578 .
2579 .TPx
2580 .REQ .writec "stream anything"
2581 Similar to
2582 .request .write
2583 without emitting a final newline.
2584 .
2585 .TPx
2586 .REQ .writem "stream xx"
2587 Write contents of macro or string
2588 .I xx
2589 to the stream named
2590 .IR stream .
2591 .
2592 .PD
2593 .
2594 .
2595 .P
2596 Besides these standard groff requests, there might be further macro
2597 calls.
2598 They can originate from a macro package (see
2599 .BR roff (@MAN7EXT@)
2600 for an overview) or from a preprocessor.
2601 .
2602 .
2603 .P
2604 Preprocessor macros are easy to be recognized.
2605 .
2606 They enclose their code into a pair of characteristic macros.
2607 .
2608 .
2609 .P
2610 .TS
2611 box, center, tab (@);
2612 c | c | c
2613 CfCB | CfCB | CfCB.
2614 preprocessor@start macro@ end macro
2615 =
2616 chem@.cstart@.cend
2617 eqn@.EQ@.EN
2618 gideal@.IS@.IE
2619 grap@.G1@.G2
2620 grn@.GS@.GE
2621 @@.IF
2622 pic@.PS@.PE
2623 refer@.R1@.R2
2624 soelim@\f[I]none@\f[I]none
2625 tbl@.TS@.TE
2626 _
2627 glilypond@.lilypond start@.lilypond stop
2628 gperl@.Perl start@.Perl stop
2629 gpinyin@.pinyin start@.pinyin stop
2630 .TE
2631 .
2632 .
2633 .P
2634 Note that the \[oq]ideal\[cq] preprocessor is not available in groff yet.
2635 .
2636 .
2637 .\" --------------------------------------------------------------------
2638 .SH "ESCAPE SEQUENCES"
2639 .\" --------------------------------------------------------------------
2640 .
2641 Escape sequences are in-line language elements usually introduced by a
2642 backslash
2643 .squoted_char \[rs]
2644 and followed by an escape name and sometimes by a required argument.
2645 .
2646 Input processing is continued directly after the escaped character or
2647 the argument (without an intervening separation character).
2648 .
2649 So there must be a way to determine the end of the escape name and the
2650 end of the argument.
2651 .
2652 .
2653 .P
2654 This is done by enclosing names (escape name and arguments consisting
2655 of a variable name) by a pair of brackets
2656 .BI \[lB] name \[rB]
2657 and constant arguments (number expressions and characters) by
2658 apostrophes (ASCII 0x27) like
2659 .BI \[cq] constant \[cq] \f[R].
2660 .
2661 .
2662 .P
2663 There are abbreviations for short names.
2664 .
2665 Two-character escape names can be specified by an opening parenthesis
2666 like
2667 .esc ( xy
2668 or
2669 .esc *( xy
2670 without a closing counterpart.
2671 .
2672 And all one-character names different from the special characters
2673 .squoted_char [
2674 and
2675 .squoted_char (
2676 can even be specified without a marker, for example
2677 .esc n c
2678 or
2679 .esc $ c.
2680 .
2681 .
2682 .P
2683 Constant arguments of length\~1 can omit the marker apostrophes, too,
2684 but there is no two-character analogue.
2685 .
2686 .
2687 .P
2688 While one-character escape sequences are mainly used for in-line
2689 functions and system related tasks, the two-letter names following the
2690 .esc (
2691 construct are glyphs predefined by the roff system; these are called
2692 \[oq]Special Characters\[cq] in the classical documentation.
2693 .
2694 Escapes sequences of the form
2695 .esc[] "" name
2696 denote glyphs too.
2697 .
2698 .
2699 .\" --------------------------------------------------------------------
2700 .SS "Single-Character Escapes"
2701 .\" --------------------------------------------------------------------
2702 .
2703 .PD 0
2704 .
2705 .\" --------- comments ---------
2706 .
2707 .TP
2708 .ESC \[dq]
2709 Start of a comment.
2710 .
2711 Everything up to the end of the line is ignored.
2712 .
2713 .TP
2714 .ESC #
2715 Everything up to and including the next newline is ignored.
2716 .
2717 This is interpreted in copy mode.
2718 .
2719 This is like
2720 .esc \[dq]
2721 except that the terminating newline is ignored as well.
2722 .
2723 .\" --------- strings ---------
2724 .
2725 .TP
2726 .ESC * s
2727 The string stored in the string variable with one-character name\~\c
2728 .IR s .
2729 .
2730 .TP
2731 .ESC *( st
2732 The string stored in the string variable with two-character name
2733 .IR st .
2734 .
2735 .TP
2736 .ESC[] * string
2737 The string stored in the string variable with name
2738 .I string
2739 (with arbitrary length).
2740 .
2741 .TP
2742 .ESC[] * "stringvar arg1 arg2 .\|.\|."
2743 The string stored in the string variable with arbitrarily long name
2744 .IR stringvar ,
2745 taking
2746 .IR arg1 ,
2747 .IR arg2 ,
2748 .I .\|.\|.\&
2749 as arguments.
2750 .
2751 .\" --------- macro arguments ---------
2752 .
2753 .TP
2754 .ESC $0
2755 The name by which the current macro was invoked.
2756 .
2757 The
2758 .request als
2759 request can make a macro have more than one name.
2760 .
2761 .TP
2762 .ESC $ x
2763 Macro or string argument with one-digit number\~\c
2764 .I x
2765 in the range 1 to\~9.
2766 .
2767 .TP
2768 .ESC $( xy
2769 Macro or string argument with two-digit number
2770 .I xy
2771 (larger than zero).
2772 .
2773 .TP
2774 .ESC[] $ nexp
2775 Macro or string argument with number
2776 .IR nexp ,
2777 where
2778 .I nexp
2779 is a numerical expression evaluating to an integer \[>=]1.
2780 .
2781 .TP
2782 .ESC $*
2783 In a macro or string, the concatenation of all the arguments separated
2784 by spaces.
2785 .
2786 .TP
2787 .ESC $@
2788 In a macro or string, the concatenation of all the arguments with each
2789 surrounded by double quotes, and separated by spaces.
2790 .
2791 .TP
2792 .ESC $^
2793 In a macro, the representation of all parameters as if they were an
2794 argument to the
2795 .request ds
2796 request.
2797 .
2798 .\" --------- escaped characters ---------
2799 .
2800 .TP
2801 .ESC \e
2802 reduces to a single backslash; useful to delay its interpretation as
2803 escape character in copy mode.
2804 .
2805 For a printable backslash, use
2806 .esc e ,
2807 or even better
2808 .esc [rs] ,
2809 to be independent from the current escape character.
2810 .
2811 .TP
2812 .ESC \[aa]
2813 The acute accent \[aa]; same as
2814 .esc (aa .
2815 Unescaped: apostrophe, right quotation mark, single quote (ASCII 0x27).
2816 .
2817 .TP
2818 .ESC \[ga]
2819 The grave accent \[ga]; same as
2820 .esc (ga .
2821 Unescaped: left quote, backquote (ASCII 0x60).
2822 .
2823 .TP
2824 .ESC -
2825 The \- (minus) sign in the current font.
2826 .
2827 .TP
2828 .ESC _
2829 The same as
2830 .esc (ul ,
2831 the underline character.
2832 .
2833 .TP
2834 .ESC .
2835 The same as a dot (\[oq].\[cq]).  Necessary in nested macro
2836 definitions so that \[oq]\[rs]\[rs]..\[cq] expands to \[oq]..\[cq].
2837 .
2838 .TP
2839 .ESC %
2840 Default optional hyphenation character.
2841 .
2842 .TP
2843 .ESC !
2844 Transparent line indicator.
2845 .
2846 .TP
2847 .ESC? anything
2848 In a diversion, this transparently embeds
2849 .I anything
2850 in the diversion.
2851 .I anything
2852 is read in copy mode.
2853 .
2854 See also the escape sequences
2855 .esc !
2856 and
2857 .esc ? .
2858 .
2859 .
2860 .\" --------- spacing ---------
2861 .
2862 .TP
2863 .ESC \& space
2864 Unpaddable space size space glyph (no line break).
2865 .
2866 .TP
2867 .ESC 0
2868 Digit-width space.
2869 .
2870 .TP
2871 .ESC |
2872 1/6\ em narrow space glyph; zero width in nroff.
2873 .
2874 .TP
2875 .ESC ^
2876 1/12\ em half-narrow space glyph; zero width in nroff.
2877 .
2878 .TP
2879 .ESC &
2880 Non-printable, zero-width glyph.
2881 .
2882 .TP
2883 .ESC )
2884 Like
2885 .esc &
2886 except that it behaves like a glyph declared with the
2887 .request cflags
2888 request to be transparent for the purposes of end-of-sentence
2889 recognition.
2890 .
2891 .TP
2892 .ESC /
2893 Increases the width of the preceding glyph so that the spacing
2894 between that glyph and the following glyph is correct if
2895 the following glyph is a roman glyph.
2896 .
2897 .TP
2898 .ESC ,
2899 Modifies the spacing of the following glyph so that the spacing
2900 between that glyph and the preceding glyph is correct if the
2901 preceding glyph is a roman glyph.
2902 .
2903 .TP
2904 .ESC ~
2905 Unbreakable space that stretches like a normal inter-word space when a
2906 line is adjusted.
2907 .
2908 .TP
2909 .ESC :
2910 Inserts a zero-width break point (similar to
2911 .esc %
2912 but without a soft hyphen character).
2913 .
2914 .TP
2915 .ESC "" newline
2916 Ignored newline, for continuation lines.
2917 .
2918 .\" --------- structuring ---------
2919 .
2920 .TP
2921 .ESC {
2922 Begin conditional input.
2923 .
2924 .TP
2925 .ESC }
2926 End conditional input.
2927 .
2928 .\" --------- longer escape names ---------
2929 .
2930 .TP
2931 .ESC ( sc
2932 A glyph with two-character name
2933 .IR sc ;
2934 see section
2935 .BR "Special Characters" .
2936 .
2937 .TP
2938 .ESC[] "" name
2939 A glyph with name
2940 .I name
2941 (of arbitrary length).
2942 .
2943 .TP
2944 .ESC[] "" "comp1 comp2 .\|.\|."
2945 A composite glyph with components
2946 .IR comp1 ,
2947 .IR comp2 ,
2948 .I .\|.\|.
2949 .
2950 .\" --------- alphabetical escapes ---------
2951 .
2952 .TP
2953 .ESC a
2954 Non-interpreted leader character.
2955 .
2956 .TP
2957 .ESCq A anything
2958 If
2959 .I anything
2960 is acceptable as a name of a string, macro, diversion, register,
2961 environment or font it expands to\~1, and to\~0 otherwise.
2962 .
2963 .TP
2964 .ESCq b abc.\|.\|.\&
2965 Bracket building function.
2966 .
2967 .TP
2968 .ESCq B anything
2969 If
2970 .I anything
2971 is acceptable as a valid numeric expression it expands to\~1, and
2972 to\~0 otherwise.
2973 .
2974 .TP
2975 .ESC c
2976 Interrupt text processing.
2977 .
2978 .TP
2979 .ESCq C glyph
2980 The glyph called
2981 .IR glyph ;
2982 same as
2983 .esc[] "" glyph ,
2984 but compatible to other roff versions.
2985 .
2986 .TP
2987 .ESC d
2988 Forward (down) 1/2 em (1/2 line in nroff).
2989 .
2990 .TP
2991 .ESCq D charseq
2992 Draw a graphical element defined by the characters in
2993 .IR charseq ;
2994 see the groff info file for details.
2995 .
2996 .TP
2997 .ESC e
2998 Printable version of the current escape character.
2999 .
3000 .TP
3001 .ESC E
3002 Equivalent to an escape character, but is not interpreted in copy mode.
3003 .
3004 .TP
3005 .ESC f F
3006 Change to font with one-character name or one-digit number\~\c
3007 .IR F .
3008 .
3009 .TP
3010 .ESC fP
3011 Switch back to previous font.
3012 .
3013 .TP
3014 .ESC f( fo
3015 Change to font with two-character name or two-digit number
3016 .IR fo .
3017 .
3018 .TP
3019 .ESC[] f font
3020 Change to font with arbitrarily long name or number expression
3021 .IR font .
3022 .
3023 .TP
3024 .ESC[] f ""
3025 Switch back to previous font.
3026 .
3027 .TP
3028 .ESC F f
3029 Change to font family with one-character name\~\c
3030 .IR f .
3031 .
3032 .TP
3033 .ESC F( fm
3034 Change to font family with two-character name
3035 .IR fm .
3036 .
3037 .TP
3038 .ESC[] F fam
3039 Change to font family with arbitrarily long name
3040 .IR fam .
3041 .
3042 .TP
3043 .ESC[] F ""
3044 Switch back to previous font family.
3045 .
3046 .TP
3047 .ESC g r
3048 Return format of register with one-character name\~\c
3049 .I r
3050 suitable for
3051 .request af
3052 request.
3053 .
3054 .TP
3055 .ESC g( rg
3056 Return format of register with two-character name
3057 .I rg
3058 suitable for
3059 .request af
3060 request.
3061 .
3062 .TP
3063 .ESC[] g reg
3064 Return format of register with arbitrarily long name
3065 .I reg
3066 suitable for
3067 .request af
3068 request.
3069 .
3070 .TP
3071 .ESCq h N
3072 Local horizontal motion; move right
3073 .I N
3074 (left if negative).
3075 .
3076 .TP
3077 .ESCq H N
3078 Set height of current font to
3079 .IR N .
3080 .
3081 .TP
3082 .ESC k r
3083 Mark horizontal input place in one-character register\~\c
3084 .IR r .
3085 .
3086 .TP
3087 .ESC k( rg
3088 Mark horizontal input place in two-character register
3089 .IR rg .
3090 .
3091 .TP
3092 .ESC[] k reg
3093 Mark horizontal input place in register with arbitrarily long name
3094 .IR reg .
3095 .
3096 .TP
3097 .ESCq l Nc
3098 Horizontal line drawing function (optionally using character
3099 .IR c ).
3100 .
3101 .TP
3102 .ESCq L Nc
3103 Vertical line drawing function (optionally using character
3104 .IR c ).
3105 .
3106 .TP
3107 .ESC m c
3108 Change to color with one-character name\~\c
3109 .IR c .
3110 .
3111 .TP
3112 .ESC m( cl
3113 Change to color with two-character name
3114 .IR cl .
3115 .
3116 .TP
3117 .ESC[] m color
3118 Change to color with arbitrarily long name
3119 .IR color .
3120 .
3121 .TP
3122 .ESC[] m ""
3123 Switch back to previous color.
3124 .
3125 .TP
3126 .ESC M c
3127 Change filling color for closed drawn objects to color with
3128 one-character name\~\c
3129 .IR c .
3130 .
3131 .TP
3132 .ESC M( cl
3133 Change filling color for closed drawn objects to color with
3134 two-character name
3135 .IR cl .
3136 .
3137 .TP
3138 .ESC[] M color
3139 Change filling color for closed drawn objects to color with
3140 arbitrarily long name
3141 .IR color .
3142 .
3143 .TP
3144 .ESC[] M ""
3145 Switch to previous fill color.
3146 .
3147 .TP
3148 .ESC n r
3149 The numerical value stored in the register variable with the
3150 one-character name\~\c
3151 .IR r .
3152 .
3153 .TP
3154 .ESC n( re
3155 The numerical value stored in the register variable with the
3156 two-character name
3157 .IR re .
3158 .
3159 .TP
3160 .ESC[] n reg
3161 The numerical value stored in the register variable with arbitrarily
3162 long name
3163 .IR reg .
3164 .
3165 .TP
3166 .ESCq N n
3167 Typeset the glyph with index\~\c
3168 .I n
3169 in the current font.
3170 .
3171 No special fonts are searched.
3172 .
3173 Useful for adding (named) entities to a document using the
3174 .request char
3175 request and friends.
3176 .
3177 .TP
3178 .ESCq o abc.\|.\|.\&
3179 Overstrike glyphs
3180 .IR a ,
3181 .IR b ,
3182 .IR c ,
3183 etc.
3184 .
3185 .TP
3186 .ESC O0
3187 Disable glyph output.
3188 .
3189 Mainly for internal use.
3190 .
3191 .TP
3192 .ESC O1
3193 Enable glyph output.
3194 .
3195 Mainly for internal use.
3196 .
3197 .TP
3198 .ESC p
3199 Break and spread output line.
3200 .
3201 .TP
3202 .ESC r
3203 Reverse 1\ em vertical motion (reverse line in nroff).
3204 .
3205 .TP
3206 .ESCq R "name\~\[+-]n"
3207 The same as
3208 .request .nr
3209 .I name
3210 .IR \[+-]n .
3211 .
3212 .TP
3213 .ESC s \[+-]N
3214 Set/increase/decrease the point size to/by
3215 .I N
3216 scaled points;
3217 .I N
3218 is a one-digit number in the range 1 to\~9.
3219 .
3220 Same as
3221 .request ps
3222 request.
3223 .
3224 .TP
3225 .ESC s( \[+-]N
3226 .TQ
3227 .ESC s\[+-]( N
3228 Set/increase/decrease the point size to/by
3229 .I N
3230 scaled points;
3231 .I N
3232 is a two-digit number \[>=]1.
3233 .
3234 Same as
3235 .request ps
3236 request.
3237 .
3238 .TP
3239 .ESC[] s \[+-]N
3240 .TQ
3241 .ESC[] s\[+-] N
3242 .TQ
3243 .ESCq s \[+-]N
3244 .TQ
3245 .ESCq s\[+-] N
3246 Set/increase/decrease the point size to/by
3247 .I N
3248 scaled points.
3249 .
3250 Same as
3251 .request ps
3252 request.
3253 .
3254 .TP
3255 .ESCq S N
3256 Slant output by
3257 .I N
3258 degrees.
3259 .
3260 .TP
3261 .ESC t
3262 Non-interpreted horizontal tab.
3263 .
3264 .TP
3265 .ESC u
3266 Reverse (up) 1/2 em vertical motion (1/2 line in nroff).
3267 .
3268 .TP
3269 .ESCq v N
3270 Local vertical motion; move down
3271 .I N
3272 (up if negative).
3273 .
3274 .TP
3275 .ESC V e
3276 The contents of the environment variable with one-character
3277 name\~\c
3278 .IR e .
3279 .
3280 .TP
3281 .ESC V( ev
3282 The contents of the environment variable with two-character name
3283 .IR ev .
3284 .
3285 .TP
3286 .ESC[] V env
3287 The contents of the environment variable with arbitrarily long name
3288 .IR env .
3289 .
3290 .TP
3291 .ESCq w string
3292 The width of the glyph sequence
3293 .IR string .
3294 .
3295 .TP
3296 .ESCq x N
3297 Extra line-space function (negative before, positive after).
3298 .
3299 .TP
3300 .ESCq X string
3301 Output
3302 .I string
3303 as device control function.
3304 .
3305 .TP
3306 .ESC Y n
3307 Output string variable or macro with one-character name\~\c
3308 .I n
3309 uninterpreted as device control function.
3310 .
3311 .TP
3312 .ESC Y( nm
3313 Output string variable or macro with two-character name
3314 .I nm
3315 uninterpreted as device control function.
3316 .
3317 .TP
3318 .ESC[] Y name
3319 Output string variable or macro with arbitrarily long name
3320 .I name
3321 uninterpreted as device control function.
3322 .
3323 .TP
3324 .ESC z c
3325 Print
3326 .I c
3327 with zero width (without spacing).
3328 .
3329 .TP
3330 .ESCq Z anything
3331 Print
3332 .I anything
3333 and then restore the horizontal and vertical position;
3334 .I anything
3335 may not contain tabs or leaders.
3336 .
3337 .
3338 .PD
3339 .P
3340 The escape sequences
3341 .esc e ,
3342 .esc . ,
3343 .esc \[dq] ,
3344 .esc $ ,
3345 .esc * ,
3346 .esc a ,
3347 .esc n ,
3348 .esc t ,
3349 .esc g ,
3350 and
3351 .escarg \& newline
3352 are interpreted in copy mode.
3353 .
3354 .
3355 .P
3356 Escape sequences starting with
3357 .esc (
3358 or
3359 .esc [
3360 do not represent single character escape sequences, but introduce escape
3361 names with two or more characters.
3362 .
3363 .
3364 .P
3365 If a backslash is followed by a character that does not constitute a
3366 defined escape sequence, the backslash is silently ignored and the
3367 character maps to itself.
3368 .
3369 .
3370 .\" --------------------------------------------------------------------
3371 .SS "Special Characters"
3372 .\" --------------------------------------------------------------------
3373 .
3374 [Note: \[oq]Special Characters\[cq] is a misnomer; those entities are
3375 (output) glyphs, not (input) characters.]
3376 .
3377 .
3378 .P
3379 Common special characters are predefined by escape sequences of the
3380 form
3381 .BI \e( xy
3382 with characters
3383 .I x
3384 and
3385 .IR y .
3386 .
3387 In
3388 .IR groff ,
3389 it is also possible to use the writing
3390 .BI \e[ xy ]
3391 as well.
3392 .
3393 .
3394 .P
3395 Some of these special characters exist in the usual font while most of
3396 them are only available in the special font.
3397 .
3398 Below you can see a small selection of the most important glyphs; a
3399 complete list can be found in
3400 .BR groff_char (@MAN7EXT@).
3401 .RS
3402 .P
3403 .PD 0
3404 .
3405 .TP
3406 .ESC (Do
3407 Dollar
3408 .B \(Do
3409 .
3410 .TP
3411 .ESC (Eu
3412 Euro
3413 .B \(Eu
3414 .
3415 .TP
3416 .ESC (Po
3417 British pound sterling
3418 .B \(Po
3419 .
3420 .TP
3421 .ESC (aq
3422 Apostrophe quote
3423 .B \(aq
3424 .
3425 .TP
3426 .ESC (bu
3427 Bullet sign
3428 .B \(bu
3429 .
3430 .TP
3431 .ESC (co
3432 Copyright
3433 .B \(co
3434 .
3435 .TP
3436 .ESC (cq
3437 Single closing quote (right)
3438 .B \(cq
3439 .TP
3440 .ESC (ct
3441 Cent
3442 .B \(ct
3443 .
3444 .TP
3445 .ESC (dd
3446 Double dagger
3447 .B  \(dd
3448 .
3449 .TP
3450 .ESC (de
3451 Degree
3452 .B \(de
3453 .
3454 .TP
3455 .ESC (dg
3456 Dagger
3457 .B \(dg
3458 .
3459 .TP
3460 .ESC (dq
3461 Double quote (ASCII 34)
3462 .B \(dq
3463 .
3464 .TP
3465 .ESC (em
3466 Em-dash
3467 .B \(em
3468 .
3469 .TP
3470 .ESC (en
3471 En-dash
3472 .B \(en
3473 .
3474 .TP
3475 .ESC (hy
3476 Hyphen
3477 .B \(hy
3478 .
3479 .TP
3480 .ESC (lq
3481 Double quote left
3482 .B \(lq
3483 .
3484 .TP
3485 .ESC (oq
3486 Single opening quote (left)
3487 .B \(oq
3488 .
3489 .TP
3490 .ESC (rg
3491 Registered sign
3492 .B \(rg
3493 .
3494 .TP
3495 .ESC (rq
3496 Double quote right
3497 .B \(rq
3498 .
3499 .TP
3500 .ESC (rs
3501 Printable backslash character
3502 .B \(rs
3503 .
3504 .TP
3505 .ESC (sc
3506 Section sign
3507 .B \(sc
3508 .
3509 .TP
3510 .ESC (tm
3511 Trademark symbol
3512 .B  \(tm
3513 .
3514 .TP
3515 .ESC (ul
3516 Underline character
3517 .B  \(ul
3518 .
3519 .TP
3520 .ESC (==
3521 Identical
3522 .B \(==
3523 .
3524 .TP
3525 .ESC (>=
3526 Larger or equal
3527 .B \(>=
3528 .
3529 .TP
3530 .ESC (<=
3531 Less or equal
3532 .B \(<=
3533 .
3534 .TP
3535 .ESC (!=
3536 Not equal
3537 .B \(!=
3538 .
3539 .TP
3540 .ESC (->
3541 Right arrow
3542 .B \(->
3543 .
3544 .TP
3545 .ESC (<-
3546 Left arrow
3547 .B \(<-
3548 .
3549 .TP
3550 .ESC (+-
3551 Plus-minus sign
3552 .B \(+-
3553 .
3554 .PD
3555 .RE
3556 .
3557 .
3558 .\" --------------------------------------------------------------------
3559 .SS "Unicode Characters"
3560 .\" --------------------------------------------------------------------
3561 .
3562 There is the extended escape
3563 .B u
3564 that allows to include all available Unicode characters into some
3565 .I roff
3566 file.
3567 .
3568 .
3569 .TP
3570 .BI \e[u xxxx ]
3571 .B u
3572 is the escape name.
3573 .
3574 .I xxxx
3575 is a hexadecimal number of 4 hex digits, such as
3576 .B 0041
3577 for the letter
3578 .BR A ,
3579 see
3580 .BR \e[u0041] .
3581 .
3582 .
3583 .TP
3584 .BI \e[u yyyyy ]
3585 .B u
3586 is the escape name.
3587 .
3588 .I yyyyy
3589 is a hexadecimal number of 5 hex digits, such as
3590 .B 2FA1A
3591 for a Chinese looking character for
3592 .IR "CJK Compatibility Ideographs Supplement" ,
3593 see
3594 .BR \e[u2FA1A] .
3595 .
3596 .
3597 .P
3598 Both hexadecimal collections mean the corresponding Unicode code for a
3599 character.
3600 .
3601 .
3602 .TP
3603 .BI \e[u hex1 _ hex2 ]
3604 .TQ
3605 .BI \e[u hex1 _ hex2 _ hex3 ]
3606 .IR hex1 ,
3607 .IR hex2 ,
3608 and
3609 .I hex3
3610 are all Unicode hexadecimal codes (4 or 5 hex digits) that are used
3611 for overstriking, e.g.
3612 .B \e[u0041_0301]
3613 is
3614 .I "A acute"
3615 .BR \['A] .
3616 .
3617 .
3618 .P
3619 The availability of the Unicode characters depends on the used font.
3620 .
3621 For text mode, the device
3622 .B -Tutf8
3623 is quite complete, for
3624 .I troff
3625 modes it might happen that some or many characters will not be
3626 displayed.
3627 .
3628 Please check your fonts.
3629 .
3630 .
3631 .\" --------------------------------------------------------------------
3632 .SS "Strings"
3633 .\" --------------------------------------------------------------------
3634 .
3635 Strings are defined by the
3636 .request ds
3637 request and can be retrieved by the
3638 .esc *
3639 escape sequence.
3640 .
3641 .
3642 .P
3643 Strings share their name space with macros.
3644 .
3645 So strings and macros without arguments are roughly equivalent; it is
3646 possible to call a string like a macro and vice-versa, but this often
3647 leads to unpredictable results.
3648 .
3649 The following string is the only one predefined in groff.
3650 .
3651 .TPx
3652 .STRING .T
3653 The name of the current output device as specified by the
3654 .option \-T
3655 command line option.
3656 .
3657 .
3658 .\" --------------------------------------------------------------------
3659 .SH REGISTERS
3660 .\" --------------------------------------------------------------------
3661 .
3662 Registers are variables that store a value.
3663 In groff, most registers store numerical values (see section
3664 .B NUMERICAL EXPRESSIONS
3665 above), but some can also hold a string value.
3666 .
3667 .
3668 .P
3669 Each register is given a name.
3670 Arbitrary registers can be defined and set with the
3671 .request nr
3672 request.
3673 .
3674 .
3675 .P
3676 The value stored in a register can be retrieved by the escape sequences
3677 introduced by
3678 .esc n .
3679 .
3680 .
3681 .P
3682 Most useful are predefined registers.
3683 .
3684 In the following the notation
3685 .I name
3686 is used to refer to
3687 .register name
3688 to make clear that we speak about registers.
3689 .
3690 Please keep in mind that the
3691 .esc[] n ""
3692 decoration is not part of the register name.
3693 .
3694 .
3695 .\" --------------------------------------------------------------------
3696 .SS "Read-only Registers"
3697 .\" --------------------------------------------------------------------
3698 .
3699 The following registers have predefined values that should not be
3700 modified by the user (usually, registers starting with a dot are
3701 read-only).
3702 .
3703 Mostly, they provide information on the current settings or store
3704 results from request calls.
3705 .
3706 .
3707 .P
3708 .PD 0
3709 .
3710 .TPx
3711 .REG $$
3712 The process ID of
3713 .BR troff .
3714 .
3715 .TPx
3716 .REG .$
3717 Number of arguments in the current macro or string.
3718 .
3719 .TPx
3720 .REG .a
3721 Post-line extra line-space most recently utilized using
3722 .esc x .
3723 .
3724 .TPx
3725 .REG .A
3726 Set to\~1 in
3727 .B troff
3728 if option
3729 .option \-A
3730 is used; always\~1 in
3731 .BR nroff .
3732 .
3733 .TPx
3734 .REG .b
3735 The emboldening offset while
3736 .request .bd
3737 is active.
3738 .
3739 .TPx
3740 .REG .br
3741 Within a macro, set to\~1 if macro called with the \[oq]normal\[cq]
3742 control character, and to\~0 otherwise.
3743 .
3744 .TPx
3745 .REG .c
3746 Current input line number.
3747 .
3748 .TPx
3749 .REG .C
3750 1\~if compatibility mode is in effect, 0\~otherwise.
3751 .
3752 .TPx
3753 .REG .cdp
3754 The depth of the last glyph added to the current environment.
3755 .
3756 It is positive if the glyph extends below the baseline.
3757 .
3758 .TPx
3759 .REG .ce
3760 The number of lines remaining to be centered, as set by the
3761 .request ce
3762 request.
3763 .
3764 .TPx
3765 .REG .cht
3766 The height of the last glyph added to the current environment.
3767 .
3768 It is positive if the glyph extends above the baseline.
3769 .
3770 .TPx
3771 .REG .color
3772 1\~if colors are enabled, 0\~otherwise.
3773 .
3774 .TPx
3775 .REG .csk
3776 The skew of the last glyph added to the current environment.
3777 .
3778 The skew of a glyph is how far to the right of the center of a glyph
3779 the center of an accent over that glyph should be placed.
3780 .
3781 .TPx
3782 .REG .d
3783 Current vertical place in current diversion; equal to
3784 .register nl .
3785 .
3786 .TPx
3787 .REG .ev
3788 The name or number of the current environment (string-valued).
3789 .
3790 .TPx
3791 .REG .f
3792 Current font number.
3793 .
3794 .TPx
3795 .REG .F
3796 The name of the current input file (string-valued).
3797 .
3798 .TPx
3799 .REG .fam
3800 The current font family (string-valued).
3801 .
3802 .TPx
3803 .REG .fn
3804 The current (internal) real font name (string-valued).
3805 .
3806 .TPx
3807 .REG .fp
3808 The number of the next free font position.
3809 .
3810 .TPx
3811 .REG .g
3812 Always 1 in GNU troff.
3813 .
3814 Macros should use it to test if running under groff.
3815 .
3816 .TPx
3817 .REG .h
3818 Text base-line high-water mark on current page or diversion.
3819 .
3820 .TPx
3821 .REG .H
3822 Available horizontal resolution in basic units.
3823 .
3824 .TPx
3825 .REG .height
3826 The current font height as set with
3827 .request \[rs]H .
3828 .
3829 .TPx
3830 .REG .hla
3831 The current hyphenation language as set by the
3832 .request hla
3833 request.
3834 .
3835 .TPx
3836 .REG .hlc
3837 The number of immediately preceding consecutive hyphenated lines.
3838 .
3839 .TPx
3840 .REG .hlm
3841 The maximum allowed number of consecutive hyphenated lines, as set by
3842 the
3843 .request hlm
3844 request.
3845 .
3846 .TPx
3847 .REG .hy
3848 The current hyphenation flags (as set by the
3849 .request hy
3850 request).
3851 .
3852 .TPx
3853 .REG .hym
3854 The current hyphenation margin (as set by the
3855 .request hym
3856 request).
3857 .
3858 .TPx
3859 .REG .hys
3860 The current hyphenation space (as set by the
3861 .request hys
3862 request).
3863 .
3864 .TPx
3865 .REG .i
3866 Current indentation.
3867 .
3868 .TPx
3869 .REG .in
3870 The indentation that applies to the current output line.
3871 .
3872 .TPx
3873 .REG .int
3874 Positive if last output line contains
3875 .esc c .
3876 .
3877 .TPx
3878 .REG .j
3879 The current adjustment mode.
3880 It can be stored and used to set adjustment.
3881 (n\ =\ 1, b\ =\ 1, l\ =\ 0, r\ =\ 5, c\ =\ 3).
3882 .
3883 .TPx
3884 .REG .k
3885 The current horizontal output position (relative to the current indentation).
3886 .TPx
3887 .REG .kern
3888 1\~if pairwise kerning is enabled, 0\~otherwise.
3889 .
3890 .TPx
3891 .REG .l
3892 Current line length.
3893 .
3894 .TPx
3895 .REG .L
3896 The current line spacing setting as set by
3897 .request .ls .
3898 .
3899 .TPx
3900 .REG .lg
3901 The current ligature mode (as set by the
3902 .request lg
3903 request).
3904 .
3905 .TPx
3906 .REG .linetabs
3907 The current line-tabs mode (as set by the
3908 .request linetabs
3909 request).
3910 .
3911 .TPx
3912 .REG .ll
3913 The line length that applies to the current output line.
3914 .
3915 .TPx
3916 .REG .lt
3917 The title length (as set by the
3918 .request lt
3919 request).
3920 .
3921 .TPx
3922 .REG .m
3923 The current drawing color (string-valued).
3924 .
3925 .TPx
3926 .REG .M
3927 The current background color (string-valued).
3928 .
3929 .TPx
3930 .REG .n
3931 Length of text portion on previous output line.
3932 .
3933 .TPx
3934 .REG .ne
3935 The amount of space that was needed in the last
3936 .request ne
3937 request that caused a trap to be sprung.
3938 .
3939 Useful in conjunction with
3940 .register .trunc .
3941 .
3942 .TPx
3943 .REG .ns
3944 1\~if in no-space mode, 0\~otherwise.
3945 .
3946 .TPx
3947 .REG .o
3948 Current page offset.
3949 .
3950 .TPx
3951 .REG .O
3952 The suppression nesting level (see
3953 .esc O ).
3954 .
3955 .TPx
3956 .REG .p
3957 Current page length.
3958 .
3959 .TPx
3960 .REG .P
3961 1\~if the current page is being printed, 0\~otherwise (as determined by the
3962 .option \-o
3963 command line option).
3964 .
3965 .TPx
3966 .REG .pe
3967 1\~during page ejection, 0\~otherwise.
3968 .
3969 .TPx
3970 .REG .pn
3971 The number of the next page: either the value set by a
3972 .request pn
3973 request, or the number of the current page plus\ 1.
3974 .
3975 .TPx
3976 .REG .ps
3977 The current point size in scaled points.
3978 .
3979 .TPx
3980 .REG .psr
3981 The last-requested point size in scaled points.
3982 .
3983 .TPx
3984 .REG .pvs
3985 The current post-vertical line spacing.
3986 .
3987 .TPx
3988 .REG .R
3989 The number of unused number registers.
3990 Always 10000 in GNU troff.
3991 .
3992 .TPx
3993 .REG .rj
3994 The number of lines to be right-justified as set by the
3995 .request rj
3996 request.
3997 .
3998 .TPx
3999 .REG .s
4000 Current point size as a decimal fraction.
4001 .
4002 .TPx
4003 .REG .slant
4004 The slant of the current font as set with
4005 .request \eS .
4006 .
4007 .TPx
4008 .REG .sr
4009 The last requested point size in points as a decimal fraction
4010 (string-valued).
4011 .
4012 .TPx
4013 .REG .ss
4014 The value of the parameters set by the first argument of the
4015 .request ss
4016 request.
4017 .
4018 .TPx
4019 .REG .sss
4020 The value of the parameters set by the second argument of the
4021 .request ss
4022 request.
4023 .
4024 .TPx
4025 .REG .sty
4026 The current font style (string-valued).
4027 .
4028 .TPx
4029 .REG .t
4030 Vertical distance to the next trap.
4031 .
4032 .TPx
4033 .REG .T
4034 Set to\~1
4035 if option
4036 .option \-T
4037 is used.
4038 .
4039 .TPx
4040 .REG .tabs
4041 A string representation of the current tab settings suitable for use
4042 as an argument to the
4043 .request ta
4044 request.
4045 .
4046 .TPx
4047 .REG .trunc
4048 The amount of vertical space truncated by the most recently sprung
4049 vertical position trap, or, if the trap was sprung by a
4050 .request ne
4051 request, minus the amount of vertical motion produced by
4052 .request .ne .
4053 .
4054 Useful in conjunction with the
4055 .register .ne .
4056 .
4057 .TPx
4058 .REG .u
4059 Equal to 1 in fill mode and 0 in no-fill mode.
4060 .
4061 .TPx
4062 .REG .U
4063 Equal to 1 in safer mode and 0 in unsafe mode.
4064 .
4065 .TPx
4066 .REG .v
4067 Current vertical line spacing.
4068 .
4069 .TPx
4070 .REG .V
4071 Available vertical resolution in basic units.
4072 .
4073 .TPx
4074 .REG .vpt
4075 1\~if vertical position traps are enabled, 0\~otherwise.
4076 .
4077 .TPx
4078 .REG .w
4079 Width of previous glyph.
4080 .
4081 .TPx
4082 .REG .warn
4083 The sum of the number codes of the currently enabled warnings.
4084 .
4085 .TPx
4086 .REG .x
4087 The major version number.
4088 .
4089 .TPx
4090 .REG .y
4091 The minor version number.
4092 .
4093 .TPx
4094 .REG .Y
4095 The revision number of groff.
4096 .
4097 .TPx
4098 .REG .z
4099 Name of current diversion.
4100 .
4101 .TPx
4102 .REG .zoom
4103 Zoom factor for current font (in multiples of 1/1000th; zero if no
4104 magnification).
4105 .PD
4106 .
4107 .
4108 .\" --------------------------------------------------------------------
4109 .SS "Writable Registers"
4110 .\" --------------------------------------------------------------------
4111 .
4112 The following registers can be read and written by the user.
4113 They have predefined default values, but these can be modified for
4114 customizing a document.
4115 .
4116 .
4117 .P
4118 .PD 0
4119 .TPx
4120 .REG %
4121 Current page number.
4122 .
4123 .TPx
4124 .REG c.
4125 Current input line number.
4126 .
4127 .TPx
4128 .REG ct
4129 Character type (set by width function
4130 .esc w ).
4131 .
4132 .TPx
4133 .REG dl
4134 Maximal width of last completed diversion.
4135 .
4136 .TPx
4137 .REG dn
4138 Height of last completed diversion.
4139 .
4140 .TPx
4141 .REG dw
4142 Current day of week (1\(en7).
4143 .
4144 .TPx
4145 .REG dy
4146 Current day of month (1\(en31).
4147 .
4148 .TPx
4149 .REG hours
4150 The number of hours past midnight.
4151 .
4152 Initialized at start-up.
4153 .
4154 .TPx
4155 .REG hp
4156 Current horizontal position at input line.
4157 .
4158 .TPx
4159 .REG llx
4160 Lower left x-coordinate (in PostScript units) of a given PostScript
4161 image (set by
4162 .request .psbb ).
4163 .
4164 .TPx
4165 .REG lly
4166 Lower left y-coordinate (in PostScript units) of a given PostScript
4167 image (set by
4168 .request .psbb ).
4169 .
4170 .TPx
4171 .REG ln
4172 Output line number.
4173 .
4174 .TPx
4175 .REG lsn
4176 The number of leading spaces of an input line.
4177 .
4178 .TPx
4179 .REG lss
4180 The horizontal space corresponding to the leading spaces of an input
4181 line.
4182 .
4183 .TPx
4184 .REG minutes
4185 The number of minutes after the hour.
4186 .
4187 Initialized at start-up.
4188 .
4189 .TPx
4190 .REG mo
4191 Current month (1\(en12).
4192 .
4193 .TPx
4194 .REG nl
4195 Vertical position of last printed text base-line.
4196 .
4197 .TPx
4198 .REG opmaxx
4199 .TPx
4200 .REG opmaxy
4201 .TPx
4202 .REG opminx
4203 .TPx
4204 .REG opminy
4205 These four registers mark the top left and bottom right hand corners of a box
4206 which encompasses all written glyphs.
4207 They are reset to \-1 by
4208 .escarg O 0
4209 or
4210 .escarg O 1 .
4211 .
4212 .TPx
4213 .REG rsb
4214 Like
4215 .register sb ,
4216 but takes account of the heights and depths of glyphs.
4217 .
4218 .TPx
4219 .REG rst
4220 Like
4221 .register st ,
4222 but takes account of the heights and depths of glyphs.
4223 .
4224 .TPx
4225 .REG sb
4226 Depth of string below base line (generated by width function
4227 .esc w ).
4228 .
4229 .TPx
4230 .REG seconds
4231 The number of seconds after the minute.
4232 .
4233 Initialized at start-up.
4234 .
4235 .TPx
4236 .REG skw
4237 Right skip width from the center of the last glyph in the
4238 .esc w
4239 argument.
4240 .
4241 .TPx
4242 .REG slimit
4243 If greater than 0, the maximum number of objects on the input stack.
4244 .
4245 If \[<=]0 there is no limit, i.e., recursion can continue until virtual
4246 memory is exhausted.
4247 .
4248 .TPx
4249 .REG ssc
4250 The amount of horizontal space (possibly negative) that should be
4251 added to the last glyph before a subscript (generated by width
4252 function
4253 .esc w ).
4254 .
4255 .TPx
4256 .REG st
4257 Height of string above base line (generated by width function
4258 .esc w ).
4259 .
4260 .TPx
4261 .REG systat
4262 The return value of the
4263 .I system()
4264 function executed by the last
4265 .request sy
4266 request.
4267 .
4268 .TPx
4269 .REG urx
4270 Upper right x-coordinate (in PostScript units) of a given PostScript
4271 image (set by
4272 .request .psbb ).
4273 .
4274 .TPx
4275 .REG ury
4276 Upper right y-coordinate (in PostScript units) of a given PostScript
4277 image (set by
4278 .request .psbb ).
4279 .
4280 .TPx
4281 .REG year
4282 The current year (year 2000 compliant).
4283 .
4284 .TPx
4285 .REG yr
4286 Current year minus 1900.
4287 .
4288 For Y2K compliance use
4289 .register year
4290 instead.
4291 .
4292 .PD
4293 .
4294 .
4295 .\" --------------------------------------------------------------------
4296 .SH UNDERLINING
4297 .\" --------------------------------------------------------------------
4298 .
4299 In the
4300 .I RUNOFF
4301 language, the underlining was quite easy.
4302 .
4303 But in
4304 .I roff
4305 this is much more difficult.
4306 .
4307 .
4308 .\" --------------------------------------------------------------------
4309 .SS Underlining with .ul
4310 .\" --------------------------------------------------------------------
4311 .
4312 There exists a
4313 .I groff
4314 request
4315 .B .ul
4316 (see above) that can underline the next or further source lines in
4317 .BR nroff ,
4318 but in
4319 .B troff
4320 it produces only a font change into
4321 .IR italic .
4322 .
4323 So this request is not really useful.
4324 .
4325 .
4326 .\" --------------------------------------------------------------------
4327 .SS Underlining with .UL from ms
4328 .\" --------------------------------------------------------------------
4329 .
4330 In the \[oq]ms\[cq] macro package in tmac/s.tmac
4331 .BR groff_ms (@MAN7EXT@),
4332 there is the macro
4333 .BR .UL .
4334 .
4335 But this works only in
4336 .BR troff ,
4337 not in
4338 .BR nroff .
4339 .
4340 .
4341 .\" --------------------------------------------------------------------
4342 .SS Underlining macro definitions
4343 .\" --------------------------------------------------------------------
4344 .
4345 So one can use the
4346 .I italic
4347 .B nroff
4348 idea from
4349 .B .ul
4350 and the
4351 .B troff
4352 definition
4353 in
4354 .I ms
4355 for writing a useful new macro, something like
4356 .
4357 .RS
4358 .EX
4359 \&.de UNDERLINE
4360 \&. ie n \[rs]\[rs]$1\[rs]f[I]\[rs]\[rs]$2\[rs]f[P]\[rs]\[rs]$3
4361 \&. el \[rs]\[rs]$1\[rs]Z\[aq]\[rs]\[rs]$2\[aq]\[rs]v\[aq].25m\[aq]\
4362 \[rs]D\[aq]l \[rs]w\[aq]\[rs]\[rs]$2\[aq]u 0\[aq]\[rs]v\[aq]-.25m\
4363 \[aq]\\[rs]\[rs]$3
4364 \&..
4365 .EE
4366 .RE
4367 .
4368 If
4369 .B doclifter (1)
4370 makes trouble, change the macro name
4371 .B UNDERLINE
4372 into some 2-letter word, like
4373 .BR Ul .
4374 .
4375 Moreover change the font writing from
4376 .B \[rs]f[P]
4377 to
4378 .BR \[rs]fP .
4379 .
4380 .
4381 .\" --------------------------------------------------------------------
4382 .SS Underlining without macro definitions
4383 .\" --------------------------------------------------------------------
4384 .
4385 If one does not want to use macro definitions, e.g. when
4386 .B doclifter
4387 gets lost, use the following:
4388 .
4389 .RS
4390 .EX
4391 \&.ds u1 before
4392 \&.ds u2 in
4393 \&.ds u3 after
4394 \&.ie n \[rs]*[u1]\[rs]f[I]\[rs]*[u2]\[rs]f[P]\[rs]*[u3]
4395 \&.el \[rs]*[u1]\[rs]Z\[aq]\[rs]*[u2]\[aq]\[rs]v\[aq].25m\[aq]\[rs]D\
4396 \[aq]l \[rs]w\[aq]\[rs]*[u2]\[aq]u 0\[aq]\[rs]v\[aq]-.25m\[aq]\[rs]*[u3]
4397 .EE
4398 .RE
4399 .
4400 Due to
4401 .BR doclifter ,
4402 it might be necessary to change the variable writing
4403 .B \e[xy]
4404 and
4405 .B \e*[xy]
4406 into the strange ancient writing
4407 .B \e*(xy
4408 and
4409 .BR \e(xy ,
4410 and so on.
4411 .
4412 .
4413 .P
4414 Then these lines could look like
4415 .RS
4416 .EX
4417 \&.ds u1 before
4418 \&.ds u2 in
4419 \&.ds u3 after
4420 \&.ie n \[rs]*[u1]\[rs]fI\[rs]*(u2\[rs]fP\[rs]*(u3
4421 \&.el \[rs]*(u1\[rs]Z\[aq]\[rs]*(u2\[aq]\[rs]v\[aq].25m'\[rs]D\[aq]l \
4422 \[rs]w\[aq]\[rs]*(u2\[aq]u 0\[aq]\[rs]v\[aq]-.25m\[aq]\[rs]*(u3
4423 .EE
4424 .RE
4425 .
4426 .
4427 .P
4428 The result looks like
4429 .RS
4430 .ft CR
4431 before
4432 \z\[ul]i\
4433 \z\[ul]n
4434 after
4435 .ft R
4436 .RE
4437 .
4438 .
4439 .\" --------------------------------------------------------------------
4440 .SS Underlining with Overstriking \ez and \e(ul
4441 .\" --------------------------------------------------------------------
4442 .
4443 There is another possibility for underlining by using overstriking
4444 with
4445 .BI \ez c
4446 (print
4447 .I c
4448 with zero width without spacing) and
4449 .B \e(ul
4450 (underline character).
4451 .
4452 This produces the underlining of 1 character, both in
4453 .B nroff
4454 and in
4455 .BR troff .
4456 .
4457 .
4458 .P
4459 For example the underlining of a character say
4460 .B t
4461 looks like
4462 .B \ez\e[ul]t
4463 or
4464 .B \ez\e(ult
4465 .
4466 .
4467 .P
4468 Longer words look then a bit strange, but a useful mode is to write
4469 each character into a whole own line.
4470 .
4471 To underlines the 3 character part "tar" of the word "start":
4472 .
4473 .RS
4474 .EX
4475 .br
4476 before s\[rs]
4477 \[rs]z\[rs][ul]t\[rs]
4478 \[rs]z\[rs][ul]a\[rs]
4479 \[rs]z\[rs][ul]r\[rs]
4480 t after
4481 .EE
4482 .RE
4483 .
4484 or
4485 .
4486 .RS
4487 .EX
4488 .br
4489 before s\[rs]
4490 \[rs]z\[rs](ult\[rs]
4491 \[rs]z\[rs](ula\[rs]
4492 \[rs]z\[rs](ulr\[rs]
4493 t after
4494 .EE
4495 .RE
4496 .
4497 .
4498 .P
4499 The result looks like
4500 .RS
4501 .ft CR
4502 before s\
4503 \z\[ul]t\
4504 \z\[ul]a\
4505 \z\[ul]r\
4506 t after
4507 .ft R
4508 .RE
4509 .
4510 .\" --------------------------------------------------------------------
4511 .SH COMPATIBILITY
4512 .\" --------------------------------------------------------------------
4513 .
4514 The differences of the groff language in comparison to classical troff
4515 as defined by
4516 .I [CSTR\~#54]
4517 are documented in
4518 .BR groff_diff (@MAN7EXT@).
4519 .
4520 .
4521 .P
4522 The groff system provides a compatibility mode, see
4523 .BR groff (@MAN1EXT@)
4524 on how to invoke this.
4525 .
4526 .
4527 .\" --------------------------------------------------------------------
4528 .SH BUGS
4529 .\" --------------------------------------------------------------------
4530 .
4531 Report bugs to the
4532 .MT bug-groff@gnu.org
4533 groff bug mailing list
4534 .ME .
4535 Include a complete, self-contained example that will allow the bug to
4536 be reproduced, and say which version of groff you are using.
4537 .
4538 .
4539 .\" --------------------------------------------------------------------
4540 .SH "SEE ALSO"
4541 .\" --------------------------------------------------------------------
4542 .
4543 The main source of information for the groff language is the
4544 .B groff
4545 .BR info (1)
4546 file.
4547 .
4548 Besides the gory details, it contains many examples.
4549 .
4550 .TP
4551 .BR groff (@MAN1EXT@)
4552 the usage of the groff program and pointers to the documentation and
4553 availability of the groff system.
4554 .
4555 .TP
4556 .BR groff_diff (@MAN7EXT@)
4557 the differences of the groff language as compared to classical roff.
4558 .
4559 This is the authoritative document for the predefined language
4560 elements that are specific to groff.
4561 .
4562 .TP
4563 .BR groff_char (@MAN7EXT@)
4564 the predefined groff special characters (glyphs).
4565 .
4566 .TP
4567 .BR groff_font (@MAN5EXT@)
4568 the specification of fonts and the DESC file.
4569 .
4570 .TP
4571 .BR roff (@MAN7EXT@)
4572 the history of roff, the common parts shared by all roff systems, and
4573 pointers to further documentation.
4574 .
4575 .TP
4576 .I [CSTR\~#54]
4577 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:54.ps.gz
4578 Nroff/\:Troff User\[aq]s Manual by Ossanna & Kernighan
4579 .UE
4580 \[em] the bible for classical troff.
4581 .
4582 .
4583 .\" --------------------------------------------------------------------
4584 .SH COPYING
4585 .\" --------------------------------------------------------------------
4586 .co
4587 .\" --------------------------------------------------------------------
4588 .SH AUTHORS
4589 .\" --------------------------------------------------------------------
4590 .au
4591 .
4592 .cp \n[groff_C]
4593 .
4594 .
4595 .\" --------------------------------------------------------------------
4596 .\" Emacs Setup
4597 .\" --------------------------------------------------------------------
4598 .
4599 .\" Local Variables:
4600 .\" mode: nroff
4601 .\" End: