/contrib/groff/doc/groff-2
https://bitbucket.org/freebsd/freebsd-head/ · #! · 4910 lines · 3933 code · 977 blank · 0 comment · 0 complexity · 49d6f50ba96bba8de8a1912d8cbd463c MD5 · raw file
Large files are truncated click here to view the full file
- This is groff, produced by makeinfo version 4.8 from ./groff.texinfo.
- This manual documents GNU `troff' version 1.19.2.
- Copyright (C) 1994-2000, 2001, 2002, 2003, 2004, 2005 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: Drawing Requests, Next: Traps, Prev: Page Motions, Up: gtroff Reference
- 5.23 Drawing Requests
- =====================
- `gtroff' provides a number of ways to draw lines and other figures on
- the page. Used in combination with the page motion commands (see *Note
- Page Motions::, for more info), a wide variety of figures can be drawn.
- However, for complex drawings these operations can be quite
- cumbersome, and it may be wise to use graphic preprocessors like `gpic'
- or `ggrn'. *Note gpic::, and *Note ggrn::, for more information.
- All drawing is done via escapes.
- -- Escape: \l'l'
- -- Escape: \l'lg'
- Draw a line horizontally. L is the length of the line to be
- drawn. If it is positive, start the line at the current location
- and draw to the right; its end point is the new current location.
- Negative values are handled differently: The line starts at the
- current location and draws to the left, but the current location
- doesn't move.
- L can also be specified absolutely (i.e. with a leading `|') which
- draws back to the beginning of the input line. Default scaling
- indicator is `m'.
- The optional second parameter G is a glyph to draw the line with.
- If this second argument is not specified, `gtroff' uses the
- underscore glyph, `\[ru]'.
- To separate the two arguments (to prevent `gtroff' from
- interpreting a drawing glyph as a scaling indicator if the glyph is
- represented by a single character) use `\&'.
- Here a small useful example:
- .de box
- \[br]\\$*\[br]\l'|0\[rn]'\l'|0\[ul]'
- ..
- Note that this works by outputting a box rule (a vertical line),
- then the text given as an argument and then another box rule.
- Finally, the line drawing escapes both draw from the current
- location to the beginning of the _input_ line - this works because
- the line length is negative, not moving the current point.
- -- Escape: \L'l'
- -- Escape: \L'lg'
- Draw vertical lines. Its parameters are similar to the `\l'
- escape, except that the default scaling indicator is `v'. The
- movement is downwards for positive values, and upwards for
- negative values. The default glyph is the box rule glyph,
- `\[br]'. As with the vertical motion escapes, text processing
- blindly continues where the line ends.
- This is a \L'3v'test.
- Here the result, produced with `grotty'.
- This is a
- |
- |
- |test.
- -- Escape: \D'command arg ...'
- The `\D' escape provides a variety of drawing functions. Note
- that on character devices, only vertical and horizontal lines are
- supported within `grotty'; other devices may only support a subset
- of the available drawing functions.
- The default scaling indicator for all subcommands of `\D' is `m'
- for horizontal distances and `v' for vertical ones. Exceptions
- are `\D'f ...'' and `\D't ...'' which use `u' as the default, and
- `\D'FX ...'' which arguments are treated similar to the `defcolor'
- request.
- `\D'l DX DY''
- Draw a line from the current location to the relative point
- specified by (DX,DY), where positive values mean down and
- right, respectively. The end point of the line is the new
- current location.
- The following example is a macro for creating a box around a
- text string; for simplicity, the box margin is taken as a
- fixed value, 0.2m.
- .de BOX
- . nr @wd \w'\\$1'
- \h'.2m'\
- \h'-.2m'\v'(.2m - \\n[rsb]u)'\
- \D'l 0 -(\\n[rst]u - \\n[rsb]u + .4m)'\
- \D'l (\\n[@wd]u + .4m) 0'\
- \D'l 0 (\\n[rst]u - \\n[rsb]u + .4m)'\
- \D'l -(\\n[@wd]u + .4m) 0'\
- \h'.2m'\v'-(.2m - \\n[rsb]u)'\
- \\$1\
- \h'.2m'
- ..
- First, the width of the string is stored in register `@wd'.
- Then, four lines are drawn to form a box, properly offset by
- the box margin. The registers `rst' and `rsb' are set by the
- `\w' escape, containing the largest height and depth of the
- whole string.
- `\D'c D''
- Draw a circle with a diameter of D with the leftmost point at
- the current position. After drawing, the current location is
- positioned at the rightmost point of the circle.
- `\D'C D''
- Draw a solid circle with the same parameters and behaviour as
- an outlined circle. No outline is drawn.
- `\D'e X Y''
- Draw an ellipse with a horizontal diameter of X and a vertical
- diameter of Y with the leftmost point at the current position.
- After drawing, the current location is positioned at the
- rightmost point of the ellipse.
- `\D'E X Y''
- Draw a solid ellipse with the same parameters and behaviour
- as an outlined ellipse. No outline is drawn.
- `\D'a DX1 DY1 DX2 DY2''
- Draw an arc clockwise from the current location through the
- two specified relative locations (DX1,DY1) and (DX2,DY2).
- The coordinates of the first point are relative to the
- current position, and the coordinates of the second point are
- relative to the first point. After drawing, the current
- position is moved to the final point of the arc.
- `\D'~ DX1 DY1 DX2 DY2 ...''
- Draw a spline from the current location to the relative point
- (DX1,DY1) and then to (DX2,DY2), and so on. The current
- position is moved to the terminal point of the drawn curve.
- `\D'f N''
- Set the shade of gray to be used for filling solid objects
- to N; N must be an integer between 0 and 1000, where 0
- corresponds solid white and 1000 to solid black, and values
- in between correspond to intermediate shades of gray. This
- applies only to solid circles, solid ellipses, and solid
- polygons. By default, a level of 1000 is used.
- Despite of being silly, the current point is moved
- horizontally to the right by N.
- Don't use this command! It has the serious drawback that it
- will be always rounded to the next integer multiple of the
- horizontal resolution (the value of the `hor' keyword in the
- `DESC' file). Use `\M' (*note Colors::) or `\D'Fg ...''
- instead.
- `\D'p DX1 DY1 DX2 DY2 ...''
- Draw a polygon from the current location to the relative
- position (DX1,DY1) and then to (DX2,DY2) and so on. When the
- specified data points are exhausted, a line is drawn back to
- the starting point. The current position is changed by
- adding the sum of all arguments with odd index to the actual
- horizontal position and the even ones to the vertical
- position.
- `\D'P DX1 DY1 DX2 DY2 ...''
- Draw a solid polygon with the same parameters and behaviour
- as an outlined polygon. No outline is drawn.
- Here a better variant of the box macro to fill the box with
- some color. Note that the box must be drawn before the text
- since colors in `gtroff' are not transparent; the filled
- polygon would hide the text completely.
- .de BOX
- . nr @wd \w'\\$1'
- \h'.2m'\
- \h'-.2m'\v'(.2m - \\n[rsb]u)'\
- \M[lightcyan]\
- \D'P 0 -(\\n[rst]u - \\n[rsb]u + .4m) \
- (\\n[@wd]u + .4m) 0 \
- 0 (\\n[rst]u - \\n[rsb]u + .4m) \
- -(\\n[@wd]u + .4m) 0'\
- \h'.2m'\v'-(.2m - \\n[rsb]u)'\
- \M[]\
- \\$1\
- \h'.2m'
- ..
- `\D't N''
- Set the current line thickness to N machine units. A value of
- zero selects the smallest available line thickness. A
- negative value makes the line thickness proportional to the
- current point size (this is the default behaviour of AT&T
- `troff').
- Despite of being silly, the current point is moved
- horizontally to the right by N.
- `\D'FSCHEME COLOR_COMPONENTS''
- Change current fill color. SCHEME is a single letter
- denoting the color scheme: `r' (rgb), `c' (cmy), `k' (cmyk),
- `g' (gray), or `d' (default color). The color components use
- exactly the same syntax as in the `defcolor' request (*note
- Colors::); the command `\D'Fd'' doesn't take an argument.
- _No_ position changing!
- Examples:
- \D'Fg .3' \" same gray as \D'f 700' \D'Fr #0000ff' \"
- blue
- *Note Graphics Commands::.
- -- Escape: \b'string'
- "Pile" a sequence of glyphs vertically, and center it vertically
- on the current line. Use it to build large brackets and braces.
- Here an example how to create a large opening brace:
- \b'\[lt]\[bv]\[lk]\[bv]\[lb]'
- The first glyph is on the top, the last glyph in STRING is at the
- bottom. Note that `gtroff' separates the glyphs vertically by 1m,
- and the whole object is centered 0.5m above the current baseline;
- the largest glyph width is used as the width for the whole object.
- This rather unflexible positioning algorithm doesn't work with
- `-Tdvi' since the bracket pieces vary in height for this device.
- Instead, use the `eqn' preprocessor.
- *Note Manipulating Spacing::, how to adjust the vertical spacing
- with the `\x' escape.
- File: groff, Node: Traps, Next: Diversions, Prev: Drawing Requests, Up: gtroff Reference
- 5.24 Traps
- ==========
- "Traps" are locations, which, when reached, call a specified macro.
- These traps can occur at a given location on the page, at a given
- location in the current diversion, at a blank line, after a certain
- number of input lines, or at the end of input.
- Setting a trap is also called "planting". It is also said that a
- trap is "sprung" if the associated macro is executed.
- * Menu:
- * Page Location Traps::
- * Diversion Traps::
- * Input Line Traps::
- * Blank Line Traps::
- * End-of-input Traps::
- File: groff, Node: Page Location Traps, Next: Diversion Traps, Prev: Traps, Up: Traps
- 5.24.1 Page Location Traps
- --------------------------
- "Page location traps" perform an action when `gtroff' reaches or passes
- a certain vertical location on the page. Page location traps have a
- variety of purposes, including:
- * setting headers and footers
- * setting body text in multiple columns
- * setting footnotes
- -- Request: .vpt flag
- -- Register: \n[.vpt]
- Enable vertical position traps if FLAG is non-zero, or disables
- them otherwise. Vertical position traps are traps set by the `wh'
- or `dt' requests. Traps set by the `it' request are not vertical
- position traps. The parameter that controls whether vertical
- position traps are enabled is global. Initially vertical position
- traps are enabled. The current setting of this is available in the
- `.vpt' read-only number register.
- Note that a page can't be ejected if `vpt' is set to zero.
- -- Request: .wh dist [macro]
- Set a page location trap. Non-negative values for DIST set the
- trap relative to the top of the page; negative values set the trap
- relative to the bottom of the page. Default scaling indicator is
- `v'.
- MACRO is the name of the macro to execute when the trap is sprung.
- If MACRO is missing, remove the first trap (if any) at DIST.
- The following is a simple example of how many macro packages set
- headers and footers.
- .de hd \" Page header
- ' sp .5i
- . tl 'Title''date'
- ' sp .3i
- ..
- .
- .de fo \" Page footer
- ' sp 1v
- . tl ''%''
- ' bp
- ..
- .
- .wh 0 hd \" trap at top of the page
- .wh -1i fo \" trap one inch from bottom
- A trap at or below the bottom of the page is ignored; it can be
- made active by either moving it up or increasing the page length
- so that the trap is on the page.
- It is possible to have more than one trap at the same location; to
- do so, the traps must be defined at different locations, then
- moved together with the `ch' request; otherwise the second trap
- would replace the first one. Earlier defined traps hide later
- defined traps if moved to the same position (the many empty lines
- caused by the `bp' request are omitted in the following example):
- .de a
- . nop a
- ..
- .de b
- . nop b
- ..
- .de c
- . nop c
- ..
- .
- .wh 1i a
- .wh 2i b
- .wh 3i c
- .bp
- => a b c
- .ch b 1i
- .ch c 1i
- .bp
- => a
- .ch a 0.5i
- .bp
- => a b
- -- Register: \n[.t]
- A read-only number register holding the distance to the next trap.
- If there are no traps between the current position and the bottom
- of the page, it contains the distance to the page bottom. In a
- diversion, the distance to the page bottom is infinite (the
- returned value is the biggest integer which can be represented in
- `groff') if there are no diversion traps.
- -- Request: .ch macro [dist]
- Change the location of a trap. The first argument is the name of
- the macro to be invoked at the trap, and the second argument is
- the new location for the trap (note that the parameters are
- specified in opposite order as in the `wh' request). This is
- useful for building up footnotes in a diversion to allow more
- space at the bottom of the page for them.
- Default scaling indicator for DIST is `v'. If DIST is missing,
- the trap is removed.
- -- Register: \n[.ne]
- The read-only number register `.ne' contains the amount of space
- that was needed in the last `ne' request that caused a trap to be
- sprung. Useful in conjunction with the `.trunc' register. *Note
- Page Control::, for more information.
- Since the `.ne' register is only set by traps it doesn't make much
- sense to use it outside of trap macros.
- -- Register: \n[.trunc]
- A read-only register containing the amount of vertical space
- truncated by the most recently sprung vertical position trap, or,
- if the trap was sprung by an `ne' request, minus the amount of
- vertical motion produced by the `ne' request. In other words, at
- the point a trap is sprung, it represents the difference of what
- the vertical position would have been but for the trap, and what
- the vertical position actually is.
- Since the `.trunc' register is only set by traps it doesn't make
- much sense to use it outside of trap macros.
- -- Register: \n[.pe]
- A read-only register which is set to 1 while a page is ejected with
- the `bp' request (or by the end of input).
- Outside of traps this register is always zero. In the following
- example, only the second call to `x' is caused by `bp'.
- .de x
- \&.pe=\\n[.pe]
- .br
- ..
- .wh 1v x
- .wh 4v x
- A line.
- .br
- Another line.
- .br
- => A line.
- .pe=0
- Another line.
- .pe=1
- An important fact to consider while designing macros is that
- diversions and traps do not interact normally. For example, if a trap
- invokes a header macro (while outputting a diversion) which tries to
- change the font on the current page, the effect will not be visible
- before the diversion has completely been printed (except for input
- protected with `\!' or `\?') since the data in the diversion is already
- formatted. In most cases, this is not the expected behaviour.
- File: groff, Node: Diversion Traps, Next: Input Line Traps, Prev: Page Location Traps, Up: Traps
- 5.24.2 Diversion Traps
- ----------------------
- -- Request: .dt [dist macro]
- Set a trap _within_ a diversion. DIST is the location of the trap
- (identical to the `wh' request; default scaling indicator is `v')
- and MACRO is the name of the macro to be invoked. If called
- without arguments, the diversion trap is removed.
- Note that there exists only a single diversion trap.
- The number register `.t' still works within diversions. *Note
- Diversions::, for more information.
- File: groff, Node: Input Line Traps, Next: Blank Line Traps, Prev: Diversion Traps, Up: Traps
- 5.24.3 Input Line Traps
- -----------------------
- -- Request: .it n macro
- -- Request: .itc n macro
- Set an input line trap. N is the number of lines of input which
- may be read before springing the trap, MACRO is the macro to be
- invoked. Request lines are not counted as input lines.
- For example, one possible use is to have a macro which prints the
- next N lines in a bold font.
- .de B
- . it \\$1 B-end
- . ft B
- ..
- .
- .de B-end
- . ft R
- ..
- The `itc' request is identical except that an interrupted text
- line (ending with `\c') is not counted as a separate line.
- Both requests are associated with the current environment (*note
- Environments::); switching to another environment disables the
- current input trap, and going back reactivates it, restoring the
- number of already processed lines.
- File: groff, Node: Blank Line Traps, Next: End-of-input Traps, Prev: Input Line Traps, Up: Traps
- 5.24.4 Blank Line Traps
- -----------------------
- -- Request: .blm macro
- Set a blank line trap. `gtroff' executes MACRO when it encounters
- a blank line in the input file.
- File: groff, Node: End-of-input Traps, Prev: Blank Line Traps, Up: Traps
- 5.24.5 End-of-input Traps
- -------------------------
- -- Request: .em macro
- Set a trap at the end of input. MACRO is executed after the last
- line of the input file has been processed.
- For example, if the document had to have a section at the bottom
- of the last page for someone to approve it, the `em' request could
- be used.
- .de approval
- . ne 5v
- . sp |(\\n[.t] - 6v)
- . in +4i
- . lc _
- . br
- Approved:\t\a
- . sp
- Date:\t\t\a
- ..
- .
- .em approval
- File: groff, Node: Diversions, Next: Environments, Prev: Traps, Up: gtroff Reference
- 5.25 Diversions
- ===============
- In `gtroff' it is possible to "divert" text into a named storage area.
- Due to the similarity to defining macros it is sometimes said to be
- stored in a macro. This is used for saving text for output at a later
- time, which is useful for keeping blocks of text on the same page,
- footnotes, tables of contents, and indices.
- For orthogonality it is said that `gtroff' is in the "top-level
- diversion" if no diversion is active (i.e., the data is diverted to the
- output device).
- -- Request: .di macro
- -- Request: .da macro
- Begin a diversion. Like the `de' request, it takes an argument of
- a macro name to divert subsequent text into. The `da' macro
- appends to an existing diversion.
- `di' or `da' without an argument ends the diversion.
- -- Request: .box macro
- -- Request: .boxa macro
- Begin (or appends to) a diversion like the `di' and `da' requests.
- The difference is that `box' and `boxa' do not include a
- partially-filled line in the diversion.
- Compare this:
- Before the box.
- .box xxx
- In the box.
- .br
- .box
- After the box.
- .br
- => Before the box. After the box.
- .xxx
- => In the box.
- with this:
- Before the diversion.
- .di yyy
- In the diversion.
- .br
- .di
- After the diversion.
- .br
- => After the diversion.
- .yyy
- => Before the diversion. In the diversion.
- `box' or `boxa' without an argument ends the diversion.
- -- Register: \n[.z]
- -- Register: \n[.d]
- Diversions may be nested. The read-only number register `.z'
- contains the name of the current diversion (this is a string-valued
- register). The read-only number register `.d' contains the current
- vertical place in the diversion. If not in a diversion it is the
- same as register `nl'.
- -- Register: \n[.h]
- The "high-water mark" on the current page. It corresponds to the
- text baseline of the lowest line on the page. This is a read-only
- register.
- .tm .h==\n[.h], nl==\n[nl]
- => .h==0, nl==-1
- This is a test.
- .br
- .sp 2
- .tm .h==\n[.h], nl==\n[nl]
- => .h==40, nl==120
- As can be seen in the previous example, empty lines are not
- considered in the return value of the `.h' register.
- -- Register: \n[dn]
- -- Register: \n[dl]
- After completing a diversion, the read-write number registers `dn'
- and `dl' contain the vertical and horizontal size of the diversion.
- Note that only the just processed lines are counted: For the
- computation of `dn' and `dl', the requests `da' and `boxa' are
- handled as if `di' and `box' had been used - lines which have been
- already stored in a macro are not taken into account.
- .\" Center text both horizontally & vertically
- .
- .\" Enclose macro definitions in .eo and .ec
- .\" to avoid the doubling of the backslash
- .eo
- .\" macro .(c starts centering mode
- .de (c
- . br
- . ev (c
- . evc 0
- . in 0
- . nf
- . di @c
- ..
- .\" macro .)c terminates centering mode
- .de )c
- . br
- . ev
- . di
- . nr @s (((\n[.t]u - \n[dn]u) / 2u) - 1v)
- . sp \n[@s]u
- . ce 1000
- . @c
- . ce 0
- . sp \n[@s]u
- . br
- . fi
- . rr @s
- . rm @s
- . rm @c
- ..
- .\" End of macro definitions, restore escape mechanism
- .ec
- -- Escape: \!
- -- Escape: \?anything\?
- Prevent requests, macros, and escapes from being interpreted when
- read into a diversion. Both escapes take the given text and
- "transparently" embed it into the diversion. This is useful for
- macros which shouldn't be invoked until the diverted text is
- actually output.
- The `\!' escape transparently embeds text up to and including the
- end of the line. The `\?' escape transparently embeds text until
- the next occurrence of the `\?' escape. Example:
- \?ANYTHING\?
- ANYTHING may not contain newlines; use `\!' to embed newlines in
- a diversion. The escape sequence `\?' is also recognized in copy
- mode and turned into a single internal code; it is this code that
- terminates ANYTHING. Thus the following example prints 4.
- .nr x 1
- .nf
- .di d
- \?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
- .di
- .nr x 2
- .di e
- .d
- .di
- .nr x 3
- .di f
- .e
- .di
- .nr x 4
- .f
- Both escapes read the data in copy mode.
- If `\!' is used in the top-level diversion, its argument is
- directly embedded into the `gtroff' intermediate output. This can
- be used for example to control a postprocessor which processes the
- data before it is sent to the device driver.
- The `\?' escape used in the top-level diversion produces no output
- at all; its argument is simply ignored.
- -- Request: .output string
- Emit STRING directly to the `gtroff' intermediate output (subject
- to copy-mode interpretation); this is similar to `\!' used at the
- top level. An initial double quote in STRING is stripped off to
- allow initial blanks.
- This request can't be used before the first page has started - if
- you get an error, simply insert `.br' before the `output' request.
- Without argument, `output' is ignored.
- Use with caution! It is normally only needed for mark-up used by a
- postprocessor which does something with the output before sending
- it to the output device, filtering out STRING again.
- -- Request: .asciify div
- "Unformat" the diversion specified by DIV in such a way that ASCII
- characters, characters translated with the `trin' request, space
- characters, and some escape sequences that were formatted and
- diverted are treated like ordinary input characters when the
- diversion is reread. It can be also used for gross hacks; for
- example, the following sets register `n' to 1.
- .tr @.
- .di x
- @nr n 1
- .br
- .di
- .tr @@
- .asciify x
- .x
- *Note Copy-in Mode::.
- -- Request: .unformat div
- Like `asciify', unformat the specified diversion. However,
- `unformat' only unformats spaces and tabs between words.
- Unformatted tabs are treated as input tokens, and spaces are
- stretchable again.
- The vertical size of lines is not preserved; glyph information
- (font, font size, space width, etc.) is retained.
- File: groff, Node: Environments, Next: Suppressing output, Prev: Diversions, Up: gtroff Reference
- 5.26 Environments
- =================
- It happens frequently that some text should be printed in a certain
- format regardless of what may be in effect at the time, for example, in
- a trap invoked macro to print headers and footers. To solve this
- `gtroff' processes text in "environments". An environment contains
- most of the parameters that control text processing. It is possible to
- switch amongst these environments; by default `gtroff' processes text
- in environment 0. The following is the information kept in an
- environment.
- * font parameters (size, family, style, glyph height and slant, space
- and sentence space size)
- * page parameters (line length, title length, vertical spacing, line
- spacing, indentation, line numbering, centering, right-justifying,
- underlining, hyphenation data)
- * fill and adjust mode
- * tab stops, tab and leader characters, escape character, no-break
- and hyphen indicators, margin character data
- * partially collected lines
- * input traps
- * drawing and fill colours
- These environments may be given arbitrary names (see *Note
- Identifiers::, for more info). Old versions of `troff' only had
- environments named `0', `1', and `2'.
- -- Request: .ev [env]
- -- Register: \n[.ev]
- Switch to another environment. The argument ENV is the name of
- the environment to switch to. With no argument, `gtroff' switches
- back to the previous environment. There is no limit on the number
- of named environments; they are created the first time that they
- are referenced. The `.ev' read-only register contains the name or
- number of the current environment. This is a string-valued
- register.
- Note that a call to `ev' (with argument) pushes the previously
- active environment onto a stack. If, say, environments `foo',
- `bar', and `zap' are called (in that order), the first `ev'
- request without parameter switches back to environment `bar'
- (which is popped off the stack), and a second call switches back
- to environment `foo'.
- Here is an example:
- .ev footnote-env
- .fam N
- .ps 6
- .vs 8
- .ll -.5i
- .ev
- ...
- .ev footnote-env
- \(dg Note the large, friendly letters.
- .ev
- -- Request: .evc env
- Copy the environment ENV into the current environment.
- The following environment data is not copied:
- * Partially filled lines.
- * The status whether the previous line was interrupted.
- * The number of lines still to center, or to right-justify, or
- to underline (with or without underlined spaces); they are
- set to zero.
- * The status whether a temporary indentation is active.
- * Input traps and its associated data.
- * Line numbering mode is disabled; it can be reactivated with
- `.nm +0'.
- * The number of consecutive hyphenated lines (set to zero).
- -- Register: \n[.w]
- -- Register: \n[.cht]
- -- Register: \n[.cdp]
- -- Register: \n[.csk]
- The `\n[.w]' register contains the width of the last glyph added
- to the current environment.
- The `\n[.cht]' register contains the height of the last glyph
- added to the current environment.
- The `\n[.cdp]' register contains the depth of the last glyph added
- to the current environment. It is positive for glyphs extending
- below the baseline.
- The `\n[.csk]' register contains the "skew" (how far to the right
- of the glyph's center that `gtroff' should place an accent) of the
- last glyph added to the current environment.
- -- Register: \n[.n]
- The `\n[.n]' register contains the length of the previous output
- line in the current environment.
- File: groff, Node: Suppressing output, Next: Colors, Prev: Environments, Up: gtroff Reference
- 5.27 Suppressing output
- =======================
- -- Escape: \Onum
- Disable or enable output depending on the value of NUM:
- `\O0'
- Disable any glyphs from being emitted to the device driver,
- provided that the escape occurs at the outer level (see
- `\O[3]' and `\O[4]'). Motion is not suppressed so
- effectively `\O[0]' means _pen up_.
- `\O1'
- Enable output of glyphs, provided that the escape occurs at
- the outer level.
- `\O0' and `\O1' also reset the four registers `opminx', `opminy',
- `opmaxx', and `opmaxy' to -1. *Note Register Index::. These four
- registers mark the top left and bottom right hand corners of a box
- which encompasses all written glyphs.
- For example the input text:
- Hello \O[0]world \O[1]this is a test.
- produces the following output:
- Hello this is a test.
- `\O2'
- Provided that the escape occurs at the outer level, enable
- output of glyphs and also write out to `stderr' the page
- number and four registers encompassing the glyphs previously
- written since the last call to `\O'.
- `\O3'
- Begin a nesting level. At start-up, `gtroff' is at outer
- level.
- `\O4'
- End a nesting level.
- `\O[5PFILENAME]'
- This escape is `grohtml' specific. Provided that this escape
- occurs at the outer nesting level write the `filename' to
- `stderr'. The position of the image, P, must be specified
- and must be one of `l', `r', `c', or `i' (left, right,
- centered, inline). FILENAME will be associated with the
- production of the next inline image.
- File: groff, Node: Colors, Next: I/O, Prev: Suppressing output, Up: gtroff Reference
- 5.28 Colors
- ===========
- -- Request: .color [n]
- -- Register: \n[.color]
- If N is missing or non-zero, activate colors (this is the default);
- otherwise, turn it off.
- The read-only number register `.color' is 1 if colors are active,
- 0 otherwise.
- Internally, `color' sets a global flag; it does not produce a
- token. Similar to the `cp' request, you should use it at the
- beginning of your document to control color output.
- Colors can be also turned off with the `-c' command line option.
- -- Request: .defcolor ident scheme color_components
- Define color with name IDENT. SCHEME can be one of the following
- values: `rgb' (three components), `cmy' (three components), `cmyk'
- (four components), and `gray' or `grey' (one component).
- Color components can be given either as a hexadecimal string or as
- positive decimal integers in the range 0-65535. A hexadecimal
- string contains all color components concatenated. It must start
- with either `#' or `##'; the former specifies hex values in the
- range 0-255 (which are internally multiplied by 257), the latter
- in the range 0-65535. Examples: `#FFC0CB' (pink), `##ffff0000ffff'
- (magenta). The default color name value is device-specific
- (usually black). It is possible that the default color for `\m'
- and `\M' is not identical.
- A new scaling indicator `f' has been introduced which multiplies
- its value by 65536; this makes it convenient to specify color
- components as fractions in the range 0 to 1 (1f equals 65536u).
- Example:
- .defcolor darkgreen rgb 0.1f 0.5f 0.2f
- Note that `f' is the default scaling indicator for the `defcolor'
- request, thus the above statement is equivalent to
- .defcolor darkgreen rgb 0.1 0.5 0.2
- -- Request: .gcolor [color]
- -- Escape: \mc
- -- Escape: \m(co
- -- Escape: \m[color]
- -- Register: \n[.m]
- Set (glyph) drawing color. The following examples show how to
- turn the next four words red.
- .gcolor red
- these are in red
- .gcolor
- and these words are in black.
- \m[red]these are in red\m[] and these words are in black.
- The escape `\m[]' returns to the previous color, as does a call to
- `gcolor' without an argument.
- The name of the current drawing color is available in the
- read-only, string-valued number register `.m'.
- The drawing color is associated with the current environment
- (*note Environments::).
- Note that `\m' doesn't produce an input token in `gtroff'. As a
- consequence, it can be used in requests like `mc' (which expects a
- single character as an argument) to change the color on the fly:
- .mc \m[red]x\m[]
- -- Request: .fcolor [color]
- -- Escape: \Mc
- -- Escape: \M(co
- -- Escape: \M[color]
- -- Register: \n[.M]
- Set fill (background) color for filled objects drawn with the
- `\D'...'' commands.
- A red ellipse can be created with the following code:
- \M[red]\h'0.5i'\D'E 2i 1i'\M[]
- The escape `\M[]' returns to the previous fill color, as does a
- call to `fcolor' without an argument.
- The name of the current fill (background) color is available in the
- read-only, string-valued number register `.M'.
- The fill color is associated with the current environment (*note
- Environments::).
- Note that `\M' doesn't produce an input token in `gtroff'.
- File: groff, Node: I/O, Next: Postprocessor Access, Prev: Colors, Up: gtroff Reference
- 5.29 I/O
- ========
- `gtroff' has several requests for including files:
- -- Request: .so file
- Read in the specified FILE and includes it in place of the `so'
- request. This is quite useful for large documents, e.g. keeping
- each chapter in a separate file. *Note gsoelim::, for more
- information.
- Since `gtroff' replaces the `so' request with the contents of
- `file', it makes a difference whether the data is terminated with
- a newline or not: Assuming that file `xxx' contains the word `foo'
- without a final newline, this
- This is
- .so xxx
- bar
- yields `This is foobar'.
- The search path for FILE can be controlled with the `-I' command
- line option.
- -- Request: .pso command
- Read the standard output from the specified COMMAND and includes
- it in place of the `pso' request.
- This request causes an error if used in safer mode (which is the
- default). Use `groff''s or `troff''s `-U' option to activate
- unsafe mode.
- The comment regarding a final newline for the `so' request is valid
- for `pso' also.
- -- Request: .mso file
- Identical to the `so' request except that `gtroff' searches for
- the specified FILE in the same directories as macro files for the
- the `-m' command line option. If the file name to be included has
- the form `NAME.tmac' and it isn't found, `mso' tries to include
- `tmac.NAME' and vice versa.
- -- Request: .trf file
- -- Request: .cf file
- Transparently output the contents of FILE. Each line is output as
- if it were preceded by `\!'; however, the lines are not subject to
- copy mode interpretation. If the file does not end with a newline,
- then a newline is added (`trf' only). For example, to define a
- macro `x' containing the contents of file `f', use
- .di x
- .trf f
- .di
- Both `trf' and `cf', when used in a diversion, embeds an object in
- the diversion which, when reread, causes the contents of FILE to
- be transparently copied through to the output. In UNIX `troff',
- the contents of FILE is immediately copied through to the output
- regardless of whether there is a current diversion; this behaviour
- is so anomalous that it must be considered a bug.
- While `cf' copies the contents of FILE completely unprocessed,
- `trf' disallows characters such as NUL that are not valid `gtroff'
- input characters (*note Identifiers::).
- Both requests cause a line break.
- -- Request: .nx [file]
- Force `gtroff' to continue processing of the file specified as an
- argument. If no argument is given, immediately jump to the end of
- file.
- -- Request: .rd [prompt [arg1 arg2 ...]]
- Read from standard input, and include what is read as though it
- were part of the input file. Text is read until a blank line is
- encountered.
- If standard input is a TTY input device (keyboard), write PROMPT
- to standard error, followed by a colon (or send BEL for a beep if
- no argument is given).
- Arguments after PROMPT are available for the input. For example,
- the line
- .rd data foo bar
- with the input `This is \$2.' prints
- This is bar.
- Using the `nx' and `rd' requests, it is easy to set up form letters.
- The form letter template is constructed like this, putting the
- following lines into a file called `repeat.let':
- .ce
- \*(td
- .sp 2
- .nf
- .rd
- .sp
- .rd
- .fi
- Body of letter.
- .bp
- .nx repeat.let
- When this is run, a file containing the following lines should be
- redirected in. Note that requests included in this file are executed
- as though they were part of the form letter. The last block of input
- is the `ex' request which tells `groff' to stop processing. If this
- was not there, `groff' would not know when to stop.
- Trent A. Fisher
- 708 NW 19th Av., #202
- Portland, OR 97209
- Dear Trent,
- Len Adollar
- 4315 Sierra Vista
- San Diego, CA 92103
- Dear Mr. Adollar,
- .ex
- -- Request: .pi pipe
- Pipe the output of `gtroff' to the shell command(s) specified by
- PIPE. This request must occur before `gtroff' has a chance to
- print anything.
- `pi' causes an error if used in safer mode (which is the default).
- Use `groff''s or `troff''s `-U' option to activate unsafe mode.
- Multiple calls to `pi' are allowed, acting as a chain. For
- example,
- .pi foo
- .pi bar
- ...
- is the same as `.pi foo | bar'.
- Note that the intermediate output format of `gtroff' is piped to
- the specified commands. Consequently, calling `groff' without the
- `-Z' option normally causes a fatal error.
- -- Request: .sy cmds
- -- Register: \n[systat]
- Execute the shell command(s) specified by CMDS. The output is not
- saved anyplace, so it is up to the user to do so.
- This request causes an error if used in safer mode (which is the
- default). Use `groff''s or `troff''s `-U' option to activate
- unsafe mode.
- For example, the following code fragment introduces the current
- time into a document:
- .sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\
- (localtime(time))[2,1,0]' > /tmp/x\n[$$]
- .so /tmp/x\n[$$]
- .sy rm /tmp/x\n[$$]
- \nH:\nM:\nS
- Note that this works by having the `perl' script (run by `sy')
- print out the `nr' requests which set the number registers `H',
- `M', and `S', and then reads those commands in with the `so'
- request.
- For most practical purposes, the number registers `seconds',
- `minutes', and `hours' which are initialized at start-up of
- `gtroff' should be sufficient. Use the `af' request to get a
- formatted output:
- .af hours 00
- .af minutes 00
- .af seconds 00
- \n[hours]:\n[minutes]:\n[seconds]
- The `systat' read-write number register contains the return value
- of the `system()' function executed by the last `sy' request.
- -- Request: .open stream file
- -- Request: .opena stream file
- Open the specified FILE for writing and associates the specified
- STREAM with it.
- The `opena' request is like `open', but if the file exists, append
- to it instead of truncating it.
- Both `open' and `opena' cause an error if used in safer mode
- (which is the default). Use `groff''s or `troff''s `-U' option to
- activate unsafe mode.
- -- Request: .write stream data
- -- Request: .writec stream data
- Write to the file associated with the specified STREAM. The
- stream must previously have been the subject of an open request.
- The remainder of the line is interpreted as the `ds' request reads
- its second argument: A leading `"' is stripped, and it is read in
- copy-in mode.
- The `writec' request is like `write', but only `write' appends a
- newline to the data.
- -- Request: .writem stream xx
- Write the contents of the macro or string XX to the file
- associated with the specified STREAM.
- XX is read in copy mode, i.e., already formatted elements are
- ignored. Consequently, diversions must be unformatted with the
- `asciify' request before calling `writem'. Usually, this means a
- loss of information.
- -- Request: .close stream
- Close the specified STREAM; the stream is no longer an acceptable
- argument to the `write' request.
- Here a simple macro to write an index entry.
- .open idx test.idx
- .
- .de IX
- . write idx \\n[%] \\$*
- ..
- .
- .IX test entry
- .
- .close idx
- -- Escape: \Ve
- -- Escape: \V(ev
- -- Escape: \V[env]
- Interpolate the contents of the specified environment variable ENV
- (one-character name E, two-character name EV) as returned by the
- function `getenv'. `\V' is interpreted in copy-in mode.
- File: groff, Node: Postprocessor Access, Next: Miscellaneous, Prev: I/O, Up: gtroff Reference
- 5.30 Postprocessor Access
- =========================
- There are two escapes which give information directly to the
- postprocessor. This is particularly useful for embedding POSTSCRIPT
- into the final document.
- -- Escape: \X'xxx'
- Embeds its argument into the `gtroff' output preceded with `x X'.
- The escapes `\&', `\)', `\%', and `\:' are ignored within `\X',
- `\ ' and `\~' are converted to single space characters. All other
- escapes (except `\\' which produces a backslash) cause an error.
- If the `use_charnames_in_special' keyword is set in the `DESC'
- file, special characters no longer cause an error; the name XX is
- represented as `\(XX)' in the `x X' output command. Additionally,
- the backslash is represented as `\\'.
- `use_charnames_in_special' is currently used by `grohtml' only.
- -- Escape: \Yn
- -- Escape: \Y(nm
- -- Escape: \Y[name]
- This is approximately equivalent to `\X'\*[NAME]'' (one-character
- name N, two-character name NM). However, the contents of the
- string or macro NAME are not interpreted; also it is permitted for
- NAME to have been defined as a macro and thus contain newlines (it
- is not permitted for the argument to `\X' to contain newlines).
- The inclusion of newlines requires an extension to the UNIX `troff'
- output format, and confuses drivers that do not know about this
- extension (*note Device Control Commands::).
- *Note Output Devices::.
- File: groff, Node: Miscellaneous, Next: Gtroff Internals, Prev: Postprocessor Access, Up: gtroff Reference
- 5.31 Miscellaneous
- ==================
- This section documents parts of `gtroff' which cannot (yet) be
- categorized elsewhere in this manual.
- -- Request: .nm [start [inc [space [indent]]]]
- Print line numbers. START is the line number of the _next_ output
- line. INC indicates which line numbers are printed. For example,
- the value 5 means to emit only line numbers which are multiples
- of 5; this defaults to 1. SPACE is the space to be left between
- the number and the text; this defaults to one digit space. The
- fourth argument is the indentation of the line numbers, defaulting
- to zero. Both SPACE and INDENT are given as multiples of digit
- spaces; they can be negative also. Without any arguments, line
- numbers are turned off.
- `gtroff' reserves three digit spaces for the line number (which is
- printed right-justified) plus the amount given by INDENT; the
- output lines are concatenated to the line numbers, separated by
- SPACE, and _without_ reducing the line length. Depending on the
- value of the horizontal page offset (as set with the `po'
- request), line numbers which are longer than the reserved space
- stick out to the left, or the whole line is moved to the right.
- Parameters corresponding to missing arguments are not changed; any
- non-digit argument (to be more precise, any argument starting with
- a character valid as a delimiter for identifiers) is also treated
- as missing.
- If line numbering has been disabled with a call to `nm' without an
- argument, it can be reactivated with `.nm +0', using the
- previously active line numbering parameters.
- The parameters of `nm' are associated with the current environment
- (*note Environments::). The current output line number is
- available in the number register `ln'.
- .po 1m
- .ll 2i
- This test shows how line numbering works with groff.
- .nm 999
- This test shows how line numbering works with groff.
- .br
- .nm xxx 3 2
- .ll -\w'0'u
- This test shows how line numbering works with groff.
- .nn 2
- This test shows how line numbering works with groff.
- And here the result:
- This test shows how
- line numbering works
- 999 with groff. This
- 1000 test shows how line
- 1001 numbering works with
- 1002 groff.
- This test shows how
- line numbering
- works with groff.
- This test shows how
- 1005 line numbering
- works with groff.
- -- Request: .nn [skip]
- Temporarily turn off line numbering. The argument is the number
- of lines not to be numbered; this defaults to 1.
- -- Request: .mc glyph [dist]
- Print a "margin character" to the right of the text.(1) (*note
- Miscellaneous-Footnote-1::) The first argument is the glyph to be
- printed. The second argument is the distance away from the right
- margin. If missing, the previously set value is used; default is
- 10pt). For text lines that are too long (that is, longer than the
- text length plus DIST), the margin character is directly appended
- to the lines.
- With no arguments the margin character is turned off. If this
- occurs before a break, no margin character is printed.
- For compatibility with AT&T `troff', a call to `mc' to set the
- margin character can't be undone immediately; at least one line
- gets a margin character. Thus
- .ll 1i
- .mc \[br]
- .mc
- xxx
- .br
- xxx
- produces
- xxx |
- xxx
- For empty lines and lines produced by the `tl' request no margin
- character is emitted.
- The margin character is associated with the current environment
- (*note Environments::).
- This is quite useful for indicating text that has changed, and, in
- fact, there are programs available for doing this (they are called
- `nrchbar' and `changebar' and can be found in any
- `comp.sources.unix' archive).…