1 This is groff, produced by makeinfo version 4.2 from ./groff.texinfo.
3 This manual documents GNU `troff' version 1.18.
5 Copyright (C) 1994-2000, 2001, 2002 Free Software Foundation, Inc.
7 Permission is granted to copy, distribute and/or modify this
8 document under the terms of the GNU Free Documentation License,
9 Version 1.1 or any later version published by the Free Software
10 Foundation; with no Invariant Sections, with the Front-Cover texts
11 being `A GNU Manual," and with the Back-Cover Texts as in (a)
12 below. A copy of the license is included in the section entitled
13 `GNU Free Documentation License."
15 (a) The FSF's Back-Cover Text is: `You have freedom to copy and
16 modify this GNU Manual, like GNU software. Copies published by
17 the Free Software Foundation raise funds for GNU development."
19 INFO-DIR-SECTION Miscellaneous
21 * Groff: (groff). The GNU troff document formatting system.
25 File: groff, Node: Tab Stops, Next: Implicit Line Breaks, Prev: Sentences, Up: Text
30 `gtroff' translates "tabulator characters", also called "tabs"
31 (normally code point ASCII `0x09' or EBCDIC `0x05'), in the input into
32 movements to the next tabulator stop. These tab stops are initially
33 located every half inch across the page. Using this, simple tables can
34 be made easily. However, it can often be deceptive as the appearance
35 (and width) of the text on a terminal and the results from `gtroff' can
38 Also, a possible sticking point is that lines beginning with tab
39 characters are still filled, again producing unexpected results. For
40 example, the following input
49 *Note Tabs and Fields::.
52 File: groff, Node: Implicit Line Breaks, Prev: Tab Stops, Up: Text
57 An important concept in `gtroff' is the "break". When a break
58 occurs, `gtroff' outputs the partially filled line (unjustified), and
59 resumes collecting and filling text on the next output line.
61 There are several ways to cause a break in `gtroff'. A blank line
62 not only causes a break, but it also outputs a one-line vertical space
63 (effectively a blank line). Note that this behaviour can be modified
64 with the blank line macro request `blm'. *Note Blank Line Traps::.
66 A line that begins with a space causes a break and the space is
67 output at the beginning of the next line. Note that this space isn't
68 adjusted, even in fill mode.
70 The end of file also causes a break - otherwise the last line of the
73 Certain requests also cause breaks, implicitly or explicitly. This
74 is discussed in *Note Manipulating Filling and Adjusting::.
77 File: groff, Node: Input Conventions, Next: Measurements, Prev: Text, Up: gtroff Reference
82 Since `gtroff' does filling automatically, it is traditional in
83 `groff' not to try and type things in as nicely formatted paragraphs.
84 These are some conventions commonly used when typing `gtroff' text:
86 * Break lines after punctuation, particularly at the end of a
87 sentence and in other logical places. Keep separate phrases on
88 lines by themselves, as entire phrases are often added or deleted
91 * Try to keep lines less than 40-60 characters, to allow space for
94 * Do not try to do any formatting in a WYSIWYG manner (i.e., don't
95 try using spaces to get proper indentation).
98 File: groff, Node: Measurements, Next: Expressions, Prev: Input Conventions, Up: gtroff Reference
103 `gtroff' (like many other programs) requires numeric parameters to
104 specify various measurements. Most numeric parameters(1) (*note
105 Measurements-Footnote-1::) may have a "measurement unit" attached.
106 These units are specified as a single character which immediately
107 follows the number or expression. Each of these units are understood,
108 by `gtroff', to be a multiple of its "basic unit". So, whenever a
109 different measurement unit is specified `gtroff' converts this into its
110 "basic units". This basic unit, represented by a `u', is a device
111 dependent measurement which is quite small, ranging from 1/75th to
112 1/72000th of an inch. The values may be given as fractional numbers;
113 however, fractional basic units are always rounded to integers.
115 Some of the measurement units are completely independent of any of
116 the current settings (e.g. type size) of `gtroff'.
119 Inches. An antiquated measurement unit still in use in certain
120 backwards countries with incredibly low-cost computer equipment.
121 One inch is equal to 2.54cm.
124 Centimeters. One centimeter is equal to 0.3937in.
127 Points. This is a typesetter's measurement used for measure type
128 size. It is 72 points to an inch.
131 Pica. Another typesetting measurement. 6 Picas to an inch (and
132 12 points to a pica).
136 *Note Fractional Type Sizes::, for a discussion of these units.
139 Fractions. Value is 65536. *Note Colors::, for usage.
141 The other measurements understood by `gtroff' depend on settings
142 currently in effect in `gtroff'. These are very useful for specifying
143 measurements which should look proper with any size of text.
146 Ems. This unit is equal to the current font size in points. So
147 called because it is _approximately_ the width of the letter `m'
151 Ens. In `groff', this is half of an em.
154 Vertical space. This is equivalent to the current line spacing.
155 *Note Sizes::, for more information about this.
165 File: groff, Node: Measurements-Footnotes, Up: Measurements
167 (1) those that specify vertical or horizontal motion or a type size
170 File: groff, Node: Default Units, Prev: Measurements, Up: Measurements
175 Many requests take a default unit. While this can be helpful at
176 times, it can cause strange errors in some expressions. For example,
177 the line length request expects em units. Here are several attempts to
178 get a line length of 3.5 inches and their results:
188 Everything is converted to basic units first. In the above example it
189 is assumed that 1i equals 240u, and 1m equals 10p (thus 1m equals 33u).
190 The value 7i/2 is first handled as 7i/2m, then converted to 1680u/66u
191 which is 25u, and this is approximately 0.1i. As can be seen, a
192 scaling indicator after a closing parenthesis is simply ignored.
194 Thus, the safest way to specify measurements is to always attach a
195 scaling indicator. If you want to multiply or divide by a certain
196 scalar value, use `u' as the unit for that value.
199 File: groff, Node: Expressions, Next: Identifiers, Prev: Measurements, Up: gtroff Reference
204 `gtroff' has most arithmetic operators common to other languages:
206 * Arithmetic: `+' (addition), `-' (subtraction), `/' (division), `*'
207 (multiplication), `%' (modulo).
209 `gtroff' only provides integer arithmetic. The internal type used
210 for computing results is `int', which is usually a 32bit signed
213 * Comparison: `<' (less than), `>' (greater than), `<=' (less than
214 or equal), `>=' (greater than or equal), `=' (equal), `==' (the
217 * Logical: `&' (logical and), `:' (logical or).
219 * Unary operators: `-' (negating, i.e. changing the sign), `+' (just
220 for completeness; does nothing in expressions), `!' (logical not;
221 this works only within `if' and `while' requests). See below for
222 the use of unary operators in motion requests.
224 * Extrema: `>?' (maximum), `<?' (minimum).
231 .nr z (\n[x] >? \n[y])
233 The register `z' now contains 5.
235 * Scaling: `(C;E)'. Evaluate E using C as the default scaling
236 indicator. If C is missing, ignore scaling indicators in the
239 Parentheses may be used as in any other language. However, in
240 `gtroff' they are necessary to ensure order of evaluation. `gtroff'
241 has no operator precedence; expressions are evaluated left to right.
242 This means that `gtroff' evaluates `3+5*4' as if it were parenthesized
243 like `(3+5)*4', not as `3+(5*4)', as might be expected.
245 For many requests which cause a motion on the page, the unary
246 operators `+' and `-' work differently if leading an expression. They
247 then indicate a motion relative to the current position (down or up,
250 Similarly, a leading `|' operator indicates an absolute position.
251 For vertical movements, it specifies the distance from the top of the
252 page; for horizontal movements, it gives the distance from the beginning
255 `+' and `-' are also treated differently by the following requests
256 and escapes: `bp', `in', `ll', `lt', `nm', `nr', `pl', `pn', `po', `ps',
257 `pvs', `rt', `ti', `\H', `\R', and `\s'. Here, leading plus and minus
258 signs indicate increments and decrements.
260 *Note Setting Registers::, for some examples.
262 - Escape: \B'ANYTHING'
263 Return 1 if ANYTHING is a valid numeric expression; or 0 if
264 ANYTHING is empty or not a valid numeric expression.
266 Due to the way arguments are parsed, spaces are not allowed in
267 expressions, unless the entire expression is surrounded by parentheses.
269 *Note Request Arguments::, and *Note Conditionals and Loops::.
272 File: groff, Node: Identifiers, Next: Embedded Commands, Prev: Expressions, Up: gtroff Reference
277 Like any other language, `gtroff' has rules for properly formed
278 "identifiers". In `gtroff', an identifier can be made up of almost any
279 printable character, with the exception of the following characters:
281 * Whitespace characters (spaces, tabs, and newlines).
283 * Backspace (ASCII `0x08' or EBCDIC `0x16') and character code
286 * The following input characters are invalid and are ignored if
287 `groff' runs on a machine based on ASCII, causing a warning
288 message of type `input' (see *Note Debugging::, for more details):
289 `0x00', `0x0B', `0x0D'-`0x1F', `0x80'-`0x9F'.
291 And here are the invalid input characters if `groff' runs on an
292 EBCDIC host: `0x00', `0x08', `0x09', `0x0B', `0x0D'-`0x14',
293 `0x17'-`0x1F', `0x30'-`0x3F'.
295 Currently, some of these reserved codepoints are used internally,
296 thus making it non-trivial to extend `gtroff' to cover Unicode or
297 other character sets and encodings which use characters of these
300 Note that invalid characters are removed before parsing; an
301 identifier `foo', followed by an invalid character, followed by
302 `bar' is treated as `foobar'.
304 For example, any of the following is valid.
313 Note that identifiers longer than two characters with a closing bracket
314 (`]') in its name can't be accessed with escape sequences which expect
315 an identifier as a parameter. For example, `\[foo]]' accesses the
316 glyph `foo', followed by `]', whereas `\C'foo]'' really asks for glyph
319 To avoid problems with the `refer' preprocessor, macro names should
320 not start with `[' or `]'. Due to backwards compatibility, everything
321 after `.[' and `.]' is handled as a special argument to `refer'. For
322 example, `.[foo' makes `refer' to start a reference, using `foo' as a
326 Test whether an identifier IDENT is valid in `gtroff'. It expands
327 to the character 1 or 0 according to whether its argument (usually
328 delimited by quotes) is or is not acceptable as the name of a
329 string, macro, diversion, number register, environment, or font.
330 It returns 0 if no argument is given. This is useful for looking
331 up user input in some sort of associative table.
338 *Note Escapes::, for details on parameter delimiting characters.
340 Identifiers in `gtroff' can be any length, but, in some contexts,
341 `gtroff' needs to be told where identifiers end and text begins (and in
342 different ways depending on their length):
346 * Two characters. Must be prefixed with `(' in some situations.
348 * Arbitrary length (`gtroff' only). Must be bracketed with `['
349 and `]' in some situations. Any length identifier can be put in
352 Unlike many other programming languages, undefined identifiers are
353 silently ignored or expanded to nothing. When `gtroff' finds an
354 undefined identifier, it emits a warning, doing the following:
356 * If the identifier is a string, macro, or diversion, `gtroff'
359 * If the identifier is a number register, `gtroff' defines it with a
362 *Note Warnings::., *Note Interpolating Registers::, and *Note
365 Note that macros, strings, and diversions share the same name space.
380 As can be seen in the previous example, `gtroff' reuses the identifier
381 `xxx', changing it from a macro to a diversion. No warning is emitted!
382 The contents of the first macro definition is lost.
384 *Note Interpolating Registers::, and *Note Strings::.
387 File: groff, Node: Embedded Commands, Next: Registers, Prev: Identifiers, Up: gtroff Reference
392 Most documents need more functionality beyond filling, adjusting and
393 implicit line breaking. In order to gain further functionality,
394 `gtroff' allows commands to be embedded into the text, in two ways.
396 The first is a "request" which takes up an entire line, and does
397 some large-scale operation (e.g. break lines, start new pages).
399 The other is an "escape" which can be usually embedded anywhere in
400 the text; most requests can accept it even as an argument. Escapes
401 generally do more minor operations like sub- and superscripts, print a
411 File: groff, Node: Requests, Next: Macros, Prev: Embedded Commands, Up: Embedded Commands
416 A request line begins with a control character, which is either a
417 single quote (`'', the "no-break control character") or a period (`.',
418 the normal "control character"). These can be changed; see *Note
419 Character Translations::, for details. After this there may be
420 optional tabs or spaces followed by an identifier which is the name of
421 the request. This may be followed by any number of space-separated
422 arguments (_no_ tabs here).
424 Since a control character followed by whitespace only is ignored, it
425 is common practice to use this feature for structuring the source code
426 of documents or macro packages.
438 Another possibility is to use the blank line macro request `blm' by
439 assigning an empty macro to it.
444 .blm do-nothing \" activate blank line macro
455 .blm \" deactivate blank line macro
457 *Note Blank Line Traps::.
459 To begin a line with a control character without it being
460 interpreted, precede it with `\&'. This represents a zero width space,
461 which means it does not affect the output.
463 In most cases the period is used as a control character. Several
464 requests cause a break implicitly; using the single quote control
465 character prevents this.
469 * Request Arguments::
472 File: groff, Node: Request Arguments, Prev: Requests, Up: Requests
477 Arguments to requests (and macros) are processed much like the shell:
478 The line is split into arguments according to spaces.(1) (*note Request
479 Arguments-Footnote-1::) An argument which is intended to contain
480 spaces can either be enclosed in double quotes, or have the spaces
481 "escaped" with backslashes.
483 Here are a few examples:
486 .uh The Mouse Problem
487 .uh "The Mouse Problem"
488 .uh The\ Mouse\ Problem
490 The first line is the `uh' macro being called with 3 arguments, `The',
491 `Mouse', and `Problem'. The latter two have the same effect of calling
492 the `uh' macro with one argument, `The Mouse Problem'.(2) (*note
493 Request Arguments-Footnote-2::)
495 A double quote which isn't preceded by a space doesn't start a macro
496 argument. If not closing a string, it is printed literally.
501 .xxx a" "b c" "de"fg"
503 has the arguments `a"', `b c', `de', and `fg"'. Don't rely on this
506 There are two possibilities to get a double quote reliably.
508 * Enclose the whole argument with double quotes and use two
509 consecutive double quotes to represent a single one. This
510 traditional solution has the disadvantage that double quotes don't
511 survive argument expansion again if called in compatibility mode
512 (using the `-C' option of `groff'):
516 . tm xx: `\\$1' `\\$2' `\\$3'
518 . yy "\\$1" "\\$2" "\\$3"
521 . tm yy: `\\$1' `\\$2' `\\$3'
523 .xx A "test with ""quotes""" .
524 => xx: `A' `test with "quotes"' `.'
525 => yy: `A' `test with ' `quotes""'
527 If not in compatibility mode, you get the expected result
530 xx: `A' `test with "quotes"' `.'
531 yy: `A' `test with "quotes"' `.'
533 since `gtroff' preserves the input level.
535 * Use the double quote glyph `\(dq'. This works with and without
536 compatibility mode enabled since `gtroff' doesn't convert `\(dq'
537 back to a double quote input character.
539 Not that this method won't work with UNIX `troff' in general since
540 the glyph `dq' isn't defined normally.
542 Double quotes in the `ds' request are handled differently. *Note
543 Strings::, for more details.
546 File: groff, Node: Request Arguments-Footnotes, Up: Request Arguments
548 (1) Plan 9's `troff' implementation also allows tabs for argument
549 separation - `gtroff' intentionally doesn't support this.
551 (2) The last solution, i.e., using escaped spaces, is "classical" in
552 the sense that it can be found in most `troff' documents.
553 Nevertheless, it is not optimal in all situations, since `\ ' inserts a
554 fixed-width, non-breaking space character which can't stretch.
555 `gtroff' provides a different command `\~' to insert a stretchable,
559 File: groff, Node: Macros, Next: Escapes, Prev: Requests, Up: Embedded Commands
564 `gtroff' has a "macro" facility for defining a series of lines which
565 can be invoked by name. They are called in the same manner as requests
566 - arguments also may be passed in the same manner.
568 *Note Writing Macros::, and *Note Request Arguments::.
571 File: groff, Node: Escapes, Prev: Macros, Up: Embedded Commands
576 Escapes may occur anywhere in the input to `gtroff'. They usually
577 begin with a backslash and are followed by a single character which
578 indicates the function to be performed. The escape character can be
579 changed; see *Note Character Translations::.
581 Escape sequences which require an identifier as a parameter accept
582 three possible syntax forms.
584 * The next single character is the identifier.
586 * If this single character is an opening parenthesis, take the
587 following two characters as the identifier. Note that there is no
588 closing parenthesis after the identifier.
590 * If this single character is an opening bracket, take all characters
591 until a closing bracket as the identifier.
600 Other escapes may require several arguments and/or some special
601 format. In such cases the argument is traditionally enclosed in single
602 quotes (and quotes are always used in this manual for the definitions
603 of escape sequences). The enclosed text is then processed according to
604 what that escape expects. Example:
609 Note that the quote character can be replaced with any other
610 character which does not occur in the argument (even a newline or a
611 space character) in the following escapes: `\o', `\b', and `\X'. This
623 possible, but it is better not to use this feature to avoid confusion.
625 The following escapes sequences (which are handled similarly to
626 characters since they don't take a parameter) are also allowed as
627 delimiters: `\%', `\ ', `\|', `\^', `\{', `\}', `\'', `\`', `\-', `\_',
628 `\!', `\?', `\@', `\)', `\/', `\,', `\&', `\:', `\~', `\0', `\a', `\c',
629 `\d', `\e', `\E', `\p', `\r', `\t', and `\u'. Again, don't use these
632 No newline characters as delimiters are allowed in the following
633 escapes: `\A', `\B', `\Z', `\C', and `\w'.
635 Finally, the escapes `\D', `\h', `\H', `\l', `\L', `\N', `\R', `\s',
636 `\S', `\v', and `\x' can't use the following characters as delimiters:
638 * The digits `0'-`9'.
640 * The (single-character) operators `+-/*%<>=&:().'.
642 * The space, tab, and newline characters.
644 * All escape sequences except `\%', `\:', `\{', `\}', `\'', `\`',
645 `\-', `\_', `\!', `\@', `\/', `\c', `\e', and `\p'.
647 To have a backslash (actually, the current escape character) appear
648 in the output several escapes are defined: `\\', `\e' or `\E'. These
649 are very similar, and only differ with respect to being used in macros
650 or diversions. *Note Character Translations::, for an exact
651 description of those escapes.
653 *Note Implementation Differences::, *Note Copy-in Mode::, and *Note
654 Diversions::, *Note Identifiers::, for more information.
661 File: groff, Node: Comments, Prev: Escapes, Up: Escapes
666 Probably one of the most(1) (*note Comments-Footnote-1::) common
667 forms of escapes is the comment.
670 Start a comment. Everything to the end of the input line is
673 This may sound simple, but it can be tricky to keep the comments
674 from interfering with the appearance of the final output.
676 If the escape is to the right of some text or a request, that
677 portion of the line is ignored, but the space leading up to it is
678 noticed by `gtroff'. This only affects the `ds' and `as' request
681 One possibly irritating idiosyncracy is that tabs must not be used
682 to line up comments. Tabs are not treated as whitespace between
683 the request and macro arguments.
685 A comment on a line by itself is treated as a blank line, because
686 after eliminating the comment, that is all that remains:
700 To avoid this, it is common to start the line with `.\"' which
701 causes the line to be treated as an undefined request and thus
704 Another commenting scheme seen sometimes is three consecutive
705 single quotes (`'''') at the beginning of a line. This works, but
706 `gtroff' gives a warning about an undefined macro (namely `'''),
707 which is harmless, but irritating.
710 To avoid all this, `gtroff' has a new comment mechanism using the
711 `\#' escape. This escape works the same as `\"' except that the
712 newline is also ignored:
727 Ignore all input until `gtroff' encounters the macro named `.'YY
728 on a line by itself (or `..' if YY is not specified). This is
729 useful for commenting out large blocks of text:
734 This is part of a large block
735 of text that has been
736 temporarily(?) commented out.
738 We can restore it simply by removing
739 the .ig request and the ".." at the
742 More text text text...
747 text text text... More text text text...
749 Note that the commented-out block of text does not cause a break.
751 The input is read in copy-mode; auto-incremented registers _are_
752 affected (*note Auto-increment::).
755 File: groff, Node: Comments-Footnotes, Up: Comments
757 (1) Unfortunately, this is a lie. But hopefully future `gtroff'
758 hackers will believe it `:-)'
761 File: groff, Node: Registers, Next: Manipulating Filling and Adjusting, Prev: Embedded Commands, Up: gtroff Reference
766 Numeric variables in `gtroff' are called "registers". There are a
767 number of built-in registers, supplying anything from the date to
768 details of formatting parameters.
770 *Note Identifiers::, for details on register identifiers.
774 * Setting Registers::
775 * Interpolating Registers::
777 * Assigning Formats::
778 * Built-in Registers::
781 File: groff, Node: Setting Registers, Next: Interpolating Registers, Prev: Registers, Up: Registers
786 Define or set registers using the `nr' request or the `\R' escape.
788 - Request: .nr ident value
789 - Escape: \R'IDENT VALUE'
790 Set number register IDENT to VALUE. If IDENT doesn't exist,
793 The argument to `\R' usually has to be enclosed in quotes. *Note
794 Escapes::, for details on parameter delimiting characters.
796 The `\R' escape doesn't produce an input token in `gtroff'; with
797 other words, it vanishes completely after `gtroff' has processed
800 For example, the following two lines are equivalent:
803 .nr a (((17 + (3 * 4))) % 4)
804 \R'a (((17 + (3 * 4))) % 4)'
807 Both `nr' and `\R' have two additional special forms to increment or
808 decrement a register.
810 - Request: .nr ident +value
811 - Request: .nr ident -value
812 - Escape: \R'IDENT +VALUE'
813 - Escape: \R'IDENT -VALUE'
814 Increment (decrement) register IDENT by VALUE.
822 To assign the negated value of a register to another register,
823 some care must be taken to get the desired result:
835 The surrounding parentheses prevent the interpretation of the
836 minus sign as a decrementing operator. An alternative is to start
837 the assignment with a `0':
851 Remove number register IDENT. If IDENT doesn't exist, the request
854 - Request: .rnn ident1 ident2
855 Rename number register IDENT1 to IDENT2. If either IDENT1 or
856 IDENT2 doesn't exist, the request is ignored.
858 - Request: .aln ident1 ident2
859 Create an alias IDENT1 for a number register IDENT2. The new name
860 and the old name are exactly equivalent. If IDENT1 is undefined,
861 a warning of type `reg' is generated, and the request is ignored.
862 *Note Debugging::, for information about warnings.
865 File: groff, Node: Interpolating Registers, Next: Auto-increment, Prev: Setting Registers, Up: Registers
867 Interpolating Registers
868 -----------------------
870 Numeric registers can be accessed via the `\n' escape.
875 Interpolate number register with name IDENT (one-character name I,
876 two-character name ID). This means that the value of the register
877 is expanded in-place while `gtroff' is parsing the input line.
878 Nested assignments (also called indirect assignments) are possible.
898 File: groff, Node: Auto-increment, Next: Assigning Formats, Prev: Interpolating Registers, Up: Registers
903 Number registers can also be auto-incremented and auto-decremented.
904 The increment or decrement value can be specified with a third argument
905 to the `nr' request or `\R' escape.
907 - Request: .nr ident value incr
908 Set number register IDENT to VALUE; the increment for
909 auto-incrementing is set to INCR. Note that the `\R' escape
910 doesn't support this notation.
912 To activate auto-incrementing, the escape `\n' has a special syntax
925 Before interpolating, increment or decrement IDENT (one-character
926 name I, two-character name ID) by the auto-increment value as
927 specified with the `nr' request (or the `\R' escape). If no
928 auto-increment value has been specified, these syntax forms are
937 \n+a, \n+a, \n+a, \n+a, \n+a
939 \n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx
941 \n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo]
947 -5, -10, -15, -20, -25
950 To change the increment value without changing the value of a
951 register (A in the example), the following can be used:
957 File: groff, Node: Assigning Formats, Next: Built-in Registers, Prev: Auto-increment, Up: Registers
962 When a register is used in the text of an input file (as opposed to
963 part of an expression), it is textually replaced (or interpolated) with
964 a representation of that number. This output format can be changed to
965 a variety of formats (numbers, Roman numerals, etc.). This is done
966 using the `af' request.
968 - Request: .af ident format
969 Change the output format of a number register. The first argument
970 IDENT is the name of the number register to be changed, and the
971 second argument FORMAT is the output format. The following output
972 formats are available:
975 Decimal arabic numbers. This is the default format: 0, 1, 2,
979 Decimal numbers with as many digits as specified. So, `00'
980 would result in printing numbers as 01, 02, 03, ....
982 In fact, any digit instead of zero will do; `gtroff' only
983 counts how many digits are specified. As a consequence,
984 `af''s default format `1' could be specified as `0' also (and
985 exactly this is returned by the `\g' escape, see below).
988 Upper-case Roman numerals: 0, I, II, III, IV, ....
991 Lower-case Roman numerals: 0, i, ii, iii, iv, ....
994 Upper-case letters: 0, A, B, C, ..., Z, AA, AB, ....
997 Lower-case letters: 0, a, b, c, ..., z, aa, ab, ....
999 Omitting the number register format causes a warning of type
1000 `missing'. *Note Debugging::, for more details. Specifying a
1001 nonexistent format causes an error.
1003 The following example produces `10, X, j, 010':
1007 .af a 1 \" the default format
1016 The largest number representable for the `i' and `I' formats is
1017 39999 (or -39999); UNIX `troff' uses `z' and `w' to represent
1018 10000 and 5000 in Roman numerals, and so does `gtroff'.
1019 Currently, the correct glyphs of Roman numeral five thousand and
1020 Roman numeral ten thousand (Unicode code points `U+2182' and
1021 `U+2181', respectively) are not available.
1023 If IDENT doesn't exist, it is created.
1025 Changing the output format of a read-only register causes an
1026 error. It is necessary to first copy the register's value to a
1027 writeable register, then apply the `af' request to this other
1033 Return the current format of the specified register IDENT
1034 (one-character name I, two-character name ID). For example, `\ga'
1035 after the previous example would produce the string `000'. If the
1036 register hasn't been defined yet, nothing is returned.
1039 File: groff, Node: Built-in Registers, Prev: Assigning Formats, Up: Registers
1044 The following lists some built-in registers which are not described
1045 elsewhere in this manual. Any register which begins with a `.' is
1046 read-only. A complete listing of all built-in registers can be found in
1047 appendix *Note Register Index::.
1050 This string-valued register returns the current input file name.
1053 Horizontal resolution in basic units.
1056 Vertical resolution in basic units.
1059 The number of seconds after the minute, normally in the range 0
1060 to 59, but can be up to 61 to allow for leap seconds. Initialized
1061 at start-up of `gtroff'.
1064 The number of minutes after the hour, in the range 0 to 59.
1065 Initialized at start-up of `gtroff'.
1068 The number of hours past midnight, in the range 0 to 23.
1069 Initialized at start-up of `gtroff'.
1072 Day of the week (1-7).
1075 Day of the month (1-31).
1078 Current month (1-12).
1084 The current year minus 1900. Unfortunately, the documentation of
1085 UNIX Version 7's `troff' had a year 2000 bug: It incorrectly
1086 claimed that `yr' contains the last two digits of the year. That
1087 claim has never been true of either AT&T `troff' or GNU `troff'.
1088 Old `troff' input that looks like this:
1091 '\" The following line stopped working after 1999
1092 This document was formatted in 19\n(yr.
1094 can be corrected as follows:
1097 This document was formatted in \n[year].
1099 or, to be portable to older `troff' versions, as follows:
1103 This document was formatted in \n(y4.
1107 The current _input_ line number. Register `.c' is read-only,
1108 whereas `c.' (a `gtroff' extension) is writable also, affecting
1112 The current _output_ line number after a call to the `nm' request
1113 to activate line numbering.
1115 *Note Miscellaneous::, for more information about line numbering.
1118 The major version number. For example, if the version number
1119 is 1.03 then `.x' contains `1'.
1122 The minor version number. For example, if the version number
1123 is 1.03 then `.y' contains `03'.
1126 The revision number of `groff'.
1129 The process ID of `gtroff'.
1132 Always 1. Macros should use this to determine whether they are
1133 running under GNU `troff'.
1136 If the command line option `-a' is used to produce an ASCII
1137 approximation of the output, this is set to 1, zero otherwise.
1138 *Note Groff Options::.
1141 This register is set to 1 (and to 0 otherwise) if the current page
1142 is actually being printed, i.e., if the `-o' option is being used
1143 to only print selected pages. *Note Groff Options::, for more
1147 If `gtroff' is called with the `-T' command line option, the
1148 number register `.T' is set to 1, and zero otherwise. *Note Groff
1151 Additionally, `gtroff' predefines a single read-write string
1152 register `.T' which contains the current output device (for
1153 example, `latin1' or `ps').
1156 File: groff, Node: Manipulating Filling and Adjusting, Next: Manipulating Hyphenation, Prev: Registers, Up: gtroff Reference
1158 Manipulating Filling and Adjusting
1159 ==================================
1161 Various ways of causing "breaks" were given in *Note Implicit Line
1162 Breaks::. The `br' request likewise causes a break. Several other
1163 requests also cause breaks, but implicitly. These are `bp', `ce',
1164 `cf', `fi', `fl', `in', `nf', `rj', `sp', `ti', and `trf'.
1167 Break the current line, i.e., the input collected so far is emitted
1170 If the no-break control character is used, `gtroff' suppresses the
1180 Initially, `gtroff' fills and adjusts text to both margins. Filling
1181 can be disabled via the `nf' request and re-enabled with the `fi'
1186 Activate fill mode (which is the default). This request implicitly
1187 enables adjusting; it also inserts a break in the text currently
1188 being filled. The read-only number register `.u' is set to 1.
1190 The fill mode status is associated with the current environment
1191 (*note Environments::).
1193 See *Note Line Control::, for interaction with the `\c' escape.
1196 Activate no-fill mode. Input lines are output as-is, retaining
1197 line breaks and ignoring the current line length. This command
1198 implicitly disables adjusting; it also causes a break. The number
1199 register `.u' is set to 0.
1201 The fill mode status is associated with the current environment
1202 (*note Environments::).
1204 See *Note Line Control::, for interaction with the `\c' escape.
1206 - Request: .ad [mode]
1210 Activation and deactivation of adjusting is done implicitly with
1211 calls to the `fi' or `nf' requests.
1213 MODE can have one of the following values:
1216 Adjust text to the left margin. This produces what is
1217 traditionally called ragged-right text.
1220 Adjust text to the right margin, producing ragged-left text.
1223 Center filled text. This is different to the `ce' request
1224 which only centers text without filling.
1228 Justify to both margins. This is the default used by
1231 With no argument, `gtroff' adjusts lines in the same way it did
1232 before adjusting was deactivated (with a call to `na', for
1243 .ad \" back to centering
1246 The current adjustment mode is available in the read-only number
1247 register `.j'; it can be stored and subsequently used to set
1250 The adjustment mode status is associated with the current
1251 environment (*note Environments::).
1254 Disable adjusting. This request won't change the current
1255 adjustment mode: A subsequent call to `ad' uses the previous
1258 The adjustment mode status is associated with the current
1259 environment (*note Environments::).
1263 Adjust the current line and cause a break.
1265 In most cases this produces very ugly results since `gtroff'
1266 doesn't have a sophisticated paragraph building algorithm (as TeX
1267 have, for example); instead, `gtroff' fills and adjusts a paragraph
1271 This is an uninteresting sentence.
1272 This is an uninteresting sentence.\p
1273 This is an uninteresting sentence.
1278 This is an uninteresting sentence. This is an
1279 uninteresting sentence.
1280 This is an uninteresting sentence.
1283 - Request: .ss word_space_size [sentence_space_size]
1285 - Register: \n[.sss]
1286 Change the minimum size of a space between filled words. It takes
1287 its units as one twelfth of the space width parameter for the
1288 current font. Initially both the WORD_SPACE_SIZE and
1289 SENTENCE_SPACE_SIZE are 12.
1291 If two arguments are given to the `ss' request, the second
1292 argument sets the sentence space size. If the second argument is
1293 not given, sentence space size is set to WORD_SPACE_SIZE. The
1294 sentence space size is used in two circumstances: If the end of a
1295 sentence occurs at the end of a line in fill mode, then both an
1296 inter-word space and a sentence space are added; if two spaces
1297 follow the end of a sentence in the middle of a line, then the
1298 second space is a sentence space. If a second argument is never
1299 given to the `ss' request, the behaviour of UNIX `troff' is the
1300 same as that exhibited by GNU `troff'. In GNU `troff', as in UNIX
1301 `troff', a sentence should always be followed by either a newline
1304 The read-only number registers `.ss' and `.sss' hold the values of
1305 the parameters set by the first and second arguments of the `ss'
1308 The word space and sentence space values are associated with the
1309 current environment (*note Environments::).
1311 Contrary to AT&T `troff', this request is _not_ ignored if a TTY
1312 output device is used; the given values are then rounded down to a
1313 multiple of 12 (*note Implementation Differences::).
1315 The request is ignored if there is no parameter.
1317 - Request: .ce [nnn]
1319 Center text. While the `.ad c' request also centers text, it
1320 fills the text as well. `ce' does not fill the text it affects.
1321 This request causes a break. The number of lines still to be
1322 centered is associated with the current environment (*note
1325 The following example demonstrates the differences. Here the
1331 This is a small text fragment which shows the differences
1332 between the `.ce' and the `.ad c' request.
1336 This is a small text fragment which shows the differences
1337 between the `.ce' and the `.ad c' request.
1339 And here the result:
1342 This is a small text fragment which
1343 shows the differences
1344 between the `.ce' and the `.ad c' request.
1346 This is a small text fragment which
1347 shows the differences between the `.ce'
1348 and the `.ad c' request.
1350 With no arguments, `ce' centers the next line of text. NNN
1351 specifies the number of lines to be centered. If the argument is
1352 zero or negative, centering is disabled.
1354 The basic length for centering text is the line length (as set
1355 with the `ll' request) minus the indentation (as set with the `in'
1356 request). Temporary indentation is ignored.
1358 As can be seen in the previous example, it is a common idiom to
1359 turn on centering for a large number of lines, and to turn off
1360 centering after text to be centered. This is useful for any
1361 request which takes a number of lines as an argument.
1363 The `.ce' read-only number register contains the number of lines
1364 remaining to be centered, as set by the `ce' request.
1366 - Request: .rj [nnn]
1368 Justify unfilled text to the right margin. Arguments are
1369 identical to the `ce' request. The `.rj' read-only number
1370 register is the number of lines to be right-justified as set by
1371 the `rj' request. This request causes a break. The number of
1372 lines still to be right-justified is associated with the current
1373 environment (*note Environments::).