diff options
Diffstat (limited to 'contrib/groff/doc/groff-4')
| -rw-r--r-- | contrib/groff/doc/groff-4 | 1406 |
1 files changed, 0 insertions, 1406 deletions
diff --git a/contrib/groff/doc/groff-4 b/contrib/groff/doc/groff-4 deleted file mode 100644 index 7591d12..0000000 --- a/contrib/groff/doc/groff-4 +++ /dev/null @@ -1,1406 +0,0 @@ -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: 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'. - - Finally, MODE can be the numeric argument returned by the `.j' - register. - - 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 - .nr ad \n[.j] - text - .ad c - text - .na - text - .ad \" back to centering - text - .ad \n[ad] \" back to right justifying - - 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 size of a space between 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. - In fill mode, the values specify the minimum distance. - - 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. - - Another useful application of the `ss' request is to insert - discardable horizontal space, i.e., space which is discarded at a - line break. For example, paragraph-style footnotes could be - separated this way: - - - .ll 4.5i - 1.\ This is the first footnote.\c - .ss 48 - .nop - .ss 12 - 2.\ This is the second footnote. - - The result: - - - 1. This is the first footnote. 2. This - is the second footnote. - - Note that the `\h' escape produces unbreakable space. - - - 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::). - - -File: groff, Node: Manipulating Hyphenation, Next: Manipulating Spacing, Prev: Manipulating Filling and Adjusting, Up: gtroff Reference - -Manipulating Hyphenation -======================== - - As discussed in *Note Hyphenation::, `gtroff' hyphenates words. -There are a number of ways to influence hyphenation. - - - Request: .hy [mode] - - Register: \n[.hy] - Enable hyphenation. The request has an optional numeric argument, - MODE, to restrict hyphenation if necessary: - - `1' - The default argument if MODE is omitted. Hyphenate without - restrictions. This is also the start-up value of `gtroff'. - - `2' - Do not hyphenate the last word on a page or column. - - `4' - Do not hyphenate the last two characters of a word. - - `8' - Do not hyphenate the first two characters of a word. - - Values in the previous table are additive. For example, the - value 12 causes `gtroff' to neither hyphenate the last two nor the - first two characters of a word. - - The current hyphenation restrictions can be found in the read-only - number register `.hy'. - - The hyphenation mode is associated with the current environment - (*note Environments::). - - - Request: .nh - Disable hyphenation (i.e., set the hyphenation mode to zero). Note - that the hyphenation mode of the last call to `hy' is not - remembered. - - The hyphenation mode is associated with the current environment - (*note Environments::). - - - Request: .hlm [nnn] - - Register: \n[.hlm] - - Register: \n[.hlc] - Set the maximum number of consecutive hyphenated lines to NNN. If - this number is negative, there is no maximum. The default value - is -1 if NNN is omitted. This value is associated with the - current environment (*note Environments::). Only lines output - from a given environment count towards the maximum associated with - that environment. Hyphens resulting from `\%' are counted; - explicit hyphens are not. - - The current setting of `hlm' is available in the `.hlm' read-only - number register. Also the number of immediately preceding - consecutive hyphenated lines are available in the read-only number - register `.hlc'. - - - Request: .hw word1 word2 ... - Define how WORD1, WORD2, etc. are to be hyphenated. The words - must be given with hyphens at the hyphenation points. For example: - - - .hw in-sa-lub-rious - - Besides the space character, any character whose hyphenation code - value is zero can be used to separate the arguments of `hw' (see - the documentation for the `hcode' request below for more - information). In addition, this request can be used more than - once. - - Hyphenation exceptions specified with the `hw' request are - associated with the current hyphenation language; it causes an - error if there is no current hyphenation language. - - This request is ignored if there is no parameter. - - In old versions of `troff' there was a limited amount of space to - store such information; fortunately, with `gtroff', this is no - longer a restriction. - - - Escape: \% - - Escape: \: - To tell `gtroff' how to hyphenate words on the fly, use the `\%' - escape, also known as the "hyphenation character". Preceding a - word with this character prevents it from being hyphenated; - putting it inside a word indicates to `gtroff' that the word may - be hyphenated at that point. Note that this mechanism only - affects that one occurrence of the word; to change the hyphenation - of a word for the entire document, use the `hw' request. - - The `\:' escape inserts a zero-width break point (that is, the - word breaks but without adding a hyphen). - - - ... check the /var/log/\:httpd/\:access_log file ... - - Note that `\X' and `\Y' start a word, that is, the `\%' escape in - (say) `\X'...'\%foobar' and `\Y'...'\%foobar' no longer prevents - hyphenation but inserts a hyphenation point at the beginning of - `foobar'; most likely this isn't what you want to do. - - - Request: .hc [char] - Change the hyphenation character to CHAR. This character then - works the same as the `\%' escape, and thus, no longer appears in - the output. Without an argument, `hc' resets the hyphenation - character to be `\%' (the default) only. - - The hyphenation character is associated with the current - environment (*note Environments::). - - - Request: .hpf pattern_file - - Request: .hpfa pattern_file - - Request: .hpfcode a b [c d ...] - Read in a file of hyphenation patterns. This file is searched for - in the same way as `NAME.tmac' (or `tmac.NAME') is searched for if - the `-mNAME' option is specified. - - It should have the same format as (simple) TeX patterns files. - More specifically, the following scanning rules are implemented. - - * A percent sign starts a comment (up to the end of the line) - even if preceded by a backslash. - - * No support for `digraphs' like `\$'. - - * `^^XX' (X is 0-9 or a-f) and `^^X' (character code of X in - the range 0-127) are recognized; other use of `^' causes an - error. - - * No macro expansion. - - * `hpf' checks for the expression `\patterns{...}' (possibly - with whitespace before and after the braces). Everything - between the braces is taken as hyphenation patterns. - Consequently, `{' and `}' are not allowed in patterns. - - * Similarly, `\hyphenation{...}' gives a list of hyphenation - exceptions. - - * `\endinput' is recognized also. - - * For backwards compatibility, if `\patterns' is missing, the - whole file is treated as a list of hyphenation patterns (only - recognizing the `%' character as the start of a comment). - - If no `hpf' request is specified (either in the document or in a - macro package), `gtroff' won't hyphenate at all. - - The `hpfa' request appends a file of patterns to the current list. - - The `hpfcode' request defines mapping values for character codes in - hyphenation patterns. `hpf' or `hpfa' then apply the mapping - (after reading the patterns) before replacing or appending them to - the current list of patterns. Its arguments are pairs of - character codes - integers from 0 to 255. The request maps - character code A to code B, code C to code D, and so on. You can - use character codes which would be invalid otherwise. - - The set of hyphenation patterns is associated with the current - language set by the `hla' request. The `hpf' request is usually - invoked by the `troffrc' or `troffrc-end' file; by default, - `troffrc' loads hyphenation patterns and exceptions for American - English (in files `hyphen.us' and `hyphenex.us'). - - A second call to `hpf' (for the same language) will replace the - hyphenation patterns with the new ones. - - Invoking `hpf' causes an error if there is no current hyphenation - language. - - - Request: .hcode c1 code1 c2 code2 ... - Set the hyphenation code of character C1 to CODE1, that of C2 to - CODE2, etc. A hyphenation code must be a single input character - (not a special character) other than a digit or a space. - Initially each lower-case letter (`a'-`z') has its hyphenation - code set to itself, and each upper-case letter (`A'-`Z') has a - hyphenation code which is the lower-case version of itself. - - This request is ignored if it has no parameter. - - - Request: .hym [length] - - Register: \n[.hym] - Set the (right) hyphenation margin to LENGTH. If the current - adjustment mode is not `b' or `n', the line is not hyphenated if - it is shorter than LENGTH. Without an argument, the hyphenation - margin is reset to its default value, which is 0. The default - scaling indicator for this request is `m'. The hyphenation margin - is associated with the current environment (*note Environments::). - - A negative argument resets the hyphenation margin to zero, emitting - a warning of type `range'. - - The current hyphenation margin is available in the `.hym' read-only - number register. - - - Request: .hys [hyphenation_space] - - Register: \n[.hys] - Set the hyphenation space to HYPHENATION_SPACE. If the current - adjustment mode is `b' or `n', don't hyphenate the line if it can - be justified by adding no more than HYPHENATION_SPACE extra space - to each word space. Without argument, the hyphenation space is - set to its default value, which is 0. The default scaling - indicator for this request is `m'. The hyphenation space is - associated with the current environment (*note Environments::). - - A negative argument resets the hyphenation space to zero, emitting - a warning of type `range'. - - The current hyphenation space is available in the `.hys' read-only - number register. - - - Request: .shc [glyph] - Set the "soft hyphen character" to GLYPH.(1) (*note Manipulating - Hyphenation-Footnote-1::) If the argument is omitted, the soft - hyphen character is set to the default glyph `\(hy' (this is the - start-up value of `gtroff' also). The soft hyphen character is - the glyph that is inserted when a word is hyphenated at a line - break. If the soft hyphen character does not exist in the font of - the character immediately preceding a potential break point, then - the line is not broken at that point. Neither definitions - (specified with the `char' request) nor translations (specified - with the `tr' request) are considered when finding the soft hyphen - character. - - - Request: .hla language - - Register: \n[.hla] - Set the current hyphenation language to the string LANGUAGE. - Hyphenation exceptions specified with the `hw' request and - hyphenation patterns specified with the `hpf' and `hpfa' requests - are both associated with the current hyphenation language. The - `hla' request is usually invoked by the `troffrc' or the - `troffrc-end' files; `troffrc' sets the default language to `us'. - - The current hyphenation language is available as a string in the - read-only number register `.hla'. - - - .ds curr_language \n[.hla] - \*[curr_language] - => us - - - -File: groff, Node: Manipulating Hyphenation-Footnotes, Up: Manipulating Hyphenation - - (1) "Soft hyphen character" is a misnomer since it is an output -glyph. - - -File: groff, Node: Manipulating Spacing, Next: Tabs and Fields, Prev: Manipulating Hyphenation, Up: gtroff Reference - -Manipulating Spacing -==================== - - - Request: .sp [distance] - Space downwards DISTANCE. With no argument it advances 1 line. A - negative argument causes `gtroff' to move up the page the - specified distance. If the argument is preceded by a `|' then - `gtroff' moves that distance from the top of the page. This - request causes a line break. The default scaling indicator is `v'. - - If a vertical trap is sprung during execution of `sp', the amount - of vertical space after the trap is discarded. For example, this - - - .de xxx - .. - . - .wh 0 xxx - . - .pl 5v - foo - .sp 2 - bar - .sp 50 - baz - - results in - - - foo - - - bar - - baz - - The amount of discarded space is available in the number register - `.trunc'. - - To protect `sp' against vertical traps, use the `vpt' request: - - - .vpt 0 - .sp -3 - .vpt 1 - - - - Request: .ls [nnn] - - Register: \n[.L] - Output NNN-1 blank lines after each line of text. With no - argument, `gtroff' uses the previous value before the last `ls' - call. - - - .ls 2 \" This causes double-spaced output - .ls 3 \" This causes triple-spaced output - .ls \" Again double-spaced - - The line spacing is associated with the current environment (*note - Environments::). - - The read-only number register `.L' contains the current line - spacing setting. - - *Note Changing Type Sizes::, for the requests `vs' and `pvs' as -alternatives to `ls'. - - - Escape: \x'spacing' - - Register: \n[.a] - Sometimes, extra vertical spacing is only needed occasionally, e.g. - to allow space for a tall construct (like an equation). The `\x' - escape does this. The escape is given a numerical argument, - usually enclosed in quotes (like `\x'3p''); the default scaling - indicator is `v'. If this number is positive extra vertical space - is inserted below the current line. A negative number adds space - above. If this escape is used multiple times on the same line, - the maximum of the values is used. - - *Note Escapes::, for details on parameter delimiting characters. - - The `.a' read-only number register contains the most recent - (nonnegative) extra vertical line space. - - Using `\x' can be necessary in combination with the `\b' escape, - as the following example shows. - - - This is a test with the \[rs]b escape. - .br - This is a test with the \[rs]b escape. - .br - This is a test with \b'xyz'\x'-1m'\x'1m'. - .br - This is a test with the \[rs]b escape. - .br - This is a test with the \[rs]b escape. - - produces - - - This is a test with the \b escape. - This is a test with the \b escape. - x - This is a test with y. - z - This is a test with the \b escape. - This is a test with the \b escape. - - - - Request: .ns - - Request: .rs - - Register: \n[.ns] - Enable "no-space mode". In this mode, spacing (either via `sp' or - via blank lines) is disabled. The `bp' request to advance to the - next page is also disabled, except if it is accompanied by a page - number (see *Note Page Control::, for more information). This - mode ends when actual text is output or the `rs' request is - encountered which ends no-space mode. The read-only number - register `.ns' is set to 1 as long as no-space mode is active. - - This request is useful for macros that conditionally insert - vertical space before the text starts (for example, a paragraph - macro could insert some space except when it is the first - paragraph after a section header). - - -File: groff, Node: Tabs and Fields, Next: Character Translations, Prev: Manipulating Spacing, Up: gtroff Reference - -Tabs and Fields -=============== - - A tab character (ASCII char 9, EBCDIC char 5) causes a horizontal -movement to the next tab stop (much like it did on a typewriter). - - - Escape: \t - This escape is a non-interpreted tab character. In copy mode - (*note Copy-in Mode::), `\t' is the same as a real tab character. - - - Request: .ta [n1 n2 ... nn T r1 r2 ... rn] - - Register: \n[.tabs] - Change tab stop positions. This request takes a series of tab - specifiers as arguments (optionally divided into two groups with - the letter `T') which indicate where each tab stop is to be - (overriding any previous settings). - - Tab stops can be specified absolutely, i.e., as the distance from - the left margin. For example, the following sets 6 tab stops every - one inch. - - - .ta 1i 2i 3i 4i 5i 6i - - Tab stops can also be specified using a leading `+' which means - that the specified tab stop is set relative to the previous tab - stop. For example, the following is equivalent to the previous - example. - - - .ta 1i +1i +1i +1i +1i +1i - - `gtroff' supports an extended syntax to specify repeat values after - the `T' mark (these values are always taken as relative) - this is - the usual way to specify tabs set at equal intervals. The - following is, yet again, the same as the previous examples. It - does even more since it defines an infinite number of tab stops - separated by one inch. - - - .ta T 1i - - Now we are ready to interpret the full syntax given at the - beginning: Set tabs at positions N1, N2, ..., NN and then set tabs - at NN+R1, NN+R2, ..., NN+RN and then at NN+RN+R1, NN+RN+R2, ..., - NN+RN+RN, and so on. - - Example: `4c +6c T 3c 5c 2c' is equivalent to `4c 10c 13c 18c 20c - 23c 28c 30c ...'. - - The material in each tab column (i.e., the column between two tab - stops) may be justified to the right or left or centered in the - column. This is specified by appending `R', `L', or `C' to the tab - specifier. The default justification is `L'. Example: - - - .ta 1i 2iC 3iR - - Some notes: - - * The default unit of the `ta' request is `m'. - - * A tab stop is converted into a non-breakable horizontal - movement which can be neither stretched nor squeezed. For - example, - - - .ds foo a\tb\tc - .ta T 5i - \*[foo] - - creates a single line which is a bit longer than 10 inches (a - string is used to show exactly where the tab characters are). - Now consider the following: - - - .ds bar a\tb b\tc - .ta T 5i - \*[bar] - - `gtroff' first converts the tab stops of the line into - unbreakable horizontal movements, then splits the line after - the second `b' (assuming a sufficiently short line length). - Usually, this isn't what the user wants. - - * Superfluous tabs (i.e., tab characters which do not - correspond to a tab stop) are ignored except the first one - which delimits the characters belonging to the last tab stop - for right-justifying or centering. Consider the following - example - - - .ds Z foo\tbar\tfoo - .ds ZZ foo\tbar\tfoobar - .ds ZZZ foo\tbar\tfoo\tbar - .ta 2i 4iR - \*[Z] - .br - \*[ZZ] - .br - \*[ZZZ] - .br - - which produces the following output: - - - foo bar foo - foo bar foobar - foo bar foobar - - The first line right-justifies the second `foo' relative to - the tab stop. The second line right-justifies `foobar'. The - third line finally right-justifies only `foo' because of the - additional tab character which marks the end of the string - belonging to the last defined tab stop. - - * Tab stops are associated with the current environment (*note - Environments::). - - * Calling `ta' without an argument removes all tab stops. - - * The start-up value of `gtroff' is `T 0.8i'. - - The read-only number register `.tabs' contains a string - representation of the current tab settings suitable for use as an - argument to the `ta' request. - - - .ds tab-string \n[.tabs] - \*[tab-string] - => T120u - - The `troff' version of the Plan 9 operating system uses register - `.S' for the same purpose. - - - Request: .tc [fill-glyph] - Normally `gtroff' fills the space to the next tab stop with - whitespace. This can be changed with the `tc' request. With no - argument `gtroff' reverts to using whitespace, which is the - default. The value of this "tab repetition character" is - associated with the current environment (*note Environments::).(1) - (*note Tabs and Fields-Footnote-1::) - - - Request: .linetabs n - - Register: \n[.linetabs] - If N is missing or not zero, enable "line-tabs" mode, or disable - it otherwise (the default). In line-tabs mode, `gtroff' computes - tab distances relative to the (current) output line instead of the - input line. - - For example, the following code: - - - .ds x a\t\c - .ds y b\t\c - .ds z c - .ta 1i 3i - \*x - \*y - \*z - - in normal mode, results in the output - - - a b c - - in line-tabs mode, the same code outputs - - - a b c - - Line-tabs mode is associated with the current environment. The - read-only register `.linetabs' is set to 1 if in line-tabs mode, - and 0 in normal mode. - -* Menu: - -* Leaders:: -* Fields:: - - -File: groff, Node: Tabs and Fields-Footnotes, Up: Tabs and Fields - - (1) "Tab repetition character" is a misnomer since it is an output -glyph. - - -File: groff, Node: Leaders, Next: Fields, Prev: Tabs and Fields, Up: Tabs and Fields - -Leaders -------- - - Sometimes it may may be desirable to use the `tc' request to fill a -particular tab stop with a given glyph (for example dots in a table of -contents), but also normal tab stops on the rest of the line. For this -`gtroff' provides an alternate tab mechanism, called "leaders" which -does just that. - - A leader character (character code 1) behaves similarly to a tab -character: It moves to the next tab stop. The only difference is that -for this movement, the fill glyph defaults to a period character and -not to space. - - - Escape: \a - This escape is a non-interpreted leader character. In copy mode - (*note Copy-in Mode::), `\a' is the same as a real leader - character. - - - Request: .lc [fill-glyph] - Declare the "leader repetition character".(1) (*note - Leaders-Footnote-1::) Without an argument, leaders act the same as - tabs (i.e., using whitespace for filling). `gtroff''s start-up - value is a dot (`.'). The value of the leader repetition - character is associated with the current environment (*note - Environments::). - - For a table of contents, to name an example, tab stops may be -defined so that the section number is one tab stop, the title is the -second with the remaining space being filled with a line of dots, and -then the page number slightly separated from the dots. - - - .ds entry 1.1\tFoo\a\t12 - .lc . - .ta 1i 5i +.25i - \*[entry] - -This produces - - - 1.1 Foo.......................................... 12 - - -File: groff, Node: Leaders-Footnotes, Up: Leaders - - (1) "Leader repetition character" is a misnomer since it is an -output glyph. - - -File: groff, Node: Fields, Prev: Leaders, Up: Tabs and Fields - -Fields ------- - - "Fields" are a more general way of laying out tabular data. A field -is defined as the data between a pair of "delimiting characters". It -contains substrings which are separated by "padding characters". The -width of a field is the distance on the _input_ line from the position -where the field starts to the next tab stop. A padding character -inserts stretchable space similar to TeX's `\hss' command (thus it can -even be negative) to make the sum of all substring lengths plus the -stretchable space equal to the field width. If more than one padding -character is inserted, the available space is evenly distributed among -them. - - - Request: .fc [delim-char [padding-char]] - Define a delimiting and a padding character for fields. If the - latter is missing, the padding character defaults to a space - character. If there is no argument at all, the field mechanism is - disabled (which is the default). Note that contrary to e.g. the - tab repetition character, delimiting and padding characters are - _not_ associated to the current environment (*note Environments::). - - Example: - - - .fc # ^ - .ta T 3i - #foo^bar^smurf# - .br - #foo^^bar^smurf# - - and here the result: - - - foo bar smurf - foo bar smurf - - - -File: groff, Node: Character Translations, Next: Troff and Nroff Mode, Prev: Tabs and Fields, Up: gtroff Reference - -Character Translations -====================== - - The control character (`.') and the no-break control character (`'') -can be changed with the `cc' and `c2' requests, respectively. - - - Request: .cc [c] - Set the control character to C. With no argument the default - control character `.' is restored. The value of the control - character is associated with the current environment (*note - Environments::). - - - Request: .c2 [c] - Set the no-break control character to C. With no argument the - default control character `'' is restored. The value of the - no-break control character is associated with the current - environment (*note Environments::). - - - Request: .eo - Disable the escape mechanism completely. After executing this - request, the backslash character `\' no longer starts an escape - sequence. - - This request can be very helpful in writing macros since it is not - necessary then to double the escape character. Here an example: - - - .\" This is a simplified version of the - .\" .BR request from the man macro package - .eo - .de BR - . ds result \& - . while (\n[.$] >= 2) \{\ - . as result \fB\$1\fR\$2 - . shift 2 - . \} - . if \n[.$] .as result \fB\$1 - \*[result] - . ft R - .. - .ec - - - - Request: .ec [c] - Set the escape character to C. With no argument the default - escape character `\' is restored. It can be also used to - re-enable the escape mechanism after an `eo' request. - - Note that changing the escape character globally will likely break - macro packages since `gtroff' has no mechanism to `intern' macros, - i.e., to convert a macro definition into an internal form which is - independent of its representation (TeX has this mechanism). If a - macro is called, it is executed literally. - - - Request: .ecs - - Request: .ecr - The `ecs' request saves the current escape character in an - internal register. Use this request in combination with the `ec' - request to temporarily change the escape character. - - The `ecr' request restores the escape character saved with `ecs'. - Without a previous call to `ecs', this request sets the escape - character to `\'. - - - Escape: \\ - - Escape: \e - - Escape: \E - Print the current escape character (which is the backslash - character `\' by default). - - `\\' is a `delayed' backslash; more precisely, it is the default - escape character followed by a backslash, which no longer has - special meaning due to the leading escape character. It is _not_ - an escape sequence in the usual sense! In any unknown escape - sequence `\X' the escape character is ignored and X is printed. - But if X is equal to the current escape character, no warning is - emitted. - - As a consequence, only at top-level or in a diversion a backslash - glyph is printed; in copy-in mode, it expands to a single - backslash which then combines with the following character to an - escape sequence. - - The `\E' escape differs from `\e' by printing an escape character - that is not interpreted in copy mode. Use this to define strings - with escapes that work when used in copy mode (for example, as a - macro argument). The following example defines strings to begin - and end a superscript: - - - .ds { \v'-.3m'\s'\En[.s]*60/100' - .ds } \s0\v'.3m' - - Another example to demonstrate the differences between the various - escape sequences, using a strange escape character, `-'. - - - .ec - - .de xxx - --A'123' - .. - .xxx - => -A'foo' - - The result is surprising for most users, expecting `1' since `foo' - is a valid identifier. What has happened? As mentioned above, - the leading escape character makes the following character - ordinary. Written with the default escape character the sequence - `--' becomes `\-' - this is the minus sign. - - If the escape character followed by itself is a valid escape - sequence, only `\E' yields the expected result: - - - .ec - - .de xxx - -EA'123' - .. - .xxx - => 1 - - - - Escape: \. - Similar to `\\', the sequence `\.' isn't a real escape sequence. - As before, a warning message is suppressed if the escape character - is followed by a dot, and the dot itself is printed. - - - .de foo - . nop foo - . - . de bar - . nop bar - \\.. - . - .. - .foo - .bar - => foo bar - - The first backslash is consumed while the macro is read, and the - second is swallowed while exexuting macro `foo'. - - A "translation" is a mapping of an input character to an output -glyph. The mapping occurs at output time, i.e., the input character -gets assigned the metric information of the mapped output character -right before input tokens are converted to nodes (*note Gtroff -Internals::, for more on this process). - - - Request: .tr abcd... - - Request: .trin abcd... - Translate character A to glyph B, character C to glyph D, etc. If - there is an odd number of arguments, the last one is translated to - an unstretchable space (`\ '). - - The `trin' request is identical to `tr', but when you unformat a - diversion with `asciify' it ignores the translation. *Note - Diversions::, for details about the `asciify' request. - - Some notes: - - * Special characters (`\(XX', `\[XXX]', `\C'XXX'', `\'', `\`', - `\-', `\_'), glyphs defined with the `char' request, and - numbered glyphs (`\N'XXX'') can be translated also. - - * The `\e' escape can be translated also. - - * Characters can be mapped onto the `\%' and `\~' escapes (but - `\%' and `\~' can't be mapped onto another glyph). - - * The following characters can't be translated: space (with one - exception, see below), backspace, newline, leader (and `\a'), - tab (and `\t'). - - * Translations are not considered for finding the soft hyphen - character set with the `shc' request. - - * The pair `C\&' (this is an arbitrary character C followed by - the zero width space character) maps this character to - nothing. - - - .tr a\& - foo bar - => foo br - - It is even possible to map the space character to nothing: - - - .tr aa \& - foo bar - => foobar - - As shown in the example, the space character can't be the - first character/glyph pair as an argument of `tr'. - Additionally, it is not possible to map the space character - to any other glyph; requests like `.tr aa x' undo `.tr aa \&' - instead. - - If justification is active, lines are justified in spite of - the `empty' space character (but there is no minimal - distance, i.e. the space character, between words). - - * After an output glyph has been constructed (this happens at - the moment immediately before the glyph is appended to an - output glyph list, either by direct output, in a macro, - diversion, or string), it is no longer affected by `tr'. - - * Translating character to glyphs where one of them or both are - undefined is possible also; `tr' does not check whether the - entities in its argument do exist. - - *Note Gtroff Internals::. - - * `troff' no longer has a hard-coded dependency on Latin-1; all - `charXXX' entities have been removed from the font - description files. This has a notable consequence which - shows up in warnings like `can't find character with input - code XXX' if the `tr' request isn't handled properly. - - Consider the following translation: - - - .tr e'E' - - This maps input character `e'' onto glyph `E'', which is - identical to glyph `char201'. But this glyph intentionally - doesn't exist! Instead, `\[char201]' is treated as an input - character entity and is by default mapped onto `\['E]', and - `gtroff' doesn't handle translations of translations. - - The right way to write the above translation is - - - .tr e'\['E] - - With other words, the first argument of `tr' should be an - input character or entity, and the second one a glyph entity. - - * Without an argument, the `tr' request is ignored. - - - Request: .trnt abcd... - `trnt' is the same as the `tr' request except that the - translations do not apply to text that is transparently throughput - into a diversion with `\!'. *Note Diversions::, for more - information. - - For example, - - - .tr ab - .di x - \!.tm a - .di - .x - - prints `b' to the standard error stream; if `trnt' is used instead - of `tr' it prints `a'. - - -File: groff, Node: Troff and Nroff Mode, Next: Line Layout, Prev: Character Translations, Up: gtroff Reference - -Troff and Nroff Mode -==================== - - Originally, `nroff' and `troff' were two separate programs, the -former for TTY output, the latter for everything else. With GNU -`troff', both programs are merged into one executable, sending its -output to a device driver (`grotty' for TTY devices, `grops' for -POSTSCRIPT, etc.) which interprets the intermediate output of `gtroff'. -For UNIX `troff' it makes sense to talk about "Nroff mode" and "Troff -mode" since the differences are hardcoded. For GNU `troff', this -distinction is not appropriate because `gtroff' simply takes the -information given in the font files for a particular device without -handling requests specially if a TTY output device is used. - - Usually, a macro package can be used with all output devices. -Nevertheless, it is sometimes necessary to make a distinction between -TTY and non-TTY devices: `gtroff' provides two built-in conditions `n' -and `t' for the `if', `ie', and `while' requests to decide whether -`gtroff' shall behave like `nroff' or like `troff'. - - - Request: .troff - Make the `t' built-in condition true (and the `n' built-in - condition false) for `if', `ie', and `while' conditional requests. - This is the default if `gtroff' (_not_ `groff') is started with - the `-R' switch to avoid loading of the start-up files `troffrc' - and `troffrc-end'. Without `-R', `gtroff' stays in troff mode if - the output device is not a TTY (e.g. `ps'). - - - Request: .nroff - Make the `n' built-in condition true (and the `t' built-in - condition false) for `if', `ie', and `while' conditional requests. - This is the default if `gtroff' uses a TTY output device; the - code for switching to nroff mode is in the file `tty.tmac' which - is loaded by the start-up file `troffrc'. - - *Note Conditionals and Loops::, for more details on built-in -conditions. - - -File: groff, Node: Line Layout, Next: Line Control, Prev: Troff and Nroff Mode, Up: gtroff Reference - -Line Layout -=========== - - The following drawing shows the dimensions which `gtroff' uses for -placing a line of output onto the page. They are labeled with the -request which manipulates each dimension. - - - -->| in |<-- - |<-----------ll------------>| - +----+----+----------------------+----+ - | : : : | - +----+----+----------------------+----+ - -->| po |<-- - |<--------paper width---------------->| - -These dimensions are: - -`po' - "Page offset" - this is the leftmost position of text on the final - output, defining the "left margin". - -`in' - "Indentation" - this is the distance from the left margin where - text is printed. - -`ll' - "Line length" - this is the distance from the left margin to right - margin. - - A simple demonstration: - - - .ll 3i - This is text without indentation. - The line length has been set to 3\~inch. - .in +.5i - .ll -.5i - Now the left and right margins are both increased. - .in - .ll - Calling .in and .ll without parameters restore - the previous values. - - Result: - - - This is text without indenta- - tion. The line length has - been set to 3 inch. - Now the left and - right margins are - both increased. - Calling .in and .ll without - parameters restore the previ- - ous values. - - - Request: .po [offset] - - Request: .po +offset - - Request: .po -offset - - Register: \n[.o] - Set horizontal page offset to OFFSET (or increment or decrement - the current value by OFFSET). Note that this request does not - cause a break, so changing the page offset in the middle of text - being filled may not yield the expected result. The initial value - is 1i. For TTY output devices, it is set to 0 in the startup file - `troffrc'; the default scaling indicator is `m' (and not `v' as - incorrectly documented in the original UNIX troff manual). - - The current page offset can be found in the read-only number - register `.o'. - - If `po' is called without an argument, the page offset is reset to - the previous value before the last call to `po'. - - - .po 3i - \n[.o] - => 720 - .po -1i - \n[.o] - => 480 - .po - \n[.o] - => 720 - - - - Request: .in [indent] - - Request: .in +indent - - Request: .in -indent - - Register: \n[.i] - Set indentation to INDENT (or increment or decrement the current - value by INDENT). This request causes a break. Initially, there - is no indentation. - - If `in' is called without an argument, the indentation is reset to - the previous value before the last call to `in'. The default - scaling indicator is `m'. - - The indentation is associated with the current environment (*note - Environments::). - - If a negative indentation value is specified (which is not - allowed), `gtroff' emits a warning of type `range' and sets the - indentation to zero. - - The effect of `in' is delayed until a partially collected line (if - it exists) is output. A temporary indent value is reset to zero - also. - - The current indentation (as set by `in') can be found in the - read-only number register `.i'. - - - Request: .ti offset - - Request: .ti +offset - - Request: .ti -offset - - Register: \n[.in] - Temporarily indent the next output line by OFFSET. If an - increment or decrement value is specified, adjust the temporary - indentation relative to the value set by the `in' request. - - This request causes a break; its value is associated with the - current environment (*note Environments::). The default scaling - indicator is `m'. A call of `ti' without an argument is ignored. - - If the total indentation value is negative (which is not allowed), - `gtroff' emits a warning of type `range' and sets the temporary - indentation to zero. `Total indentation' is either OFFSET if - specified as an absolute value, or the temporary plus normal - indentation, if OFFSET is given as a relative value. - - The effect of `ti' is delayed until a partially collected line (if - it exists) is output. - - The read-only number register `.in' is the indentation that applies - to the current output line. - - The difference between `.i' and `.in' is that the latter takes - into account whether a partially collected line still uses the old - indentation value or a temporary indentation value is active. - - - Request: .ll [length] - - Request: .ll +length - - Request: .ll -length - - Register: \n[.l] - - Register: \n[.ll] - Set the line length to LENGTH (or increment or decrement the - current value by LENGTH). Initially, the line length is set to - 6.5i. The effect of `ll' is delayed until a partially collected - line (if it exists) is output. The default scaling indicator is - `m'. - - If `ll' is called without an argument, the line length is reset to - the previous value before the last call to `ll'. If a negative - line length is specified (which is not allowed), `gtroff' emits a - warning of type `range' and sets the line length to zero. - - The line length is associated with the current environment (*note - Environments::). - - The current line length (as set by `ll') can be found in the - read-only number register `.l'. The read-only number register - `.ll' is the line length that applies to the current output line. - - Similar to `.i' and `.in', the difference between `.l' and `.ll' - is that the latter takes into account whether a partially - collected line still uses the old line length value. - |
