PageRenderTime 66ms CodeModel.GetById 33ms app.highlight 7ms RepoModel.GetById 1ms app.codeStats 1ms

/contrib/groff/doc/groff-2

https://bitbucket.org/freebsd/freebsd-head/
#! | 4910 lines | 3933 code | 977 blank | 0 comment | 0 complexity | 49d6f50ba96bba8de8a1912d8cbd463c MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   1This is groff, produced by makeinfo version 4.8 from ./groff.texinfo.
   2
   3   This manual documents GNU `troff' version 1.19.2.
   4
   5   Copyright (C) 1994-2000, 2001, 2002, 2003, 2004, 2005 Free Software
   6Foundation, Inc.
   7
   8     Permission is granted to copy, distribute and/or modify this
   9     document under the terms of the GNU Free Documentation License,
  10     Version 1.1 or any later version published by the Free Software
  11     Foundation; with no Invariant Sections, with the Front-Cover texts
  12     being `A GNU Manual," and with the Back-Cover Texts as in (a)
  13     below.  A copy of the license is included in the section entitled
  14     `GNU Free Documentation License."
  15
  16     (a) The FSF's Back-Cover Text is: `You have freedom to copy and
  17     modify this GNU Manual, like GNU software.  Copies published by
  18     the Free Software Foundation raise funds for GNU development."
  19
  20INFO-DIR-SECTION Typesetting
  21START-INFO-DIR-ENTRY
  22* Groff: (groff).               The GNU troff document formatting system.
  23END-INFO-DIR-ENTRY
  24
  25
  26File: groff,  Node: Drawing Requests,  Next: Traps,  Prev: Page Motions,  Up: gtroff Reference
  27
  285.23 Drawing Requests
  29=====================
  30
  31`gtroff' provides a number of ways to draw lines and other figures on
  32the page.  Used in combination with the page motion commands (see *Note
  33Page Motions::, for more info), a wide variety of figures can be drawn.
  34However, for complex drawings these operations can be quite
  35cumbersome, and it may be wise to use graphic preprocessors like `gpic'
  36or `ggrn'.  *Note gpic::, and *Note ggrn::, for more information.
  37
  38   All drawing is done via escapes.
  39
  40 -- Escape: \l'l'
  41 -- Escape: \l'lg'
  42     Draw a line horizontally.  L is the length of the line to be
  43     drawn.  If it is positive, start the line at the current location
  44     and draw to the right; its end point is the new current location.
  45     Negative values are handled differently: The line starts at the
  46     current location and draws to the left, but the current location
  47     doesn't move.
  48
  49     L can also be specified absolutely (i.e. with a leading `|') which
  50     draws back to the beginning of the input line.  Default scaling
  51     indicator is `m'.
  52
  53     The optional second parameter G is a glyph to draw the line with.
  54     If this second argument is not specified, `gtroff' uses the
  55     underscore glyph, `\[ru]'.
  56
  57     To separate the two arguments (to prevent `gtroff' from
  58     interpreting a drawing glyph as a scaling indicator if the glyph is
  59     represented by a single character) use `\&'.
  60
  61     Here a small useful example:
  62
  63
  64          .de box
  65          \[br]\\$*\[br]\l'|0\[rn]'\l'|0\[ul]'
  66          ..
  67
  68     Note that this works by outputting a box rule (a vertical line),
  69     then the text given as an argument and then another box rule.
  70     Finally, the line drawing escapes both draw from the current
  71     location to the beginning of the _input_ line - this works because
  72     the line length is negative, not moving the current point.
  73
  74 -- Escape: \L'l'
  75 -- Escape: \L'lg'
  76     Draw vertical lines.  Its parameters are similar to the `\l'
  77     escape, except that the default scaling indicator is `v'.  The
  78     movement is downwards for positive values, and upwards for
  79     negative values.  The default glyph is the box rule glyph,
  80     `\[br]'.  As with the vertical motion escapes, text processing
  81     blindly continues where the line ends.
  82
  83
  84          This is a \L'3v'test.
  85
  86     Here the result, produced with `grotty'.
  87
  88
  89          This is a
  90                    |
  91                    |
  92                    |test.
  93
  94
  95 -- Escape: \D'command arg ...'
  96     The `\D' escape provides a variety of drawing functions.  Note
  97     that on character devices, only vertical and horizontal lines are
  98     supported within `grotty'; other devices may only support a subset
  99     of the available drawing functions.
 100
 101     The default scaling indicator for all subcommands of `\D' is `m'
 102     for horizontal distances and `v' for vertical ones.  Exceptions
 103     are `\D'f ...'' and `\D't ...'' which use `u' as the default, and
 104     `\D'FX ...'' which arguments are treated similar to the `defcolor'
 105     request.
 106
 107    `\D'l DX DY''
 108          Draw a line from the current location to the relative point
 109          specified by (DX,DY), where positive values mean down and
 110          right, respectively.  The end point of the line is the new
 111          current location.
 112
 113          The following example is a macro for creating a box around a
 114          text string; for simplicity, the box margin is taken as a
 115          fixed value, 0.2m.
 116
 117
 118               .de BOX
 119               .  nr @wd \w'\\$1'
 120               \h'.2m'\
 121               \h'-.2m'\v'(.2m - \\n[rsb]u)'\
 122               \D'l 0 -(\\n[rst]u - \\n[rsb]u + .4m)'\
 123               \D'l (\\n[@wd]u + .4m) 0'\
 124               \D'l 0 (\\n[rst]u - \\n[rsb]u + .4m)'\
 125               \D'l -(\\n[@wd]u + .4m) 0'\
 126               \h'.2m'\v'-(.2m - \\n[rsb]u)'\
 127               \\$1\
 128               \h'.2m'
 129               ..
 130
 131          First, the width of the string is stored in register `@wd'.
 132          Then, four lines are drawn to form a box, properly offset by
 133          the box margin.  The registers `rst' and `rsb' are set by the
 134          `\w' escape, containing the largest height and depth of the
 135          whole string.
 136
 137    `\D'c D''
 138          Draw a circle with a diameter of D with the leftmost point at
 139          the current position.  After drawing, the current location is
 140          positioned at the rightmost point of the circle.
 141
 142    `\D'C D''
 143          Draw a solid circle with the same parameters and behaviour as
 144          an outlined circle.  No outline is drawn.
 145
 146    `\D'e X Y''
 147          Draw an ellipse with a horizontal diameter of X and a vertical
 148          diameter of Y with the leftmost point at the current position.
 149          After drawing, the current location is positioned at the
 150          rightmost point of the ellipse.
 151
 152    `\D'E X Y''
 153          Draw a solid ellipse with the same parameters and behaviour
 154          as an outlined ellipse.  No outline is drawn.
 155
 156    `\D'a DX1 DY1 DX2 DY2''
 157          Draw an arc clockwise from the current location through the
 158          two specified relative locations (DX1,DY1) and (DX2,DY2).
 159          The coordinates of the first point are relative to the
 160          current position, and the coordinates of the second point are
 161          relative to the first point.  After drawing, the current
 162          position is moved to the final point of the arc.
 163
 164    `\D'~ DX1 DY1 DX2 DY2 ...''
 165          Draw a spline from the current location to the relative point
 166          (DX1,DY1) and then to (DX2,DY2), and so on.  The current
 167          position is moved to the terminal point of the drawn curve.
 168
 169    `\D'f N''
 170          Set the shade of gray to be used for filling solid objects
 171          to N; N must be an integer between 0 and 1000, where 0
 172          corresponds solid white and 1000 to solid black, and values
 173          in between correspond to intermediate shades of gray.  This
 174          applies only to solid circles, solid ellipses, and solid
 175          polygons.  By default, a level of 1000 is used.
 176
 177          Despite of being silly, the current point is moved
 178          horizontally to the right by N.
 179
 180          Don't use this command!  It has the serious drawback that it
 181          will be always rounded to the next integer multiple of the
 182          horizontal resolution (the value of the `hor' keyword in the
 183          `DESC' file).  Use `\M' (*note Colors::) or `\D'Fg ...''
 184          instead.
 185
 186    `\D'p DX1 DY1 DX2 DY2 ...''
 187          Draw a polygon from the current location to the relative
 188          position (DX1,DY1) and then to (DX2,DY2) and so on.  When the
 189          specified data points are exhausted, a line is drawn back to
 190          the starting point.  The current position is changed by
 191          adding the sum of all arguments with odd index to the actual
 192          horizontal position and the even ones to the vertical
 193          position.
 194
 195    `\D'P DX1 DY1 DX2 DY2 ...''
 196          Draw a solid polygon with the same parameters and behaviour
 197          as an outlined polygon.  No outline is drawn.
 198
 199          Here a better variant of the box macro to fill the box with
 200          some color.  Note that the box must be drawn before the text
 201          since colors in `gtroff' are not transparent; the filled
 202          polygon would hide the text completely.
 203
 204
 205               .de BOX
 206               .  nr @wd \w'\\$1'
 207               \h'.2m'\
 208               \h'-.2m'\v'(.2m - \\n[rsb]u)'\
 209               \M[lightcyan]\
 210               \D'P 0 -(\\n[rst]u - \\n[rsb]u + .4m) \
 211                    (\\n[@wd]u + .4m) 0 \
 212                    0 (\\n[rst]u - \\n[rsb]u + .4m) \
 213                    -(\\n[@wd]u + .4m) 0'\
 214               \h'.2m'\v'-(.2m - \\n[rsb]u)'\
 215               \M[]\
 216               \\$1\
 217               \h'.2m'
 218               ..
 219
 220    `\D't N''
 221          Set the current line thickness to N machine units.  A value of
 222          zero selects the smallest available line thickness.  A
 223          negative value makes the line thickness proportional to the
 224          current point size (this is the default behaviour of AT&T
 225          `troff').
 226
 227          Despite of being silly, the current point is moved
 228          horizontally to the right by N.
 229
 230    `\D'FSCHEME COLOR_COMPONENTS''
 231          Change current fill color.  SCHEME is a single letter
 232          denoting the color scheme: `r' (rgb), `c' (cmy), `k' (cmyk),
 233          `g' (gray), or `d' (default color).  The color components use
 234          exactly the same syntax as in the `defcolor' request (*note
 235          Colors::); the command `\D'Fd'' doesn't take an argument.
 236
 237          _No_ position changing!
 238
 239          Examples:
 240
 241
 242          \D'Fg .3'      \" same gray as \D'f 700' \D'Fr #0000ff' \"
 243          blue
 244
 245   *Note Graphics Commands::.
 246
 247 -- Escape: \b'string'
 248     "Pile" a sequence of glyphs vertically, and center it vertically
 249     on the current line.  Use it to build large brackets and braces.
 250
 251     Here an example how to create a large opening brace:
 252
 253
 254          \b'\[lt]\[bv]\[lk]\[bv]\[lb]'
 255
 256     The first glyph is on the top, the last glyph in STRING is at the
 257     bottom.  Note that `gtroff' separates the glyphs vertically by 1m,
 258     and the whole object is centered 0.5m above the current baseline;
 259     the largest glyph width is used as the width for the whole object.
 260     This rather unflexible positioning algorithm doesn't work with
 261     `-Tdvi' since the bracket pieces vary in height for this device.
 262     Instead, use the `eqn' preprocessor.
 263
 264     *Note Manipulating Spacing::, how to adjust the vertical spacing
 265     with the `\x' escape.
 266
 267
 268File: groff,  Node: Traps,  Next: Diversions,  Prev: Drawing Requests,  Up: gtroff Reference
 269
 2705.24 Traps
 271==========
 272
 273"Traps" are locations, which, when reached, call a specified macro.
 274These traps can occur at a given location on the page, at a given
 275location in the current diversion, at a blank line, after a certain
 276number of input lines, or at the end of input.
 277
 278   Setting a trap is also called "planting".  It is also said that a
 279trap is "sprung" if the associated macro is executed.
 280
 281* Menu:
 282
 283* Page Location Traps::
 284* Diversion Traps::
 285* Input Line Traps::
 286* Blank Line Traps::
 287* End-of-input Traps::
 288
 289
 290File: groff,  Node: Page Location Traps,  Next: Diversion Traps,  Prev: Traps,  Up: Traps
 291
 2925.24.1 Page Location Traps
 293--------------------------
 294
 295"Page location traps" perform an action when `gtroff' reaches or passes
 296a certain vertical location on the page.  Page location traps have a
 297variety of purposes, including:
 298
 299   * setting headers and footers
 300
 301   * setting body text in multiple columns
 302
 303   * setting footnotes
 304
 305 -- Request: .vpt flag
 306 -- Register: \n[.vpt]
 307     Enable vertical position traps if FLAG is non-zero, or disables
 308     them otherwise.  Vertical position traps are traps set by the `wh'
 309     or `dt' requests.  Traps set by the `it' request are not vertical
 310     position traps.  The parameter that controls whether vertical
 311     position traps are enabled is global.  Initially vertical position
 312     traps are enabled.  The current setting of this is available in the
 313     `.vpt' read-only number register.
 314
 315     Note that a page can't be ejected if `vpt' is set to zero.
 316
 317 -- Request: .wh dist [macro]
 318     Set a page location trap.  Non-negative values for DIST set the
 319     trap relative to the top of the page; negative values set the trap
 320     relative to the bottom of the page.  Default scaling indicator is
 321     `v'.
 322
 323     MACRO is the name of the macro to execute when the trap is sprung.
 324     If MACRO is missing, remove the first trap (if any) at DIST.
 325
 326     The following is a simple example of how many macro packages set
 327     headers and footers.
 328
 329
 330          .de hd                \" Page header
 331          '  sp .5i
 332          .  tl 'Title''date'
 333          '  sp .3i
 334          ..
 335          .
 336          .de fo                \" Page footer
 337          '  sp 1v
 338          .  tl ''%''
 339          '  bp
 340          ..
 341          .
 342          .wh 0   hd            \" trap at top of the page
 343          .wh -1i fo            \" trap one inch from bottom
 344
 345     A trap at or below the bottom of the page is ignored; it can be
 346     made active by either moving it up or increasing the page length
 347     so that the trap is on the page.
 348
 349     It is possible to have more than one trap at the same location; to
 350     do so, the traps must be defined at different locations, then
 351     moved together with the `ch' request; otherwise the second trap
 352     would replace the first one.  Earlier defined traps hide later
 353     defined traps if moved to the same position (the many empty lines
 354     caused by the `bp' request are omitted in the following example):
 355
 356
 357          .de a
 358          .  nop a
 359          ..
 360          .de b
 361          .  nop b
 362          ..
 363          .de c
 364          .  nop c
 365          ..
 366          .
 367          .wh 1i a
 368          .wh 2i b
 369          .wh 3i c
 370          .bp
 371              => a b c
 372
 373
 374          .ch b 1i
 375          .ch c 1i
 376          .bp
 377              => a
 378
 379
 380          .ch a 0.5i
 381          .bp
 382              => a b
 383
 384
 385 -- Register: \n[.t]
 386     A read-only number register holding the distance to the next trap.
 387
 388     If there are no traps between the current position and the bottom
 389     of the page, it contains the distance to the page bottom.  In a
 390     diversion, the distance to the page bottom is infinite (the
 391     returned value is the biggest integer which can be represented in
 392     `groff') if there are no diversion traps.
 393
 394 -- Request: .ch macro [dist]
 395     Change the location of a trap.  The first argument is the name of
 396     the macro to be invoked at the trap, and the second argument is
 397     the new location for the trap (note that the parameters are
 398     specified in opposite order as in the `wh' request).  This is
 399     useful for building up footnotes in a diversion to allow more
 400     space at the bottom of the page for them.
 401
 402     Default scaling indicator for DIST is `v'.  If DIST is missing,
 403     the trap is removed.
 404
 405
 406 -- Register: \n[.ne]
 407     The read-only number register `.ne' contains the amount of space
 408     that was needed in the last `ne' request that caused a trap to be
 409     sprung.  Useful in conjunction with the `.trunc' register.  *Note
 410     Page Control::, for more information.
 411
 412     Since the `.ne' register is only set by traps it doesn't make much
 413     sense to use it outside of trap macros.
 414
 415 -- Register: \n[.trunc]
 416     A read-only register containing the amount of vertical space
 417     truncated by the most recently sprung vertical position trap, or,
 418     if the trap was sprung by an `ne' request, minus the amount of
 419     vertical motion produced by the `ne' request.  In other words, at
 420     the point a trap is sprung, it represents the difference of what
 421     the vertical position would have been but for the trap, and what
 422     the vertical position actually is.
 423
 424     Since the `.trunc' register is only set by traps it doesn't make
 425     much sense to use it outside of trap macros.
 426
 427 -- Register: \n[.pe]
 428     A read-only register which is set to 1 while a page is ejected with
 429     the `bp' request (or by the end of input).
 430
 431     Outside of traps this register is always zero.  In the following
 432     example, only the second call to `x' is caused by `bp'.
 433
 434
 435          .de x
 436          \&.pe=\\n[.pe]
 437          .br
 438          ..
 439          .wh 1v x
 440          .wh 4v x
 441          A line.
 442          .br
 443          Another line.
 444          .br
 445              => A line.
 446                 .pe=0
 447                 Another line.
 448
 449                 .pe=1
 450
 451
 452   An important fact to consider while designing macros is that
 453diversions and traps do not interact normally.  For example, if a trap
 454invokes a header macro (while outputting a diversion) which tries to
 455change the font on the current page, the effect will not be visible
 456before the diversion has completely been printed (except for input
 457protected with `\!' or `\?') since the data in the diversion is already
 458formatted.  In most cases, this is not the expected behaviour.
 459
 460
 461File: groff,  Node: Diversion Traps,  Next: Input Line Traps,  Prev: Page Location Traps,  Up: Traps
 462
 4635.24.2 Diversion Traps
 464----------------------
 465
 466 -- Request: .dt [dist macro]
 467     Set a trap _within_ a diversion.  DIST is the location of the trap
 468     (identical to the `wh' request; default scaling indicator is `v')
 469     and MACRO is the name of the macro to be invoked.  If called
 470     without arguments, the diversion trap is removed.
 471
 472     Note that there exists only a single diversion trap.
 473
 474     The number register `.t' still works within diversions.  *Note
 475     Diversions::, for more information.
 476
 477
 478File: groff,  Node: Input Line Traps,  Next: Blank Line Traps,  Prev: Diversion Traps,  Up: Traps
 479
 4805.24.3 Input Line Traps
 481-----------------------
 482
 483 -- Request: .it n macro
 484 -- Request: .itc n macro
 485     Set an input line trap.  N is the number of lines of input which
 486     may be read before springing the trap, MACRO is the macro to be
 487     invoked.  Request lines are not counted as input lines.
 488
 489     For example, one possible use is to have a macro which prints the
 490     next N lines in a bold font.
 491
 492
 493          .de B
 494          .  it \\$1 B-end
 495          .  ft B
 496          ..
 497          .
 498          .de B-end
 499          .  ft R
 500          ..
 501
 502     The `itc' request is identical except that an interrupted text
 503     line (ending with `\c') is not counted as a separate line.
 504
 505     Both requests are associated with the current environment (*note
 506     Environments::); switching to another environment disables the
 507     current input trap, and going back reactivates it, restoring the
 508     number of already processed lines.
 509
 510
 511File: groff,  Node: Blank Line Traps,  Next: End-of-input Traps,  Prev: Input Line Traps,  Up: Traps
 512
 5135.24.4 Blank Line Traps
 514-----------------------
 515
 516 -- Request: .blm macro
 517     Set a blank line trap.  `gtroff' executes MACRO when it encounters
 518     a blank line in the input file.
 519
 520
 521File: groff,  Node: End-of-input Traps,  Prev: Blank Line Traps,  Up: Traps
 522
 5235.24.5 End-of-input Traps
 524-------------------------
 525
 526 -- Request: .em macro
 527     Set a trap at the end of input.  MACRO is executed after the last
 528     line of the input file has been processed.
 529
 530     For example, if the document had to have a section at the bottom
 531     of the last page for someone to approve it, the `em' request could
 532     be used.
 533
 534
 535          .de approval
 536          .  ne 5v
 537          .  sp |(\\n[.t] - 6v)
 538          .  in +4i
 539          .  lc _
 540          .  br
 541          Approved:\t\a
 542          .  sp
 543          Date:\t\t\a
 544          ..
 545          .
 546          .em approval
 547
 548
 549
 550File: groff,  Node: Diversions,  Next: Environments,  Prev: Traps,  Up: gtroff Reference
 551
 5525.25 Diversions
 553===============
 554
 555In `gtroff' it is possible to "divert" text into a named storage area.
 556Due to the similarity to defining macros it is sometimes said to be
 557stored in a macro.  This is used for saving text for output at a later
 558time, which is useful for keeping blocks of text on the same page,
 559footnotes, tables of contents, and indices.
 560
 561   For orthogonality it is said that `gtroff' is in the "top-level
 562diversion" if no diversion is active (i.e., the data is diverted to the
 563output device).
 564
 565 -- Request: .di macro
 566 -- Request: .da macro
 567     Begin a diversion.  Like the `de' request, it takes an argument of
 568     a macro name to divert subsequent text into.  The `da' macro
 569     appends to an existing diversion.
 570
 571     `di' or `da' without an argument ends the diversion.
 572
 573 -- Request: .box macro
 574 -- Request: .boxa macro
 575     Begin (or appends to) a diversion like the `di' and `da' requests.
 576     The difference is that `box' and `boxa' do not include a
 577     partially-filled line in the diversion.
 578
 579     Compare this:
 580
 581
 582          Before the box.
 583          .box xxx
 584          In the box.
 585          .br
 586          .box
 587          After the box.
 588          .br
 589              => Before the box.  After the box.
 590          .xxx
 591              => In the box.
 592
 593     with this:
 594
 595
 596          Before the diversion.
 597          .di yyy
 598          In the diversion.
 599          .br
 600          .di
 601          After the diversion.
 602          .br
 603              => After the diversion.
 604          .yyy
 605              => Before the diversion.  In the diversion.
 606
 607     `box' or `boxa' without an argument ends the diversion.
 608
 609 -- Register: \n[.z]
 610 -- Register: \n[.d]
 611     Diversions may be nested.  The read-only number register `.z'
 612     contains the name of the current diversion (this is a string-valued
 613     register).  The read-only number register `.d' contains the current
 614     vertical place in the diversion.  If not in a diversion it is the
 615     same as register `nl'.
 616
 617 -- Register: \n[.h]
 618     The "high-water mark" on the current page.  It corresponds to the
 619     text baseline of the lowest line on the page.  This is a read-only
 620     register.
 621
 622
 623          .tm .h==\n[.h], nl==\n[nl]
 624              => .h==0, nl==-1
 625          This is a test.
 626          .br
 627          .sp 2
 628          .tm .h==\n[.h], nl==\n[nl]
 629              => .h==40, nl==120
 630
 631     As can be seen in the previous example, empty lines are not
 632     considered in the return value of the `.h' register.
 633
 634 -- Register: \n[dn]
 635 -- Register: \n[dl]
 636     After completing a diversion, the read-write number registers `dn'
 637     and `dl' contain the vertical and horizontal size of the diversion.
 638     Note that only the just processed lines are counted: For the
 639     computation of `dn' and `dl', the requests `da' and `boxa' are
 640     handled as if `di' and `box' had been used - lines which have been
 641     already stored in a macro are not taken into account.
 642
 643
 644          .\" Center text both horizontally & vertically
 645          .
 646          .\" Enclose macro definitions in .eo and .ec
 647          .\" to avoid the doubling of the backslash
 648          .eo
 649          .\" macro .(c starts centering mode
 650          .de (c
 651          .  br
 652          .  ev (c
 653          .  evc 0
 654          .  in 0
 655          .  nf
 656          .  di @c
 657          ..
 658
 659
 660          .\" macro .)c terminates centering mode
 661          .de )c
 662          .  br
 663          .  ev
 664          .  di
 665          .  nr @s (((\n[.t]u - \n[dn]u) / 2u) - 1v)
 666          .  sp \n[@s]u
 667          .  ce 1000
 668          .  @c
 669          .  ce 0
 670          .  sp \n[@s]u
 671          .  br
 672          .  fi
 673          .  rr @s
 674          .  rm @s
 675          .  rm @c
 676          ..
 677          .\" End of macro definitions, restore escape mechanism
 678          .ec
 679
 680
 681 -- Escape: \!
 682 -- Escape: \?anything\?
 683     Prevent requests, macros, and escapes from being interpreted when
 684     read into a diversion.  Both escapes take the given text and
 685     "transparently" embed it into the diversion.  This is useful for
 686     macros which shouldn't be invoked until the diverted text is
 687     actually output.
 688
 689     The `\!' escape transparently embeds text up to and including the
 690     end of the line.  The `\?' escape transparently embeds text until
 691     the next occurrence of the `\?' escape.  Example:
 692
 693
 694          \?ANYTHING\?
 695
 696     ANYTHING may not contain newlines; use `\!'  to embed newlines in
 697     a diversion.  The escape sequence `\?' is also recognized in copy
 698     mode and turned into a single internal code; it is this code that
 699     terminates ANYTHING.  Thus the following example prints 4.
 700
 701
 702          .nr x 1
 703          .nf
 704          .di d
 705          \?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
 706          .di
 707          .nr x 2
 708          .di e
 709          .d
 710          .di
 711          .nr x 3
 712          .di f
 713          .e
 714          .di
 715          .nr x 4
 716          .f
 717
 718     Both escapes read the data in copy mode.
 719
 720     If `\!' is used in the top-level diversion, its argument is
 721     directly embedded into the `gtroff' intermediate output.  This can
 722     be used for example to control a postprocessor which processes the
 723     data before it is sent to the device driver.
 724
 725     The `\?' escape used in the top-level diversion produces no output
 726     at all; its argument is simply ignored.
 727
 728 -- Request: .output string
 729     Emit STRING directly to the `gtroff' intermediate output (subject
 730     to copy-mode interpretation); this is similar to `\!' used at the
 731     top level.  An initial double quote in STRING is stripped off to
 732     allow initial blanks.
 733
 734     This request can't be used before the first page has started - if
 735     you get an error, simply insert `.br' before the `output' request.
 736
 737     Without argument, `output' is ignored.
 738
 739     Use with caution!  It is normally only needed for mark-up used by a
 740     postprocessor which does something with the output before sending
 741     it to the output device, filtering out STRING again.
 742
 743 -- Request: .asciify div
 744     "Unformat" the diversion specified by DIV in such a way that ASCII
 745     characters, characters translated with the `trin' request, space
 746     characters, and some escape sequences that were formatted and
 747     diverted are treated like ordinary input characters when the
 748     diversion is reread.  It can be also used for gross hacks; for
 749     example, the following sets register `n' to 1.
 750
 751
 752          .tr @.
 753          .di x
 754          @nr n 1
 755          .br
 756          .di
 757          .tr @@
 758          .asciify x
 759          .x
 760
 761     *Note Copy-in Mode::.
 762
 763 -- Request: .unformat div
 764     Like `asciify', unformat the specified diversion.  However,
 765     `unformat' only unformats spaces and tabs between words.
 766     Unformatted tabs are treated as input tokens, and spaces are
 767     stretchable again.
 768
 769     The vertical size of lines is not preserved; glyph information
 770     (font, font size, space width, etc.) is retained.
 771
 772
 773File: groff,  Node: Environments,  Next: Suppressing output,  Prev: Diversions,  Up: gtroff Reference
 774
 7755.26 Environments
 776=================
 777
 778It happens frequently that some text should be printed in a certain
 779format regardless of what may be in effect at the time, for example, in
 780a trap invoked macro to print headers and footers.  To solve this
 781`gtroff' processes text in "environments".  An environment contains
 782most of the parameters that control text processing.  It is possible to
 783switch amongst these environments; by default `gtroff' processes text
 784in environment 0.  The following is the information kept in an
 785environment.
 786
 787   * font parameters (size, family, style, glyph height and slant, space
 788     and sentence space size)
 789
 790   * page parameters (line length, title length, vertical spacing, line
 791     spacing, indentation, line numbering, centering, right-justifying,
 792     underlining, hyphenation data)
 793
 794   * fill and adjust mode
 795
 796   * tab stops, tab and leader characters, escape character, no-break
 797     and hyphen indicators, margin character data
 798
 799   * partially collected lines
 800
 801   * input traps
 802
 803   * drawing and fill colours
 804
 805   These environments may be given arbitrary names (see *Note
 806Identifiers::, for more info).  Old versions of `troff' only had
 807environments named `0', `1', and `2'.
 808
 809 -- Request: .ev [env]
 810 -- Register: \n[.ev]
 811     Switch to another environment.  The argument ENV is the name of
 812     the environment to switch to.  With no argument, `gtroff' switches
 813     back to the previous environment.  There is no limit on the number
 814     of named environments; they are created the first time that they
 815     are referenced.  The `.ev' read-only register contains the name or
 816     number of the current environment.  This is a string-valued
 817     register.
 818
 819     Note that a call to `ev' (with argument) pushes the previously
 820     active environment onto a stack.  If, say, environments `foo',
 821     `bar', and `zap' are called (in that order), the first `ev'
 822     request without parameter switches back to environment `bar'
 823     (which is popped off the stack), and a second call switches back
 824     to environment `foo'.
 825
 826     Here is an example:
 827
 828
 829          .ev footnote-env
 830          .fam N
 831          .ps 6
 832          .vs 8
 833          .ll -.5i
 834          .ev
 835
 836          ...
 837
 838          .ev footnote-env
 839          \(dg Note the large, friendly letters.
 840          .ev
 841
 842
 843 -- Request: .evc env
 844     Copy the environment ENV into the current environment.
 845
 846     The following environment data is not copied:
 847
 848        * Partially filled lines.
 849
 850        * The status whether the previous line was interrupted.
 851
 852        * The number of lines still to center, or to right-justify, or
 853          to underline (with or without underlined spaces); they are
 854          set to zero.
 855
 856        * The status whether a temporary indentation is active.
 857
 858        * Input traps and its associated data.
 859
 860        * Line numbering mode is disabled; it can be reactivated with
 861          `.nm +0'.
 862
 863        * The number of consecutive hyphenated lines (set to zero).
 864
 865 -- Register: \n[.w]
 866 -- Register: \n[.cht]
 867 -- Register: \n[.cdp]
 868 -- Register: \n[.csk]
 869     The `\n[.w]' register contains the width of the last glyph added
 870     to the current environment.
 871
 872     The `\n[.cht]' register contains the height of the last glyph
 873     added to the current environment.
 874
 875     The `\n[.cdp]' register contains the depth of the last glyph added
 876     to the current environment.  It is positive for glyphs extending
 877     below the baseline.
 878
 879     The `\n[.csk]' register contains the "skew" (how far to the right
 880     of the glyph's center that `gtroff' should place an accent) of the
 881     last glyph added to the current environment.
 882
 883 -- Register: \n[.n]
 884     The `\n[.n]' register contains the length of the previous output
 885     line in the current environment.
 886
 887
 888File: groff,  Node: Suppressing output,  Next: Colors,  Prev: Environments,  Up: gtroff Reference
 889
 8905.27 Suppressing output
 891=======================
 892
 893 -- Escape: \Onum
 894     Disable or enable output depending on the value of NUM:
 895
 896    `\O0'
 897          Disable any glyphs from being emitted to the device driver,
 898          provided that the escape occurs at the outer level (see
 899          `\O[3]' and `\O[4]').  Motion is not suppressed so
 900          effectively `\O[0]' means _pen up_.
 901
 902    `\O1'
 903          Enable output of glyphs, provided that the escape occurs at
 904          the outer level.
 905
 906     `\O0' and `\O1' also reset the four registers `opminx', `opminy',
 907     `opmaxx', and `opmaxy' to -1.  *Note Register Index::.  These four
 908     registers mark the top left and bottom right hand corners of a box
 909     which encompasses all written glyphs.
 910
 911     For example the input text:
 912
 913
 914          Hello \O[0]world \O[1]this is a test.
 915
 916     produces the following output:
 917
 918
 919          Hello       this is a test.
 920
 921    `\O2'
 922          Provided that the escape occurs at the outer level, enable
 923          output of glyphs and also write out to `stderr' the page
 924          number and four registers encompassing the glyphs previously
 925          written since the last call to `\O'.
 926
 927    `\O3'
 928          Begin a nesting level.  At start-up, `gtroff' is at outer
 929          level.
 930
 931    `\O4'
 932          End a nesting level.
 933
 934    `\O[5PFILENAME]'
 935          This escape is `grohtml' specific.  Provided that this escape
 936          occurs at the outer nesting level write the `filename' to
 937          `stderr'.  The position of the image, P, must be specified
 938          and must be one of `l', `r', `c', or `i' (left, right,
 939          centered, inline).  FILENAME will be associated with the
 940          production of the next inline image.
 941
 942
 943File: groff,  Node: Colors,  Next: I/O,  Prev: Suppressing output,  Up: gtroff Reference
 944
 9455.28 Colors
 946===========
 947
 948 -- Request: .color [n]
 949 -- Register: \n[.color]
 950     If N is missing or non-zero, activate colors (this is the default);
 951     otherwise, turn it off.
 952
 953     The read-only number register `.color' is 1 if colors are active,
 954     0 otherwise.
 955
 956     Internally, `color' sets a global flag; it does not produce a
 957     token.  Similar to the `cp' request, you should use it at the
 958     beginning of your document to control color output.
 959
 960     Colors can be also turned off with the `-c' command line option.
 961
 962 -- Request: .defcolor ident scheme color_components
 963     Define color with name IDENT.  SCHEME can be one of  the following
 964     values: `rgb' (three components), `cmy' (three components), `cmyk'
 965     (four components), and `gray' or `grey' (one component).
 966
 967     Color components can be given either as a hexadecimal string or as
 968     positive decimal integers in the range 0-65535.  A hexadecimal
 969     string contains all color components concatenated.  It must start
 970     with either `#' or `##'; the former specifies hex values in the
 971     range 0-255 (which are internally multiplied by 257), the latter
 972     in the range 0-65535.  Examples: `#FFC0CB' (pink), `##ffff0000ffff'
 973     (magenta).  The default color name value is device-specific
 974     (usually black).  It is possible that the default color for `\m'
 975     and `\M' is not identical.
 976
 977     A new scaling indicator `f' has been introduced which multiplies
 978     its value by 65536; this makes it convenient to specify color
 979     components as fractions in the range 0 to 1 (1f equals 65536u).
 980     Example:
 981
 982
 983          .defcolor darkgreen rgb 0.1f 0.5f 0.2f
 984
 985     Note that `f' is the default scaling indicator for the `defcolor'
 986     request, thus the above statement is equivalent to
 987
 988
 989          .defcolor darkgreen rgb 0.1 0.5 0.2
 990
 991
 992 -- Request: .gcolor [color]
 993 -- Escape: \mc
 994 -- Escape: \m(co
 995 -- Escape: \m[color]
 996 -- Register: \n[.m]
 997     Set (glyph) drawing color.  The following examples show how to
 998     turn the next four words red.
 999
1000
1001          .gcolor red
1002          these are in red
1003          .gcolor
1004          and these words are in black.
1005
1006
1007          \m[red]these are in red\m[] and these words are in black.
1008
1009     The escape `\m[]' returns to the previous color, as does a call to
1010     `gcolor' without an argument.
1011
1012     The name of the current drawing color is available in the
1013     read-only, string-valued number register `.m'.
1014
1015     The drawing color is associated with the current environment
1016     (*note Environments::).
1017
1018     Note that `\m' doesn't produce an input token in `gtroff'.  As a
1019     consequence, it can be used in requests like `mc' (which expects a
1020     single character as an argument) to change the color on the fly:
1021
1022
1023          .mc \m[red]x\m[]
1024
1025
1026 -- Request: .fcolor [color]
1027 -- Escape: \Mc
1028 -- Escape: \M(co
1029 -- Escape: \M[color]
1030 -- Register: \n[.M]
1031     Set fill (background) color for filled objects drawn with the
1032     `\D'...'' commands.
1033
1034     A red ellipse can be created with the following code:
1035
1036
1037          \M[red]\h'0.5i'\D'E 2i 1i'\M[]
1038
1039     The escape `\M[]' returns to the previous fill color, as does a
1040     call to `fcolor' without an argument.
1041
1042     The name of the current fill (background) color is available in the
1043     read-only, string-valued number register `.M'.
1044
1045     The fill color is associated with the current environment (*note
1046     Environments::).
1047
1048     Note that `\M' doesn't produce an input token in `gtroff'.
1049
1050
1051File: groff,  Node: I/O,  Next: Postprocessor Access,  Prev: Colors,  Up: gtroff Reference
1052
10535.29 I/O
1054========
1055
1056`gtroff' has several requests for including files:
1057
1058 -- Request: .so file
1059     Read in the specified FILE and includes it in place of the `so'
1060     request.  This is quite useful for large documents, e.g. keeping
1061     each chapter in a separate file.  *Note gsoelim::, for more
1062     information.
1063
1064     Since `gtroff' replaces the `so' request with the contents of
1065     `file', it makes a difference whether the data is terminated with
1066     a newline or not: Assuming that file `xxx' contains the word `foo'
1067     without a final newline, this
1068
1069
1070          This is
1071          .so xxx
1072          bar
1073
1074     yields `This is foobar'.
1075
1076     The search path for FILE can be controlled with the `-I' command
1077     line option.
1078
1079 -- Request: .pso command
1080     Read the standard output from the specified COMMAND and includes
1081     it in place of the `pso' request.
1082
1083     This request causes an error if used in safer mode (which is the
1084     default).  Use `groff''s or `troff''s `-U' option to activate
1085     unsafe mode.
1086
1087     The comment regarding a final newline for the `so' request is valid
1088     for `pso' also.
1089
1090 -- Request: .mso file
1091     Identical to the `so' request except that `gtroff' searches for
1092     the specified FILE in the same directories as macro files for the
1093     the `-m' command line option.  If the file name to be included has
1094     the form `NAME.tmac' and it isn't found, `mso' tries to include
1095     `tmac.NAME' and vice versa.
1096
1097 -- Request: .trf file
1098 -- Request: .cf file
1099     Transparently output the contents of FILE.  Each line is output as
1100     if it were preceded by `\!'; however, the lines are not subject to
1101     copy mode interpretation.  If the file does not end with a newline,
1102     then a newline is added (`trf' only).  For example, to define a
1103     macro `x' containing the contents of file `f', use
1104
1105
1106          .di x
1107          .trf f
1108          .di
1109
1110     Both `trf' and `cf', when used in a diversion, embeds an object in
1111     the diversion which, when reread, causes the contents of FILE to
1112     be transparently copied through to the output.  In UNIX `troff',
1113     the contents of FILE is immediately copied through to the output
1114     regardless of whether there is a current diversion; this behaviour
1115     is so anomalous that it must be considered a bug.
1116
1117     While `cf' copies the contents of FILE completely unprocessed,
1118     `trf' disallows characters such as NUL that are not valid `gtroff'
1119     input characters (*note Identifiers::).
1120
1121     Both requests cause a line break.
1122
1123 -- Request: .nx [file]
1124     Force `gtroff' to continue processing of the file specified as an
1125     argument.  If no argument is given, immediately jump to the end of
1126     file.
1127
1128 -- Request: .rd [prompt [arg1 arg2 ...]]
1129     Read from standard input, and include what is read as though it
1130     were part of the input file.  Text is read until a blank line is
1131     encountered.
1132
1133     If standard input is a TTY input device (keyboard), write PROMPT
1134     to standard error, followed by a colon (or send BEL for a beep if
1135     no argument is given).
1136
1137     Arguments after PROMPT are available for the input.  For example,
1138     the line
1139
1140
1141          .rd data foo bar
1142
1143     with the input `This is \$2.' prints
1144
1145
1146          This is bar.
1147
1148
1149   Using the `nx' and `rd' requests, it is easy to set up form letters.
1150The form letter template is constructed like this, putting the
1151following lines into a file called `repeat.let':
1152
1153
1154     .ce
1155     \*(td
1156     .sp 2
1157     .nf
1158     .rd
1159     .sp
1160     .rd
1161     .fi
1162     Body of letter.
1163     .bp
1164     .nx repeat.let
1165
1166When this is run, a file containing the following lines should be
1167redirected in.  Note that requests included in this file are executed
1168as though they were part of the form letter.  The last block of input
1169is the `ex' request which tells `groff' to stop processing.  If this
1170was not there, `groff' would not know when to stop.
1171
1172
1173     Trent A. Fisher
1174     708 NW 19th Av., #202
1175     Portland, OR  97209
1176
1177     Dear Trent,
1178
1179     Len Adollar
1180     4315 Sierra Vista
1181     San Diego, CA  92103
1182
1183     Dear Mr. Adollar,
1184
1185     .ex
1186
1187 -- Request: .pi pipe
1188     Pipe the output of `gtroff' to the shell command(s) specified by
1189     PIPE.  This request must occur before `gtroff' has a chance to
1190     print anything.
1191
1192     `pi' causes an error if used in safer mode (which is the default).
1193     Use `groff''s or `troff''s `-U' option to activate unsafe mode.
1194
1195     Multiple calls to `pi' are allowed, acting as a chain.  For
1196     example,
1197
1198
1199          .pi foo
1200          .pi bar
1201          ...
1202
1203     is the same as `.pi foo | bar'.
1204
1205     Note that the intermediate output format of `gtroff' is piped to
1206     the specified commands.  Consequently, calling `groff' without the
1207     `-Z' option normally causes a fatal error.
1208
1209 -- Request: .sy cmds
1210 -- Register: \n[systat]
1211     Execute the shell command(s) specified by CMDS.  The output is not
1212     saved anyplace, so it is up to the user to do so.
1213
1214     This request causes an error if used in safer mode (which is the
1215     default).  Use `groff''s or `troff''s `-U' option to activate
1216     unsafe mode.
1217
1218     For example, the following code fragment introduces the current
1219     time into a document:
1220
1221
1222          .sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\
1223                       (localtime(time))[2,1,0]' > /tmp/x\n[$$]
1224          .so /tmp/x\n[$$]
1225          .sy rm /tmp/x\n[$$]
1226          \nH:\nM:\nS
1227
1228     Note that this works by having the `perl' script (run by `sy')
1229     print out the `nr' requests which set the number registers `H',
1230     `M', and `S', and then reads those commands in with the `so'
1231     request.
1232
1233     For most practical purposes, the number registers `seconds',
1234     `minutes', and `hours' which are initialized at start-up of
1235     `gtroff' should be sufficient.  Use the `af' request to get a
1236     formatted output:
1237
1238
1239          .af hours 00
1240          .af minutes 00
1241          .af seconds 00
1242          \n[hours]:\n[minutes]:\n[seconds]
1243
1244     The `systat' read-write number register contains the return value
1245     of the `system()' function executed by the last `sy' request.
1246
1247 -- Request: .open stream file
1248 -- Request: .opena stream file
1249     Open the specified FILE for writing and associates the specified
1250     STREAM with it.
1251
1252     The `opena' request is like `open', but if the file exists, append
1253     to it instead of truncating it.
1254
1255     Both `open' and `opena' cause an error if used in safer mode
1256     (which is the default).  Use `groff''s or `troff''s `-U' option to
1257     activate unsafe mode.
1258
1259 -- Request: .write stream data
1260 -- Request: .writec stream data
1261     Write to the file associated with the specified STREAM.  The
1262     stream must previously have been the subject of an open request.
1263     The remainder of the line is interpreted as the `ds' request reads
1264     its second argument: A leading `"' is stripped, and it is read in
1265     copy-in mode.
1266
1267     The `writec' request is like `write', but only `write' appends a
1268     newline to the data.
1269
1270 -- Request: .writem stream xx
1271     Write the contents of the macro or string XX to the file
1272     associated with the specified STREAM.
1273
1274     XX is read in copy mode, i.e., already formatted elements are
1275     ignored.  Consequently, diversions must be unformatted with the
1276     `asciify' request before calling `writem'.  Usually, this means a
1277     loss of information.
1278
1279 -- Request: .close stream
1280     Close the specified STREAM; the stream is no longer an acceptable
1281     argument to the `write' request.
1282
1283     Here a simple macro to write an index entry.
1284
1285
1286          .open idx test.idx
1287          .
1288          .de IX
1289          .  write idx \\n[%] \\$*
1290          ..
1291          .
1292          .IX test entry
1293          .
1294          .close idx
1295
1296
1297 -- Escape: \Ve
1298 -- Escape: \V(ev
1299 -- Escape: \V[env]
1300     Interpolate the contents of the specified environment variable ENV
1301     (one-character name E, two-character name EV) as returned by the
1302     function `getenv'.  `\V' is interpreted in copy-in mode.
1303
1304
1305File: groff,  Node: Postprocessor Access,  Next: Miscellaneous,  Prev: I/O,  Up: gtroff Reference
1306
13075.30 Postprocessor Access
1308=========================
1309
1310There are two escapes which give information directly to the
1311postprocessor.  This is particularly useful for embedding POSTSCRIPT
1312into the final document.
1313
1314 -- Escape: \X'xxx'
1315     Embeds its argument into the `gtroff' output preceded with `x X'.
1316
1317     The escapes `\&', `\)', `\%', and `\:' are ignored within `\X',
1318     `\ ' and `\~' are converted to single space characters.  All other
1319     escapes (except `\\' which produces a backslash) cause an error.
1320
1321     If the `use_charnames_in_special' keyword is set in the `DESC'
1322     file, special characters no longer cause an error; the name XX is
1323     represented as `\(XX)' in the `x X' output command.  Additionally,
1324     the backslash is represented as `\\'.
1325
1326     `use_charnames_in_special' is currently used by `grohtml' only.
1327
1328 -- Escape: \Yn
1329 -- Escape: \Y(nm
1330 -- Escape: \Y[name]
1331     This is approximately equivalent to `\X'\*[NAME]'' (one-character
1332     name N, two-character name NM).  However, the contents of the
1333     string or macro NAME are not interpreted; also it is permitted for
1334     NAME to have been defined as a macro and thus contain newlines (it
1335     is not permitted for the argument to `\X' to contain newlines).
1336     The inclusion of newlines requires an extension to the UNIX `troff'
1337     output format, and confuses drivers that do not know about this
1338     extension (*note Device Control Commands::).
1339
1340   *Note Output Devices::.
1341
1342
1343File: groff,  Node: Miscellaneous,  Next: Gtroff Internals,  Prev: Postprocessor Access,  Up: gtroff Reference
1344
13455.31 Miscellaneous
1346==================
1347
1348This section documents parts of `gtroff' which cannot (yet) be
1349categorized elsewhere in this manual.
1350
1351 -- Request: .nm [start [inc [space [indent]]]]
1352     Print line numbers.  START is the line number of the _next_ output
1353     line.  INC indicates which line numbers are printed.  For example,
1354     the value 5 means to emit only line numbers which are multiples
1355     of 5; this defaults to 1.  SPACE is the space to be left between
1356     the number and the text; this defaults to one digit space.  The
1357     fourth argument is the indentation of the line numbers, defaulting
1358     to zero.  Both SPACE and INDENT are given as multiples of digit
1359     spaces; they can be negative also.  Without any arguments, line
1360     numbers are turned off.
1361
1362     `gtroff' reserves three digit spaces for the line number (which is
1363     printed right-justified) plus the amount given by INDENT; the
1364     output lines are concatenated to the line numbers, separated by
1365     SPACE, and _without_ reducing the line length.  Depending on the
1366     value of the horizontal page offset (as set with the `po'
1367     request), line numbers which are longer than the reserved space
1368     stick out to the left, or the whole line is moved to the right.
1369
1370     Parameters corresponding to missing arguments are not changed; any
1371     non-digit argument (to be more precise, any argument starting with
1372     a character valid as a delimiter for identifiers) is also treated
1373     as missing.
1374
1375     If line numbering has been disabled with a call to `nm' without an
1376     argument, it can be reactivated with `.nm +0', using the
1377     previously active line numbering parameters.
1378
1379     The parameters of `nm' are associated with the current environment
1380     (*note Environments::).  The current output line number is
1381     available in the number register `ln'.
1382
1383
1384          .po 1m
1385          .ll 2i
1386          This test shows how line numbering works with groff.
1387          .nm 999
1388          This test shows how line numbering works with groff.
1389          .br
1390          .nm xxx 3 2
1391          .ll -\w'0'u
1392          This test shows how line numbering works with groff.
1393          .nn 2
1394          This test shows how line numbering works with groff.
1395
1396     And here the result:
1397
1398
1399           This  test shows how
1400           line numbering works
1401           999 with   groff.   This
1402          1000 test shows how  line
1403          1001 numbering works with
1404          1002 groff.
1405                This test shows how
1406                line      numbering
1407           works  with  groff.
1408           This test shows how
1409          1005  line      numbering
1410                works with groff.
1411
1412
1413 -- Request: .nn [skip]
1414     Temporarily turn off line numbering.  The argument is the number
1415     of lines not to be numbered; this defaults to 1.
1416
1417 -- Request: .mc glyph [dist]
1418     Print a "margin character" to the right of the text.(1) (*note
1419     Miscellaneous-Footnote-1::)  The first argument is the glyph to be
1420     printed.  The second argument is the distance away from the right
1421     margin.  If missing, the previously set value is used; default is
1422     10pt).  For text lines that are too long (that is, longer than the
1423     text length plus DIST), the margin character is directly appended
1424     to the lines.
1425
1426     With no arguments the margin character is turned off.  If this
1427     occurs before a break, no margin character is printed.
1428
1429     For compatibility with AT&T `troff', a call to `mc' to set the
1430     margin character can't be undone immediately; at least one line
1431     gets a margin character.  Thus
1432
1433
1434          .ll 1i
1435          .mc \[br]
1436          .mc
1437          xxx
1438          .br
1439          xxx
1440
1441     produces
1442
1443
1444          xxx        |
1445          xxx
1446
1447     For empty lines and lines produced by the `tl' request no margin
1448     character is emitted.
1449
1450     The margin character is associated with the current environment
1451     (*note Environments::).
1452
1453     This is quite useful for indicating text that has changed, and, in
1454     fact, there are programs available for doing this (they are called
1455     `nrchbar' and `changebar' and can be found in any
1456     `comp.sources.unix' archive).
1457
1458
1459

Large files files are truncated, but you can click here to view the full file