1 This is groff, produced by makeinfo version 4.2 from ./groff.texinfo.
3 This manual documents GNU `troff' version 1.18.
5 Copyright (C) 1994-2000, 2001, 2002 Free Software Foundation, Inc.
7 Permission is granted to copy, distribute and/or modify this
8 document under the terms of the GNU Free Documentation License,
9 Version 1.1 or any later version published by the Free Software
10 Foundation; with no Invariant Sections, with the Front-Cover texts
11 being `A GNU Manual," and with the Back-Cover Texts as in (a)
12 below. A copy of the license is included in the section entitled
13 `GNU Free Documentation License."
15 (a) The FSF's Back-Cover Text is: `You have freedom to copy and
16 modify this GNU Manual, like GNU software. Copies published by
17 the Free Software Foundation raise funds for GNU development."
19 INFO-DIR-SECTION Miscellaneous
21 * Groff: (groff). The GNU troff document formatting system.
25 File: groff, Node: Page Control, Next: Fonts, Prev: Page Layout, Up: gtroff Reference
33 Stop processing the current page and move to the next page. This
34 request causes a break. It can also take an argument to set
35 (increase, decrease) the page number of the next page. The only
36 difference between `bp' and `pn' is that `pn' does not cause a
37 break or actually eject a page.
40 .de newpage \" define macro
42 'sp .5i \" vertical space
43 .tl 'left top'center top'right top' \" title
44 'sp .3i \" vertical space
47 `bp' has no effect if not called within the top-level diversion
50 - Request: .ne [space]
51 It is often necessary to force a certain amount of space before a
52 new page occurs. This is most useful to make sure that there is
53 not a single "orphan" line left at the bottom of a page. The `ne'
54 request ensures that there is a certain distance, specified by the
55 first argument, before the next page is triggered (see *Note
56 Traps::, for further information). The default scaling indicator
57 for `ne' is `v'; the default value of SPACE is 1v if no argument
60 For example, to make sure that no fewer than 2 lines get orphaned,
61 do the following before each paragraph:
67 `ne' will then automatically cause a page break if there is space
70 - Request: .sv [space]
72 `sv' is similar to the `ne' request; it reserves the specified
73 amount of vertical space. If the desired amount of space exists
74 before the next trap (or the bottom page boundary if no trap is
75 set), the space is output immediately (ignoring a partially filled
76 line which stays untouched). If there is not enough space, it is
77 stored for later output via the `os' request. The default value
78 is 1v if no argument is given; the default scaling indicator is
81 Both `sv' and `os' ignore no-space mode. While the `sv' request
82 allows negative values for SPACE, `os' will ignore them.
85 This register contains the current vertical position. If the
86 vertical position is zero and the top of page transition hasn't
87 happened yet, `nl' is set to negative value. `gtroff' itself does
88 this at the very beginning of a document before anything has been
89 printed, but the main usage is to plant a header trap on a page if
90 this page has already started.
92 Consider the following:
120 Without resetting `nl' to a negative value, the just planted trap
121 would be active beginning with the _next_ page, not the current
124 *Note Diversions::, for a comparison with the `.h' and `.d'
128 File: groff, Node: Fonts, Next: Sizes, Prev: Page Control, Up: gtroff Reference
133 `gtroff' can switch fonts at any point in the text.
135 The basic set of fonts is `R', `I', `B', and `BI'. These are Times
136 Roman, Italic, Bold, and Bold Italic. For non-TTY devices, there is
137 also at least one symbol font which contains various special symbols
138 (Greek, mathematics).
148 * Ligatures and Kerning::
151 File: groff, Node: Changing Fonts, Next: Font Families, Prev: Fonts, Up: Fonts
156 - Request: .ft [font]
160 The `ft' request and the `\f' escape change the current font to
161 FONT (one-character name F, two-character name FN).
163 If FONT is a style name (as set with the `sty' request or with the
164 `styles' command in the `DESC' file), use it within the current
165 font family (as set with the `fam' request, `\F' escape, or with
166 the `family' command in the `DESC' file).
168 With no argument or using `P' as an argument, `.ft' switches to
169 the previous font. Use `\f[]' to do this with the escape. The
170 old syntax forms `\fP' or `\f[P]' are also supported.
172 Fonts are generally specified as upper-case strings, which are
173 usually 1 to 4 characters representing an abbreviation or acronym
174 of the font name. This is no limitation, just a convention.
176 The example below produces two identical lines.
185 eggs, bacon, \fBspam\fP and sausage.
187 Note that `\f' doesn't produce an input token in `gtroff'. As a
188 consequence, it can be used in requests like `mc' (which expects a
189 single character as an argument) to change the font on the fly:
194 *Note Font Positions::, for an alternative syntax.
196 - Request: .ftr f [g]
197 Translate font F to font G. Whenever a font named F is referred
198 to in a `\f' escape sequence, or in the `ft', `ul', `bd', `cs',
199 `tkf', `special', `fspecial', `fp', or `sty' requests, font G is
200 used. If G is missing or equal to F the translation is undone.
203 File: groff, Node: Font Families, Next: Font Positions, Prev: Changing Fonts, Up: Fonts
208 Due to the variety of fonts available, `gtroff' has added the
209 concept of "font families" and "font styles". The fonts are specified
210 as the concatenation of the font family and style. Specifying a font
211 without the family part causes `gtroff' to use that style of the
214 Currently, fonts for the devices `-Tps', `-Tdvi', and `-Tlbp' are
215 set up to this mechanism. By default, `gtroff' uses the Times family
216 with the four styles `R', `I', `B', and `BI'.
218 This way, it is possible to use the basic four fonts and to select a
219 different font family on the command line (*note Groff Options::).
221 - Request: .fam [family]
227 Switch font family to FAMILY (one-character name F, two-character
228 name FM). If no argument is given, switch back to the previous
229 font family. Use `\F[]' to do this with the escape. Note that
230 `\FP' doesn't work; it selects font family `P' instead.
232 The value at start-up is `T'. The current font family is
233 available in the read-only number register `.fam' (this is a
234 string-valued register); it is associated with the current
239 .fam H \" helvetica family
240 spam, \" used font is family H + style R = HR
241 .ft B \" family H + style B = font HB
243 .fam T \" times family
244 spam, \" used font is family T + style B = TB
245 .ft AR \" font AR (not a style)
247 .ft R \" family T + style R = font TR
250 Note that `\F' doesn't produce an input token in `gtroff'. As a
251 consequence, it can be used in requests like `mc' (which expects a
252 single character as an argument) to change the font family on the
258 The `.fn' register contains the current "real font name" of the
259 current font. This is a string-valued register. If the current
260 font is a style, the value of `\n[.fn]' is the proper
261 concatenation of family and style name.
263 - Request: .sty n style
264 Associate STYLE with font position N. A font position can be
265 associated either with a font or with a style. The current font
266 is the index of a font position and so is also either a font or a
267 style. If it is a style, the font that is actually used is the
268 font which name is the concatenation of the name of the current
269 family and the name of the current style. For example, if the
270 current font is 1 and font position 1 is associated with style `R'
271 and the current font family is `T', then font `TR' will be used.
272 If the current font is not a style, then the current family is
273 ignored. If the requests `cs', `bd', `tkf', `uf', or `fspecial'
274 are applied to a style, they will instead be applied to the member
275 of the current family corresponding to that style.
277 N must be a non-negative integer value.
279 The default family can be set with the `-f' option (*note Groff
280 Options::). The `styles' command in the `DESC' file controls
281 which font positions (if any) are initially associated with styles
282 rather than fonts. For example, the default setting for
296 `fam' and `\F' always check whether the current font position is
297 valid; this can give surprising results if the current font
298 position is associated with a style.
300 In the following example, we want to access the POSTSCRIPT font
301 `FooBar' from the font family `Foo':
306 => warning: can't find font `FooR'
308 The default font position at start-up is 1; for the POSTSCRIPT
309 device, this is associated with style `R', so `gtroff' tries to
312 A solution to this problem is to use a dummy font like the
316 .fp 0 dummy TR \" set up dummy font at position 0
317 .sty \n[.fp] Bar \" register style `Bar'
318 .ft 0 \" switch to font at position 0
319 .fam Foo \" activate family `Foo'
320 .ft Bar \" switch to font `FooBar'
322 *Note Font Positions::.
325 File: groff, Node: Font Positions, Next: Using Symbols, Prev: Font Families, Up: Fonts
330 For the sake of old phototypesetters and compatibility with old
331 versions of `troff', `gtroff' has the concept of font "positions", on
332 which various fonts are mounted.
334 - Request: .fp pos font [external-name]
337 Mount font FONT at position POS (which must be a non-negative
338 integer). This numeric position can then be referred to with font
339 changing commands. When `gtroff' starts it is using font
340 position 1 (which must exist; position 0 is unused usually at
343 The current font in use, as a font position, is available in the
344 read-only number register `.f'. This can be useful to remember the
345 current font for later recall. It is associated with the current
346 environment (*note Environments::).
351 ... text text text ...
354 The number of the next free font position is available in the
355 read-only number register `.fp'. This is useful when mounting a
359 .fp \n[.fp] NEATOFONT
361 Fonts not listed in the `DESC' file are automatically mounted on
362 the next available font position when they are referenced. If a
363 font is to be mounted explicitly with the `fp' request on an unused
364 font position, it should be mounted on the first unused font
365 position, which can be found in the `.fp' register. Although
366 `gtroff' does not enforce this strictly, it is not allowed to
367 mount a font at a position whose number is much greater (approx.
368 1000 positions) than that of any currently used position.
370 The `fp' request has an optional third argument. This argument
371 gives the external name of the font, which is used for finding the
372 font description file. The second argument gives the internal
373 name of the font which is used to refer to the font in `gtroff'
374 after it has been mounted. If there is no third argument then the
375 internal name is used as the external name. This feature makes it
376 possible to use fonts with long names in compatibility mode.
378 Both the `ft' request and the `\f' escape have alternative syntax
379 forms to access font positions.
385 Change the current font position to NNN (one-digit position N,
386 two-digit position NN), which must be a non-negative integer.
388 If NNN is associated with a style (as set with the `sty' request
389 or with the `styles' command in the `DESC' file), use it within
390 the current font family (as set with the `fam' request, the `\F'
391 escape, or with the `family' command in the `DESC' file).
397 .ft \" switch back to font 1
403 *Note Changing Fonts::, for the standard syntax form.
406 File: groff, Node: Using Symbols, Next: Special Fonts, Prev: Font Positions, Up: Fonts
411 A "glyph" is a graphical representation of a "character". While a
412 character is an abstract entity containing semantic information, a
413 glyph is something which can be actually seen on screen or paper. It
414 is possible that a character has multiple glyph representation forms
415 (for example, the character `A' can be either written in a roman or an
416 italic font, yielding two different glyphs); sometimes more than one
417 character maps to a single glyph (this is a "ligature" - the most
420 A "symbol" is simply a named glyph. Within `gtroff', all glyph
421 names of a particular font are defined in its font file. If the user
422 requests a glyph not available in this font, `gtroff' looks up an
423 ordered list of "special fonts". By default, the POSTSCRIPT output
424 device supports the two special fonts `SS' (slanted symbols) and `S'
425 (symbols) (the former is looked up before the latter). Other output
426 devices use different names for special fonts. Fonts mounted with the
427 `fonts' keyword in the `DESC' file are globally available. To install
428 additional special fonts locally (i.e. for a particular font), use the
431 In summary, `gtroff' tries the following to find a given symbol:
433 * If the symbol has been defined with the `char' request, use it.
434 This hides a symbol with the same name in the current font.
436 * Check the current font.
438 * If the symbol has been defined with the `fchar' request, use it.
440 * Check all fonts given with the `fspecial' request, in the order of
441 appearance in `fspecial' calls.
443 * Check all fonts given with the `special' request, in the order of
444 appearance in `special' calls (inclusively the special fonts
445 defined in the `DESC' file, which come first).
447 * As a last resort, consult all fonts loaded up to now (in the order
448 they have been called the first time) for special fonts and check
451 *Note Font Files::, and *Note Special Fonts::, for more details.
455 Insert a symbol NAME (two-character name NM). There is no special
456 syntax for one-character names - the natural form `\N' would
457 collide with escapes.(1) (*note Using Symbols-Footnote-1::)
459 If NAME is undefined, a warning of type `char' is generated, and
460 the escape is ignored. *Note Debugging::, for information about
463 The list of available symbols is device dependent; see the
464 `groff_char(7)' man page for a complete list for the given output
465 device. For example, say
468 man -Tdvi groff_char > groff_char.dvi
470 for a list using the default DVI fonts (not all versions of the
471 `man' program support the `-T' option). If you want to use an
472 additional macro package to change the used fonts, `groff' must be
476 groff -Tdvi -mec -man groff_char.7 > groff_char.dvi
480 Typeset the glyph named XXX.(2) (*note Using Symbols-Footnote-2::)
481 Normally it is more convenient to use `\[XXX]', but `\C' has the
482 advantage that it is compatible with newer versions of AT&T
483 `troff' and is available in compatibility mode.
486 Typeset the glyph with code N in the current font (`n' is *not*
487 the input character code). The number N can be any non-negative
488 decimal integer. Most devices only have glyphs with codes between
489 0 and 255; the Unicode output device uses codes in the range
490 0-65535. If the current font does not contain a glyph with that
491 code, special fonts are _not_ searched. The `\N' escape sequence
492 can be conveniently used in conjunction with the `char' request:
495 .char \[phone] \f[ZD]\N'37'
497 The code of each glyph is given in the fourth column in the font
498 description file after the `charset' command. It is possible to
499 include unnamed glyphs in the font description file by using a
500 name of `---'; the `\N' escape sequence is the only way to use
503 Some escape sequences directly map onto special glyphs.
506 This is a backslash followed by the apostrophe character, ASCII
507 character `0x27' (EBCDIC character `0x7D'). The same as `\[aa]',
511 This is a backslash followed by ASCII character `0x60' (EBCDIC
512 character `0x79' usually). The same as `\[ga]', the grave accent.
515 This is the same as `\[-]', the minus sign in the current font.
517 - Request: .cflags n c1 c2 ...
518 Input characters and symbols have certain properties associated
519 with it.(3) (*note Using Symbols-Footnote-3::) These properties
520 can be modified with the `cflags' request. The first argument is
521 the sum of the desired flags and the remaining arguments are the
522 characters or symbols to have those properties. It is possible to
523 omit the spaces between the characters or symbols.
526 The character ends sentences (initially characters `.?!' have
530 Lines can be broken before the character (initially no
531 characters have this property).
534 Lines can be broken after the character (initially the
535 character `-' and the symbols `\(hy' and `\(em' have this
539 The character overlaps horizontally (initially the symbols
540 `\(ul\(rn\(ru' have this property).
543 The character overlaps vertically (initially symbol `\(br' has
547 An end-of-sentence character followed by any number of
548 characters with this property is treated as the end of a
549 sentence if followed by a newline or two spaces; in other
550 words the character is "transparent" for the purposes of
551 end-of-sentence recognition - this is the same as having a
552 zero space factor in TeX (initially characters `"')]*' and
553 the symbols `\(dg\(rq' have this property).
555 - Request: .char g [string]
556 - Request: .fchar g [string]
557 Define a new glyph G to be STRING (which can be empty).(4) (*note
558 Using Symbols-Footnote-4::) Every time glyph G needs to be
559 printed, STRING is processed in a temporary environment and the
560 result is wrapped up into a single object. Compatibility mode is
561 turned off and the escape character is set to `\' while STRING is
562 being processed. Any emboldening, constant spacing or track
563 kerning is applied to this object rather than to individual
564 characters in STRING.
566 A glyph defined by this request can be used just like a normal
567 glyph provided by the output device. In particular, other
568 characters can be translated to it with the `tr' or `trin'
569 requests; it can be made the leader character by the `lc' request;
570 repeated patterns can be drawn with the glyph using the `\l' and
571 `\L' escape sequences; words containing the glyph can be
572 hyphenated correctly if the `hcode' request is used to give the
573 glyph's symbol a hyphenation code.
575 There is a special anti-recursion feature: Use of `g' within the
576 glyph's definition is handled like normal characters and symbols
577 not defined with `char'.
579 Note that the `tr' and `trin' requests take precedence if `char'
580 accesses the same symbol.
593 The `fchar' request defines a fallback glyph: `gtroff' only checks
594 for glyphs defined with `fchar' if it cannot find the glyph in the
595 current font. `gtroff' carries out this test before checking
598 - Request: .rchar c1 c2 ...
599 Remove the definitions of glyphs C1, C2, .... This undoes the
600 effect of a `char' or `fchar' request.
602 It is possible to omit the whitespace between arguments.
604 *Note Special Characters::.
607 File: groff, Node: Using Symbols-Footnotes, Up: Using Symbols
609 (1) Note that a one-character symbol is not the same as an input
610 character, i.e., the character `a' is not the same as `\[a]'. By
611 default, `groff' defines only a single one-character symbol, `\[-]'; it
612 is usually accessed as `\-'. On the other hand, `gtroff' has the
613 special feature that `\[charXXX]' is the same as the input character
614 with character code XXX. For example, `\[char97]' is identical to the
615 letter `a' if ASCII encoding is active.
617 (2) `\C' is actually a misnomer since it accesses an output glyph.
619 (3) Note that the output glyphs themselves don't have such
620 properties. For `gtroff', a glyph is a numbered box with a given
621 width, depth, and height, nothing else. All manipulations with the
622 `cflags' request work on the input level.
624 (4) `char' is a misnomer since an output glyph is defined.
627 File: groff, Node: Special Fonts, Next: Artificial Fonts, Prev: Using Symbols, Up: Fonts
632 Special fonts are those that `gtroff' searches when it cannot find
633 the requested glyph in the current font. The Symbol font is usually a
636 `gtroff' provides the following two requests to add more special
637 fonts. *Note Using Symbols::, for a detailed description of the glyph
638 searching mechanism in `gtroff'.
640 Usually, only non-TTY devices have special fonts.
642 - Request: .special s1 s2 ...
643 - Request: .fspecial f s1 s2 ...
644 Use the `special' request to define special fonts. They are
645 appended to the list of global special fonts in the given order.
646 The first entries in this list are the fonts defined with the
647 `fonts' command in the `DESC' file which are marked as special in
648 the corresponding font description files.
650 Use the `fspecial' request to designate special fonts only when
651 font F font is active. They are appended to the list of special
652 fonts for F in the given order. Initially, this list is empty.
655 File: groff, Node: Artificial Fonts, Next: Ligatures and Kerning, Prev: Special Fonts, Up: Fonts
660 There are a number of requests and escapes for artificially creating
661 fonts. These are largely vestiges of the days when output devices did
662 not have a wide variety of fonts, and when `nroff' and `troff' were
663 separate programs. Most of them are no longer necessary in GNU
664 `troff'. Nevertheless, they are supported.
667 - Escape: \H'+HEIGHT'
668 - Escape: \H'-HEIGHT'
669 Change (increment, decrement) the height of the current font, but
670 not the width. If HEIGHT is zero, restore the original height.
671 Default scaling indicator is `z'.
673 Currently, only the `-Tps' device supports this feature.
675 Note that `\H' doesn't produce an input token in `gtroff'. As a
676 consequence, it can be used in requests like `mc' (which expects a
677 single character as an argument) to change the font on the fly:
682 In compatibility mode, `gtroff' behaves differently: If an
683 increment or decrement is used, it is always taken relative to the
684 current point size and not relative to the previously selected font
689 \H'+5'test \H'+5'test
691 prints the word `test' twice with the same font height (five
692 points larger than the current font size).
695 Slant the current font by SLANT degrees. Positive values slant to
698 Currently, only the `-Tps' device supports this feature.
700 Note that `\S' doesn't produce an input token in `gtroff'. As a
701 consequence, it can be used in requests like `mc' (which expects a
702 single character as an argument) to change the font on the fly:
707 This request is incorrectly documented in the original UNIX troff
708 manual; the slant is always set to an absolute value.
710 - Request: .ul [lines]
711 The `ul' request normally underlines subsequent lines if a TTY
712 output device is used. Otherwise, the lines are printed in italics
713 (only the term `underlined' is used in the following). The single
714 argument is the number of input lines to be underlined; with no
715 argument, the next line is underlined. If LINES is zero or
716 negative, stop the effects of `ul' (if it was active). Requests
717 and empty lines do not count for computing the number of underlined
718 input lines, even if they produce some output like `tl'. Lines
719 inserted by macros (e.g. invoked by a trap) do count.
721 At the beginning of `ul', the current font is stored and the
722 underline font is activated. Within the span of a `ul' request,
723 it is possible to change fonts, but after the last line affected by
724 `ul' the saved font is restored.
726 This number of lines still to be underlined is associated with the
727 current environment (*note Environments::). The underline font
728 can be changed with the `uf' request.
730 The `ul' request does not underline spaces.
732 - Request: .cu [lines]
733 The `cu' request is similar to `ul' but underlines spaces as well
734 (if a TTY output device is used).
737 Set the underline font (globally) used by `ul' and `cu'. By
738 default, this is the font at position 2. FONT can be either a
739 non-negative font position or the name of a font.
741 - Request: .bd font [offset]
742 - Request: .bd font1 font2 [offset]
744 Artificially create a bold font by printing each glyph twice,
747 Two syntax forms are available.
749 * Imitate a bold font unconditionally. The first argument
750 specifies the font to embolden, and the second is the number
751 of basic units, minus one, by which the two glyphs are
752 offset. If the second argument is missing, emboldening is
755 FONT can be either a non-negative font position or the name
758 OFFSET is available in the `.b' read-only register if a
759 special font is active; in the `bd' request, its default unit
762 * Imitate a bold form conditionally. Embolden FONT1 by OFFSET
763 only if font FONT2 is the current font. This command can be
764 issued repeatedly to set up different emboldening values for
765 different current fonts. If the second argument is missing,
766 emboldening is turned off for this particular current font.
768 This affects special fonts only (either set up with the
769 `special' command in font files or with the `fspecial'
772 - Request: .cs font [width [em-size]]
773 Switch to and from "constant glyph space mode". If activated, the
774 width of every glyph is WIDTH/36 ems. The em size is given
775 absolutely by EM-SIZE; if this argument is missing, the em value
776 is taken from the current font size (as set with the `ps' request)
777 when the font is effectively in use. Without second and third
778 argument, constant glyph space mode is deactivated.
780 Default scaling indicator for EM-SIZE is `z'; WIDTH is an integer.
783 File: groff, Node: Ligatures and Kerning, Prev: Artificial Fonts, Up: Fonts
785 Ligatures and Kerning
786 ---------------------
788 Ligatures are groups of characters that are run together, i.e,
789 producing a single glyph. For example, the letters `f' and `i' can
790 form a ligature `fi' as in the word `file'. This produces a cleaner
791 look (albeit subtle) to the printed output. Usually, ligatures are not
792 available in fonts for TTY output devices.
794 Most POSTSCRIPT fonts support the fi and fl ligatures. The C/A/T
795 typesetter that was the target of AT&T `troff' also supported `ff',
796 `ffi', and `ffl' ligatures. Advanced typesetters or `expert' fonts may
797 include ligatures for `ft' and `ct', although GNU `troff' does not
800 - Request: .lg [flag]
802 Switch the ligature mechanism on or off; if the parameter is
803 non-zero or missing, ligatures are enabled, otherwise disabled.
804 Default is on. The current ligature mode can be found in the
805 read-only number register `.lg' (set to 1 or 2 if ligatures are
806 enabled, 0 otherwise).
808 Setting the ligature mode to 2 enables the two-character ligatures
809 (fi, fl, and ff) and disables the three-character ligatures (ffi
812 "Pairwise kerning" is another subtle typesetting mechanism that
813 modifies the distance between a glyph pair to improve readability. In
814 most cases (but not always) the distance is decreased. Typewriter-like
815 fonts and fonts for terminals where all glyphs have the same width
818 - Request: .kern [flag]
819 - Register: \n[.kern]
820 Switch kerning on or off. If the parameter is non-zero or missing,
821 enable pairwise kerning, otherwise disable it. The read-only
822 number register `.kern' is set to 1 if pairwise kerning is enabled,
825 If the font description file contains pairwise kerning information,
826 glyphs from that font are kerned. Kerning between two glyphs can
827 be inhibited by placing `\&' between them: `V\&A'.
829 *Note Font File Format::.
831 "Track kerning" expands or reduces the space between glyphs. This
832 can be handy, for example, if you need to squeeze a long word onto a
833 single line or spread some text to fill a narrow column. It must be
834 used with great care since it is usually considered bad typography if
835 the reader notices the effect.
837 - Request: .tkf f s1 n1 s2 n2
838 Enable track kerning for font F. If the current font is F the
839 width of every glyph is increased by an amount between N1 and N2
840 (N1, N2 can be negative); if the current point size is less than
841 or equal to S1 the width is increased by N1; if it is greater than
842 or equal to S2 the width is increased by N2; if the point size is
843 greater than or equal to S1 and less than or equal to S2 the
844 increase in width is a linear function of the point size.
846 The default scaling indicator is `z' for S1 and S2, `p' for N1 and
849 Note that the track kerning amount is added even to the rightmost
850 glyph in a line; for large values it is thus recommended to
851 increase the line length by the same amount to compensate it.
853 Sometimes, when typesetting letters of different fonts, more or less
854 space at such boundaries are needed. There are two escapes to help
858 Increase the width of the preceding glyph so that the spacing
859 between that glyph and the following glyph is correct if the
860 following glyph is a roman glyph. For example, if an italic `f'
861 is immediately followed by a roman right parenthesis, then in many
862 fonts the top right portion of the `f' overlaps the top left of
863 the right parenthesis. Use this escape sequence whenever an
864 italic glyph is immediately followed by a roman glyph without any
865 intervening space. This small amount of space is also called
870 Modify the spacing of the following glyph so that the spacing
871 between that glyph and the preceding glyph is correct if the
872 preceding glyph is a roman glyph. Use this escape sequence
873 whenever a roman glyph is immediately followed by an italic glyph
874 without any intervening space. In analogy to above, this space
875 could be called "left italic correction", but this term isn't used
880 Insert a zero-width character, which is invisible. Its intended
881 use is to stop interaction of a character with its surrounding.
883 * It prevents the insertion of extra space after an
884 end-of-sentence character.
894 * It prevents interpretation of a control character at the
895 beginning of an input line.
899 => warning: `Test' not defined
903 * It prevents kerning between two glyphs.
905 * It is needed to map an arbitrary character to nothing in the
906 `tr' request (*note Character Translations::).
909 This escape is similar to `\&' except that it behaves like a
910 character declared with the `cflags' request to be transparent for
911 the purposes of an end-of-sentence character.
913 Its main usage is in macro definitions to protect against arguments
914 starting with a control character.
926 =>This is a test.' This is a test.
930 =>This is a test.' This is a test.
934 File: groff, Node: Sizes, Next: Strings, Prev: Fonts, Up: gtroff Reference
939 `gtroff' uses two dimensions with each line of text, type size and
940 vertical spacing. The "type size" is approximately the height of the
941 tallest glyph.(1) (*note Sizes-Footnote-1::) "Vertical spacing" is the
942 amount of space `gtroff' allows for a line of text; normally, this is
943 about 20% larger than the current type size. Ratios smaller than this
944 can result in hard-to-read text; larger than this, it spreads the text
945 out more vertically (useful for term papers). By default, `gtroff'
946 uses 10 point type on 12 point spacing.
948 The difference between type size and vertical spacing is known, by
949 typesetters, as "leading" (this is pronounced `ledding').
953 * Changing Type Sizes::
954 * Fractional Type Sizes::
957 File: groff, Node: Sizes-Footnotes, Up: Sizes
959 (1) This is usually the parenthesis. Note that in most cases the
960 real dimensions of the glyphs in a font are _not_ related to its type
961 size! For example, the standard POSTSCRIPT font families `Times
962 Roman', `Helvetica', and `Courier' can't be used together at 10pt; to
963 get acceptable output, the size of `Helvetica' has to be reduced by one
964 point, and the size of `Courier' must be increased by one point.
967 File: groff, Node: Changing Type Sizes, Next: Fractional Type Sizes, Prev: Sizes, Up: Sizes
972 - Request: .ps [size]
977 Use the `ps' request or the `\s' escape to change (increase,
978 decrease) the type size (in points). Specify SIZE as either an
979 absolute point size, or as a relative change from the current size.
980 The size 0, or no argument, goes back to the previous size.
982 Default scaling indicator of `size' is `z'. If `size' is zero or
983 negative, it is set to 1u.
985 The read-only number register `.s' returns the point size in
986 points as a decimal fraction. This is a string. To get the point
987 size in scaled points, use the `.ps' register instead.
989 `.s' is associated with the current environment (*note
997 wink, wink, \s+2nudge, nudge,\s+8 say no more!
1000 The `\s' escape may be called in a variety of ways. Much like
1001 other escapes there must be a way to determine where the argument
1002 ends and the text begins. Any of the following forms are valid:
1005 Set the point size to N points. N must be either 0 or in the
1010 Increase or decrease the point size by N points. N must be
1014 Set the point size to NN points. NN must be exactly two
1021 Increase or decrease the point size by NN points. NN must be
1024 Note that `\s' doesn't produce an input token in `gtroff'. As a
1025 consequence, it can be used in requests like `mc' (which expects a
1026 single character as an argument) to change the font on the fly:
1031 *Note Fractional Type Sizes::, for yet another syntactical form of
1032 using the `\s' escape.
1034 - Request: .sizes s1 s2 ... sn [0]
1035 Some devices may only have certain permissible sizes, in which case
1036 `gtroff' rounds to the nearest permissible size. The `DESC' file
1037 specifies which sizes are permissible for the device.
1039 Use the `sizes' request to change the permissible sizes for the
1040 current output device. Arguments are in scaled points; the
1041 `sizescale' line in the `DESC' file for the output device provides
1042 the scaling factor. For example, if the scaling factor is 1000,
1043 then the value 12000 is 12 points.
1045 Each argument can be a single point size (such as `12000'), or a
1046 range of sizes (such as `4000-72000'). You can optionally end the
1049 - Request: .vs [space]
1050 - Request: .vs +space
1051 - Request: .vs -space
1053 Change (increase, decrease) the vertical spacing by SPACE. The
1054 default scaling indicator is `p'.
1056 If `vs' is called without an argument, the vertical spacing is
1057 reset to the previous value before the last call to `vs'.
1059 `gtroff' creates a warning of type `range' if SPACE is zero or
1060 negative; the vertical spacing is then set to the vertical
1061 resolution (as given in the `.V' register).
1063 The read-only number register `.v' contains the current vertical
1064 spacing; it is associated with the current environment (*note
1067 The effective vertical line spacing consists of four components.
1069 * The vertical line spacing as set with the `vs' request.
1071 * The "post-vertical line spacing" as set with the `pvs' request.
1072 This is vertical space which will be added after a line has been
1075 * The "extra pre-vertical line space" as set with the `\x' request,
1076 using a negative value. This is vertical space which will be
1077 added once before the current line has been output.
1079 * The "extra post-vertical line space" as set with the `\x' request,
1080 using a positive value. This is vertical space which will be
1081 added once after the current line has been output.
1083 It is usually better to use `vs' or `pvs' instead of `ls' to produce
1084 double-spaced documents: `vs' and `pvs' have a finer granularity for
1085 the inserted vertical space compared to `ls'; furthermore, certain
1086 preprocessors assume single-spacing.
1088 *Note Manipulating Spacing::, for more details on the `\x' escape
1089 and the `ls' request.
1091 - Request: .pvs [space]
1092 - Request: .pvs +space
1093 - Request: .pvs -space
1094 - Register: \n[.pvs]
1095 Change (increase, decrease) the post-vertical spacing by SPACE.
1096 The default scaling indicator is `p'.
1098 If `pvs' is called without an argument, the post-vertical spacing
1099 is reset to the previous value before the last call to `pvs'.
1101 `gtroff' creates a warning of type `range' if SPACE is zero or
1102 negative; the vertical spacing is then set to zero.
1104 The read-only number register `.pvs' contains the current
1105 post-vertical spacing; it is associated with the current
1106 environment (*note Environments::).
1109 File: groff, Node: Fractional Type Sizes, Prev: Changing Type Sizes, Up: Sizes
1111 Fractional Type Sizes
1112 ---------------------
1114 A "scaled point" is equal to 1/SIZESCALE points, where SIZESCALE is
1115 specified in the `DESC' file (1 by default). There is a new scale
1116 indicator `z' which has the effect of multiplying by SIZESCALE.
1117 Requests and escape sequences in `gtroff' interpret arguments that
1118 represent a point size as being in units of scaled points, but they
1119 evaluate each such argument using a default scale indicator of `z'.
1120 Arguments treated in this way are the argument to the `ps' request, the
1121 third argument to the `cs' request, the second and fourth arguments to
1122 the `tkf' request, the argument to the `\H' escape sequence, and those
1123 variants of the `\s' escape sequence that take a numeric expression as
1124 their argument (see below).
1126 For example, suppose SIZESCALE is 1000; then a scaled point is
1127 equivalent to a millipoint; the request `.ps 10.25' is equivalent to
1128 `.ps 10.25z' and thus sets the point size to 10250 scaled points, which
1129 is equal to 10.25 points.
1131 `gtroff' disallows the use of the `z' scale indicator in instances
1132 where it would make no sense, such as a numeric expression whose
1133 default scale indicator was neither `u' nor `z'. Similarly it would
1134 make no sense to use a scaling indicator other than `z' or `u' in a
1135 numeric expression whose default scale indicator was `z', and so
1136 `gtroff' disallows this as well.
1138 There is also new scale indicator `s' which multiplies by the number
1139 of units in a scaled point. So, for example, `\n[.ps]s' is equal to
1140 `1m'. Be sure not to confuse the `s' and `z' scale indicators.
1143 A read-only number register returning the point size in scaled
1146 `.ps' is associated with the current environment (*note
1149 - Register: \n[.psr]
1151 The last-requested point size in scaled points is contained in the
1152 `.psr' read-only number register. The last requested point size
1153 in points as a decimal fraction can be found in `.sr'. This is a
1154 string-valued read-only number register.
1156 Note that the requested point sizes are device-independent, whereas
1157 the values returned by the `.ps' and `.s' registers are not. For
1158 example, if a point size of 11pt is requested, and a `sizes'
1159 request (or a `sizescale' line in a `DESC' file) specifies 10.95pt
1160 instead, this value is actually used.
1162 Both registers are associated with the current environment (*note
1165 The `\s' escape has the following syntax for working with fractional
1170 Set the point size to N scaled points; N is a numeric expression
1171 with a default scale indicator of `z'.
1181 Increase or or decrease the point size by N scaled points; N is a
1182 numeric expression with a default scale indicator of `z'.