Initial import from FreeBSD RELENG_4:

[dragonfly.git] / contrib / groff / doc / groff-3

This is groff, produced by makeinfo version 4.2 from ./groff.texinfo.

This manual documents GNU `troff' version 1.18.

   Copyright (C) 1994-2000, 2001, 2002 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.1 or any later version published by the Free Software
     Foundation; with no Invariant Sections, with the Front-Cover texts
     being `A GNU Manual," and with the Back-Cover Texts as in (a)
     below.  A copy of the license is included in the section entitled
     `GNU Free Documentation License."

     (a) The FSF's Back-Cover Text is: `You have freedom to copy and
     modify this GNU Manual, like GNU software.  Copies published by
     the Free Software Foundation raise funds for GNU development."
   
INFO-DIR-SECTION Miscellaneous
START-INFO-DIR-ENTRY
* Groff: (groff).               The GNU troff document formatting system.
END-INFO-DIR-ENTRY

\1f
File: groff,  Node: Tab Stops,  Next: Implicit Line Breaks,  Prev: Sentences,  Up: Text

Tab Stops
---------

   `gtroff' translates "tabulator characters", also called "tabs"
(normally code point ASCII `0x09' or EBCDIC `0x05'), in the input into
movements to the next tabulator stop.  These tab stops are initially
located every half inch across the page.  Using this, simple tables can
be made easily.  However, it can often be deceptive as the appearance
(and width) of the text on a terminal and the results from `gtroff' can
vary greatly.

   Also, a possible sticking point is that lines beginning with tab
characters are still filled, again producing unexpected results.  For
example, the following input

           1          2          3
                      4          5

produces

           1          2          3                     4          5

   *Note Tabs and Fields::.

\1f
File: groff,  Node: Implicit Line Breaks,  Prev: Tab Stops,  Up: Text

Implicit Line Breaks
--------------------

   An important concept in `gtroff' is the "break".  When a break
occurs, `gtroff' outputs the partially filled line (unjustified), and
resumes collecting and filling text on the next output line.

   There are several ways to cause a break in `gtroff'.  A blank line
not only causes a break, but it also outputs a one-line vertical space
(effectively a blank line).  Note that this behaviour can be modified
with the blank line macro request `blm'.  *Note Blank Line Traps::.

   A line that begins with a space causes a break and the space is
output at the beginning of the next line.  Note that this space isn't
adjusted, even in fill mode.

   The end of file also causes a break - otherwise the last line of the
document may vanish!

   Certain requests also cause breaks, implicitly or explicitly.  This
is discussed in *Note Manipulating Filling and Adjusting::.

\1f
File: groff,  Node: Input Conventions,  Next: Measurements,  Prev: Text,  Up: gtroff Reference

Input Conventions
=================

   Since `gtroff' does filling automatically, it is traditional in
`groff' not to try and type things in as nicely formatted paragraphs.
These are some conventions commonly used when typing `gtroff' text:

   * Break lines after punctuation, particularly at the end of a
     sentence and in other logical places.  Keep separate phrases on
     lines by themselves, as entire phrases are often added or deleted
     when editing.

   * Try to keep lines less than 40-60 characters, to allow space for
     inserting more text.

   * Do not try to do any formatting in a WYSIWYG manner (i.e., don't
     try using spaces to get proper indentation).

\1f
File: groff,  Node: Measurements,  Next: Expressions,  Prev: Input Conventions,  Up: gtroff Reference

Measurements
============

   `gtroff' (like many other programs) requires numeric parameters to
specify various measurements.  Most numeric parameters(1) (*note
Measurements-Footnote-1::) may have a "measurement unit" attached.
These units are specified as a single character which immediately
follows the number or expression.  Each of these units are understood,
by `gtroff', to be a multiple of its "basic unit".  So, whenever a
different measurement unit is specified `gtroff' converts this into its
"basic units".  This basic unit, represented by a `u', is a device
dependent measurement which is quite small, ranging from 1/75th to
1/72000th of an inch.  The values may be given as fractional numbers;
however, fractional basic units are always rounded to integers.

   Some of the measurement units are completely independent of any of
the current settings (e.g. type size) of `gtroff'.

`i'
     Inches.  An antiquated measurement unit still in use in certain
     backwards countries with incredibly low-cost computer equipment.
     One inch is equal to 2.54cm.

`c'
     Centimeters.  One centimeter is equal to 0.3937in.

`p'
     Points.  This is a typesetter's measurement used for measure type
     size.  It is 72 points to an inch.

`P'
     Pica.  Another typesetting measurement.  6 Picas to an inch (and
     12 points to a pica).

`s'
`z'
     *Note Fractional Type Sizes::, for a discussion of these units.

`f'
     Fractions. Value is 65536.  *Note Colors::, for usage.

   The other measurements understood by `gtroff' depend on settings
currently in effect in `gtroff'.  These are very useful for specifying
measurements which should look proper with any size of text.

`m'
     Ems.  This unit is equal to the current font size in points.  So
     called because it is _approximately_ the width of the letter `m'
     in the current font.

`n'
     Ens.  In `groff', this is half of an em.

`v'
     Vertical space.  This is equivalent to the current line spacing.
     *Note Sizes::, for more information about this.

`M'
     100ths of an em.

* Menu:

* Default Units::

\1f
File: groff,  Node: Measurements-Footnotes,  Up: Measurements

   (1) those that specify vertical or horizontal motion or a type size

\1f
File: groff,  Node: Default Units,  Prev: Measurements,  Up: Measurements

Default Units
-------------

   Many requests take a default unit.  While this can be helpful at
times, it can cause strange errors in some expressions.  For example,
the line length request expects em units.  Here are several attempts to
get a line length of 3.5 inches and their results:


     3.5i      =>   3.5i
     7/2       =>   0i
     7/2i      =>   0i
     (7 / 2)u  =>   0i
     7i/2      =>   0.1i
     7i/2u     =>   3.5i

Everything is converted to basic units first.  In the above example it
is assumed that 1i equals 240u, and 1m equals 10p (thus 1m equals 33u).
The value 7i/2 is first handled as 7i/2m, then converted to 1680u/66u
which is 25u, and this is approximately 0.1i.  As can be seen, a
scaling indicator after a closing parenthesis is simply ignored.

   Thus, the safest way to specify measurements is to always attach a
scaling indicator.  If you want to multiply or divide by a certain
scalar value, use `u' as the unit for that value.

\1f
File: groff,  Node: Expressions,  Next: Identifiers,  Prev: Measurements,  Up: gtroff Reference

Expressions
===========

   `gtroff' has most arithmetic operators common to other languages:

   * Arithmetic: `+' (addition), `-' (subtraction), `/' (division), `*'
     (multiplication), `%' (modulo).

     `gtroff' only provides integer arithmetic.  The internal type used
     for computing results is `int', which is usually a 32bit signed
     integer.

   * Comparison: `<' (less than), `>' (greater than), `<=' (less than
     or equal), `>=' (greater than or equal), `=' (equal), `==' (the
     same as `=').

   * Logical: `&' (logical and), `:' (logical or).

   * Unary operators: `-' (negating, i.e. changing the sign), `+' (just
     for completeness; does nothing in expressions), `!' (logical not;
     this works only within `if' and `while' requests).  See below for
     the use of unary operators in motion requests.

   * Extrema: `>?' (maximum), `<?' (minimum).

     Example:


          .nr x 5
          .nr y 3
          .nr z (\n[x] >? \n[y])

     The register `z' now contains 5.

   * Scaling: `(C;E)'.  Evaluate E using C as the default scaling
     indicator.  If C is missing, ignore scaling indicators in the
     evaluation of E.

   Parentheses may be used as in any other language.  However, in
`gtroff' they are necessary to ensure order of evaluation.  `gtroff'
has no operator precedence; expressions are evaluated left to right.
This means that `gtroff' evaluates `3+5*4' as if it were parenthesized
like `(3+5)*4', not as `3+(5*4)', as might be expected.

   For many requests which cause a motion on the page, the unary
operators `+' and `-' work differently if leading an expression.  They
then indicate a motion relative to the current position (down or up,
respectively).

   Similarly, a leading `|' operator indicates an absolute position.
For vertical movements, it specifies the distance from the top of the
page; for horizontal movements, it gives the distance from the beginning
of the _input_ line.

   `+' and `-' are also treated differently by the following requests
and escapes: `bp', `in', `ll', `lt', `nm', `nr', `pl', `pn', `po', `ps',
`pvs', `rt', `ti', `\H', `\R', and `\s'.  Here, leading plus and minus
signs indicate increments and decrements.

   *Note Setting Registers::, for some examples.

 - Escape: \B'ANYTHING'
     Return 1 if ANYTHING is a valid numeric expression; or 0 if
     ANYTHING is empty or not a valid numeric expression.

   Due to the way arguments are parsed, spaces are not allowed in
expressions, unless the entire expression is surrounded by parentheses.

   *Note Request Arguments::, and *Note Conditionals and Loops::.

\1f
File: groff,  Node: Identifiers,  Next: Embedded Commands,  Prev: Expressions,  Up: gtroff Reference

Identifiers
===========

   Like any other language, `gtroff' has rules for properly formed
"identifiers".  In `gtroff', an identifier can be made up of almost any
printable character, with the exception of the following characters:

   * Whitespace characters (spaces, tabs, and newlines).

   * Backspace (ASCII `0x08' or EBCDIC `0x16') and character code
     `0x01'.

   * The following input characters are invalid and are ignored if
     `groff' runs on a machine based on ASCII, causing a warning
     message of type `input' (see *Note Debugging::, for more details):
     `0x00', `0x0B', `0x0D'-`0x1F', `0x80'-`0x9F'.

     And here are the invalid input characters if `groff' runs on an
     EBCDIC host: `0x00', `0x08', `0x09', `0x0B', `0x0D'-`0x14',
     `0x17'-`0x1F', `0x30'-`0x3F'.

     Currently, some of these reserved codepoints are used internally,
     thus making it non-trivial to extend `gtroff' to cover Unicode or
     other character sets and encodings which use characters of these
     ranges.

     Note that invalid characters are removed before parsing; an
     identifier `foo', followed by an invalid character, followed by
     `bar' is treated as `foobar'.

   For example, any of the following is valid.


     br
     PP
     (l
     end-list
     @_

Note that identifiers longer than two characters with a closing bracket
(`]') in its name can't be accessed with escape sequences which expect
an identifier as a parameter.  For example, `\[foo]]' accesses the
glyph `foo', followed by `]', whereas `\C'foo]'' really asks for glyph
`foo]'.

   To avoid problems with the `refer' preprocessor, macro names should
not start with `[' or `]'.  Due to backwards compatibility, everything
after `.[' and `.]' is handled as a special argument to `refer'.  For
example, `.[foo' makes `refer' to start a reference, using `foo' as a
parameter.

 - Escape: \A'IDENT'
     Test whether an identifier IDENT is valid in `gtroff'.  It expands
     to the character 1 or 0 according to whether its argument (usually
     delimited by quotes) is or is not acceptable as the name of a
     string, macro, diversion, number register, environment, or font.
     It returns 0 if no argument is given.  This is useful for looking
     up user input in some sort of associative table.


          \A'end-list'
              => 1


   *Note Escapes::, for details on parameter delimiting characters.

   Identifiers in `gtroff' can be any length, but, in some contexts,
`gtroff' needs to be told where identifiers end and text begins (and in
different ways depending on their length):

   * Single character.

   * Two characters.  Must be prefixed with `(' in some situations.

   * Arbitrary length (`gtroff' only).  Must be bracketed with `['
     and `]' in some situations.  Any length identifier can be put in
     brackets.

   Unlike many other programming languages, undefined identifiers are
silently ignored or expanded to nothing.  When `gtroff' finds an
undefined identifier, it emits a warning, doing the following:

   * If the identifier is a string, macro, or diversion, `gtroff'
     defines it as empty.

   * If the identifier is a number register, `gtroff' defines it with a
     value of 0.

   *Note Warnings::., *Note Interpolating Registers::, and *Note
Strings::.

   Note that macros, strings, and diversions share the same name space.


     .de xxx
     .  nop foo
     ..
     .
     .di xxx
     bar
     .br
     .di
     .
     .xxx
         => bar

As can be seen in the previous example, `gtroff' reuses the identifier
`xxx', changing it from a macro to a diversion.  No warning is emitted!
The contents of the first macro definition is lost.

   *Note Interpolating Registers::, and *Note Strings::.

\1f
File: groff,  Node: Embedded Commands,  Next: Registers,  Prev: Identifiers,  Up: gtroff Reference

Embedded Commands
=================

   Most documents need more functionality beyond filling, adjusting and
implicit line breaking.  In order to gain further functionality,
`gtroff' allows commands to be embedded into the text, in two ways.

   The first is a "request" which takes up an entire line, and does
some large-scale operation (e.g. break lines, start new pages).

   The other is an "escape" which can be usually embedded anywhere in
the text; most requests can accept it even as an argument.  Escapes
generally do more minor operations like sub- and superscripts, print a
symbol, etc.

* Menu:

* Requests::
* Macros::
* Escapes::

\1f
File: groff,  Node: Requests,  Next: Macros,  Prev: Embedded Commands,  Up: Embedded Commands

Requests
--------

   A request line begins with a control character, which is either a
single quote (`'', the "no-break control character") or a period (`.',
the normal "control character").  These can be changed; see *Note
Character Translations::, for details.  After this there may be
optional tabs or spaces followed by an identifier which is the name of
the request.  This may be followed by any number of space-separated
arguments (_no_ tabs here).

   Since a control character followed by whitespace only is ignored, it
is common practice to use this feature for structuring the source code
of documents or macro packages.


     .de foo
     .  tm This is foo.
     ..
     .
     .
     .de bar
     .  tm This is bar.
     ..

   Another possibility is to use the blank line macro request `blm' by
assigning an empty macro to it.


     .de do-nothing
     ..
     .blm do-nothing  \" activate blank line macro
     
     .de foo
     .  tm This is foo.
     ..
     
     
     .de bar
     .  tm This is bar.
     ..
     
     .blm             \" deactivate blank line macro

   *Note Blank Line Traps::.

   To begin a line with a control character without it being
interpreted, precede it with `\&'.  This represents a zero width space,
which means it does not affect the output.

   In most cases the period is used as a control character.  Several
requests cause a break implicitly; using the single quote control
character prevents this.

* Menu:

* Request Arguments::

\1f
File: groff,  Node: Request Arguments,  Prev: Requests,  Up: Requests

Request Arguments
.................

   Arguments to requests (and macros) are processed much like the shell:
The line is split into arguments according to spaces.(1) (*note Request
Arguments-Footnote-1::)  An argument which is intended to contain
spaces can either be enclosed in double quotes, or have the spaces
"escaped" with backslashes.

   Here are a few examples:


     .uh The Mouse Problem
     .uh "The Mouse Problem"
     .uh The\ Mouse\ Problem

The first line is the `uh' macro being called with 3 arguments, `The',
`Mouse', and `Problem'.  The latter two have the same effect of calling
the `uh' macro with one argument, `The Mouse Problem'.(2) (*note
Request Arguments-Footnote-2::)

   A double quote which isn't preceded by a space doesn't start a macro
argument.  If not closing a string, it is printed literally.

   For example,


     .xxx a" "b c" "de"fg"

has the arguments `a"', `b c', `de', and `fg"'.  Don't rely on this
obscure behaviour!

   There are two possibilities to get a double quote reliably.

   * Enclose the whole argument with double quotes and use two
     consecutive double quotes to represent a single one.  This
     traditional solution has the disadvantage that double quotes don't
     survive argument expansion again if called in compatibility mode
     (using the `-C' option of `groff'):


          .de xx
          .  tm xx: `\\$1' `\\$2' `\\$3'
          .
          .  yy "\\$1" "\\$2" "\\$3"
          ..
          .de yy
          .  tm yy: `\\$1' `\\$2' `\\$3'
          ..
          .xx A "test with ""quotes""" .
              => xx: `A' `test with "quotes"' `.'
              => yy: `A' `test with ' `quotes""'

     If not in compatibility mode, you get the expected result


          xx: `A' `test with "quotes"' `.'
          yy: `A' `test with "quotes"' `.'

     since `gtroff' preserves the input level.

   * Use the double quote glyph `\(dq'.  This works with and without
     compatibility mode enabled since `gtroff' doesn't convert `\(dq'
     back to a double quote input character.

     Not that this method won't work with UNIX `troff' in general since
     the glyph `dq' isn't defined normally.

   Double quotes in the `ds' request are handled differently.  *Note
Strings::, for more details.

\1f
File: groff,  Node: Request Arguments-Footnotes,  Up: Request Arguments

   (1) Plan 9's `troff' implementation also allows tabs for argument
separation - `gtroff' intentionally doesn't support this.

   (2) The last solution, i.e., using escaped spaces, is "classical" in
the sense that it can be found in most `troff' documents.
Nevertheless, it is not optimal in all situations, since `\ ' inserts a
fixed-width, non-breaking space character which can't stretch.
`gtroff' provides a different command `\~' to insert a stretchable,
non-breaking space.

\1f
File: groff,  Node: Macros,  Next: Escapes,  Prev: Requests,  Up: Embedded Commands

Macros
------

   `gtroff' has a "macro" facility for defining a series of lines which
can be invoked by name.  They are called in the same manner as requests
- arguments also may be passed in the same manner.

   *Note Writing Macros::, and *Note Request Arguments::.

\1f
File: groff,  Node: Escapes,  Prev: Macros,  Up: Embedded Commands

Escapes
-------

   Escapes may occur anywhere in the input to `gtroff'.  They usually
begin with a backslash and are followed by a single character which
indicates the function to be performed.  The escape character can be
changed; see *Note Character Translations::.

   Escape sequences which require an identifier as a parameter accept
three possible syntax forms.

   * The next single character is the identifier.

   * If this single character is an opening parenthesis, take the
     following two characters as the identifier.  Note that there is no
     closing parenthesis after the identifier.

   * If this single character is an opening bracket, take all characters
     until a closing bracket as the identifier.

Examples:


     \fB
     \n(XX
     \*[TeX]

   Other escapes may require several arguments and/or some special
format.  In such cases the argument is traditionally enclosed in single
quotes (and quotes are always used in this manual for the definitions
of escape sequences).  The enclosed text is then processed according to
what that escape expects.  Example:


     \l'1.5i\(bu'

   Note that the quote character can be replaced with any other
character which does not occur in the argument (even a newline or a
space character) in the following escapes: `\o', `\b', and `\X'.  This
makes e.g.


     A caf
     \o
     e\'
     
     
     in Paris
       => A cafe' in Paris

possible, but it is better not to use this feature to avoid confusion.

   The following escapes sequences (which are handled similarly to
characters since they don't take a parameter) are also allowed as
delimiters: `\%', `\ ', `\|', `\^', `\{', `\}', `\'', `\`', `\-', `\_',
`\!', `\?', `\@', `\)', `\/', `\,', `\&', `\:', `\~', `\0', `\a', `\c',
`\d', `\e', `\E', `\p', `\r', `\t', and `\u'.  Again, don't use these
if possible.

   No newline characters as delimiters are allowed in the following
escapes: `\A', `\B', `\Z', `\C', and `\w'.

   Finally, the escapes `\D', `\h', `\H', `\l', `\L', `\N', `\R', `\s',
`\S', `\v', and `\x' can't use the following characters as delimiters:

   * The digits `0'-`9'.

   * The (single-character) operators `+-/*%<>=&:().'.

   * The space, tab, and newline characters.

   * All escape sequences except `\%', `\:', `\{', `\}', `\'', `\`',
     `\-', `\_', `\!', `\@', `\/', `\c', `\e', and `\p'.

   To have a backslash (actually, the current escape character) appear
in the output several escapes are defined: `\\', `\e' or `\E'.  These
are very similar, and only differ with respect to being used in macros
or diversions.  *Note Character Translations::, for an exact
description of those escapes.

   *Note Implementation Differences::, *Note Copy-in Mode::, and *Note
Diversions::, *Note Identifiers::, for more information.

* Menu:

* Comments::

\1f
File: groff,  Node: Comments,  Prev: Escapes,  Up: Escapes

Comments
........

   Probably one of the most(1) (*note Comments-Footnote-1::) common
forms of escapes is the comment.

 - Escape: \"
     Start a comment.  Everything to the end of the input line is
     ignored.

     This may sound simple, but it can be tricky to keep the comments
     from interfering with the appearance of the final output.

     If the escape is to the right of some text or a request, that
     portion of the line is ignored, but the space leading up to it is
     noticed by `gtroff'.  This only affects the `ds' and `as' request
     and its variants.

     One possibly irritating idiosyncracy is that tabs must not be used
     to line up comments.  Tabs are not treated as whitespace between
     the request and macro arguments.

     A comment on a line by itself is treated as a blank line, because
     after eliminating the comment, that is all that remains:


          Test
          \" comment
          Test

     produces


          Test
          
          Test

     To avoid this, it is common to start the line with `.\"' which
     causes the line to be treated as an undefined request and thus
     ignored completely.

     Another commenting scheme seen sometimes is three consecutive
     single quotes (`'''') at the beginning of a line.  This works, but
     `gtroff' gives a warning about an undefined macro (namely `'''),
     which is harmless, but irritating.

 - Escape: \#
     To avoid all this, `gtroff' has a new comment mechanism using the
     `\#' escape.  This escape works the same as `\"' except that the
     newline is also ignored:


          Test
          \# comment
          Test

     produces


          Test Test

     as expected.

 - Request: .ig yy
     Ignore all input until `gtroff' encounters the macro named `.'YY
     on a line by itself (or `..' if YY is not specified).  This is
     useful for commenting out large blocks of text:


          text text text...
          .ig
          This is part of a large block
          of text that has been
          temporarily(?) commented out.
          
          We can restore it simply by removing
          the .ig request and the ".." at the
          end of the block.
          ..
          More text text text...

     produces


          text text text...  More text text text...

     Note that the commented-out block of text does not cause a break.

     The input is read in copy-mode; auto-incremented registers _are_
     affected (*note Auto-increment::).

\1f
File: groff,  Node: Comments-Footnotes,  Up: Comments

   (1) Unfortunately, this is a lie.  But hopefully future `gtroff'
hackers will believe it `:-)'

\1f
File: groff,  Node: Registers,  Next: Manipulating Filling and Adjusting,  Prev: Embedded Commands,  Up: gtroff Reference

Registers
=========

   Numeric variables in `gtroff' are called "registers".  There are a
number of built-in registers, supplying anything from the date to
details of formatting parameters.

   *Note Identifiers::, for details on register identifiers.

* Menu:

* Setting Registers::
* Interpolating Registers::
* Auto-increment::
* Assigning Formats::
* Built-in Registers::

\1f
File: groff,  Node: Setting Registers,  Next: Interpolating Registers,  Prev: Registers,  Up: Registers

Setting Registers
-----------------

   Define or set registers using the `nr' request or the `\R' escape.

 - Request: .nr ident value
 - Escape: \R'IDENT VALUE'
     Set number register IDENT to VALUE.  If IDENT doesn't exist,
     `gtroff' creates it.

     The argument to `\R' usually has to be enclosed in quotes.  *Note
     Escapes::, for details on parameter delimiting characters.

     The `\R' escape doesn't produce an input token in `gtroff'; with
     other words, it vanishes completely after `gtroff' has processed
     it.

   For example, the following two lines are equivalent:


     .nr a (((17 + (3 * 4))) % 4)
     \R'a (((17 + (3 * 4))) % 4)'
         => 1

   Both `nr' and `\R' have two additional special forms to increment or
decrement a register.

 - Request: .nr ident +value
 - Request: .nr ident -value
 - Escape: \R'IDENT +VALUE'
 - Escape: \R'IDENT -VALUE'
     Increment (decrement) register IDENT by VALUE.


          .nr a 1
          .nr a +1
          \na
              => 2

     To assign the negated value of a register to another register,
     some care must be taken to get the desired result:


          .nr a 7
          .nr b 3
          .nr a -\nb
          \na
              => 4
          .nr a (-\nb)
          \na
              => -3

     The surrounding parentheses prevent the interpretation of the
     minus sign as a decrementing operator.  An alternative is to start
     the assignment with a `0':


          .nr a 7
          .nr b -3
          .nr a \nb
          \na
              => 4
          .nr a 0\nb
          \na
              => -3


 - Request: .rr ident
     Remove number register IDENT.  If IDENT doesn't exist, the request
     is ignored.

 - Request: .rnn ident1 ident2
     Rename number register IDENT1 to IDENT2.  If either IDENT1 or
     IDENT2 doesn't exist, the request is ignored.

 - Request: .aln ident1 ident2
     Create an alias IDENT1 for a number register IDENT2.  The new name
     and the old name are exactly equivalent.  If IDENT1 is undefined,
     a warning of type `reg' is generated, and the request is ignored.
     *Note Debugging::, for information about warnings.

\1f
File: groff,  Node: Interpolating Registers,  Next: Auto-increment,  Prev: Setting Registers,  Up: Registers

Interpolating Registers
-----------------------

   Numeric registers can be accessed via the `\n' escape.

 - Escape: \nI
 - Escape: \n(ID
 - Escape: \n[IDENT]
     Interpolate number register with name IDENT (one-character name I,
     two-character name ID). This means that the value of the register
     is expanded in-place while `gtroff' is parsing the input line.
     Nested assignments (also called indirect assignments) are possible.


          .nr a 5
          .nr as \na+\na
          \n(as
              => 10


          .nr a1 5
          .nr ab 6
          .ds str b
          .ds num 1
          \n[a\n[num]]
              => 5
          \n[a\*[str]]
              => 6


\1f
File: groff,  Node: Auto-increment,  Next: Assigning Formats,  Prev: Interpolating Registers,  Up: Registers

Auto-increment
--------------

   Number registers can also be auto-incremented and auto-decremented.
The increment or decrement value can be specified with a third argument
to the `nr' request or `\R' escape.

 - Request: .nr ident value incr
     Set number register IDENT to VALUE; the increment for
     auto-incrementing is set to INCR.  Note that the `\R' escape
     doesn't support this notation.

   To activate auto-incrementing, the escape `\n' has a special syntax
form.

 - Escape: \n+I
 - Escape: \n-I
 - Escape: \n(+ID
 - Escape: \n(-ID
 - Escape: \n+(ID
 - Escape: \n-(ID
 - Escape: \n[+IDENT]
 - Escape: \n[-IDENT]
 - Escape: \n+[IDENT]
 - Escape: \n-[IDENT]
     Before interpolating, increment or decrement IDENT (one-character
     name I, two-character name ID) by the auto-increment value as
     specified with the `nr' request (or the `\R' escape).  If no
     auto-increment value has been specified, these syntax forms are
     identical to `\n'.

   For example,


     .nr a 0 1
     .nr xx 0 5
     .nr foo 0 -2
     \n+a, \n+a, \n+a, \n+a, \n+a
     .br
     \n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx
     .br
     \n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo]

produces


     1, 2, 3, 4, 5
     -5, -10, -15, -20, -25
     -2, -4, -6, -8, -10

   To change the increment value without changing the value of a
register (A in the example), the following can be used:


     .nr a \na 10

\1f
File: groff,  Node: Assigning Formats,  Next: Built-in Registers,  Prev: Auto-increment,  Up: Registers

Assigning Formats
-----------------

   When a register is used in the text of an input file (as opposed to
part of an expression), it is textually replaced (or interpolated) with
a representation of that number.  This output format can be changed to
a variety of formats (numbers, Roman numerals, etc.).  This is done
using the `af' request.

 - Request: .af ident format
     Change the output format of a number register.  The first argument
     IDENT is the name of the number register to be changed, and the
     second argument FORMAT is the output format.  The following output
     formats are available:

    `1'
          Decimal arabic numbers.  This is the default format: 0, 1, 2,
          3, ....

    `0...0'
          Decimal numbers with as many digits as specified.  So, `00'
          would result in printing numbers as 01, 02, 03, ....

          In fact, any digit instead of zero will do; `gtroff' only
          counts how many digits are specified.  As a consequence,
          `af''s default format `1' could be specified as `0' also (and
          exactly this is returned by the `\g' escape, see below).

    `I'
          Upper-case Roman numerals: 0, I, II, III, IV, ....

    `i'
          Lower-case Roman numerals: 0, i, ii, iii, iv, ....

    `A'
          Upper-case letters: 0, A, B, C, ..., Z, AA, AB, ....

    `a'
          Lower-case letters: 0, a, b, c, ..., z, aa, ab, ....

     Omitting the number register format causes a warning of type
     `missing'.  *Note Debugging::, for more details.  Specifying a
     nonexistent format causes an error.

     The following example produces `10, X, j, 010':


          .nr a 10
          .af a 1           \" the default format
          \na,
          .af a I
          \na,
          .af a a
          \na,
          .af a 001
          \na

     The largest number representable for the `i' and `I' formats is
     39999 (or -39999); UNIX `troff' uses `z' and `w' to represent
     10000 and 5000 in Roman numerals, and so does `gtroff'.
     Currently, the correct glyphs of Roman numeral five thousand and
     Roman numeral ten thousand (Unicode code points `U+2182' and
     `U+2181', respectively) are not available.

     If IDENT doesn't exist, it is created.

     Changing the output format of a read-only register causes an
     error.  It is necessary to first copy the register's value to a
     writeable register, then apply the `af' request to this other
     register.

 - Escape: \gI
 - Escape: \g(ID
 - Escape: \g[IDENT]
     Return the current format of the specified register IDENT
     (one-character name I, two-character name ID).  For example, `\ga'
     after the previous example would produce the string `000'.  If the
     register hasn't been defined yet, nothing is returned.

\1f
File: groff,  Node: Built-in Registers,  Prev: Assigning Formats,  Up: Registers

Built-in Registers
------------------

   The following lists some built-in registers which are not described
elsewhere in this manual.  Any register which begins with a `.' is
read-only.  A complete listing of all built-in registers can be found in
appendix *Note Register Index::.

`.F'
     This string-valued register returns the current input file name.

`.H'
     Horizontal resolution in basic units.

`.V'
     Vertical resolution in basic units.

`seconds'
     The number of seconds after the minute, normally in the range 0
     to 59, but can be up to 61 to allow for leap seconds.  Initialized
     at start-up of `gtroff'.

`minutes'
     The number of minutes after the hour, in the range 0 to 59.
     Initialized at start-up of `gtroff'.

`hours'
     The number of hours past midnight, in the range 0 to 23.
     Initialized at start-up of `gtroff'.

`dw'
     Day of the week (1-7).

`dy'
     Day of the month (1-31).

`mo'
     Current month (1-12).

`year'
     The current year.

`yr'
     The current year minus 1900.  Unfortunately, the documentation of
     UNIX Version 7's `troff' had a year 2000 bug: It incorrectly
     claimed that `yr' contains the last two digits of the year.  That
     claim has never been true of either AT&T `troff' or GNU `troff'.
     Old `troff' input that looks like this:


          '\" The following line stopped working after 1999
          This document was formatted in 19\n(yr.

     can be corrected as follows:


          This document was formatted in \n[year].

     or, to be portable to older `troff' versions, as follows:


          .nr y4 1900+\n(yr
          This document was formatted in \n(y4.

`.c'
`c.'
     The current _input_ line number.  Register `.c' is read-only,
     whereas `c.' (a `gtroff' extension) is writable also, affecting
     both `.c' and `c.'.

`ln'
     The current _output_ line number after a call to the `nm' request
     to activate line numbering.

     *Note Miscellaneous::, for more information about line numbering.

`.x'
     The major version number.  For example, if the version number
     is 1.03 then `.x' contains `1'.

`.y'
     The minor version number.  For example, if the version number
     is 1.03 then `.y' contains `03'.

`.Y'
     The revision number of `groff'.

`$$'
     The process ID of `gtroff'.

`.g'
     Always 1.  Macros should use this to determine whether they are
     running under GNU `troff'.

`.A'
     If the command line option `-a' is used to produce an ASCII
     approximation of the output, this is set to 1, zero otherwise.
     *Note Groff Options::.

`.P'
     This register is set to 1 (and to 0 otherwise) if the current page
     is actually being printed, i.e., if the `-o' option is being used
     to only print selected pages.  *Note Groff Options::, for more
     information.

`.T'
     If `gtroff' is called with the `-T' command line option, the
     number register `.T' is set to 1, and zero otherwise.  *Note Groff
     Options::.

     Additionally, `gtroff' predefines a single read-write string
     register `.T' which contains the current output device (for
     example, `latin1' or `ps').

\1f
File: groff,  Node: Manipulating Filling and Adjusting,  Next: Manipulating Hyphenation,  Prev: Registers,  Up: gtroff Reference

Manipulating Filling and Adjusting
==================================

   Various ways of causing "breaks" were given in *Note Implicit Line
Breaks::.  The `br' request likewise causes a break.  Several other
requests also cause breaks, but implicitly.  These are `bp', `ce',
`cf', `fi', `fl', `in', `nf', `rj', `sp', `ti', and `trf'.

 - Request: .br
     Break the current line, i.e., the input collected so far is emitted
     without adjustment.

     If the no-break control character is used, `gtroff' suppresses the
     break:


          a
          'br
          b
              => a b


   Initially, `gtroff' fills and adjusts text to both margins.  Filling
can be disabled via the `nf' request and re-enabled with the `fi'
request.

 - Request: .fi
 - Register: \n[.u]
     Activate fill mode (which is the default).  This request implicitly
     enables adjusting; it also inserts a break in the text currently
     being filled.  The read-only number register `.u' is set to 1.

     The fill mode status is associated with the current environment
     (*note Environments::).

     See *Note Line Control::, for interaction with the `\c' escape.

 - Request: .nf
     Activate no-fill mode.  Input lines are output as-is, retaining
     line breaks and ignoring the current line length.  This command
     implicitly disables adjusting; it also causes a break.  The number
     register `.u' is set to 0.

     The fill mode status is associated with the current environment
     (*note Environments::).

     See *Note Line Control::, for interaction with the `\c' escape.

 - Request: .ad [mode]
 - Register: \n[.j]
     Set adjusting mode.

     Activation and deactivation of adjusting is done implicitly with
     calls to the `fi' or `nf' requests.

     MODE can have one of the following values:

    `l'
          Adjust text to the left margin.  This produces what is
          traditionally called ragged-right text.

    `r'
          Adjust text to the right margin, producing ragged-left text.

    `c'
          Center filled text.  This is different to the `ce' request
          which only centers text without filling.

    `b'
    `n'
          Justify to both margins.  This is the default used by
          `gtroff'.

     With no argument, `gtroff' adjusts lines in the same way it did
     before adjusting was deactivated (with a call to `na', for
     example).


          text
          .ad r
          text
          .ad c
          text
          .na
          text
          .ad  \" back to centering
          text

     The current adjustment mode is available in the read-only number
     register `.j'; it can be stored and subsequently used to set
     adjustment.

     The adjustment mode status is associated with the current
     environment (*note Environments::).

 - Request: .na
     Disable adjusting.  This request won't change the current
     adjustment mode: A subsequent call to `ad' uses the previous
     adjustment setting.

     The adjustment mode status is associated with the current
     environment (*note Environments::).

 - Request: .brp
 - Escape: \p
     Adjust the current line and cause a break.

     In most cases this produces very ugly results since `gtroff'
     doesn't have a sophisticated paragraph building algorithm (as TeX
     have, for example); instead, `gtroff' fills and adjusts a paragraph
     line by line:


            This is an uninteresting sentence.
            This is an uninteresting sentence.\p
            This is an uninteresting sentence.

     is formatted as


            This is  an uninteresting  sentence.   This  is an
            uninteresting                            sentence.
            This is an uninteresting sentence.


 - Request: .ss word_space_size [sentence_space_size]
 - Register: \n[.ss]
 - Register: \n[.sss]
     Change the minimum size of a space between filled words.  It takes
     its units as one twelfth of the space width parameter for the
     current font.  Initially both the WORD_SPACE_SIZE and
     SENTENCE_SPACE_SIZE are 12.

     If two arguments are given to the `ss' request, the second
     argument sets the sentence space size.  If the second argument is
     not given, sentence space size is set to WORD_SPACE_SIZE.  The
     sentence space size is used in two circumstances: If the end of a
     sentence occurs at the end of a line in fill mode, then both an
     inter-word space and a sentence space are added; if two spaces
     follow the end of a sentence in the middle of a line, then the
     second space is a sentence space.  If a second argument is never
     given to the `ss' request, the behaviour of UNIX `troff' is the
     same as that exhibited by GNU `troff'.  In GNU `troff', as in UNIX
     `troff', a sentence should always be followed by either a newline
     or two spaces.

     The read-only number registers `.ss' and `.sss' hold the values of
     the parameters set by the first and second arguments of the `ss'
     request.

     The word space and sentence space values are associated with the
     current environment (*note Environments::).

     Contrary to AT&T `troff', this request is _not_ ignored if a TTY
     output device is used; the given values are then rounded down to a
     multiple of 12 (*note Implementation Differences::).

     The request is ignored if there is no parameter.

 - Request: .ce [nnn]
 - Register: \n[.ce]
     Center text.  While the `.ad c' request also centers text, it
     fills the text as well.  `ce' does not fill the text it affects.
     This request causes a break.  The number of lines still to be
     centered is associated with the current environment (*note
     Environments::).

     The following example demonstrates the differences.  Here the
     input:


          .ll 4i
          .ce 1000
          This is a small text fragment which shows the differences
          between the `.ce' and the `.ad c' request.
          .ce 0
          
          .ad c
          This is a small text fragment which shows the differences
          between the `.ce' and the `.ad c' request.

     And here the result:


            This is a small text fragment which
                   shows the differences
          between the `.ce' and the `.ad c' request.
          
            This is a small text fragment which
          shows the differences between the `.ce'
                  and the `.ad c' request.

     With no arguments, `ce' centers the next line of text.  NNN
     specifies the number of lines to be centered.  If the argument is
     zero or negative, centering is disabled.

     The basic length for centering text is the line length (as set
     with the `ll' request) minus the indentation (as set with the `in'
     request).  Temporary indentation is ignored.

     As can be seen in the previous example, it is a common idiom to
     turn on centering for a large number of lines, and to turn off
     centering after text to be centered.  This is useful for any
     request which takes a number of lines as an argument.

     The `.ce' read-only number register contains the number of lines
     remaining to be centered, as set by the `ce' request.

 - Request: .rj [nnn]
 - Register: \n[.rj]
     Justify unfilled text to the right margin.  Arguments are
     identical to the `ce' request.  The `.rj' read-only number
     register is the number of lines to be right-justified as set by
     the `rj' request.  This request causes a break.  The number of
     lines still to be right-justified is associated with the current
     environment (*note Environments::).