aboutsummaryrefslogtreecommitdiff
path: root/contrib/groff/doc/groff-3
diff options
context:
space:
mode:
Diffstat (limited to 'contrib/groff/doc/groff-3')
-rw-r--r--contrib/groff/doc/groff-31374
1 files changed, 1374 insertions, 0 deletions
diff --git a/contrib/groff/doc/groff-3 b/contrib/groff/doc/groff-3
new file mode 100644
index 000000000000..b808a39b6c49
--- /dev/null
+++ b/contrib/groff/doc/groff-3
@@ -0,0 +1,1374 @@
+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
+
+
+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::.
+
+
+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::.
+
+
+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).
+
+
+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::
+
+
+File: groff, Node: Measurements-Footnotes, Up: Measurements
+
+ (1) those that specify vertical or horizontal motion or a type size
+
+
+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.
+
+
+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::.
+
+
+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::.
+
+
+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::
+
+
+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::
+
+
+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.
+
+
+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.
+
+
+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::.
+
+
+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::
+
+
+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::).
+
+
+File: groff, Node: Comments-Footnotes, Up: Comments
+
+ (1) Unfortunately, this is a lie. But hopefully future `gtroff'
+hackers will believe it `:-)'
+
+
+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::
+
+
+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.
+
+
+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
+
+
+
+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
+
+
+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.
+
+
+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').
+
+
+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::).
+
generated by cgit v1.2.3 (git 2.25.1) at 2025-03-31 20:37:57 +0000