man/groff.7.man

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