This is groff, produced by makeinfo version 4.3d from ./groff.texinfo. This manual documents GNU `troff' version 1.19. Copyright (C) 1994-2000, 2001, 2002, 2003 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 Typesetting START-INFO-DIR-ENTRY * Groff: (groff). The GNU troff document formatting system. END-INFO-DIR-ENTRY  File: groff, Node: ms Strings and Special Characters, Prev: ms TOC, Up: ms Page Layout Strings and Special Characters .............................. The `ms' macros provide the following predefined strings. You can change the string definitions to help in creating documents in languages other than English. - String: \*[REFERENCES] Contains the string printed at the beginning of the references (bibliography) page. The default is `References'. - String: \*[ABSTRACT] Contains the string printed at the beginning of the abstract. The default is `ABSTRACT'. - String: \*[TOC] Contains the string printed at the beginning of the table of contents. - String: \*[MONTH1] - String: \*[MONTH2] - String: \*[MONTH3] - String: \*[MONTH4] - String: \*[MONTH5] - String: \*[MONTH6] - String: \*[MONTH7] - String: \*[MONTH8] - String: \*[MONTH9] - String: \*[MONTH10] - String: \*[MONTH11] - String: \*[MONTH12] Prints the full name of the month in dates. The default is `January', `February', etc. The following special characters are available(1) (*note ms Strings and Special Characters-Footnote-1::): - String: \*[-] Prints an em dash. - String: \*[*Q] - String: \*[*U] Prints typographer's quotes in troff, plain quotes in nroff. `*Q' is the left quote and `*U' is the right quote. Improved accent marks are available in the `ms' macros. - Macro: .AM Specify this macro at the beginning of your document to enable extended accent marks and special characters. This is a Berkeley extension. To use the accent marks, place them *after* the character being accented. The following accent marks are available after invoking the `AM' macro: - String: \*['] Acute accent. - String: \*[`] Grave accent. - String: \*[^] Circumflex. - String: \*[,] Cedilla. - String: \*[~] Tilde. - String: \*[:] Umlaut. - String: \*[v] Hacek. - String: \*[_] Macron (overbar). - String: \*[.] Underdot. - String: \*[o] Ring above. The following are standalone characters available after invoking the `AM' macro: - String: \*[?] Upside-down question mark. - String: \*[!] Upside-down exclamation point. - String: \*[8] German ss ligature. - String: \*[3] Yogh. - String: \*[Th] Uppercase thorn. - String: \*[th] Lowercase thorn. - String: \*[D-] Uppercase eth. - String: \*[d-] Lowercase eth. - String: \*[q] Hooked o. - String: \*[ae] Lowercase ae ligature. - String: \*[Ae] Uppercase AE ligature.  File: groff, Node: ms Strings and Special Characters-Footnotes, Up: ms Strings and Special Characters (1) For an explanation what special characters are see *Note Special Characters::.  File: groff, Node: Differences from AT&T ms, Prev: ms Page Layout, Up: ms Differences from AT&T `ms' -------------------------- This section lists the (minor) differences between the `groff -ms' macros and AT&T `troff -ms' macros. * Menu: * Missing ms Macros:: * Additional ms Macros::  File: groff, Node: Missing ms Macros, Next: Additional ms Macros, Prev: Differences from AT&T ms, Up: Differences from AT&T ms `troff' macros not appearing in `groff' ....................................... Macros missing from `groff -ms' are cover page macros specific to Bell Labs. The macros known to be missing are: `.TM' Technical memorandum; a cover sheet style `.IM' Internal memorandum; a cover sheet style `.MR' Memo for record; a cover sheet style `.MF' Memo for file; a cover sheet style `.EG' Engineer's notes; a cover sheet style `.TR' Computing Science Tech Report; a cover sheet style `.OK' Other keywords `.CS' Cover sheet information `.MH' A cover sheet macro  File: groff, Node: Additional ms Macros, Prev: Missing ms Macros, Up: Differences from AT&T ms `groff' macros not appearing in AT&T `troff' ............................................ The `groff -ms' macros have a few minor extensions compared to the AT&T `troff -ms' macros. - Macro: .AM Improved accent marks. *Note ms Strings and Special Characters::, for details. - Macro: .DS I Indented display. The default behavior of AT&T `troff -ms' was to indent; the `groff' default prints displays flush left with the body text. - Macro: .CW Print text in `constant width' (Courier) font. - Macro: .IX Indexing term (printed on standard error). You can write a script to capture and process an index generated in this manner. The following additional number registers appear in `groff -ms': - Register: \n[MINGW] Specifies a minimum space between columns (for multi-column output); this takes the place of the `GW' register that was documented but apparently not implemented in AT&T `troff'. Several new string registers are available as well. You can change these to handle (for example) the local language. *Note ms Strings and Special Characters::, for details.  File: groff, Node: me, Next: mm, Prev: ms, Up: Macro Packages `me' ==== See the `meintro.me' and `meref.me' documents in groff's `doc' directory.  File: groff, Node: mm, Prev: me, Up: Macro Packages `mm' ==== See the `groff_mm(7)' man page (type `man groff_mm' at the command line).  File: groff, Node: gtroff Reference, Next: Preprocessors, Prev: Macro Packages, Up: Top `gtroff' Reference ****************** This chapter covers *all* of the facilities of `gtroff'. Users of macro packages may skip it if not interested in details. * Menu: * Text:: * Measurements:: * Expressions:: * Identifiers:: * Embedded Commands:: * Registers:: * Manipulating Filling and Adjusting:: * Manipulating Hyphenation:: * Manipulating Spacing:: * Tabs and Fields:: * Character Translations:: * Troff and Nroff Mode:: * Line Layout:: * Line Control:: * Page Layout:: * Page Control:: * Fonts and Symbols:: * Sizes:: * Strings:: * Conditionals and Loops:: * Writing Macros:: * Page Motions:: * Drawing Requests:: * Traps:: * Diversions:: * Environments:: * Suppressing output:: * Colors:: * I/O:: * Postprocessor Access:: * Miscellaneous:: * Gtroff Internals:: * Debugging:: * Implementation Differences::  File: groff, Node: Text, Next: Measurements, Prev: gtroff Reference, Up: gtroff Reference Text ==== `gtroff' input files contain text with control commands interspersed throughout. But, even without control codes, `gtroff' still does several things with the input text: * filling and adjusting * adding additional space after sentences * hyphenating * inserting implicit line breaks * Menu: * Filling and Adjusting:: * Hyphenation:: * Sentences:: * Tab Stops:: * Implicit Line Breaks:: * Input Conventions:: * Input Encodings::  File: groff, Node: Filling and Adjusting, Next: Hyphenation, Prev: Text, Up: Text Filling and Adjusting --------------------- When `gtroff' reads text, it collects words from the input and fits as many of them together on one output line as it can. This is known as "filling". Once `gtroff' has a "filled" line, it tries to "adjust" it. This means it widens the spacing between words until the text reaches the right margin (in the default adjustment mode). Extra spaces between words are preserved, but spaces at the end of lines are ignored. Spaces at the front of a line cause a "break" (breaks are explained in *Note Implicit Line Breaks::). *Note Manipulating Filling and Adjusting::.  File: groff, Node: Hyphenation, Next: Sentences, Prev: Filling and Adjusting, Up: Text Hyphenation ----------- Since the odds are not great for finding a set of words, for every output line, which fit nicely on a line without inserting excessive amounts of space between words, `gtroff' hyphenates words so that it can justify lines without inserting too much space between words. It uses an internal hyphenation algorithm (a simplified version of the algorithm used within TeX) to indicate which words can be hyphenated and how to do so. When a word is hyphenated, the first part of the word is added to the current filled line being output (with an attached hyphen), and the other portion is added to the next line to be filled. *Note Manipulating Hyphenation::.  File: groff, Node: Sentences, Next: Tab Stops, Prev: Hyphenation, Up: Text Sentences --------- Although it is often debated, some typesetting rules say there should be different amounts of space after various punctuation marks. For example, the `Chicago typsetting manual' says that a period at the end of a sentence should have twice as much space following it as would a comma or a period as part of an abbreviation. `gtroff' does this by flagging certain characters (normally `!', `?', and `.') as "end-of-sentence" characters. When `gtroff' encounters one of these characters at the end of a line, it appends a normal space followed by a "sentence space" in the formatted output. (This justifies one of the conventions mentioned in *Note Input Conventions::.) In addition, the following characters and symbols are treated transparently while handling end-of-sentence characters: `"', `'', `)', `]', `*', `\[dg]', and `\[rq]'. See the `cflags' request in *Note Using Symbols::, for more details. To prevent the insertion of extra space after an end-of-sentence character (at the end of a line), append `\&'.  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, Next: Input Conventions, 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: Input Encodings, Prev: Implicit Line Breaks, Up: Text 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: Input Encodings, Prev: Input Conventions, Up: Text Input Encodings --------------- Currently, the following input encodings are available. cp1047 This input encoding works only on EBCDIC platforms (and vice versa, the other input encodings don't work with EBCDIC); the file `cp1047.tmac' is by default loaded at start-up. latin-1 This is the default input encoding on non-EBCDIC platforms; the file `latin1.tmac' is loaded at start-up. latin-2 To use this encoding, either say `.mso latin2.tmac' at the very beginning of your document or use `-mlatin2' as a command line argument for `groff'. latin-9 (latin-0) This encoding is intended (at least in Europe) to replace latin-1 encoding. The main difference to latin-1 is that latin-9 contains the Euro character. To use this encoding, either say `.mso latin9.tmac' at the very beginning of your document or use `-mlatin9' as a command line argument for `groff'. Note that it can happen that some input encoding characters are not available for a particular output device. For example, saying groff -Tlatin1 -mlatin9 ... will fail if you use the Euro character in the input. Usually, this limitation is present only for devices which have a limited set of output glyphs (e.g. `-Tascii' and `-Tlatin1'); for other devices it is usually sufficient to install proper fonts which contain the necessary glyphs. Due to the importance of the Euro glyph in Europe, the groff package now comes with a POSTSCRIPT font called `freeeuro.pfa' which provides various glyph shapes for the Euro. With other words, latin-9 encoding is supported for the `-Tps' device out of the box (latin-2 isn't). By its very nature, `-Tutf8' supports all input encodings; `-Tdvi' has support for both latin-2 and latin-9 if the command line `-mec' is used also to load the file `ec.tmac' (which flips to the EC fonts).  File: groff, Node: Measurements, Next: Expressions, Prev: Text, 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), `? \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 and Macro 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 and Macro Arguments::  File: groff, Node: Request and Macro Arguments, Prev: Requests, Up: Requests Request and Macro Arguments ........................... Arguments to requests and macros are processed much like the shell: The line is split into arguments according to spaces.(1) (*note Request and Macro Arguments-Footnote-1::) An argument to a macro which is intended to contain spaces can either be enclosed in double quotes, or have the spaces "escaped" with backslashes. This is _not_ true for requests. Here are a few examples for a hypothetical macro `uh': .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 and Macro 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 and Macro Arguments-Footnotes, Up: Request and Macro 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 basically in the same manner. *Note Writing Macros::, and *Note Request and Macro 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 [end] Ignore all input until `gtroff' encounters the macro named `.'END on a line by itself (or `..' if END 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').