contrib/groff/doc/groff-4

   1 This is groff, produced by makeinfo version 4.2 from ./groff.texinfo.
   2
   3 This manual documents GNU `troff' version 1.18.
   4
   5    Copyright (C) 1994-2000, 2001, 2002 Free Software Foundation, Inc.
   6
   7      Permission is granted to copy, distribute and/or modify this
   8      document under the terms of the GNU Free Documentation License,
   9      Version 1.1 or any later version published by the Free Software
  10      Foundation; with no Invariant Sections, with the Front-Cover texts
  11      being `A GNU Manual," and with the Back-Cover Texts as in (a)
  12      below.  A copy of the license is included in the section entitled
  13      `GNU Free Documentation License."
  14
  15      (a) The FSF's Back-Cover Text is: `You have freedom to copy and
  16      modify this GNU Manual, like GNU software.  Copies published by
  17      the Free Software Foundation raise funds for GNU development."
  18
  19 INFO-DIR-SECTION Miscellaneous
  20 START-INFO-DIR-ENTRY
  21 * Groff: (groff).               The GNU troff document formatting system.
  22 END-INFO-DIR-ENTRY
  23
  24 \1f
  25 File: groff,  Node: Manipulating Hyphenation,  Next: Manipulating Spacing,  Prev: Manipulating Filling and Adjusting,  Up: gtroff Reference
  26
  27 Manipulating Hyphenation
  28 ========================
  29
  30    As discussed in *Note Hyphenation::, `gtroff' hyphenates words.
  31 There are a number of ways to influence hyphenation.
  32
  33  - Request: .hy [mode]
  34  - Register: \n[.hy]
  35      Enable hyphenation.  The request has an optional numeric argument,
  36      MODE, to restrict hyphenation if necessary:
  37
  38     `1'
  39           The default argument if MODE is omitted.  Hyphenate without
  40           restrictions.  This is also the start-up value of `gtroff'.
  41
  42     `2'
  43           Do not hyphenate the last word on a page or column.
  44
  45     `4'
  46           Do not hyphenate the last two characters of a word.
  47
  48     `8'
  49           Do not hyphenate the first two characters of a word.
  50
  51      Values in the previous table are additive.  For example, the
  52      value 12 causes `gtroff' to neither hyphenate the last two nor the
  53      first two characters of a word.
  54
  55      The current hyphenation restrictions can be found in the read-only
  56      number register `.hy'.
  57
  58      The hyphenation mode is associated with the current environment
  59      (*note Environments::).
  60
  61  - Request: .nh
  62      Disable hyphenation (i.e., set the hyphenation mode to zero).  Note
  63      that the hyphenation mode of the last call to `hy' is not
  64      remembered.
  65
  66      The hyphenation mode is associated with the current environment
  67      (*note Environments::).
  68
  69  - Request: .hlm [nnn]
  70  - Register: \n[.hlm]
  71  - Register: \n[.hlc]
  72      Set the maximum number of consecutive hyphenated lines to NNN.  If
  73      this number is negative, there is no maximum.  The default value
  74      is -1 if NNN is omitted.  This value is associated with the
  75      current environment (*note Environments::).  Only lines output
  76      from a given environment count towards the maximum associated with
  77      that environment.  Hyphens resulting from `\%' are counted;
  78      explicit hyphens are not.
  79
  80      The current setting of `hlm' is available in the `.hlm' read-only
  81      number register.  Also the number of immediately preceding
  82      consecutive hyphenated lines are available in the read-only number
  83      register `.hlc'.
  84
  85  - Request: .hw word1 word2 ...
  86      Define how WORD1, WORD2, etc. are to be hyphenated.  The words
  87      must be given with hyphens at the hyphenation points.  For example:
  88
  89
  90           .hw in-sa-lub-rious
  91
  92      Besides the space character, any character whose hyphenation code
  93      value is zero can be used to separate the arguments of `hw' (see
  94      the documentation for the `hcode' request below for more
  95      information).  In addition, this request can be used more than
  96      once.
  97
  98      Hyphenation exceptions specified with the `hw' request are
  99      associated with the current hyphenation language; it causes an
 100      error if there is no current hyphenation language.
 101
 102      This request is ignored if there is no parameter.
 103
 104      In old versions of `troff' there was a limited amount of space to
 105      store such information; fortunately, with `gtroff', this is no
 106      longer a restriction.
 107
 108  - Escape: \%
 109  - Escape: \:
 110      To tell `gtroff' how to hyphenate words on the fly, use the `\%'
 111      escape, also known as the "hyphenation character".  Preceding a
 112      word with this character prevents it from being hyphenated;
 113      putting it inside a word indicates to `gtroff' that the word may
 114      be hyphenated at that point.  Note that this mechanism only
 115      affects that one occurrence of the word; to change the hyphenation
 116      of a word for the entire document, use the `hw' request.
 117
 118      The `\:' escape inserts a zero-width break point (that is, the
 119      word breaks but without adding a hyphen).
 120
 121
 122           ... check the /var/log/\:httpd/\:access_log file ...
 123
 124      Note that `\X' and `\Y' start a word, that is, the `\%' escape in
 125      (say) ` \X'...'\%foobar' and ` \Y'...'\%foobar' no longer prevents
 126      hyphenation but inserts a hyphenation point at the beginning of
 127      `foobar'; most likely this isn't what you want to do.
 128
 129  - Request: .hc [char]
 130      Change the hyphenation character to CHAR.  This character then
 131      works the same as the `\%' escape, and thus, no longer appears in
 132      the output.  Without an argument, `hc' resets the hyphenation
 133      character to be `\%' (the default) only.
 134
 135      The hyphenation character is associated with the current
 136      environment (*note Environments::).
 137
 138  - Request: .hpf pattern_file
 139  - Request: .hpfa pattern_file
 140  - Request: .hpfcode a b [c d ...]
 141      Read in a file of hyphenation patterns.  This file is searched for
 142      in the same way as `NAME.tmac' (or `tmac.NAME') is searched for if
 143      the `-mNAME' option is specified.
 144
 145      It should have the same format as (simple) TeX patterns files.
 146      More specifically, the following scanning rules are implemented.
 147
 148         * A percent sign starts a comment (up to the end of the line)
 149           even if preceded by a backslash.
 150
 151         * No support for `digraphs' like `\$'.
 152
 153         * `^^XX' (X is 0-9 or a-f) and `^^X' (character code of X in
 154           the range 0-127) are recognized; other use of `^' causes an
 155           error.
 156
 157         * No macro expansion.
 158
 159         * `hpf' checks for the expression `\patterns{...}' (possibly
 160           with whitespace before and after the braces).  Everything
 161           between the braces is taken as hyphenation patterns.
 162           Consequently, `{' and `}' are not allowed in patterns.
 163
 164         * Similarly, `\hyphenation{...}' gives a list of hyphenation
 165           exceptions.
 166
 167         * `\endinput' is recognized also.
 168
 169         * For backwards compatibility, if `\patterns' is missing, the
 170           whole file is treated as a list of hyphenation patterns (only
 171           recognizing the `%' character as the start of a comment).
 172
 173      If no `hpf' request is specified (either in the document or in a
 174      macro package), `gtroff' won't hyphenate at all.
 175
 176      The `hpfa' request appends a file of patterns to the current list.
 177
 178      The `hpfcode' request defines mapping values for character codes in
 179      hyphenation patterns.  `hpf' or `hpfa' then apply the mapping
 180      (after reading the patterns) before replacing or appending them to
 181      the current list of patterns.  Its arguments are pairs of
 182      character codes - integers from 0 to 255.  The request maps
 183      character code A to code B, code C to code D, and so on.  You can
 184      use character codes which would be invalid otherwise.
 185
 186      The set of hyphenation patterns is associated with the current
 187      language set by the `hla' request.  The `hpf' request is usually
 188      invoked by the `troffrc' or `troffrc-end' file; by default,
 189      `troffrc' loads hyphenation patterns for American English (in file
 190      `hyphen.us').
 191
 192      A second call to `hpf' (for the same language) will replace the
 193      hyphenation patterns with the new ones.
 194
 195      Invoking `hpf' causes an error if there is no current hyphenation
 196      language.
 197
 198  - Request: .hcode c1 code1 c2 code2 ...
 199      Set the hyphenation code of character C1 to CODE1, that of C2 to
 200      CODE2, etc.  A hyphenation code must be a single input character
 201      (not a special character) other than a digit or a space.
 202      Initially each lower-case letter (`a'-`z') has its hyphenation
 203      code set to itself, and each upper-case letter (`A'-`Z') has a
 204      hyphenation code which is the lower-case version of itself.
 205
 206      This request is ignored if it has no parameter.
 207
 208  - Request: .hym [length]
 209  - Register: \n[.hym]
 210      Set the (right) hyphenation margin to LENGTH.  If the current
 211      adjustment mode is not `b' or `n', the line is not hyphenated if
 212      it is shorter than LENGTH.  Without an argument, the hyphenation
 213      margin is reset to its default value, which is 0.  The default
 214      scaling indicator for this request is `m'.  The hyphenation margin
 215      is associated with the current environment (*note Environments::).
 216
 217      A negative argument resets the hyphenation margin to zero, emitting
 218      a warning of type `range'.
 219
 220      The current hyphenation margin is available in the `.hym' read-only
 221      number register.
 222
 223  - Request: .hys [hyphenation_space]
 224  - Register: \n[.hys]
 225      Set the hyphenation space to HYPHENATION_SPACE.  If the current
 226      adjustment mode is `b' or `n', don't hyphenate the line if it can
 227      be justified by adding no more than HYPHENATION_SPACE extra space
 228      to each word space.  Without argument, the hyphenation space is
 229      set to its default value, which is 0.  The default scaling
 230      indicator for this request is `m'.  The hyphenation space is
 231      associated with the current environment (*note Environments::).
 232
 233      A negative argument resets the hyphenation space to zero, emitting
 234      a warning of type `range'.
 235
 236      The current hyphenation space is available in the `.hys' read-only
 237      number register.
 238
 239  - Request: .shc [glyph]
 240      Set the "soft hyphen character" to GLYPH.(1) (*note Manipulating
 241      Hyphenation-Footnote-1::)  If the argument is omitted, the soft
 242      hyphen character is set to the default glyph `\(hy' (this is the
 243      start-up value of `gtroff' also).  The soft hyphen character is
 244      the glyph that is inserted when a word is hyphenated at a line
 245      break.  If the soft hyphen character does not exist in the font of
 246      the character immediately preceding a potential break point, then
 247      the line is not broken at that point.  Neither definitions
 248      (specified with the `char' request) nor translations (specified
 249      with the `tr' request) are considered when finding the soft hyphen
 250      character.
 251
 252  - Request: .hla language
 253  - Register: \n[.hla]
 254      Set the current hyphenation language to the string LANGUAGE.
 255      Hyphenation exceptions specified with the `hw' request and
 256      hyphenation patterns specified with the `hpf' and `hpfa' requests
 257      are both associated with the current hyphenation language.  The
 258      `hla' request is usually invoked by the `troffrc' or the
 259      `troffrc-end' files; `troffrc' sets the default language to `us'.
 260
 261      The current hyphenation language is available as a string in the
 262      read-only number register `.hla'.
 263
 264
 265           .ds curr_language \n[.hla]
 266           \*[curr_language]
 267               => us
 268
 269
 270 \1f
 271 File: groff,  Node: Manipulating Hyphenation-Footnotes,  Up: Manipulating Hyphenation
 272
 273    (1) "Soft hyphen character" is a misnomer since it is an output
 274 glyph.
 275
 276 \1f
 277 File: groff,  Node: Manipulating Spacing,  Next: Tabs and Fields,  Prev: Manipulating Hyphenation,  Up: gtroff Reference
 278
 279 Manipulating Spacing
 280 ====================
 281
 282  - Request: .sp [distance]
 283      Space downwards DISTANCE.  With no argument it advances 1 line.  A
 284      negative argument causes `gtroff' to move up the page the
 285      specified distance.  If the argument is preceded by a `|' then
 286      `gtroff' moves that distance from the top of the page.  This
 287      request causes a line break.  The default scaling indicator is `v'.
 288
 289  - Request: .ls [nnn]
 290  - Register: \n[.L]
 291      Output NNN-1 blank lines after each line of text.  With no
 292      argument, `gtroff' uses the previous value before the last `ls'
 293      call.
 294
 295
 296           .ls 2    \" This causes double-spaced output
 297           .ls 3    \" This causes triple-spaced output
 298           .ls      \" Again double-spaced
 299
 300      The line spacing is associated with the current environment (*note
 301      Environments::).
 302
 303      The read-only number register `.L' contains the current line
 304      spacing setting.
 305
 306    *Note Changing Type Sizes::, for the requests `vs' and `pvs' as
 307 alternatives to `ls'.
 308
 309  - Escape: \x'SPACING'
 310  - Register: \n[.a]
 311      Sometimes, extra vertical spacing is only needed occasionally, e.g.
 312      to allow space for a tall construct (like an equation).  The `\x'
 313      escape does this.  The escape is given a numerical argument,
 314      usually enclosed in quotes (like `\x'3p''); the default scaling
 315      indicator is `v'.  If this number is positive extra vertical space
 316      is inserted below the current line.  A negative number adds space
 317      above.  If this escape is used multiple times on the same line,
 318      the maximum of the values is used.
 319
 320      *Note Escapes::, for details on parameter delimiting characters.
 321
 322      The `.a' read-only number register contains the most recent
 323      (nonnegative) extra vertical line space.
 324
 325      Using `\x' can be necessary in combination with the `\b' escape,
 326      as the following example shows.
 327
 328
 329           This is a test with the \[rs]b escape.
 330           .br
 331           This is a test with the \[rs]b escape.
 332           .br
 333           This is a test with \b'xyz'\x'-1m'\x'1m'.
 334           .br
 335           This is a test with the \[rs]b escape.
 336           .br
 337           This is a test with the \[rs]b escape.
 338
 339      produces
 340
 341
 342           This is a test with the \b escape.
 343           This is a test with the \b escape.
 344                               x
 345           This is a test with y.
 346                               z
 347           This is a test with the \b escape.
 348           This is a test with the \b escape.
 349
 350
 351  - Request: .ns
 352  - Request: .rs
 353  - Register: \n[.ns]
 354      Enable "no-space mode".  In this mode, spacing (either via `sp' or
 355      via blank lines) is disabled.  The `bp' request to advance to the
 356      next page is also disabled, except if it is accompanied by a page
 357      number (see *Note Page Control::, for more information).  This
 358      mode ends when actual text is output or the `rs' request is
 359      encountered which ends no-space mode.  The read-only number
 360      register `.ns' is set to 1 as long as no-space mode is active.
 361
 362      This request is useful for macros that conditionally insert
 363      vertical space before the text starts (for example, a paragraph
 364      macro could insert some space except when it is the first
 365      paragraph after a section header).
 366
 367 \1f
 368 File: groff,  Node: Tabs and Fields,  Next: Character Translations,  Prev: Manipulating Spacing,  Up: gtroff Reference
 369
 370 Tabs and Fields
 371 ===============
 372
 373    A tab character (ASCII char 9, EBCDIC char 5) causes a horizontal
 374 movement to the next tab stop (much like it did on a typewriter).
 375
 376  - Escape: \t
 377      This escape is a non-interpreted tab character.  In copy mode
 378      (*note Copy-in Mode::), `\t' is the same as a real tab character.
 379
 380  - Request: .ta [n1 n2 ... nn T r1 r2 ... rn]
 381  - Register: \n[.tabs]
 382      Change tab stop positions.  This request takes a series of tab
 383      specifiers as arguments (optionally divided into two groups with
 384      the letter `T') which indicate where each tab stop is to be
 385      (overriding any previous settings).
 386
 387      Tab stops can be specified absolutely, i.e., as the distance from
 388      the left margin.  For example, the following sets 6 tab stops every
 389      one inch.
 390
 391
 392           .ta 1i 2i 3i 4i 5i 6i
 393
 394      Tab stops can also be specified using a leading `+' which means
 395      that the specified tab stop is set relative to the previous tab
 396      stop.  For example, the following is equivalent to the previous
 397      example.
 398
 399
 400           .ta 1i +1i +1i +1i +1i +1i
 401
 402      `gtroff' supports an extended syntax to specify repeat values after
 403      the `T' mark (these values are always taken as relative) - this is
 404      the usual way to specify tabs set at equal intervals.  The
 405      following is, yet again, the same as the previous examples.  It
 406      does even more since it defines an infinite number of tab stops
 407      separated by one inch.
 408
 409
 410           .ta T 1i
 411
 412      Now we are ready to interpret the full syntax given at the
 413      beginning: Set tabs at positions N1, N2, ..., NN and then set tabs
 414      at NN+R1, NN+R2, ..., NN+RN and then at NN+RN+R1, NN+RN+R2, ...,
 415      NN+RN+RN, and so on.
 416
 417      Example: `4c +6c T 3c 5c 2c' is equivalent to `4c 10c 13c 18c 20c
 418      23c 28c 30c ...'.
 419
 420      The material in each tab column (i.e., the column between two tab
 421      stops) may be justified to the right or left or centered in the
 422      column.  This is specified by appending `R', `L', or `C' to the tab
 423      specifier.  The default justification is `L'.  Example:
 424
 425
 426           .ta 1i 2iC 3iR
 427
 428      Some notes:
 429
 430         * The default unit of the `ta' request is `m'.
 431
 432         * A tab stop is converted into a non-breakable horizontal
 433           movement which can be neither stretched nor squeezed.  For
 434           example,
 435
 436
 437                .ds foo a\tb\tc
 438                .ta T 5i
 439                \*[foo]
 440
 441           creates a single line which is a bit longer than 10 inches (a
 442           string is used to show exactly where the tab characters are).
 443           Now consider the following:
 444
 445
 446                .ds bar a\tb b\tc
 447                .ta T 5i
 448                \*[bar]
 449
 450           `gtroff' first converts the tab stops of the line into
 451           unbreakable horizontal movements, then splits the line after
 452           the second `b' (assuming a sufficiently short line length).
 453           Usually, this isn't what the user wants.
 454
 455         * Superfluous tabs (i.e., tab characters which do not
 456           correspond to a tab stop) are ignored except the first one
 457           which delimits the characters belonging to the last tab stop
 458           for right-justifying or centering.  Consider the following
 459           example
 460
 461
 462                .ds Z   foo\tbar\tfoo
 463                .ds ZZ  foo\tbar\tfoobar
 464                .ds ZZZ foo\tbar\tfoo\tbar
 465                .ta 2i 4iR
 466                \*[Z]
 467                .br
 468                \*[ZZ]
 469                .br
 470                \*[ZZZ]
 471                .br
 472
 473           which produces the following output:
 474
 475
 476                foo                 bar              foo
 477                foo                 bar           foobar
 478                foo                 bar              foobar
 479
 480           The first line right-justifies the second `foo' relative to
 481           the tab stop.  The second line right-justifies `foobar'.  The
 482           third line finally right-justifies only `foo' because of the
 483           additional tab character which marks the end of the string
 484           belonging to the last defined tab stop.
 485
 486         * Tab stops are associated with the current environment (*note
 487           Environments::).
 488
 489         * Calling `ta' without an argument removes all tab stops.
 490
 491         * The start-up value of `gtroff' is `T 0.5i' in troff mode and
 492           `T 0.8i' in nroff mode (the latter is done with an explicit
 493           call to the `ta' request in the file `tty.tmac'.
 494
 495      The read-only number register `.tabs' contains a string
 496      representation of the current tab settings suitable for use as an
 497      argument to the `ta' request.
 498
 499
 500           .ds tab-string \n[.tabs]
 501           \*[tab-string]
 502               => T120u
 503
 504      The `troff' version of the Plan 9 operating system uses register
 505      `.S' for the same purpose.
 506
 507  - Request: .tc [fill-glyph]
 508      Normally `gtroff' fills the space to the next tab stop with
 509      whitespace.  This can be changed with the `tc' request.  With no
 510      argument `gtroff' reverts to using whitespace, which is the
 511      default.  The value of this "tab repetition character" is
 512      associated with the current environment (*note Environments::).(1)
 513      (*note Tabs and Fields-Footnote-1::)
 514
 515  - Request: .linetabs n
 516  - Register: \n[.linetabs]
 517      If N is missing or not zero, enable "line-tabs" mode, or disable
 518      it otherwise (the default).  In line-tabs mode, `gtroff' computes
 519      tab distances relative to the (current) output line instead of the
 520      input line.
 521
 522      For example, the following code:
 523
 524
 525           .ds x a\t\c
 526           .ds y b\t\c
 527           .ds z c
 528           .ta 1i 3i
 529           \*x
 530           \*y
 531           \*z
 532
 533      in normal mode, results in the output
 534
 535
 536           a         b         c
 537
 538      in line-tabs mode, the same code outputs
 539
 540
 541           a         b                   c
 542
 543      Line-tabs mode is associated with the current environment.  The
 544      read-only register `.linetabs' is set to 1 if in line-tabs mode,
 545      and 0 in normal mode.
 546
 547 * Menu:
 548
 549 * Leaders::
 550 * Fields::
 551
 552 \1f
 553 File: groff,  Node: Tabs and Fields-Footnotes,  Up: Tabs and Fields
 554
 555    (1) "Tab repetition character" is a misnomer since it is an output
 556 glyph.
 557
 558 \1f
 559 File: groff,  Node: Leaders,  Next: Fields,  Prev: Tabs and Fields,  Up: Tabs and Fields
 560
 561 Leaders
 562 -------
 563
 564    Sometimes it may may be desirable to use the `tc' request to fill a
 565 particular tab stop with a given glyph (for example dots in a table of
 566 contents), but also normal tab stops on the rest of the line.  For this
 567 `gtroff' provides an alternate tab mechanism, called "leaders" which
 568 does just that.
 569
 570    A leader character (character code 1) behaves similarly to a tab
 571 character: It moves to the next tab stop.  The only difference is that
 572 for this movement, the fill glyph defaults to a period character and
 573 not to space.
 574
 575  - Escape: \a
 576      This escape is a non-interpreted leader character.  In copy mode
 577      (*note Copy-in Mode::), `\a' is the same as a real leader
 578      character.
 579
 580  - Request: .lc [fill-glyph]
 581      Declare the "leader repetition character".(1) (*note
 582      Leaders-Footnote-1::) Without an argument, leaders act the same as
 583      tabs (i.e., using whitespace for filling).  `gtroff''s start-up
 584      value is a dot (`.').  The value of the leader repetition
 585      character is associated with the current environment (*note
 586      Environments::).
 587
 588    For a table of contents, to name an example, tab stops may be
 589 defined so that the section number is one tab stop, the title is the
 590 second with the remaining space being filled with a line of dots, and
 591 then the page number slightly separated from the dots.
 592
 593
 594      .ds entry 1.1\tFoo\a\t12
 595      .lc .
 596      .ta 1i 5i +.25i
 597      \*[entry]
 598
 599 This produces
 600
 601
 602      1.1  Foo..........................................  12
 603
 604 \1f
 605 File: groff,  Node: Leaders-Footnotes,  Up: Leaders
 606
 607    (1) "Leader repetition character" is a misnomer since it is an
 608 output glyph.
 609
 610 \1f
 611 File: groff,  Node: Fields,  Prev: Leaders,  Up: Tabs and Fields
 612
 613 Fields
 614 ------
 615
 616    "Fields" are a more general way of laying out tabular data.  A field
 617 is defined as the data between a pair of "delimiting characters".  It
 618 contains substrings which are separated by "padding characters".  The
 619 width of a field is the distance on the _input_ line from the position
 620 where the field starts to the next tab stop.  A padding character
 621 inserts stretchable space similar to TeX's `\hss' command (thus it can
 622 even be negative) to make the sum of all substring lengths plus the
 623 stretchable space equal to the field width.  If more than one padding
 624 character is inserted, the available space is evenly distributed among
 625 them.
 626
 627  - Request: .fc [delim-char [padding-char]]
 628      Define a delimiting and a padding character for fields.  If the
 629      latter is missing, the padding character defaults to a space
 630      character.  If there is no argument at all, the field mechanism is
 631      disabled (which is the default).  Note that contrary to e.g. the
 632      tab repetition character, delimiting and padding characters are
 633      _not_ associated to the current environment (*note Environments::).
 634
 635      Example:
 636
 637
 638           .fc # ^
 639           .ta T 3i
 640           #foo^bar^smurf#
 641           .br
 642           #foo^^bar^smurf#
 643
 644      and here the result:
 645
 646
 647           foo         bar          smurf
 648           foo            bar       smurf
 649
 650
 651 \1f
 652 File: groff,  Node: Character Translations,  Next: Troff and Nroff Mode,  Prev: Tabs and Fields,  Up: gtroff Reference
 653
 654 Character Translations
 655 ======================
 656
 657    The control character (`.') and the no-break control character (`'')
 658 can be changed with the `cc' and `c2' requests, respectively.
 659
 660  - Request: .cc [c]
 661      Set the control character to C.  With no argument the default
 662      control character `.' is restored.  The value of the control
 663      character is associated with the current environment (*note
 664      Environments::).
 665
 666  - Request: .c2 [c]
 667      Set the no-break control character to C.  With no argument the
 668      default control character `'' is restored.  The value of the
 669      no-break control character is associated with the current
 670      environment (*note Environments::).
 671
 672  - Request: .eo
 673      Disable the escape mechanism completely.  After executing this
 674      request, the backslash character `\' no longer starts an escape
 675      sequence.
 676
 677      This request can be very helpful in writing macros since it is not
 678      necessary then to double the escape character.  Here an example:
 679
 680
 681           .\" This is a simplified version of the
 682           .\" .BR request from the man macro package
 683           .eo
 684           .de BR
 685           .  ds result \&
 686           .  while (\n[.$] >= 2) \{\
 687           .    as result \fB\$1\fR\$2
 688           .    shift 2
 689           .  \}
 690           .  if \n[.$] .as result \fB\$1
 691           \*[result]
 692           .  ft R
 693           ..
 694           .ec
 695
 696
 697  - Request: .ec [c]
 698      Set the escape character to C.  With no argument the default
 699      escape character `\' is restored.  It can be also used to
 700      re-enable the escape mechanism after an `eo' request.
 701
 702      Note that changing the escape character globally will likely break
 703      macro packages since `gtroff' has no mechanism to `intern' macros,
 704      i.e., to convert a macro definition into an internal form which is
 705      independent of its representation (TeX has this mechanism).  If a
 706      macro is called, it is executed literally.
 707
 708  - Request: .ecs
 709  - Request: .ecr
 710      The `ecs' request saves the current escape character in an
 711      internal register.  Use this request in combination with the `ec'
 712      request to temporarily change the escape character.
 713
 714      The `ecr' request restores the escape character saved with `ecs'.
 715      Without a previous call to `ecs', this request sets the escape
 716      character to `\'.
 717
 718  - Escape: \\
 719  - Escape: \e
 720  - Escape: \E
 721      Print the current escape character (which is the backslash
 722      character `\' by default).
 723
 724      `\\' is a `delayed' backslash; more precisely, it is the default
 725      escape character followed by a backslash, which no longer has
 726      special meaning due to the leading escape character.  It is _not_
 727      an escape sequence in the usual sense!  In any unknown escape
 728      sequence `\X' the escape character is ignored and X is printed.
 729      But if X is equal to the current escape character, no warning is
 730      emitted.
 731
 732      As a consequence, only at top-level or in a diversion a backslash
 733      glyph is printed; in copy-in mode, it expands to a single
 734      backslash which then combines with the following character to an
 735      escape sequence.
 736
 737      The `\E' escape differs from `\e' by printing an escape character
 738      that is not interpreted in copy mode.  Use this to define strings
 739      with escapes that work when used in copy mode (for example, as a
 740      macro argument).  The following example defines strings to begin
 741      and end a superscript:
 742
 743
 744           .ds { \v'-.3m'\s'\Es[.s]*60/100'
 745           .ds } \s0\v'.3m'
 746
 747      Another example to demonstrate the differences between the various
 748      escape sequences, using a strange escape character, `-'.
 749
 750
 751           .ec -
 752           .de xxx
 753           --A'123'
 754           ..
 755           .xxx
 756               => -A'foo'
 757
 758      The result is surprising for most users, expecting `1' since `foo'
 759      is a valid identifier.  What has happened?  As mentioned above,
 760      the leading escape character makes the following character
 761      ordinary.  Written with the default escape character the sequence
 762      `--' becomes `\-' - this is the minus sign.
 763
 764      If the escape character followed by itself is a valid escape
 765      sequence, only `\E' yields the expected result:
 766
 767
 768           .ec -
 769           .de xxx
 770           -EA'123'
 771           ..
 772           .xxx
 773               => 1
 774
 775
 776  - Escape: \.
 777      Similar to `\\', the sequence `\.' isn't a real escape sequence.
 778      As before, a warning message is suppressed if the escape character
 779      is followed by a dot, and the dot itself is printed.
 780
 781
 782           .de foo
 783           .  nop foo
 784           .
 785           .  de bar
 786           .    nop bar
 787           \\..
 788           .
 789           ..
 790           .foo
 791           .bar
 792               => foo bar
 793
 794      The first backslash is consumed while the macro is read, and the
 795      second is swallowed while exexuting macro `foo'.
 796
 797    A "translation" is a mapping of an input character to an output
 798 glyph.  The mapping occurs at output time, i.e., the input character
 799 gets assigned the metric information of the mapped output character
 800 right before input tokens are converted to nodes (*note Gtroff
 801 Internals::, for more on this process).
 802
 803  - Request: .tr abcd...
 804  - Request: .trin abcd...
 805      Translate character A to glyph B, character C to glyph D, etc.  If
 806      there is an odd number of arguments, the last one is translated to
 807      an unstretchable space (`\ ').
 808
 809      The `trin' request is identical to `tr', but when you unformat a
 810      diversion with `asciify' it ignores the translation.  *Note
 811      Diversions::, for details about the `asciify' request.
 812
 813      Some notes:
 814
 815         * Special characters (`\(XX', `\[XXX]', `\C'XXX'', `\'', `\`',
 816           `\-', `\_'), glyphs defined with the `char' request, and
 817           numbered glyphs (`\N'XXX'') can be translated also.
 818
 819         * The `\e' escape can be translated also.
 820
 821         * Characters can be mapped onto the `\%' and `\~' escapes (but
 822           `\%' and `\~' can't be mapped onto another glyph).
 823
 824         * The following characters can't be translated: space (with one
 825           exception, see below), backspace, newline, leader (and `\a'),
 826           tab (and `\t').
 827
 828         * Translations are not considered for finding the soft hyphen
 829           character set with the `shc' request.
 830
 831         * The pair `C\&' (this is an arbitrary character C followed by
 832           the zero width space character) maps this character to
 833           nothing.
 834
 835
 836                .tr a\&
 837                foo bar
 838                    => foo br
 839
 840           It is even possible to map the space character to nothing:
 841
 842
 843                .tr aa \&
 844                foo bar
 845                    => foobar
 846
 847           As shown in the example, the space character can't be the
 848           first character/glyph pair as an argument of `tr'.
 849           Additionally, it is not possible to map the space character
 850           to any other glyph; requests like `.tr aa x' undo `.tr aa \&'
 851           instead.
 852
 853           If justification is active, lines are justified in spite of
 854           the `empty' space character (but there is no minimal
 855           distance, i.e. the space character, between words).
 856
 857         * After an output glyph has been constructed (this happens at
 858           the moment immediately before the glyph is appended to an
 859           output glyph list, either by direct output, in a macro,
 860           diversion, or string), it is no longer affected by `tr'.
 861
 862         * Translating character to glyphs where one of them or both are
 863           undefined is possible also; `tr' does not check whether the
 864           entities in its argument do exist.
 865
 866           *Note Gtroff Internals::.
 867
 868         * `troff' no longer has a hard-coded dependency on Latin-1; all
 869           `charXXX' entities have been removed from the font
 870           description files.  This has a notable consequence which
 871           shows up in warnings like `can't find character with input
 872           code XXX' if the `tr' request isn't handled properly.
 873
 874           Consider the following translation:
 875
 876
 877                .tr e'E'
 878
 879           This maps input character `e'' onto glyph `E'', which is
 880           identical to glyph `char201'.  But this glyph intentionally
 881           doesn't exist!  Instead, `\[char201]' is treated as an input
 882           character entity and is by default mapped onto `\['E]', and
 883           `gtroff' doesn't handle translations of translations.
 884
 885           The right way to write the above translation is
 886
 887
 888                .tr e'\['E]
 889
 890           With other words, the first argument of `tr' should be an
 891           input character or entity, and the second one a glyph entity.
 892
 893         * Without an argument, the `tr' request is ignored.
 894
 895  - Request: .trnt abcd...
 896      `trnt' is the same as the `tr' request except that the
 897      translations do not apply to text that is transparently throughput
 898      into a diversion with `\!'.  *Note Diversions::, for more
 899      information.
 900
 901      For example,
 902
 903
 904           .tr ab
 905           .di x
 906           \!.tm a
 907           .di
 908           .x
 909
 910      prints `b' to the standard error stream; if `trnt' is used instead
 911      of `tr' it prints `a'.
 912
 913 \1f
 914 File: groff,  Node: Troff and Nroff Mode,  Next: Line Layout,  Prev: Character Translations,  Up: gtroff Reference
 915
 916 Troff and Nroff Mode
 917 ====================
 918
 919    Originally, `nroff' and `troff' were two separate programs, the
 920 former for TTY output, the latter for everything else.  With GNU
 921 `troff', both programs are merged into one executable, sending its
 922 output to a device driver (`grotty' for TTY devices, `grops' for
 923 POSTSCRIPT, etc.) which interprets the intermediate output of `gtroff'.
 924 For UNIX `troff' it makes sense to talk about "Nroff mode" and "Troff
 925 mode" since the differences are hardcoded.  For GNU `troff', this
 926 distinction is not appropriate because `gtroff' simply takes the
 927 information given in the font files for a particular device without
 928 handling requests specially if a TTY output device is used.
 929
 930    Usually, a macro package can be used with all output devices.
 931 Nevertheless, it is sometimes necessary to make a distinction between
 932 TTY and non-TTY devices: `gtroff' provides two built-in conditions `n'
 933 and `t' for the `if', `ie', and `while' requests to decide whether
 934 `gtroff' shall behave like `nroff' or like `troff'.
 935
 936  - Request: .troff
 937      Make the `t' built-in condition true (and the `n' built-in
 938      condition false) for `if', `ie', and `while' conditional requests.
 939      This is the default if `gtroff' (_not_ `groff') is started with
 940      the `-R' switch to avoid loading of the start-up files `troffrc'
 941      and `troffrc-end'.  Without `-R', `gtroff' stays in troff mode if
 942      the output device is not a TTY (e.g. `ps').
 943
 944  - Request: .nroff
 945      Make the `n' built-in condition true (and the `t' built-in
 946      condition false) for `if', `ie', and `while' conditional requests.
 947      This is the default if `gtroff' uses a TTY output device; the
 948      code for switching to nroff mode is in the file `tty.tmac' which
 949      is loaded by the start-up file `troffrc'.
 950
 951    *Note Conditionals and Loops::, for more details on built-in
 952 conditions.
 953
 954 \1f
 955 File: groff,  Node: Line Layout,  Next: Line Control,  Prev: Troff and Nroff Mode,  Up: gtroff Reference
 956
 957 Line Layout
 958 ===========
 959
 960    The following drawing shows the dimensions which `gtroff' uses for
 961 placing a line of output onto the page.  They are labeled with the
 962 request which manipulates each dimension.
 963
 964
 965                      -->| in |<--
 966                         |<-----------ll------------>|
 967                    +----+----+----------------------+----+
 968                    |    :    :                      :    |
 969                    +----+----+----------------------+----+
 970                 -->| po |<--
 971                    |<--------paper width---------------->|
 972
 973 These dimensions are:
 974
 975 `po'
 976      "Page offset" - this is the leftmost position of text on the final
 977      output, defining the "left margin".
 978
 979 `in'
 980      "Indentation" - this is the distance from the left margin where
 981      text is printed.
 982
 983 `ll'
 984      "Line length" - this is the distance from the left margin to right
 985      margin.
 986
 987    A simple demonstration:
 988
 989
 990      .ll 3i
 991      This is text without indentation.
 992      The line length has been set to 3\~inch.
 993      .in +.5i
 994      .ll -.5i
 995      Now the left and right margins are both increased.
 996      .in
 997      .ll
 998      Calling .in and .ll without parameters restore
 999      the previous values.
1000
1001    Result:
1002
1003
1004      This  is text without indenta-
1005      tion.   The  line  length  has
1006      been set to 3 inch.
1007           Now   the  left  and
1008           right  margins   are
1009           both increased.
1010      Calling  .in  and  .ll without
1011      parameters restore the  previ-
1012      ous values.
1013
1014  - Request: .po [offset]
1015  - Request: .po +offset
1016  - Request: .po -offset
1017  - Register: \n[.o]
1018      Set horizontal page offset to OFFSET (or increment or decrement
1019      the current value by OFFSET).  Note that this request does not
1020      cause a break, so changing the page offset in the middle of text
1021      being filled may not yield the expected result.  The initial value
1022      is 1i.  For TTY output devices, it is set to 0 in the startup file
1023      `troffrc'; the default scaling indicator is `m' (and not `v' as
1024      incorrectly documented in the original UNIX troff manual).
1025
1026      The current page offset can be found in the read-only number
1027      register `.o'.
1028
1029      If `po' is called without an argument, the page offset is reset to
1030      the previous value before the last call to `po'.
1031
1032
1033           .po 3i
1034           \n[.o]
1035               => 720
1036           .po -1i
1037           \n[.o]
1038               => 480
1039           .po
1040           \n[.o]
1041               => 720
1042
1043
1044  - Request: .in [indent]
1045  - Request: .in +indent
1046  - Request: .in -indent
1047  - Register: \n[.i]
1048      Set indentation to INDENT (or increment or decrement the current
1049      value by INDENT).  This request causes a break.  Initially, there
1050      is no indentation.
1051
1052      If `in' is called without an argument, the indentation is reset to
1053      the previous value before the last call to `in'.  The default
1054      scaling indicator is `m'.
1055
1056      The indentation is associated with the current environment (*note
1057      Environments::).
1058
1059      If a negative indentation value is specified (which is not
1060      allowed), `gtroff' emits a warning of type `range' and sets the
1061      indentation to zero.
1062
1063      The effect of `in' is delayed until a partially collected line (if
1064      it exists) is output.  A temporary indent value is reset to zero
1065      also.
1066
1067      The current indentation (as set by `in') can be found in the
1068      read-only number register `.i'.
1069
1070  - Request: .ti offset
1071  - Request: .ti +offset
1072  - Request: .ti -offset
1073  - Register: \n[.in]
1074      Temporarily indent the next output line by OFFSET.  If an
1075      increment or decrement value is specified, adjust the temporary
1076      indentation relative to the value set by the `in' request.
1077
1078      This request causes a break; its value is associated with the
1079      current environment (*note Environments::).  The default scaling
1080      indicator is `m'.  A call of `ti' without an argument is ignored.
1081
1082      If the total indentation value is negative (which is not allowed),
1083      `gtroff' emits a warning of type `range' and sets the temporary
1084      indentation to zero.  `Total indentation' is either OFFSET if
1085      specified as an absolute value, or the temporary plus normal
1086      indentation, if OFFSET is given as a relative value.
1087
1088      The effect of `ti' is delayed until a partially collected line (if
1089      it exists) is output.
1090
1091      The read-only number register `.in' is the indentation that applies
1092      to the current output line.
1093
1094      The difference between `.i' and `.in' is that the latter takes
1095      into account whether a partially collected line still uses the old
1096      indentation value or a temporary indentation value is active.
1097
1098  - Request: .ll [length]
1099  - Request: .ll +length
1100  - Request: .ll -length
1101  - Register: \n[.l]
1102  - Register: \n[.ll]
1103      Set the line length to LENGTH (or increment or decrement the
1104      current value by LENGTH).  Initially, the line length is set to
1105      6.5i.  The effect of `ll' is delayed until a partially collected
1106      line (if it exists) is output.  The default scaling indicator is
1107      `m'.
1108
1109      If `ll' is called without an argument, the line length is reset to
1110      the previous value before the last call to `ll'.  If a negative
1111      line length is specified (which is not allowed), `gtroff' emits a
1112      warning of type `range' and sets the line length to zero.
1113
1114      The line length is associated with the current environment (*note
1115      Environments::).
1116
1117      The current line length (as set by `ll') can be found in the
1118      read-only number register `.l'.  The read-only number register
1119      `.ll' is the line length that applies to the current output line.
1120
1121      Similar to `.i' and `.in', the difference between `.l' and `.ll'
1122      is that the latter takes into account whether a partially
1123      collected line still uses the old line length value.
1124
1125 \1f
1126 File: groff,  Node: Line Control,  Next: Page Layout,  Prev: Line Layout,  Up: gtroff Reference
1127
1128 Line Control
1129 ============
1130
1131    It is important to understand how `gtroff' handles input and output
1132 lines.
1133
1134    Many escapes use positioning relative to the input line.  For
1135 example, this
1136
1137
1138      This is a \h'|1.2i'test.
1139
1140      This is a
1141      \h'|1.2i'test.
1142
1143 produces
1144
1145
1146      This is a   test.
1147
1148      This is a             test.
1149
1150    The main usage of this feature is to define macros which act exactly
1151 at the place where called.
1152
1153
1154      .\" A simple macro to underline a word
1155      .de underline
1156      .  nop \\$1\l'|0\[ul]'
1157      ..
1158
1159 In the above example, `|0' specifies a negative distance from the
1160 current position (at the end of the just emitted argument `\$1') back
1161 to the beginning of the input line.  Thus, the `\l' escape draws a line
1162 from right to left.
1163
1164    `gtroff' makes a difference between input and output line
1165 continuation; the latter is also called "interrupting" a line.
1166
1167  - Escape: \<RET>
1168  - Escape: \c
1169  - Register: \n[.int]
1170      Continue a line.  `\<RET>' (this is a backslash at the end of a
1171      line immediately followed by a newline) works on the input level,
1172      suppressing the effects of the following newline in the input.
1173
1174
1175           This is a \
1176           .test
1177               => This is a .test
1178
1179      The `|' operator is also affected.
1180
1181      `\c' works on the output level.  Anything after this escape on the
1182      same line is ignored, except `\R' which works as usual.  Anything
1183      before `\c' on the same line will be appended to the current
1184      partial output line.  The next non-command line after an
1185      interrupted line counts as a new input line.
1186
1187      The visual results depend on whether no-fill mode is active.
1188
1189         * If no-fill mode is active (using the `nf' request), the next
1190           input text line after `\c' will be handled as a continuation
1191           of the same input text line.
1192
1193
1194                .nf
1195                This is a \c
1196                test.
1197                    => This is a test.
1198
1199         * If fill mode is active (using the `fi' request), a word
1200           interrupted with `\c' will be continued with the text on the
1201           next input text line, without an intervening space.
1202
1203
1204                This is a te\c
1205                st.
1206                    => This is a test.
1207
1208
1209      Note that an intervening control line which causes a break is
1210      stronger than `\c', flushing out the current partial line in the
1211      usual way.
1212
1213      The `.int' register contains a positive value if the last output
1214      line was interrupted with `\c'; this is associated with the
1215      current environment (*note Environments::).
1216
1217
1218 \1f
1219 File: groff,  Node: Page Layout,  Next: Page Control,  Prev: Line Control,  Up: gtroff Reference
1220
1221 Page Layout
1222 ===========
1223
1224    `gtroff' provides some very primitive operations for controlling
1225 page layout.
1226
1227  - Request: .pl [length]
1228  - Request: .pl +length
1229  - Request: .pl -length
1230  - Register: \n[.p]
1231      Set the "page length" to LENGTH (or increment or decrement the
1232      current value by LENGTH).  This is the length of the physical
1233      output page.  The default scaling indicator is `v'.
1234
1235      The current setting can be found in the read-only number register
1236      `.p'.
1237
1238      Note that this only specifies the size of the page, not the top and
1239      bottom margins.  Those are not set by `gtroff' directly.  *Note
1240      Traps::, for further information on how to do this.
1241
1242      Negative `pl' values are possible also, but not very useful: No
1243      trap is sprung, and each line is output on a single page (thus
1244      suppressing all vertical spacing).
1245
1246      If no argument or an invalid argument is given, `pl' sets the page
1247      length to 11i.
1248
1249    `gtroff' provides several operations which help in setting up top
1250 and bottom titles (or headers and footers).
1251
1252  - Request: .tl 'left'center'right'
1253      Print a "title line".  It consists of three parts: a left
1254      justified portion, a centered portion, and a right justified
1255      portion.  The argument separator `'' can be replaced with any
1256      character not occurring in the title line.  The `%' character is
1257      replaced with the current page number.  This character can be
1258      changed with the `pc' request (see below).
1259
1260      Without argument, `tl' is ignored.
1261
1262      Some notes:
1263
1264         * A title line is not restricted to the top or bottom of a page.
1265
1266         * `tl' prints the title line immediately, ignoring a partially
1267           filled line (which stays untouched).
1268
1269         * It is not an error to omit closing delimiters.  For example,
1270           `.tl /foo' is equivalent to `.tl /foo///': It prints a title
1271           line with the left justified word `foo'; the centered and
1272           right justfied parts are empty.
1273
1274         * `tl' accepts the same parameter delimiting characters as the
1275           `\A' escape; see *Note Escapes::.
1276
1277  - Request: .lt [length]
1278  - Request: .lt +length
1279  - Request: .lt -length
1280  - Register: \n[.lt]
1281      The title line is printed using its own line length, which is
1282      specified (or incremented or decremented) with the `lt' request.
1283      Initially, the title line length is set to 6.5i.  If a negative
1284      line length is specified (which is not allowed), `gtroff' emits a
1285      warning of type `range' and sets the title line length to zero.
1286      The default scaling indicator is `m'.  If `lt' is called without
1287      an argument, the title length is reset to the previous value
1288      before the last call to `lt'.
1289
1290      The current setting of this is available in the `.lt' read-only
1291      number register; it is associated with the current environment
1292      (*note Environments::).
1293
1294
1295  - Request: .pn page
1296  - Request: .pn +page
1297  - Request: .pn -page
1298  - Register: \n[.pn]
1299      Change (increase or decrease) the page number of the _next_ page.
1300      The only argument is the page number; the request is ignored
1301      without a parameter.
1302
1303      The read-only number register `.pn' contains the number of the next
1304      page: either the value set by a `pn' request, or the number of the
1305      current page plus 1.
1306
1307  - Register: \n[%]
1308      A read-write register holding the current page number.
1309
1310  - Request: .pc [char]
1311      Change the page number character (used by the `tl' request) to a
1312      different character.  With no argument, this mechanism is disabled.
1313      Note that this doesn't affect the number register `%'.
1314
1315    *Note Traps::.
1316