diff options
Diffstat (limited to 'contrib/groff/doc/groff.texinfo')
| -rw-r--r-- | contrib/groff/doc/groff.texinfo | 1998 |
1 files changed, 1404 insertions, 594 deletions
diff --git a/contrib/groff/doc/groff.texinfo b/contrib/groff/doc/groff.texinfo index 410a9d5..d3f9f63 100644 --- a/contrib/groff/doc/groff.texinfo +++ b/contrib/groff/doc/groff.texinfo @@ -1,10 +1,10 @@ \input texinfo @c -*-texinfo-*- @c -@c Please convert this manual with `texi2dvi -e groff.texinfo' due to a bug -@c in texinfo regarding expansion of user-defined macros. +@c Please convert this manual with `texi2dvi -e groff.texinfo' due to +@c problems in texinfo regarding expansion of user-defined macros. @c -@c You need texinfo 4.2 or newer to format this document! +@c You need texinfo 4.3 or newer to format this document! @c @c %**start of header (This is for running Texinfo on a region.) @@ -21,9 +21,10 @@ @copying -This manual documents GNU @code{troff} version 1.18. +This manual documents GNU @code{troff} version 1.19. -Copyright @copyright{} 1994-2000, 2001, 2002 Free Software Foundation, Inc. +Copyright @copyright{} 1994-2000, 2001, 2002, 2003 +Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -64,12 +65,12 @@ Software Foundation raise funds for GNU development.'' @syncodeindex tp cp -@c to avoid uppercasing in @deffn while converting to info, we define -@c our special @Var{} +@c To avoid uppercasing in @deffn while converting to info, we define +@c our special @Var{}. @c -@c due to a (not officially documented) `feature' in makeinfo 4.0, +@c Due to a (not officially documented) `feature' in makeinfo 4.0, @c macros are not expanded in @deffn (but the macro definition is -@c properly removed), so we have to define @Var{} directly in TeX also +@c properly removed), so we have to define @Var{} directly in TeX also. @macro Var{arg} \arg\ @@ -108,7 +109,7 @@ Software Foundation raise funds for GNU development.'' @c @c @endDef... @c -@c The above is valid for texinfo 4.0f. +@c The above is valid for texinfo 4.0f and above. @c a dummy macro to assure the `@def...' @@ -149,24 +150,24 @@ Software Foundation raise funds for GNU development.'' @c definition of escapes @macro Defesc{name, delimI, arg, delimII} -@deffn Escape @t{\name\\delimI\}@var{\arg\}@t{\delimII\} +@deffn Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\} @esindex \name\ @end macro @macro DefescList{name, delimI, arg, delimII} -@deffn Escape @t{\name\\delimI\}@var{\arg\}@t{\delimII\} +@deffn Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\} @defdummy @esindex \name\ @end macro @macro DefescItem{name, delimI, arg, delimII} -@deffnx Escape @t{\name\\delimI\}@var{\arg\}@t{\delimII\} +@deffnx Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\} @defdummy @esindex \name\ @end macro @macro DefescListEnd{name, delimI, arg, delimII} -@deffnx Escape @t{\name\\delimI\}@var{\arg\}@t{\delimII\} +@deffnx Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\} @esindex \name\ @end macro @@ -326,21 +327,10 @@ Software Foundation raise funds for GNU development.'' @end macro -@c due to a bug in texinfo 4.2, the spacing of `<' is bad in @item - -@tex -\gdef\LT{\string<} -@end tex - -@macro LT -< -@end macro - - @c We need special parentheses and brackets: @c @c . Real parentheses in @deffn produce an error while compiling with -@c TeX +@c TeX. @c . Real brackets use the wrong font in @deffn, overriding @t{}. @c @c Since macros aren't expanded in @deffn during -E, the following @@ -371,7 +361,7 @@ Software Foundation raise funds for GNU development.'' @c Note: We say `Roman numerals' but `roman font'. -@dircategory Miscellaneous +@dircategory Typesetting @direntry * Groff: (groff). The GNU troff document formatting system. @end direntry @@ -380,9 +370,9 @@ Software Foundation raise funds for GNU development.'' @titlepage @title groff @subtitle The GNU implementation of @code{troff} -@subtitle Edition 1.18 -@subtitle Spring 2002 -@author by Trent A.@w{ }Fisher +@subtitle Edition 1.19 +@subtitle Spring 2003 +@author by Trent A.@tie{}Fisher @author and Werner Lemberg (@email{bug-groff@@gnu.org}) @page @@ -441,7 +431,7 @@ Software Foundation raise funds for GNU development.'' GNU @code{troff} (or @code{groff}) is a system for typesetting documents. @code{troff} is very flexible and has been in existence (and -use) for about 3@w{ }decades. It is quite widespread and firmly +use) for about 3@tie{}decades. It is quite widespread and firmly entrenched in the @acronym{UNIX} community. @menu @@ -514,7 +504,7 @@ impossible to accomplish complex actions.'' --Doug Gwyn (22/Jun/91 in @cindex @code{runoff}, the program @cindex @code{rf}, the program @code{troff} can trace its origins back to a formatting program called -@code{runoff}, written by J.@w{ }E.@w{ }Saltzer, which ran on MIT's CTSS +@code{runoff}, written by J.@tie{}E.@tie{}Saltzer, which ran on MIT's CTSS operating system in the mid-sixties. This name came from the common phrase of the time ``I'll run off a document.'' Bob Morris ported it to the 635 architecture and called the program @code{roff} (an abbreviation @@ -530,7 +520,7 @@ was sitting around Bell Labs. In 1971 the developers wanted to get a justify the cost for this system, they proposed that they would implement a document formatting system for the @acronym{AT&T} patents division. This first formatting program was a reimplementation of -McIllroy's @code{roff}, written by J.@w{ }F.@w{ }Ossanna. +McIllroy's @code{roff}, written by J.@tie{}F.@tie{}Ossanna. @cindex @code{nroff}, the program When they needed a more flexible language, a new version of @code{roff} @@ -562,7 +552,7 @@ according to a bibliographic database. Unfortunately, Ossanna's @code{troff} was written in @w{PDP-11} assembly language and produced output specifically for the CAT phototypesetter. -He rewrote it in C, although it was now 7000@w{ }lines of uncommented +He rewrote it in C, although it was now 7000@tie{}lines of uncommented code and still dependent on the CAT. As the CAT became less common, and was no longer supported by the manufacturer, the need to make it support other devices became a priority. However, before this could be done, @@ -585,8 +575,8 @@ preprocessor did the same, although via a much different paradigm. The other preprocessors, produced @code{pic} code. James Clark began work on a GNU implementation of @code{ditroff} in -early@w{ }1989. The first version, @code{groff}@w{ }0.3.1, was released -June@w{ }1990. @code{groff} included: +early@tie{}1989. The first version, @code{groff}@tie{}0.3.1, was released +June@tie{}1990. @code{groff} included: @itemize @bullet @item @@ -597,7 +587,7 @@ The @code{soelim}, @code{pic}, @code{tbl}, and @code{eqn} preprocessors. @item Postprocessors for character devices, @sc{PostScript}, @TeX{} DVI, and -X@w{ }Windows. GNU @code{troff} also eliminated the need for a +X@tie{}Windows. GNU @code{troff} also eliminated the need for a separate @code{nroff} program with a postprocessor which would produce @acronym{ASCII} output. @@ -615,9 +605,9 @@ additions of a replacement for @code{refer}, an implementation of the document (@code{grog}). It was declared a stable (i.e.@: non-beta) package with the release of -version@w{ }1.04 around November@w{ }1991. +version@tie{}1.04 around November@tie{}1991. -Beginning in@w{ }1999, @code{groff} has new maintainers (the package was +Beginning in@tie{}1999, @code{groff} has new maintainers (the package was an orphan for a few years). As a result, new features and programs like @code{grn}, a preprocessor for gremlin images, and an output device to produce @acronym{HTML} output have been added. @@ -704,9 +694,9 @@ output and error messages Since @code{groff} provides such low-level facilities, it can be quite difficult to use by itself. However, @code{groff} provides a -@dfn{macro} facility to specify how certain routine operations (e.g.@w{ -}starting paragraphs, printing headers and footers, etc.)@: should be -done. These macros can be collected together into a @dfn{macro +@dfn{macro} facility to specify how certain routine operations +(e.g.@tie{}starting paragraphs, printing headers and footers, etc.)@: +should be done. These macros can be collected together into a @dfn{macro package}. There are a number of macro packages available; the most common (and the ones described in this manual) are @file{man}, @file{mdoc}, @file{me}, @file{ms}, and @file{mm}. @@ -759,8 +749,8 @@ mathematical pictures (@code{ideal}) and chemical structures @code{groff} actually produces device independent code which may be fed into a postprocessor to produce output for a particular device. Currently, @code{groff} has postprocessors for @sc{PostScript} -devices, character terminals, X@w{ }Windows (for previewing), @TeX{} -DVI format, HP LaserJet@w{ }4 and Canon LBP printers (which use +devices, character terminals, X@tie{}Windows (for previewing), @TeX{} +DVI format, HP LaserJet@tie{}4 and Canon LBP printers (which use @acronym{CAPSL}), and @acronym{HTML}. @@ -774,9 +764,9 @@ Large portions of this manual were taken from existing documents, most notably, the manual pages for the @code{groff} package by James Clark, and Eric Allman's papers on the @file{me} macro package. -The section on the @file{man} macro package is partly based on Susan@w{ -}G.@: Kleinmann's @file{groff_man} manual page written for the Debian -GNU/Linux system. +The section on the @file{man} macro package is partly based on +Susan@tie{}G.@: Kleinmann's @file{groff_man} manual page written for the +Debian GNU/Linux system. Larry Kollar contributed the section in the @file{ms} macro package. @@ -815,6 +805,7 @@ Similarly, we say @samp{gpic}, @samp{geqn}, etc. * Environment:: * Macro Directories:: * Font Directories:: +* Paper Size:: * Invocation Examples:: @end menu @@ -872,8 +863,8 @@ gtroff [ -abcivzCERU ] [ -w@var{name} ] [ -W@var{name} ] [ -d@var{cs} ] Obviously, many of the options to @code{groff} are actually passed on to @code{gtroff}. -Options without an argument can be grouped behind a single@w{ }@option{-}. -A filename of@w{ }@file{-} denotes the standard input. It is possible to +Options without an argument can be grouped behind a single@tie{}@option{-}. +A filename of@tie{}@file{-} denotes the standard input. It is possible to have whitespace between an option and its parameter. The @code{grog} command can be used to guess the correct @code{groff} @@ -977,29 +968,35 @@ For a 100@dmn{dpi} X11 previewer with a 12@dmn{pt} base font in the document. @item ascii -@cindex encoding, @acronym{ASCII} -@cindex @acronym{ASCII}, encoding +@cindex encoding, output, @acronym{ASCII} +@cindex @acronym{ASCII}, output encoding +@cindex output encoding, @acronym{ASCII} For typewriter-like devices using the (7-bit) @acronym{ASCII} character set. @item latin1 -@cindex encoding, latin-1 -@cindex latin-1, encoding -For typewriter-like devices that support the @w{Latin-1} (@w{ISO -8859-1}) character set. +@cindex encoding, output, @w{latin-1} (ISO @w{8859-1}) +@cindex @w{latin-1} (ISO @w{8859-1}), output encoding +@cindex ISO @w{8859-1} (@w{latin-1}), output encoding +@cindex output encoding, @w{latin-1} (ISO @w{8859-1}) +For typewriter-like devices that support the @w{Latin-1} +(ISO@tie{}@w{8859-1}) character set. @item utf8 -@cindex encoding, utf-8 -@cindex utf-8, encoding -For typewriter-like devices which use the Unicode (@w{ISO 10646}) +@cindex encoding, output, @w{utf-8} +@cindex @w{utf-8}, output encoding +@cindex output encoding, @w{utf-8} +For typewriter-like devices which use the Unicode (ISO@tie{}10646) character set with @w{UTF-8} encoding. @item cp1047 -@cindex @acronym{EBCDIC} encoding -@cindex encoding, @acronym{EBCDIC} -@cindex encoding, cp1047 -@cindex cp1047 -@cindex IBM cp1047 +@cindex encoding, output, @acronym{EBCDIC} +@cindex @acronym{EBCDIC}, output encoding +@cindex output encoding, @acronym{EBCDIC} +@cindex encoding, output, cp1047 +@cindex cp1047, output encoding +@cindex output encoding, cp1047 +@cindex IBM cp1047 output encoding For typewriter-like devices which use the @acronym{EBCDIC} encoding IBM cp1047. @@ -1023,7 +1020,7 @@ postprocessor (@code{post-grohtml}). @cindex output device usage number register (@code{.T}) The predefined @code{gtroff} string register @code{.T} contains the current output device; the read-only number register @code{.T} is set -to@w{ }1 if this option is used (which is always true if @code{groff} is +to@tie{}1 if this option is used (which is always true if @code{groff} is used to call @code{gtroff}). @xref{Built-in Registers}. The postprocessor to be used for a device is specified by the @@ -1065,7 +1062,7 @@ Unsafe mode. This enables the @code{open}, @code{opena}, @code{pso}, @item -a @cindex @acronym{ASCII} approximation output register (@code{.A}) Generate an @acronym{ASCII} approximation of the typeset output. The -read-only register @code{.A} is then set to@w{ }1. @xref{Built-in +read-only register @code{.A} is then set to@tie{}1. @xref{Built-in Registers}. A typical example is @Example @@ -1104,7 +1101,7 @@ list of incompatibilities between @code{groff} and @acronym{AT&T} @item -d@var{c}@var{s} @itemx -d@var{name}=@var{s} -Define @var{c} or @var{name} to be a string@w{ }@var{s}. @var{c}@w{ }must +Define @var{c} or @var{name} to be a string@tie{}@var{s}. @var{c}@tie{}must be a one-letter name; @var{name} can be of arbitrary length. All string assignments happen before loading any macro file (including the start-up file). @@ -1123,10 +1120,10 @@ Number the first page @var{num}. @item -o@var{list} @cindex print current page register (@code{.P}) Output only pages in @var{list}, which is a comma-separated list of page -ranges; @samp{@var{n}} means print page@w{ }@var{n}, @samp{@var{m}-@var{n}} -means print every page between @var{m} and@w{ }@var{n}, @samp{-@var{n}} -means print every page up to@w{ }@var{n}, @samp{@var{n}-} means print every -page beginning with@w{ }@var{n}. @code{gtroff} exits after printing the +ranges; @samp{@var{n}} means print page@tie{}@var{n}, @samp{@var{m}-@var{n}} +means print every page between @var{m} and@tie{}@var{n}, @samp{-@var{n}} +means print every page up to@tie{}@var{n}, @samp{@var{n}-} means print every +page beginning with@tie{}@var{n}. @code{gtroff} exits after printing the last page in the list. All the ranges are inclusive on both ends. Within @code{gtroff}, this information can be extracted with the @@ -1138,10 +1135,10 @@ chapter. @item -r@var{c}@var{n} @itemx -r@var{name}=@var{n} -Set number register@w{ }@var{c} or @var{name} to the value@w{ }@var{n}. -@var{c}@w{ }must be a one-letter name; @var{name} can be of arbitrary -length. @var{n}@w{ }can be any @code{gtroff} numeric expression. All -register assignments happen before loading any macro file (including +Set number register@tie{}@var{c} or @var{name} to the value@tie{}@var{n}. +@var{c}@tie{}must be a one-letter name; @var{name} can be of arbitrary +length. @var{n}@tie{}can be any @code{gtroff} numeric expression. All +register assignments happen before loading any macro file (including the start-up file). @item -F@var{dir} @@ -1176,7 +1173,7 @@ not within @code{gtroff}) which can modify the behavior of @code{groff}. @tindex GROFF_COMMAND_PREFIX@r{, environment variable} @cindex command prefix @cindex prefix, for commands -If this is set to@w{ }@var{X}, then @code{groff} runs @code{@var{X}troff} +If this is set to@tie{}@var{X}, then @code{groff} runs @code{@var{X}troff} instead of @code{gtroff}. This also applies to @code{tbl}, @code{pic}, @code{eqn}, @code{grn}, @code{refer}, and @code{soelim}. It does not apply to @code{grops}, @code{grodvi}, @code{grotty}, @code{pre-grohtml}, @@ -1284,11 +1281,11 @@ directory, and the main tmac directory; the default locations are @Example /usr/local/lib/groff/site-tmac /usr/local/share/groff/site-tmac -/usr/local/share/groff/1.18/tmac +/usr/local/share/groff/1.18.2/tmac @endExample @noindent -assuming that the version of @code{groff} is 1.18, and the installation +assuming that the version of @code{groff} is 1.18.2, and the installation prefix was @file{/usr/local}. It is possible to fine-tune those directories during the installation process. @end itemize @@ -1296,7 +1293,7 @@ directories during the installation process. @c ===================================================================== -@node Font Directories, Invocation Examples, Macro Directories, Invoking groff +@node Font Directories, Paper Size, Macro Directories, Invoking groff @section Font Directories @cindex font directories @cindex directories for fonts @@ -1342,11 +1339,11 @@ locations are @Example /usr/local/share/groff/site-font -/usr/local/share/groff/1.18/font +/usr/local/share/groff/1.18.2/font @endExample @noindent -assuming that the version of @code{groff} is 1.18, and the installation +assuming that the version of @code{groff} is 1.18.2, and the installation prefix was @file{/usr/local}. It is possible to fine-tune those directories during the installation process. @end itemize @@ -1354,7 +1351,49 @@ directories during the installation process. @c ===================================================================== -@node Invocation Examples, , Font Directories, Invoking groff +@node Paper Size, Invocation Examples, Font Directories, Invoking groff +@section Paper Size +@cindex paper size +@cindex size, paper +@cindex landscape page orientation +@cindex orientation, landscape +@cindex page orientation, landscape + +In groff, the page size for @code{gtroff} and for output devices are +handled separately. @xref{Page Layout}, for vertical manipulation of +the page size. @xref{Line Layout}, for horizontal changes. + +A default paper size can be set in the device's @file{DESC} file. Most +output devices also have a command line option @option{-p} to override +the default paper size and option @option{-l} to use landscape +orientation. @xref{DESC File Format}, for a description of the +@code{papersize} keyword which takes the same argument as @option{-p}. + +@pindex papersize.tmac +@pindex troffrc +A convenient shorthand to set a particular paper size for @code{gtroff} +is command line option @option{-dpaper=@var{size}}. This defines string +@code{paper} which is processed in file @file{papersize.tmac} (loaded in +the start-up file @file{troffrc} by default). Possible values for +@var{size} are the same as the predefined values for the +@code{papersize} keyword (but only in lowercase) except +@code{a7}-@code{d7}. An appended @samp{l} (ell) character denotes +landscape orientation. + +For example, use the following for PS output on A4 paper in landscape +orientation: + +@Example +groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps +@endExample + +Note that it is up to the particular macro package to respect default +page dimensions set in this way (most do). + + +@c ===================================================================== + +@node Invocation Examples, , Paper Size, Invoking groff @section Invocation Examples @cindex invocation examples @cindex examples of invocation @@ -1424,7 +1463,7 @@ generates one or more of the options @option{-e}, @option{-man}, @option{-mdoc-old}, @option{-p}, @option{-R}, @option{-g}, @option{-G}, @option{-s}, and @option{-t}. -A special file name@w{ }@file{-} refers to the standard input. Specifying +A special file name@tie{}@file{-} refers to the standard input. Specifying no files also means to read the standard input. Any specified options are included in the printed command. No space is allowed between options and their arguments. The only options recognized are @@ -1484,7 +1523,7 @@ macro package. This section covers some of the basic concepts necessary to understand how to use a macro package.@footnote{This section is derived from -@cite{Writing Papers with nroff using -me} by Eric P.@w{ }Allman.} +@cite{Writing Papers with nroff using -me} by Eric P.@tie{}Allman.} References are made throughout to more detailed information, if desired. @code{gtroff} reads an input file prepared by the user and outputs a @@ -1510,10 +1549,11 @@ spaces one line, but @endExample @noindent -spaces four lines. The number@w{ }4 is an argument to the @code{sp} +spaces four lines. The number@tie{}4 is an argument to the @code{sp} request which says to space four lines instead of one. Arguments are separated from the request and from each other by spaces (@emph{no} -tabs). More details on this can be found in @ref{Request Arguments}. +tabs). More details on this can be found in @ref{Request and Macro +Arguments}. The primary function of @code{gtroff} is to collect words from input lines, fill output lines with those words, justify the right-hand margin @@ -1598,10 +1638,10 @@ The @code{bp} request starts a new page, causing a line break. @cindex blank line (@code{sp}) @cindex empty line (@code{sp}) @cindex line, empty (@code{sp}) -The request @w{@samp{.sp @var{N}}} leaves @var{N}@w{ }lines of blank -space. @var{N}@w{ }can be omitted (meaning skip a single line) or can -be of the form @var{N}i (for @var{N}@w{ }inches) or @var{N}c (for -@var{N}@w{ }centimeters). For example, the input: +The request @w{@samp{.sp @var{N}}} leaves @var{N}@tie{}lines of blank +space. @var{N}@tie{}can be omitted (meaning skip a single line) or can +be of the form @var{N}i (for @var{N}@tie{}inches) or @var{N}c (for +@var{N}@tie{}centimeters). For example, the input: @Example .sp 1.5i @@ -1619,7 +1659,7 @@ measurement units are available, see @ref{Measurements}). Text lines can be centered by using the @code{ce} request. The line after @code{ce} is centered (horizontally) on the page. To center more than one line, use @w{@samp{.ce @var{N}}} (where @var{N} is the number -of lines to center), followed by the @var{N}@w{ }lines. To center many +of lines to center), followed by the @var{N}@tie{}lines. To center many lines without counting them, type: @Example @@ -1716,7 +1756,6 @@ A variation of this is a bulleted list. is used instead of a real bullet. @endExample - @c --------------------------------------------------------------------- @node Sections and Chapters, Headers and Footers, Paragraphs, Common Features @@ -1784,7 +1823,7 @@ not. @cindex keep, floating @cindex floating keep @dfn{Floating keeps} move relative to the text. Hence, they are good for -things which are referred to by name, such as ``See figure@w{ }3''. A +things which are referred to by name, such as ``See figure@tie{}3''. A floating keep appears at the bottom of the current page if it fits; otherwise, it appears at the top of the next page. Meanwhile, the surrounding text `flows' around the keep, thus leaving no blank areas. @@ -1883,7 +1922,7 @@ extend their functionality. For example, all macro packages mark tables (which are processed with @code{gtbl}) by placing them between @code{TS} and @code{TE} macros. -The @file{ms} macro package has an option, @samp{.TS@w{ }H}, that prints +The @file{ms} macro package has an option, @samp{.TS@tie{}H}, that prints a caption at the top of a new page (when the table is too long to fit on a single page). @@ -1909,6 +1948,20 @@ to changing the appearance of section headers. This chapter documents the main macro packages that come with @code{groff}. +Different main macro packages can't be used at the same time; for example + +@Example +groff -m man foo.man -m ms bar.doc +@endExample + +@noindent +doesn't work. Note that option arguments are processed before non-option +arguments; the above (failing) sample is thus reordered to + +@Example +groff -m man -m ms foo.man bar.doc +@endExample + @menu * man:: * mdoc:: @@ -1939,6 +1992,7 @@ are based on it. * Miscellaneous man macros:: * Predefined man strings:: * Preprocessors in man pages:: +* Optional man extensions:: @end menu @c --------------------------------------------------------------------- @@ -1950,25 +2004,16 @@ The command line format for using the @file{man} macros with @code{groff} is: @Example -groff -m man [ -rLL=@var{length} ] [ -rLT=@var{length} ] - [ -rcR=1 ] [ -rC1 ] [ -rD1 ] [ -rP@var{nnn} ] - [ -rS@var{xx} ] [ -rX@var{nnn} ] [ @var{files}@dots{} ] +groff -m man [ -rLL=@var{length} ] [ -rLT=@var{length} ] [ -rFT=@var{dist} ] + [ -rcR=1 ] [ -rC1 ] [ -rD1 ] [-rHY=@var{flags} ] + [ -rP@var{nnn} ] [ -rS@var{xx} ] [ -rX@var{nnn} ] + [ -rIN=@var{length} ] [ -rSN=@var{length} ] [ @var{files}@dots{} ] @endExample @noindent It is possible to use @samp{-man} instead of @w{@samp{-m man}}. @table @code -@item -rLL=@var{length} -Set line length to @var{length}. If not specified, the line length -defaults to 78@w{ }en in nroff mode (this is 78@w{ }characters per -line) and 6.5@w{ }inch otherwise. - -@item -rLT=@var{length} -Set title length to @var{length}. If not specified, the title length -defaults to 78@w{ }en in nroff mode (this is 78@w{ }characters per -line) and 6.5@w{ }inch otherwise. - @item -rcR=1 This option (the default if a TTY output device is used) creates a single, very long page instead of multiple pages. Use @code{-rcR=0} @@ -1976,18 +2021,50 @@ to disable it. @item -rC1 If more than one manual page is given on the command line, number the -pages continuously, rather than starting each at@w{ }1. +pages continuously, rather than starting each at@tie{}1. @item -rD1 Double-sided printing. Footers for even and odd pages are formatted differently. +@item -rFT=@var{dist} +Set the position of the footer text to @var{dist}. If positive, the +distance is measured relative to the top of the page, otherwise it is +relative to the bottom. The default is @minus{}0.5@dmn{i}. + +@item -rHY=@var{flags} +Set hyphenation flags. Possible values are 1@tie{}to hyphenate without +restrictions, 2@tie{} to not hyphenate the last word on a page, +4@tie{}to not hyphenate the last two characters of a word, and +8@tie{}to not hyphenate the first two characters of a word. These +values are additive; the default is@tie{}14. + +@item -rIN=@var{length} +Set the body text indent to @var{length}. +If not specified, the indent defaults to 7@dmn{n} +(7@tie{}characters) in nroff mode and 7.2@dmn{n} otherwise. +For nroff, this value should always be an integer multiple of unit @samp{n} +to get consistent indentation. + +@item -rLL=@var{length} +Set line length to @var{length}. If not specified, the line length +defaults to 78@tie{}en in nroff mode (this is 78@tie{}characters per +line) and 6.5@tie{}inch otherwise. + +@item -rLT=@var{length} +Set title length to @var{length}. If not specified, the title length +defaults to the line length. + @item -rP@var{nnn} -Page numbering starts with @var{nnn} rather than with@w{ }1. +Page numbering starts with @var{nnn} rather than with@tie{}1. @item -rS@var{xx} -Use @var{xx} (which can be 10, 11, or@w{ }12@dmn{pt}) as the base -document font size instead of the default value of@w{ }10@dmn{pt}. +Use @var{xx} (which can be 10, 11, or@tie{}12@dmn{pt}) as the base +document font size instead of the default value of@tie{}10@dmn{pt}. + +@item -rSN=@var{length} +Set the indent for sub-subheadings to @var{length}. +If not specified, the indent defaults to 3@dmn{n}. @item -rX@var{nnn} After page @var{nnn}, number pages as @var{nnn}a, @var{nnn}b, @@ -2010,7 +2087,7 @@ package. @Defmac {TH, title section [@Var{extra1} [@Var{extra2} [@Var{extra3}]]], man} Set the title of the man page to @var{title} and the section to -@var{section}, which must have a value between 1 and@w{ }8. The value +@var{section}, which must have a value between 1 and@tie{}8. The value of @var{section} may also have a string appended, e.g.@: @samp{.pm}, to indicate a specific subsection of the man pages. @@ -2024,7 +2101,7 @@ header line. For @acronym{HTML} output, headers and footers are completely suppressed. -Additionally, this macro starts a new page; the new line number is@w{ }1 +Additionally, this macro starts a new page; the new line number is@tie{}1 again (except if the @option{-rC1} option is given on the command line) -- this feature is intended only for formatting multiple man pages; a single man page should contain exactly one @code{TH} macro at the @@ -2035,30 +2112,34 @@ beginning of the file. Set up an unnumbered section heading sticking out to the left. Prints out all the text following @code{SH} up to the end of the line (or the text in the next line if there is no argument to @code{SH}) in bold -face, one size larger than the base document size. Additionally, the -left margin for the following text is reset to its default value. +face (or the font specified by the string @code{HF}), one size larger than +the base document size. Additionally, the left margin and the indentation +for the following text is reset to its default value. @endDefmac @Defmac {SS, [@Var{heading}], man} Set up an unnumbered (sub)section heading. Prints out all the text following @code{SS} up to the end of the line (or the text in the next -line if there is no argument to @code{SS}) in bold face, at the same -size as the base document size. Additionally, the left margin for the +line if there is no argument to @code{SS}) in bold face (or the font +specified by the string @code{HF}), at the same size as the base document +size. Additionally, the left margin and the indentation for the following text is reset to its default value. @endDefmac @Defmac {TP, [@Var{nnn}], man} Set up an indented paragraph with label. The indentation is set to @var{nnn} if that argument is supplied (the default unit is @samp{n} -if omitted), otherwise it is set to the default indentation value. +if omitted), otherwise it is set to the previous indentation value +specified with @code{TP}, @code{IP}, or @code{HP} (or to the default +value if none of them have been used yet). The first line of text following this macro is interpreted as a string to be printed flush-left, as it is appropriate for a label. It is not interpreted as part of a paragraph, so there is no attempt to fill the first line with text from the following input lines. Nevertheless, if -the label is not as wide as the indentation, then the paragraph starts +the label is not as wide as the indentation the paragraph starts at the same line (but indented), continuing on the following lines. -If the label is wider than the indentation, then the descriptive part +If the label is wider than the indentation the descriptive part of the paragraph begins on the line following the label, entirely indented. Note that neither font shape nor font size of the label is set to a default value; on the other hand, the rest of the text has @@ -2072,22 +2153,25 @@ These macros are mutual aliases. Any of them causes a line break at the current position, followed by a vertical space downwards by the amount specified by the @code{PD} macro. The font size and shape are reset to the default value (10@dmn{pt} roman if no @option{-rS} option -is given on the command line). Finally, the current left margin is -restored. +is given on the command line). Finally, the current left margin and the +indentation is restored. @endDefmac @Defmac {IP, [@Var{designator} [@Var{nnn}]], man} Set up an indented paragraph, using @var{designator} as a tag to mark its beginning. The indentation is set to @var{nnn} if that argument -is supplied (default unit is @samp{n}), otherwise the default -indentation value is used. Font size and face of the paragraph (but -not the designator) are reset to their default values. To start an -indented paragraph with a particular indentation but without a -designator, use @samp{""} (two double quotes) as the first argument of +is supplied (default unit is @samp{n}), otherwise it is set to the +previous indentation value specified with @code{TP}, @code{IP}, or +@code{HP} (or the default value if none of them have been used yet). +Font size and face of the paragraph (but not the designator) are reset +to their default values. + +To start an indented paragraph with a particular indentation but without +a designator, use @samp{""} (two double quotes) as the first argument of @code{IP}. For example, to start a paragraph with bullets as the designator and -4@w{ }en indentation, write +4@tie{}en indentation, write @Example .IP \(bu 4 @@ -2099,23 +2183,29 @@ For example, to start a paragraph with bullets as the designator and @cindex @code{man} macros, hanging indentation Set up a paragraph with hanging left indentation. The indentation is set to @var{nnn} if that argument is supplied (default unit is -@samp{n}), otherwise the default indentation value is used. Font size -and face are reset to their default values. +@samp{n}), otherwise it is set to the previous indentation value +specified with @code{TP}, @code{IP}, or @code{HP} (or the default +value if non of them have been used yet). Font size and face are reset +to their default values. @endDefmac @Defmac {RS, [@Var{nnn}], man} @cindex left margin, how to move [@code{man}] @cindex @code{man} macros, moving left margin Move the left margin to the right by the value @var{nnn} if specified -(default unit is @samp{n}); otherwise the default indentation value -is used. Calls to the @code{RS} macro can be nested. +(default unit is @samp{n}); otherwise it is set to the previous +indentation value specified with @code{TP}, @code{IP}, or @code{HP} +(or to the default value if none of them have been used yet). The +indentation value is then set to the default. + +Calls to the @code{RS} macro can be nested. @endDefmac @Defmac {RE, [@Var{nnn}], man} -Move the left margin back to level @var{nnn}; if no argument is given, -it moves one level back. The first level (i.e., no call to @code{RS} -yet) has number@w{ }1, and each call to @code{RS} increases the level -by@w{ }1. +Move the left margin back to level @var{nnn}, restoring the previous left +margin. If no argument is given, it moves one level back. The first +level (i.e., no call to @code{RS} yet) has number@tie{}1, and each call +to @code{RS} increases the level by@tie{}1. @endDefmac @cindex line breaks, with vertical space [@code{man}] @@ -2143,7 +2233,7 @@ and @code{RS} reset the indentation to its default value. @cindex font selection [@code{man}] @cindex @code{man} macros, how to set fonts -The standard font is roman; the default text size is 10@w{ }point. +The standard font is roman; the default text size is 10@tie{}point. If command line option @option{-rS=@var{n}} is given, use @var{n}@dmn{pt} as the default text size. @@ -2160,35 +2250,41 @@ font, one point size smaller than the default font. @endDefmac @Defmac {BI, text, man} -Set its arguments alternately in bold face and italic. Thus, +Set its arguments alternately in bold face and italic, without a space +between the arguments. Thus, @Example .BI this "word and" that @endExample @noindent -would set ``this'' and ``that'' in bold face, and ``word and'' in -italics. +produces ``thisword andthat'' with ``this'' and ``that'' in bold face, +and ``word and'' in italics. @endDefmac @Defmac {IB, text, man} -Set its arguments alternately in italic and bold face. +Set its arguments alternately in italic and bold face, without a space +between the arguments. @endDefmac @Defmac {RI, text, man} -Set its arguments alternately in roman and italic. +Set its arguments alternately in roman and italic, without a space between +the arguments. @endDefmac @Defmac {IR, text, man} -Set its arguments alternately in italic and roman. +Set its arguments alternately in italic and roman, without a space between +the arguments. @endDefmac @Defmac {BR, text, man} -Set its arguments alternately in bold face and roman. +Set its arguments alternately in bold face and roman, without a space +between the arguments. @endDefmac @Defmac {RB, text, man} -Set its arguments alternately in roman and bold face. +Set its arguments alternately in roman and bold face, without a space +between the arguments. @endDefmac @Defmac {B, [@Var{text}], man} @@ -2212,13 +2308,13 @@ macro is called, then the text of the next line appears in italic. @pindex grohtml @cindex @code{man} macros, default indentation @cindex default indentation [@code{man}] -The default indentation is 7.2@w{ }en for all output devices except for -@code{grohtml} which ignores indentation. +The default indentation is 7.2@dmn{n} in troff mode and 7@dmn{n} in +nroff mode except for @code{grohtml} which ignores indentation. @Defmac {DT, , man} @cindex tab stops [@code{man}] @cindex @code{man} macros, tab stops -Set tabs every 0.5@w{ }inches. Since this macro is always executed +Set tabs every 0.5@tie{}inches. Since this macro is always executed during a call to the @code{TH} macro, it makes sense to call it only if the tab positions have been changed. @endDefmac @@ -2229,11 +2325,59 @@ the tab positions have been changed. Adjust the empty space before a new paragraph (or section). The optional argument gives the amount of space (default unit is @samp{v}); without parameter, the value is reset to its default value -(1@w{ }line for TTY devices, 0.4@dmn{v}@w{ }otherwise). -@endDefmac +(1@tie{}line in nroff mode, 0.4@dmn{v}@tie{}otherwise). This affects the macros @code{SH}, @code{SS}, @code{TP}, @code{LP} (as well as @code{PP} and @code{P}), @code{IP}, and @code{HP}. +@endDefmac + +The following two macros are included for +BSD compatibility. + +@Defmac {AT, [@Var{system} [@Var{release}]], man} +@cindex @code{man}macros, BSD compatibility +Alter the footer for use with @acronym{AT&T} manpages. +This command exists only for compatibility; don't use it. +The first argument @var{system} can be: + +@table @code +@item 3 +7th Edition (the default) + +@item 4 +System III + +@item 5 +System V +@end table + +An optional second argument @var{release} to @code{AT} specifies the +release number (such as ``System V Release 3''). +@endDefmac + +@Defmac {UC, [@Var{version}], man} +@cindex @code{man}macros, BSD compatibility +Alters the footer for use with @acronym{BSD} manpages. +This command exists only for compatibility; don't use it. +The argument can be: + +@table @code +@item 3 +3rd Berkeley Distribution (the default) + +@item 4 +4th Berkeley Distribution + +@item 5 +4.2 Berkeley Distribution + +@item 6 +4.3 Berkeley Distribution + +@item 7 +4.4 Berkeley Distribution +@end table +@endDefmac @c --------------------------------------------------------------------- @@ -2246,6 +2390,11 @@ The following strings are defined: Switch back to the default font size. @endDefstr +@Defstr {HF, man} +The typeface used for headings. +The default is @samp{B}. +@endDefstr + @Defstr {R, man} The `registered' sign. @endDefstr @@ -2264,7 +2413,7 @@ respectively. @c --------------------------------------------------------------------- -@node Preprocessors in man pages, , Predefined man strings, man +@node Preprocessors in man pages, Optional man extensions, Predefined man strings, man @subsection Preprocessors in @file{man} pages @cindex preprocessor, calling convention @@ -2288,6 +2437,173 @@ consists of letters for the needed preprocessors: @samp{e} for Modern implementations of the @code{man} program read this first line and automatically call the right preprocessor(s). +@c --------------------------------------------------------------------- + +@node Optional man extensions, , Preprocessors in man pages, man +@subsection Optional @file{man} extensions + +@pindex man.local +Use the file @file{man.local} for local extensions +to the @code{man} macros or for style changes. + +@unnumberedsubsubsec Custom headers and footers +@cindex @code{man} macros, custom headers and footers + +In groff versions 1.18.2 and later, you can specify custom +headers and footers by redefining the following macros in +@file{man.local}. + +@Defmac {PT, , man} +Control the content of the headers. +Normally, the header prints the command name +and section number on either side, and the +optional fifth argument to @code{TH} in the center. +@endDefmac + +@Defmac {BT, , man} +Control the content of the footers. +Normally, the footer prints the page number +and the third and fourth arguments to @code{TH}. + +Use the @code{FT} number register to specify the +footer position. +The default is @minus{}0.5@dmn{i}. +@endDefmac + +@unnumberedsubsubsec Ultrix-specific man macros +@cindex Ultrix-specific @code{man} macros +@cindex @code{man} macros, Ultrix-specific + +@pindex man.ultrix +The @code{groff} source distribution includes +a file named @file{man.ultrix}, containing +macros compatible with the Ultrix variant of +@code{man}. +Copy this file into @file{man.local} (or use the @code{mso} request to +load it) to enable the following macros. + +@Defmac {CT, @Var{key}, man} +Print @samp{<CTRL/@var{key}>}. +@endDefmac + +@Defmac {CW, , man} +Print subsequent text using the constant width (Courier) typeface. +@endDefmac + +@Defmac {Ds, , man} +Begin a non-filled display. +@endDefmac + +@Defmac {De, , man} +End a non-filled display started with @code{Ds}. +@endDefmac + +@Defmac {EX, [@Var{indent}], man} +Begins a non-filled display +using the constant width (Courier) typeface. +Use the optional @var{indent} argument to +indent the display. +@endDefmac + +@Defmac {EE, , man} +End a non-filled display started with @code{EX}. +@endDefmac + +@Defmac {G, [@Var{text}], man} +Sets @var{text} in Helvetica. +If no text is present on the line where +the macro is called, then the text of the +next line appears in Helvetica. +@endDefmac + +@Defmac {GL, [@Var{text}], man} +Sets @var{text} in Helvetica Oblique. +If no text is present on the line where +the macro is called, then the text of the +next line appears in Helvetica Oblique. +@endDefmac + +@Defmac {HB, [@Var{text}], man} +Sets @var{text} in Helvetica Bold. +If no text is present on the line where +the macro is called, then all text up to +the next @code{HB} appears in Helvetica Bold. +@endDefmac + +@Defmac {TB, [@Var{text}], man} +Identical to @code{HB}. +@endDefmac + +@Defmac {MS, @Var{title} @Var{sect} [@Var{punct}], man} +Set a manpage reference in Ultrix format. +The @var{title} is in Courier instead of italic. +Optional punctuation follows the section number without +an intervening space. +@endDefmac + +@Defmac {NT, [@code{C}] [@Var{title}], man} +Begin a note. +Print the optional @Var{title}, or the word ``Note'', +centered on the page. +Text following the macro makes up the body of the note, +and is indented on both sides. +If the first argument is @code{C}, the body of the +note is printed centered (the second argument replaces +the word ``Note'' if specified). +@endDefmac + +@Defmac {NE, , man} +End a note begun with @code{NT}. +@endDefmac + +@Defmac {PN, @Var{path} [@Var{punct}], man} +Set the path name in constant width (Courier), +followed by optional punctuation. +@endDefmac + +@Defmac {Pn, [@Var{punct}] @Var{path} [@Var{punct}], man} +When called with two arguments, identical to @code{PN}. +When called with three arguments, +set the second argument in constant width (Courier), +bracketed by the first and third arguments in the current font. +@endDefmac + +@Defmac {R, , man} +Switch to roman font and turn off any underlining in effect. +@endDefmac + +@Defmac {RN, , man} +Print the string @samp{<RETURN>}. +@endDefmac + +@Defmac {VS, [@code{4}], man} +Start printing a change bar in the margin if +the number @code{4} is specified. +Otherwise, this macro does nothing. +@endDefmac + +@Defmac {VE, , man} +End printing the change bar begun by @code{VS}. +@endDefmac + +@unnumberedsubsubsec Simple example + +The following example @file{man.local} file +alters the @code{SH} macro to add some extra +vertical space before printing the heading. +Headings are printed in Helvetica Bold. + +@Example +.\" Make the heading fonts Helvetica +.ds HF HB +. +.\" Put more whitespace in front of headings. +.rn SH SH-orig +.de SH +. if t .sp (u;\\n[PD]*2) +. SH-orig \\$* +.. +@endExample @c ===================================================================== @@ -2780,7 +3096,7 @@ The following describes the heading macros: @DefmacListEnd {NH, @t{S} @Var{level0} @dots{}, ms} Numbered heading. The argument is either a numeric argument to indicate the -level of the heading, or the letter@w{ }@code{S} followed by numeric +level of the heading, or the letter@tie{}@code{S} followed by numeric arguments to set the heading level explicitly. If you specify heading levels out of sequence, such as invoking @@ -2824,22 +3140,22 @@ the next highlighting, paragraph, or heading macro. @Defmac {R, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} Sets its first argument in roman (or regular) type. -It operates similarly to the @code{B}@w{ }macro otherwise. +It operates similarly to the @code{B}@tie{}macro otherwise. @endDefmac @Defmac {I, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} Sets its first argument in @emph{italic type}. -It operates similarly to the @code{B}@w{ }macro otherwise. +It operates similarly to the @code{B}@tie{}macro otherwise. @endDefmac @Defmac {CW, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} Sets its first argument in a @code{constant width face}. -It operates similarly to the @code{B}@w{ }macro otherwise. +It operates similarly to the @code{B}@tie{}macro otherwise. @endDefmac @Defmac {BI, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} Sets its first argument in bold italic type. -It operates similarly to the @code{B}@w{ }macro otherwise. +It operates similarly to the @code{B}@tie{}macro otherwise. @endDefmac @Defmac {BX, [@Var{txt}], ms} @@ -3242,7 +3558,7 @@ in pairs of tags as follows. @DefmacList {TS, [@code{H}], ms} @DefmacListEnd {TE, , ms} Denotes a table, to be processed by the @code{tbl} preprocessor. -The optional argument@w{ }@code{H} to @code{TS} instructs @code{groff} +The optional argument@tie{}@code{H} to @code{TS} instructs @code{groff} to create a running header with the information up to the @code{TH} macro. @code{groff} prints the header at the beginning of the @@ -3261,8 +3577,9 @@ a graphics program such as @code{xfig}. @DefmacList {EQ, [@Var{align}], ms} @DefmacListEnd {EN, , ms} Denotes an equation, to be processed by the @code{eqn} preprocessor. -The optional @var{align} argument can be @code{C}, @code{L}, or@w{ -}@code{I} to center (the default), left-justify, or indent the equation. +The optional @var{align} argument can be @code{C}, @code{L}, +or@tie{}@code{I} to center (the default), left-justify, or indent the +equation. @endDefmac @DefmacList {[, , ms} @@ -3475,7 +3792,7 @@ Introduction .NH 2 Methodology .XS - Methodology +Methodology .XE .LP ... @@ -3505,7 +3822,7 @@ Details of Galactic Formation @Defmac {TC, [@code{no}], ms} Prints the table of contents on a new page, -setting the page number to@w{ }@strong{i} (Roman numeral one). +setting the page number to@tie{}@strong{i} (Roman numeral one). You should usually place this macro at the end of the file, since @code{groff} is a single-pass formatter and can only print what has been collected up to the point @@ -3632,7 +3949,7 @@ Tilde. @stindex : @r{[}ms@r{]} @end ifnotinfo @ifinfo -@stindex @r{<colon>} @r{[}ms@r{]} +@stindex \*[@r{<colon>}] @r{[}ms@r{]} @end ifinfo Umlaut. @end deffn @@ -3839,7 +4156,6 @@ Users of macro packages may skip it if not interested in details. @menu * Text:: -* Input Conventions:: * Measurements:: * Expressions:: * Identifiers:: @@ -3855,7 +4171,7 @@ Users of macro packages may skip it if not interested in details. * Line Control:: * Page Layout:: * Page Control:: -* Fonts:: +* Fonts and Symbols:: * Sizes:: * Strings:: * Conditionals and Loops:: @@ -3878,7 +4194,7 @@ Users of macro packages may skip it if not interested in details. @c ===================================================================== -@node Text, Input Conventions, gtroff Reference, gtroff Reference +@node Text, Measurements, gtroff Reference, gtroff Reference @section Text @cindex text, @code{gtroff} processing @@ -3906,6 +4222,8 @@ inserting implicit line breaks * Sentences:: * Tab Stops:: * Implicit Line Breaks:: +* Input Conventions:: +* Input Encodings:: @end menu @c --------------------------------------------------------------------- @@ -4036,7 +4354,7 @@ produces @c --------------------------------------------------------------------- -@node Implicit Line Breaks, , Tab Stops, Text +@node Implicit Line Breaks, Input Conventions, Tab Stops, Text @subsection Implicit Line Breaks @cindex implicit line breaks @cindex implicit breaks of lines @@ -4071,11 +4389,10 @@ the document may vanish! Certain requests also cause breaks, implicitly or explicitly. This is discussed in @ref{Manipulating Filling and Adjusting}. +@c --------------------------------------------------------------------- -@c ===================================================================== - -@node Input Conventions, Measurements, Text, gtroff Reference -@section Input Conventions +@node Input Conventions, Input Encodings, Implicit Line Breaks, Text +@subsection Input Conventions @cindex input conventions @cindex conventions for input @@ -4091,7 +4408,7 @@ and in other logical places. Keep separate phrases on lines by themselves, as entire phrases are often added or deleted when editing. @item -Try to keep lines less than 40-60@w{ }characters, to allow space for +Try to keep lines less than 40-60@tie{}characters, to allow space for inserting more text. @item @@ -4099,10 +4416,90 @@ Do not try to do any formatting in a @acronym{WYSIWYG} manner (i.e., don't try using spaces to get proper indentation). @end itemize +@c --------------------------------------------------------------------- + +@node Input Encodings, , Input Conventions, Text +@subsection Input Encodings + +Currently, the following input encodings are available. + +@table @asis +@item cp1047 +@cindex encoding, input, @acronym{EBCDIC} +@cindex @acronym{EBCDIC}, input encoding +@cindex input encoding, @acronym{EBCDIC} +@cindex encoding, input, cp1047 +@cindex cp1047, input encoding +@cindex input encoding, cp1047 +@cindex IBM cp1047 input encoding +@pindex cp1047.tmac +This input encoding works only on @acronym{EBCDIC} platforms (and vice +versa, the other input encodings don't work with @acronym{EBCDIC}); the +file @file{cp1047.tmac} is by default loaded at start-up. + +@item latin-1 +@cindex encoding, input, @w{latin-1} (ISO @w{8859-1}) +@cindex @w{latin-1} (ISO @w{8859-1}), input encoding +@cindex ISO @w{8859-1} (@w{latin-1}), input encoding +@cindex input encoding, @w{latin-1} (ISO @w{8859-1}) +@pindex latin1.tmac +This is the default input encoding on non-@acronym{EBCDIC} platforms; +the file @file{latin1.tmac} is loaded at start-up. + +@item latin-2 +@cindex encoding, input, @w{latin-2} (ISO @w{8859-2}) +@cindex @w{latin-2} (ISO @w{8859-2}), input encoding +@cindex ISO @w{8859-2} (@w{latin-2}), input encoding +@cindex input encoding, @w{latin-2} (ISO @w{8859-2}) +@pindex latin2.tmac +To use this encoding, either say @w{@samp{.mso latin2.tmac}} at the very +beginning of your document or use @samp{-mlatin2} as a command line +argument for @code{groff}. + +@item latin-9 (latin-0) +@cindex encoding, input, @w{latin-9} (@w{latin-0}, ISO @w{8859-15}) +@cindex @w{latin-9} (@w{latin-0}, ISO @w{8859-15}), input encoding +@cindex ISO @w{8859-15} (@w{latin-9}, @w{latin-0}), input encoding +@cindex input encoding, @w{latin-9} (@w{latin-9}, ISO @w{8859-15}) +@pindex latin9.tmac +This encoding is intended (at least in Europe) to replace @w{latin-1} +encoding. The main difference to @w{latin-1} is that @w{latin-9} +contains the Euro character. To use this encoding, either say +@w{@samp{.mso latin9.tmac}} at the very beginning of your document or +use @samp{-mlatin9} as a command line argument for @code{groff}. +@end table + +Note that it can happen that some input encoding characters are not +available for a particular output device. For example, saying + +@Example +groff -Tlatin1 -mlatin9 ... +@endExample + +@noindent +will fail if you use the Euro character in the input. Usually, this +limitation is present only for devices which have a limited set of +output glyphs (e.g.@: @option{-Tascii} and @option{-Tlatin1}); for other +devices it is usually sufficient to install proper fonts which contain +the necessary glyphs. + +@pindex freeeuro.pfa +@pindex ec.tmac +Due to the importance of the Euro glyph in Europe, the groff package now +comes with a @sc{PostScript} font called @file{freeeuro.pfa} which +provides various glyph shapes for the Euro. With other words, +@w{latin-9} encoding is supported for the @option{-Tps} device out of +the box (@w{latin-2} isn't). + +By its very nature, @option{-Tutf8} supports all input encodings; +@option{-Tdvi} has support for both @w{latin-2} and @w{latin-9} if the +command line @option{-mec} is used also to load the file @file{ec.tmac} +(which flips to the EC fonts). + @c ===================================================================== -@node Measurements, Expressions, Input Conventions, gtroff Reference +@node Measurements, Expressions, Text, gtroff Reference @section Measurements @cindex measurements @@ -4135,27 +4532,27 @@ current settings (e.g.@: type size) of @code{gtroff}. @cindex unit, @code{i} Inches. An antiquated measurement unit still in use in certain backwards countries with incredibly low-cost computer equipment. One -inch is equal to@w{ }2.54@dmn{cm}. +inch is equal to@tie{}2.54@dmn{cm}. @item c @cindex centimeter unit (@code{c}) @cindex @code{c} unit @cindex unit, @code{c} -Centimeters. One centimeter is equal to@w{ }0.3937@dmn{in}. +Centimeters. One centimeter is equal to@tie{}0.3937@dmn{in}. @item p @cindex point unit (@code{p}) @cindex @code{p} unit @cindex unit, @code{p} Points. This is a typesetter's measurement used for measure type size. -It is 72@w{ }points to an inch. +It is 72@tie{}points to an inch. @item P @cindex pica unit (@code{P}) @cindex @code{P} unit @cindex unit, @code{P} -Pica. Another typesetting measurement. 6@w{ }Picas to an inch (and -12@w{ }points to a pica). +Pica. Another typesetting measurement. 6@tie{}Picas to an inch (and +12@tie{}points to a pica). @item s @itemx z @@ -4183,7 +4580,7 @@ text. @cindex @code{m} unit @cindex unit, @code{m} Ems. This unit is equal to the current font size in points. So called -because it is @emph{approximately} the width of the letter@w{ }@samp{m} +because it is @emph{approximately} the width of the letter@tie{}@samp{m} in the current font. @item n @@ -4220,7 +4617,7 @@ Vertical space. This is equivalent to the current line spacing. Many requests take a default unit. While this can be helpful at times, it can cause strange errors in some expressions. For example, the line length request expects em units. Here are several attempts to get a -line length of 3.5@w{ }inches and their results: +line length of 3.5@tie{}inches and their results: @Example 3.5i @result{} 3.5i @@ -4233,9 +4630,9 @@ line length of 3.5@w{ }inches and their results: @noindent Everything is converted to basic units first. In the above example it -is assumed that 1@dmn{i} equals@w{ }240@dmn{u}, and 1@dmn{m} equals@w{ -}10@dmn{p} (thus 1@dmn{m} equals@w{ }33@dmn{u}). The value 7@dmn{i}/2 -is first handled as 7@dmn{i}/2@dmn{m}, then converted to +is assumed that 1@dmn{i} equals@tie{}240@dmn{u}, and 1@dmn{m} +equals@tie{}10@dmn{p} (thus 1@dmn{m} equals@tie{}33@dmn{u}). The value +7@dmn{i}/2 is first handled as 7@dmn{i}/2@dmn{m}, then converted to 1680@dmn{u}/66@dmn{u} which is 25@dmn{u}, and this is approximately 0.1@dmn{i}. As can be seen, a scaling indicator after a closing parenthesis is simply ignored. @@ -4324,14 +4721,14 @@ Example: @endExample @noindent -The register@w{ }@code{z} now contains@w{ }5. +The register@tie{}@code{z} now contains@tie{}5. @item @cindex scaling operator @cindex operator, scaling -Scaling: @code{(@var{c};@var{e})}. Evaluate@w{ }@var{e} using@w{ }@var{c} +Scaling: @code{(@var{c};@var{e})}. Evaluate@tie{}@var{e} using@tie{}@var{c} as the default scaling indicator. If @var{c} is missing, ignore scaling -indicators in the evaluation of@w{ }@var{e}. +indicators in the evaluation of@tie{}@var{e}. @end itemize @cindex parentheses @@ -4363,22 +4760,22 @@ For vertical movements, it specifies the distance from the top of the page; for horizontal movements, it gives the distance from the beginning of the @emph{input} line. -@cindex @code{bp} request, using @code{+} and@w{ }@code{-} -@cindex @code{in} request, using @code{+} and@w{ }@code{-} -@cindex @code{ll} request, using @code{+} and@w{ }@code{-} -@cindex @code{lt} request, using @code{+} and@w{ }@code{-} -@cindex @code{nm} request, using @code{+} and@w{ }@code{-} -@cindex @code{nr} request, using @code{+} and@w{ }@code{-} -@cindex @code{pl} request, using @code{+} and@w{ }@code{-} -@cindex @code{pn} request, using @code{+} and@w{ }@code{-} -@cindex @code{po} request, using @code{+} and@w{ }@code{-} -@cindex @code{ps} request, using @code{+} and@w{ }@code{-} -@cindex @code{pvs} request, using @code{+} and@w{ }@code{-} -@cindex @code{rt} request, using @code{+} and@w{ }@code{-} -@cindex @code{ti} request, using @code{+} and@w{ }@code{-} -@cindex @code{\H}, using @code{+} and@w{ }@code{-} -@cindex @code{\R}, using @code{+} and@w{ }@code{-} -@cindex @code{\s}, using @code{+} and@w{ }@code{-} +@cindex @code{bp} request, using @code{+} and@tie{}@code{-} +@cindex @code{in} request, using @code{+} and@tie{}@code{-} +@cindex @code{ll} request, using @code{+} and@tie{}@code{-} +@cindex @code{lt} request, using @code{+} and@tie{}@code{-} +@cindex @code{nm} request, using @code{+} and@tie{}@code{-} +@cindex @code{nr} request, using @code{+} and@tie{}@code{-} +@cindex @code{pl} request, using @code{+} and@tie{}@code{-} +@cindex @code{pn} request, using @code{+} and@tie{}@code{-} +@cindex @code{po} request, using @code{+} and@tie{}@code{-} +@cindex @code{ps} request, using @code{+} and@tie{}@code{-} +@cindex @code{pvs} request, using @code{+} and@tie{}@code{-} +@cindex @code{rt} request, using @code{+} and@tie{}@code{-} +@cindex @code{ti} request, using @code{+} and@tie{}@code{-} +@cindex @code{\H}, using @code{+} and@tie{}@code{-} +@cindex @code{\R}, using @code{+} and@tie{}@code{-} +@cindex @code{\s}, using @code{+} and@tie{}@code{-} @samp{+} and @samp{-} are also treated differently by the following requests and escapes: @code{bp}, @code{in}, @code{ll}, @code{lt}, @code{nm}, @code{nr}, @code{pl}, @code{pn}, @code{po}, @code{ps}, @@ -4390,8 +4787,8 @@ Here, leading plus and minus signs indicate increments and decrements. @Defesc {\\B, ', anything, '} @cindex numeric expression, valid @cindex valid numeric expression -Return@w{ }1 if @var{anything} is a valid numeric expression; -or@w{ }0 if @var{anything} is empty or not a valid numeric expression. +Return@tie{}1 if @var{anything} is a valid numeric expression; +or@tie{}0 if @var{anything} is empty or not a valid numeric expression. @endDefesc @cindex space characters, in expressions @@ -4399,7 +4796,7 @@ or@w{ }0 if @var{anything} is empty or not a valid numeric expression. Due to the way arguments are parsed, spaces are not allowed in expressions, unless the entire expression is surrounded by parentheses. -@xref{Request Arguments}, and @ref{Conditionals and Loops}. +@xref{Request and Macro Arguments}, and @ref{Conditionals and Loops}. @c ===================================================================== @@ -4424,8 +4821,8 @@ Whitespace characters (spaces, tabs, and newlines). @cindex character, backspace @cindex backspace character @cindex @acronym{EBCDIC} encoding of backspace -Backspace (@acronym{ASCII}@w{ }@code{0x08} or @acronym{EBCDIC}@w{ -}@code{0x16}) and character code @code{0x01}. +Backspace (@acronym{ASCII}@tie{}@code{0x08} or +@acronym{EBCDIC}@tie{}@code{0x16}) and character code @code{0x01}. @item @cindex invalid input characters @@ -4482,10 +4879,10 @@ a special argument to @code{refer}. For example, @samp{.[foo} makes @Defesc {\\A, ', ident, '} Test whether an identifier @var{ident} is valid in @code{gtroff}. It -expands to the character@w{ }1 or@w{ }0 according to whether its +expands to the character@tie{}1 or@tie{}0 according to whether its argument (usually delimited by quotes) is or is not acceptable as the name of a string, macro, diversion, number register, environment, or -font. It returns@w{ }0 if no argument is given. This is useful for +font. It returns@tie{}0 if no argument is given. This is useful for looking up user input in some sort of associative table. @Example @@ -4512,7 +4909,7 @@ Two characters. Must be prefixed with @samp{(} in some situations. @cindex @code{]}, ending an identifier @item Arbitrary length (@code{gtroff} only). Must be bracketed with @samp{[} -and@w{ }@samp{]} in some situations. Any length identifier can be put +and@tie{}@samp{]} in some situations. Any length identifier can be put in brackets. @end itemize @@ -4530,7 +4927,7 @@ If the identifier is a string, macro, or diversion, @item If the identifier is a number register, @code{gtroff} -defines it with a value of@w{ }0. +defines it with a value of@tie{}0. @end itemize @xref{Warnings}., @ref{Interpolating Registers}, and @ref{Strings}. @@ -4659,23 +5056,27 @@ requests cause a break implicitly; using the single quote control character prevents this. @menu -* Request Arguments:: +* Request and Macro Arguments:: @end menu -@node Request Arguments, , Requests, Requests -@subsubsection Request Arguments +@node Request and Macro Arguments, , Requests, Requests +@subsubsection Request and Macro Arguments @cindex request arguments -@cindex arguments to requests +@cindex macro arguments +@cindex arguments to requests and macros -Arguments to requests (and macros) are processed much like the shell: +Arguments to requests and macros are processed much like the shell: The line is split into arguments according to -spaces.@footnote{Plan@w{ }9's @code{troff} implementation also allows +spaces.@footnote{Plan@tie{}9's @code{troff} implementation also allows tabs for argument separation -- @code{gtroff} intentionally doesn't -support this.} An argument which is intended to contain spaces can -either be enclosed in double quotes, or have the spaces @dfn{escaped} -with backslashes. +support this.} -Here are a few examples: +@cindex spaces, in a macro argument +An argument to a macro which is intended to contain spaces can either be +enclosed in double quotes, or have the spaces @dfn{escaped} with +backslashes. This is @emph{not} true for requests. + +Here are a few examples for a hypothetical macro @code{uh}: @Example .uh The Mouse Problem @@ -4766,9 +5167,9 @@ Double quotes in the @code{ds} request are handled differently. @code{gtroff} has a @dfn{macro} facility for defining a series of lines which can be invoked by name. They are called in the same manner as -requests -- arguments also may be passed in the same manner. +requests -- arguments also may be passed basically in the same manner. -@xref{Writing Macros}, and @ref{Request Arguments}. +@xref{Writing Macros}, and @ref{Request and Macro Arguments}. @c --------------------------------------------------------------------- @@ -5068,9 +5469,9 @@ Test Test as expected. @endDefesc -@Defreq {ig, yy} +@Defreq {ig, [@Var{end}]} Ignore all input until @code{gtroff} encounters the macro named -@code{.}@var{yy} on a line by itself (or @code{..} if @var{yy} is not +@code{.}@var{end} on a line by itself (or @code{..} if @var{end} is not specified). This is useful for commenting out large blocks of text: @Example @@ -5159,8 +5560,8 @@ increment or decrement a register. @DefreqList {nr, ident @t{+}@Var{value}} @DefreqItem {nr, ident @t{-}@Var{value}} -@DefescItem {\\R, ', ident @t{+}@Var{value}, '} -@DefescListEnd {\\R, ', ident @t{-}@Var{value}, '} +@DefescItem {\\R, ', ident @t{+}value, '} +@DefescListEnd {\\R, ', ident @t{-}value, '} Increment (decrement) register @var{ident} by @var{value}. @Example @@ -5245,10 +5646,11 @@ Numeric registers can be accessed via the @code{\n} escape. @cindex assignments, nested @cindex indirect assignments @cindex assignments, indirect -Interpolate number register with name @var{ident} (one-character name@w{ -}@var{i}, two-character name @var{id}). This means that the value of the -register is expanded in-place while @code{gtroff} is parsing the input line. -Nested assignments (also called indirect assignments) are possible. +Interpolate number register with name @var{ident} (one-character +name@tie{}@var{i}, two-character name @var{id}). This means that the value +of the register is expanded in-place while @code{gtroff} is parsing the +input line. Nested assignments (also called indirect assignments) are +possible. @Example .nr a 5 @@ -5301,7 +5703,7 @@ syntax form. @DefescItem {\\n, +@lbrack{}, ident, @rbrack{}} @DefescListEnd {\\n, -@lbrack{}, ident, @rbrack{}} Before interpolating, increment or decrement @var{ident} -(one-character name@w{ }@var{i}, two-character name @var{id}) by the +(one-character name@tie{}@var{i}, two-character name @var{id}) by the auto-increment value as specified with the @code{nr} request (or the @code{\R} escape). If no auto-increment value has been specified, these syntax forms are identical to @code{\n}. @@ -5359,12 +5761,12 @@ output formats are available: @table @code @item 1 -Decimal arabic numbers. This is the default format: 0, 1, 2, 3,@w{ -}@enddots{} +Decimal arabic numbers. This is the default format: 0, 1, 2, +3,@tie{}@enddots{} @item 0@dots{}0 Decimal numbers with as many digits as specified. So, @samp{00} would -result in printing numbers as 01, 02, 03,@w{ }@enddots{} +result in printing numbers as 01, 02, 03,@tie{}@enddots{} In fact, any digit instead of zero will do; @code{gtroff} only counts how many digits are specified. As a consequence, @code{af}'s default @@ -5374,16 +5776,16 @@ returned by the @code{\g} escape, see below). @item I @cindex Roman numerals @cindex numerals, Roman -Upper-case Roman numerals: 0, I, II, III, IV,@w{ }@enddots{} +Upper-case Roman numerals: 0, I, II, III, IV,@tie{}@enddots{} @item i -Lower-case Roman numerals: 0, i, ii, iii, iv,@w{ }@enddots{} +Lower-case Roman numerals: 0, i, ii, iii, iv,@tie{}@enddots{} @item A -Upper-case letters: 0, A, B, C, @dots{},@w{ }Z, AA, AB,@w{ }@enddots{} +Upper-case letters: 0, A, B, C, @dots{},@tie{}Z, AA, AB,@tie{}@enddots{} @item a -Lower-case letters: 0, a, b, c, @dots{},@w{ }z, aa, ab,@w{ }@enddots{} +Lower-case letters: 0, a, b, c, @dots{},@tie{}z, aa, ab,@tie{}@enddots{} @end table Omitting the number register format causes a warning of type @@ -5429,7 +5831,7 @@ then apply the @code{af} request to this other register. @cindex format of register (@code{\g}) @cindex register, format (@code{\g}) Return the current format of the specified register @var{ident} -(one-character name@w{ }@var{i}, two-character name @var{id}). For +(one-character name@tie{}@var{i}, two-character name @var{id}). For example, @samp{\ga} after the previous example would produce the string @samp{000}. If the register hasn't been defined yet, nothing is returned. @@ -5445,7 +5847,7 @@ is returned. The following lists some built-in registers which are not described elsewhere in this manual. Any register which begins with a @samp{.} is read-only. A complete listing of all built-in registers can be found in -appendix@w{ }@ref{Register Index}. +appendix@tie{}@ref{Register Index}. @table @code @item .F @@ -5471,8 +5873,8 @@ Vertical resolution in basic units. @cindex time, current, seconds (@code{seconds}) @cindex current time, seconds (@code{seconds}) @vindex seconds -The number of seconds after the minute, normally in the range@w{ }0 -to@w{ }59, but can be up to@w{ }61 to allow for leap seconds. Initialized +The number of seconds after the minute, normally in the range@tie{}0 +to@tie{}59, but can be up to@tie{}61 to allow for leap seconds. Initialized at start-up of @code{gtroff}. @item minutes @@ -5480,7 +5882,7 @@ at start-up of @code{gtroff}. @cindex time, current, minutes (@code{minutes}) @cindex current time, minutes (@code{minutes}) @vindex minutes -The number of minutes after the hour, in the range@w{ }0 to@w{ }59. +The number of minutes after the hour, in the range@tie{}0 to@tie{}59. Initialized at start-up of @code{gtroff}. @item hours @@ -5488,7 +5890,7 @@ Initialized at start-up of @code{gtroff}. @cindex time, current, hours (@code{hours}) @cindex current time, hours (@code{hours}) @vindex hours -The number of hours past midnight, in the range@w{ }0 to@w{ }23. +The number of hours past midnight, in the range@tie{}0 to@tie{}23. Initialized at start-up of @code{gtroff}. @item dw @@ -5517,8 +5919,8 @@ The current year. @item yr @vindex yr -The current year minus@w{ }1900. Unfortunately, the documentation of -@acronym{UNIX} Version@w{ }7's @code{troff} had a year@w{ }2000 bug: It +The current year minus@tie{}1900. Unfortunately, the documentation of +@acronym{UNIX} Version@tie{}7's @code{troff} had a year@tie{}2000 bug: It incorrectly claimed that @code{yr} contains the last two digits of the year. That claim has never been true of either @acronym{AT&T} @code{troff} or GNU @code{troff}. Old @code{troff} input that looks @@ -5567,15 +5969,15 @@ request to activate line numbering. @vindex .x @cindex major version number register (@code{.x}) @cindex version number, major, register (@code{.x}) -The major version number. For example, if the version number is@w{ -}1.03 then @code{.x} contains@w{ }@samp{1}. +The major version number. For example, if the version number +is 1.03 then @code{.x} contains@tie{}@samp{1}. @item .y @vindex .y @cindex minor version number register (@code{.y}) @cindex version number, minor, register (@code{.y}) -The minor version number. For example, if the version number is@w{ -}1.03 then @code{.y} contains@w{ }@samp{03}. +The minor version number. For example, if the version number +is 1.03 then @code{.y} contains@tie{}@samp{03}. @item .Y @vindex .Y @@ -5592,19 +5994,19 @@ The process ID of @code{gtroff}. @vindex .g @cindex @code{gtroff}, identification register (@code{.g}) @cindex GNU-specific register (@code{.g}) -Always@w{ }1. Macros should use this to determine whether they are +Always@tie{}1. Macros should use this to determine whether they are running under GNU @code{troff}. @item .A @vindex .A @cindex @acronym{ASCII} approximation output register (@code{.A}) If the command line option @option{-a} is used to produce an -@acronym{ASCII} approximation of the output, this is set to@w{ }1, zero +@acronym{ASCII} approximation of the output, this is set to@tie{}1, zero otherwise. @xref{Groff Options}. @item .P @vindex .P -This register is set to@w{ }1 (and to@w{ }0 otherwise) if the current +This register is set to@tie{}1 (and to@tie{}0 otherwise) if the current page is actually being printed, i.e., if the @option{-o} option is being used to only print selected pages. @xref{Groff Options}, for more information. @@ -5612,7 +6014,7 @@ information. @item .T @vindex .T If @code{gtroff} is called with the @option{-T} command line option, the -number register @code{.T} is set to@w{ }1, and zero otherwise. +number register @code{.T} is set to@tie{}1, and zero otherwise. @xref{Groff Options}. @stindex .T @@ -5677,7 +6079,7 @@ the @code{fi} request. @cindex mode, fill (@code{fi}) 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 @code{.u} is set to@w{ }1. +filled. The read-only number register @code{.u} is set to@tie{}1. The fill mode status is associated with the current environment (@pxref{Environments}). @@ -5691,7 +6093,7 @@ See @ref{Line Control}, for interaction with the @code{\c} escape. 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 -@code{.u} is set to@w{ }0. +@code{.u} is set to@tie{}0. The fill mode status is associated with the current environment (@pxref{Environments}). @@ -5720,7 +6122,7 @@ Adjust text to the right margin, producing ragged-left text. @item c @cindex centered text -@cindex @code{ce} request, difference to @samp{.ad@w{ }c} +@cindex @code{ce} request, difference to @samp{.ad@tie{}c} Center filled text. This is different to the @code{ce} request which only centers text without filling. @@ -5729,6 +6131,9 @@ only centers text without filling. Justify to both margins. This is the default used by @code{gtroff}. @end table +Finally, @var{mode} can be the numeric argument returned by the @code{.j} +register. + With no argument, @code{gtroff} adjusts lines in the same way it did before adjusting was deactivated (with a call to @code{na}, for example). @@ -5736,13 +6141,15 @@ example). @Example text .ad r +.nr ad \n[.j] text .ad c text .na text -.ad \" back to centering +.ad \" back to centering text +.ad \n[ad] \" back to right justifying @endExample @cindex adjustment mode register (@code{.j}) @@ -5797,10 +6204,10 @@ is formatted as @cindex sentence space size register (@code{.sss}) @cindex size of sentence space register (@code{.sss}) @cindex space between sentences register (@code{.sss}) -Change the minimum size of a space between filled words. It takes its -units as one twelfth of the space width parameter for the current -font. Initially both the @var{word_space_size} and -@var{sentence_space_size} are@w{ }12. +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 @var{word_space_size} and @var{sentence_space_size} +are@tie{}12. In fill mode, the values specify the minimum distance. @cindex fill mode @cindex mode, fill @@ -5826,9 +6233,37 @@ environment (@pxref{Environments}). Contrary to @acronym{AT&T} @code{troff}, this request is @emph{not} ignored if a TTY output device is used; the given values are then -rounded down to a multiple of@w{ }12 (@pxref{Implementation Differences}). +rounded down to a multiple of@tie{}12 (@pxref{Implementation Differences}). The request is ignored if there is no parameter. + +@cindex discardable horizontal space +@cindex space, discardable, horizontal +@cindex horizontal discardable space +Another useful application of the @code{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: + +@Example +.ll 4.5i +1.\ This is the first footnote.\c +.ss 48 +.nop +.ss 12 +2.\ This is the second footnote. +@endExample + +@noindent +The result: + +@Example +1. This is the first footnote. 2. This +is the second footnote. +@endExample + +@noindent +Note that the @code{\h} escape produces unbreakable space. @endDefreq @DefreqList {ce, [@Var{nnn}]} @@ -5930,9 +6365,9 @@ Do not hyphenate the last two characters of a word. Do not hyphenate the first two characters of a word. @end table -Values in the previous table are additive. For example, the value@w{ -}12 causes @code{gtroff} to neither hyphenate the last two nor the first -two characters of a word. +Values in the previous table are additive. For example, the +value@tie{}12 causes @code{gtroff} to neither hyphenate the last +two nor the first two characters of a word. @cindex hyphenation restrictions register (@code{.hy}) The current hyphenation restrictions can be found in the read-only @@ -5961,7 +6396,7 @@ The hyphenation mode is associated with the current environment @cindex hyphenated lines, consecutive (@code{hlm}) Set the maximum number of consecutive hyphenated lines to @var{nnn}. If this number is negative, there is no maximum. The default value -is@w{ }@minus{}1 if @var{nnn} is omitted. This value is associated +is@tie{}@minus{}1 if @var{nnn} is omitted. This value is associated with the current environment (@pxref{Environments}). Only lines output from a given environment count towards the maximum associated with that environment. Hyphens resulting from @code{\%} are counted; @@ -6005,7 +6440,7 @@ longer a restriction. @esindex \: @end ifnotinfo @ifinfo -@esindex @r{<colon>} +@esindex \@r{<colon>} @end ifinfo @cindex hyphenation character (@code{\%}) @cindex character, hyphenation (@code{\%}) @@ -6031,8 +6466,8 @@ The @code{\:} escape inserts a zero-width break point @cindex @code{\Y}, followed by @code{\%} @cindex @code{\%}, following @code{\X} or @code{\Y} Note that @code{\X} and @code{\Y} start a word, that is, the @code{\%} -escape in (say) @w{@samp{ \X'...'\%foobar}} and -@w{@samp{ \Y'...'\%foobar}} no longer prevents hyphenation but inserts +escape in (say) @w{@samp{\X'...'\%foobar}} and +@w{@samp{\Y'...'\%foobar}} no longer prevents hyphenation but inserts a hyphenation point at the beginning of @samp{foobar}; most likely this isn't what you want to do. @endDefesc @@ -6103,18 +6538,19 @@ The @code{hpfcode} request defines mapping values for character codes in hyphenation patterns. @code{hpf} or @code{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@w{ }255. The request maps character code@w{ }@var{a} -to code@w{ }@var{b}, code@w{ }@var{c} to code@w{ }@var{d}, and so on. You +-- integers from 0 to@tie{}255. The request maps character code@tie{}@var{a} +to code@tie{}@var{b}, code@tie{}@var{c} to code@tie{}@var{d}, and so on. You can use character codes which would be invalid otherwise. @pindex troffrc @pindex troffrc-end @pindex hyphen.us +@pindex hyphenex.us The set of hyphenation patterns is associated with the current language set by the @code{hla} request. The @code{hpf} request is usually invoked by the @file{troffrc} or @file{troffrc-end} file; by default, -@file{troffrc} loads hyphenation patterns for American English (in file -@file{hyphen.us}). +@file{troffrc} loads hyphenation patterns and exceptions for American +English (in files @file{hyphen.us} and @file{hyphenex.us}). A second call to @code{hpf} (for the same language) will replace the hyphenation patterns with the new ones. @@ -6145,7 +6581,7 @@ This request is ignored if it has no parameter. Set the (right) hyphenation margin to @var{length}. If the current adjustment mode is not @samp{b} or @samp{n}, the line is not hyphenated if it is shorter than @var{length}. Without an argument, -the hyphenation margin is reset to its default value, which is@w{ }0. +the hyphenation margin is reset to its default value, which is@tie{}0. The default scaling indicator for this request is @samp{m}. The hyphenation margin is associated with the current environment (@pxref{Environments}). @@ -6166,7 +6602,7 @@ Set the hyphenation space to @var{hyphenation_space}. If the current adjustment mode is @samp{b} or @samp{n}, don't hyphenate the line if it can be justified by adding no more than @var{hyphenation_space} extra space to each word space. Without argument, the hyphenation -space is set to its default value, which is@w{ }0. The default +space is set to its default value, which is@tie{}0. The default scaling indicator for this request is @samp{m}. The hyphenation space is associated with the current environment (@pxref{Environments}). @@ -6233,11 +6669,55 @@ read-only number register @samp{.hla}. @cindex spacing, manipulating @Defreq {sp, [@Var{distance}]} -Space downwards @var{distance}. With no argument it advances 1@w{ -}line. A negative argument causes @code{gtroff} to move up the page +Space downwards @var{distance}. With no argument it advances +1@tie{}line. A negative argument causes @code{gtroff} to move up the page the specified distance. If the argument is preceded by a @samp{|} then @code{gtroff} moves that distance from the top of the page. This request causes a line break. The default scaling indicator is @samp{v}. + +If a vertical trap is sprung during execution of @code{sp}, the amount of +vertical space after the trap is discarded. For example, this + +@Example +.de xxx +.. +. +.wh 0 xxx +. +.pl 5v +foo +.sp 2 +bar +.sp 50 +baz +@endExample + +@noindent +results in + +@Example +foo + + +bar + +baz +@endExample + +@cindex @code{sp} request, and traps +@cindex discarded space in traps +@cindex space, discarded, in traps +@cindex traps, and discarded space +The amount of discarded space is available in the number register +@code{.trunc}. + +To protect @code{sp} against vertical traps, use the @code{vpt} request: + +@Example +.vpt 0 +.sp -3 +.vpt 1 +@endExample @endDefreq @DefreqList {ls, [@Var{nnn}]} @@ -6324,7 +6804,7 @@ advance to the next page is also disabled, except if it is accompanied by a page number (see @ref{Page Control}, for more information). This mode ends when actual text is output or the @code{rs} request is encountered which ends no-space mode. The read-only number register -@code{.ns} is set to@w{ }1 as long as no-space mode is active. +@code{.ns} is set to@tie{}1 as long as no-space mode is active. This request is useful for macros that conditionally insert vertical space before the text starts @@ -6341,8 +6821,8 @@ except when it is the first paragraph after a section header). @cindex fields, and tabs @cindex @acronym{EBCDIC} encoding of a tab -A tab character (@acronym{ASCII} char@w{ }9, @acronym{EBCDIC} char@w{ -}5) causes a horizontal movement to the next tab stop (much +A tab character (@acronym{ASCII} char@tie{}9, @acronym{EBCDIC} +char@tie{}5) causes a horizontal movement to the next tab stop (much like it did on a typewriter). @Defesc {\\t, , , } @@ -6360,7 +6840,7 @@ letter @samp{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@w{ }tab stops every +left margin. For example, the following sets 6@tie{}tab stops every one inch. @Example @@ -6421,7 +6901,7 @@ can be neither stretched nor squeezed. For example, @endExample @noindent -creates a single line which is a bit longer than 10@w{ }inches (a string +creates a single line which is a bit longer than 10@tie{}inches (a string is used to show exactly where the tab characters are). Now consider the following: @@ -6480,9 +6960,7 @@ Calling @code{ta} without an argument removes all tab stops. @item @cindex tab stops, for TTY output devices -The start-up value of @code{gtroff} is @w{@samp{T 0.5i}} in troff mode -and @w{@samp{T 0.8i}} in nroff mode (the latter is done with an -explicit call to the @code{ta} request in the file @file{tty.tmac}. +The start-up value of @code{gtroff} is @w{@samp{T 0.8i}}. @end itemize @cindex tab settings register (@code{.tabs}) @@ -6496,9 +6974,9 @@ argument to the @code{ta} request. @result{} T120u @endExample -@cindex @code{.S} register, Plan@w{ }9 alias for @code{.tabs} -@cindex @code{.tabs} register, Plan@w{ }9 alias (@code{.S}) -The @code{troff} version of the Plan@w{ }9 operating system uses +@cindex @code{.S} register, Plan@tie{}9 alias for @code{.tabs} +@cindex @code{.tabs} register, Plan@tie{}9 alias (@code{.S}) +The @code{troff} version of the Plan@tie{}9 operating system uses register @code{.S} for the same purpose. @endDefreq @@ -6552,7 +7030,7 @@ a b c @endExample Line-tabs mode is associated with the current environment. -The read-only register @code{.linetabs} is set to@w{ }1 if in line-tabs +The read-only register @code{.linetabs} is set to@tie{}1 if in line-tabs mode, and 0 in normal mode. @endDefreq @@ -6574,7 +7052,7 @@ this @code{gtroff} provides an alternate tab mechanism, called @dfn{leaders} which does just that. @cindex leader character -A leader character (character code@w{ }1) behaves similarly to a tab +A leader character (character code@tie{}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. @@ -6688,14 +7166,14 @@ The control character (@samp{.}) and the no-break control character respectively. @Defreq {cc, [@Var{c}]} -Set the control character to@w{ }@var{c}. With no argument the default +Set the control character to@tie{}@var{c}. With no argument the default control character @samp{.} is restored. The value of the control character is associated with the current environment (@pxref{Environments}). @endDefreq @Defreq {c2, [@Var{c}]} -Set the no-break control character to@w{ }@var{c}. With no argument the +Set the no-break control character to@tie{}@var{c}. With no argument the default control character @samp{'} is restored. The value of the no-break control character is associated with the current environment (@pxref{Environments}). @@ -6732,7 +7210,7 @@ necessary then to double the escape character. Here an example: @Defreq {ec, [@Var{c}]} @cindex escape character, changing (@code{ec}) @cindex character, escape, changing (@code{ec}) -Set the escape character to@w{ }@var{c}. With no argument the default +Set the escape character to@tie{}@var{c}. With no argument the default escape character @samp{\} is restored. It can be also used to re-enable the escape mechanism after an @code{eo} request. @@ -6782,7 +7260,7 @@ The following example defines strings to begin and end a superscript: @Example -.ds @{ \v'-.3m'\s'\Es[.s]*60/100' +.ds @{ \v'-.3m'\s'\En[.s]*60/100' .ds @} \s0\v'.3m' @endExample @@ -6850,8 +7328,8 @@ Internals}, for more on this process). @DefreqList {tr, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}} @DefreqListEnd {trin, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}} -Translate character @var{a} to glyph@w{ }@var{b}, character @var{c} to -glyph@w{ }@var{d}, etc. If there is an odd number of arguments, the +Translate character @var{a} to glyph@tie{}@var{b}, character @var{c} to +glyph@tie{}@var{d}, etc. If there is an odd number of arguments, the last one is translated to an unstretchable space (@w{@samp{\ }}). The @code{trin} request is identical to @code{tr}, @@ -6913,9 +7391,8 @@ set with the @code{shc} request. @item @cindex @code{\&}, and translations -The pair @samp{@var{c}\&} (this is an arbitrary character@w{ -}@var{c} followed by the zero width space character) maps this -character to nothing. +The pair @samp{@var{c}\&} (this is an arbitrary character@tie{}@var{c} +followed by the zero width space character) maps this character to nothing. @Example .tr a\& @@ -7497,7 +7974,7 @@ parameter. The read-only number register @code{.pn} contains the number of the next page: either the value set by a @code{pn} request, or the number of the -current page plus@w{ }1. +current page plus@tie{}1. @endDefreq @Defreg {%} @@ -7511,7 +7988,7 @@ A read-write register holding the current page number. @vindex % Change the page number character (used by the @code{tl} request) to a different character. With no argument, this mechanism is disabled. -Note that this doesn't affect the number register@w{ }@code{%}. +Note that this doesn't affect the number register@tie{}@code{%}. @endDefreq @xref{Traps}. @@ -7519,7 +7996,7 @@ Note that this doesn't affect the number register@w{ }@code{%}. @c ===================================================================== -@node Page Control, Fonts, Page Layout, gtroff Reference +@node Page Control, Fonts and Symbols, Page Layout, gtroff Reference @section Page Control @cindex page control @cindex control, page @@ -7549,6 +8026,9 @@ cause a break or actually eject a page. @cindex diversion, top-level, and @code{bp} @code{bp} has no effect if not called within the top-level diversion (@pxref{Diversions}). + +The number register @code{.pe} is set to@tie{}1 while @code{bp} is +active. @xref{Page Location Traps}. @endDefreq @Defreq {ne, [@Var{space}]} @@ -7561,10 +8041,10 @@ single @dfn{orphan} line left at the bottom of a page. The @code{ne} request ensures that there is a certain distance, specified by the first argument, before the next page is triggered (see @ref{Traps}, for further information). The default scaling indicator for @code{ne} -is @samp{v}; the default value of @var{space} is@w{ }1@dmn{v} if no +is @samp{v}; the default value of @var{space} is@tie{}1@dmn{v} if no argument is given. -For example, to make sure that no fewer than 2@w{ }lines get orphaned, +For example, to make sure that no fewer than 2@tie{}lines get orphaned, do the following before each paragraph: @Example @@ -7584,7 +8064,7 @@ specified amount of vertical space. If the desired amount of space exists before the next trap (or the bottom page boundary if no trap is set), the space is output immediately (ignoring a partially filled line which stays untouched). If there is not enough space, it is stored for -later output via the @code{os} request. The default value is@w{ }1@dmn{v} +later output via the @code{os} request. The default value is@tie{}1@dmn{v} if no argument is given; the default scaling indicator is @samp{v}. @cindex @code{sv} request, and no-space mode @@ -7644,8 +8124,8 @@ registers. @c ===================================================================== -@node Fonts, Sizes, Page Control, gtroff Reference -@section Fonts +@node Fonts and Symbols, Sizes, Page Control, gtroff Reference +@section Fonts and Symbols @cindex fonts @code{gtroff} can switch fonts at any point in the text. @@ -7667,7 +8147,7 @@ special symbols (Greek, mathematics). @c --------------------------------------------------------------------- -@node Changing Fonts, Font Families, Fonts, Fonts +@node Changing Fonts, Font Families, Fonts and Symbols, Fonts and Symbols @subsection Changing Fonts @cindex fonts @@ -7684,7 +8164,7 @@ special symbols (Greek, mathematics). @kindex family @pindex DESC The @code{ft} request and the @code{\f} escape change the current font -to @var{font} (one-character name@w{ }@var{f}, two-character name +to @var{font} (one-character name@tie{}@var{f}, two-character name @var{fn}). If @var{font} is a style name (as set with the @code{sty} request or @@ -7699,7 +8179,7 @@ to the previous font. Use @code{\f[]} to do this with the escape. The old syntax forms @code{\fP} or @code{\f[P]} are also supported. Fonts are generally specified as upper-case strings, which are usually -1@w{ }to 4 characters representing an abbreviation or acronym of the +1@tie{}to 4 characters representing an abbreviation or acronym of the font name. This is no limitation, just a convention. The example below produces two identical lines. @@ -7737,17 +8217,17 @@ the fly: @cindex @code{fspecial} request, and font translations @cindex @code{fp} request, and font translations @cindex @code{sty} request, and font translations -Translate font@w{ }@var{f} to font@w{ }@var{g}. Whenever a font named@w{ -}@var{f} is referred to in a @code{\f} escape sequence, or in the +Translate font@tie{}@var{f} to font@tie{}@var{g}. Whenever a font +named@tie{}@var{f} is referred to in a @code{\f} escape sequence, or in the @code{ft}, @code{ul}, @code{bd}, @code{cs}, @code{tkf}, @code{special}, @code{fspecial}, @code{fp}, or @code{sty} requests, -font@w{ }@var{g} is used. If @var{g} is missing or equal to@w{ }@var{f} +font@tie{}@var{g} is used. If @var{g} is missing or equal to@tie{}@var{f} the translation is undone. @endDefreq @c --------------------------------------------------------------------- -@node Font Families, Font Positions, Changing Fonts, Fonts +@node Font Families, Font Positions, Changing Fonts, Fonts and Symbols @subsection Font Families @cindex font families @cindex families, font @@ -7778,7 +8258,7 @@ different font family on the command line (@pxref{Groff Options}). @DefregListEnd {.fn} @cindex changing font family (@code{fam}, @code{\F}) @cindex font family, changing (@code{fam}, @code{\F}) -Switch font family to @var{family} (one-character name@w{ }@var{f}, +Switch font family to @var{family} (one-character name@tie{}@var{f}, two-character name @var{fm}). If no argument is given, switch back to the previous font family. Use @code{\F[]} to do this with the escape. Note that @code{\FP} doesn't work; it selects font family @@ -7827,13 +8307,13 @@ is the proper concatenation of family and style name. @cindex @code{tkf} request, and font styles @cindex @code{uf} request, and font styles @cindex @code{fspecial} request, and font styles -Associate @var{style} with font position@w{ }@var{n}. A font position +Associate @var{style} with font position@tie{}@var{n}. A font position can be associated either with a font or with a style. The current font is the index of a font position and so is also either a font or a style. If it is a style, the font that is actually used is the font which name is the concatenation of the name of the current family and the name of the current style. For example, if the current -font is@w{ }1 and font position@w{ }1 is associated with style +font is@tie{}1 and font position@tie{}1 is associated with style @samp{R} and the current font family is @samp{T}, then font @samp{TR} will be used. If the current font is not a style, then the current family is ignored. If the requests @code{cs}, @code{bd}, @@ -7841,7 +8321,7 @@ current family is ignored. If the requests @code{cs}, @code{bd}, they will instead be applied to the member of the current family corresponding to that style. -@var{n}@w{ }must be a non-negative integer value. +@var{n}@tie{}must be a non-negative integer value. @pindex DESC @kindex styles @@ -7879,7 +8359,7 @@ In the following example, we want to access the @sc{PostScript} font @endExample @noindent -The default font position at start-up is@w{ }1; for the +The default font position at start-up is@tie{}1; for the @sc{PostScript} device, this is associated with style @samp{R}, so @code{gtroff} tries to open @code{FooR}. @@ -7898,7 +8378,7 @@ A solution to this problem is to use a dummy font like the following: @c --------------------------------------------------------------------- -@node Font Positions, Using Symbols, Font Families, Fonts +@node Font Positions, Using Symbols, Font Families, Fonts and Symbols @subsection Font Positions @cindex font positions @cindex positions, font @@ -7915,7 +8395,7 @@ on which various fonts are mounted. Mount font @var{font} at position @var{pos} (which must be a non-negative integer). This numeric position can then be referred to with font changing commands. When @code{gtroff} starts it is using -font position@w{ }1 (which must exist; position@w{ }0 is unused +font position@tie{}1 (which must exist; position@tie{}0 is unused usually at start-up). @cindex font position register (@code{.f}) @@ -7974,9 +8454,9 @@ syntax forms to access font positions. @kindex styles @kindex family @pindex DESC -Change the current font position to @var{nnn} (one-digit position@w{ -}@var{n}, two-digit position @var{nn}), which must be a non-negative -integer. +Change the current font position to @var{nnn} (one-digit +position@tie{}@var{n}, two-digit position @var{nn}), which must be a +non-negative integer. If @var{nnn} is associated with a style (as set with the @code{sty} request or with the @code{styles} command in the @file{DESC} file), use @@ -8000,7 +8480,7 @@ this is font 1 again @c --------------------------------------------------------------------- -@node Using Symbols, Special Fonts, Font Positions, Fonts +@node Using Symbols, Special Fonts, Font Positions, Fonts and Symbols @subsection Using Symbols @cindex using symbols @cindex symbols, using @@ -8021,6 +8501,8 @@ sometimes more than one character maps to a single glyph (this is a @cindex special fonts @kindex fonts @pindex DESC +@cindex @code{special} request, and glyph search order +@cindex @code{fspecial} request, and glyph search order A @dfn{symbol} is simply a named glyph. Within @code{gtroff}, all glyph names of a particular font are defined in its font file. If the user requests a glyph not available in this font, @code{gtroff} looks @@ -8033,7 +8515,7 @@ special fonts. Fonts mounted with the @code{fonts} keyword in the special fonts locally (i.e.@: for a particular font), use the @code{fspecial} request. -In summary, @code{gtroff} tries the following to find a given symbol: +Here the exact rules how @code{gtroff} searches a given symbol: @itemize @bullet @item @@ -8047,45 +8529,66 @@ Check the current font. If the symbol has been defined with the @code{fchar} request, use it. @item -Check all fonts given with the @code{fspecial} request, in the order -of appearance in @code{fspecial} calls. +Check whether the current font has a font-specific list of special fonts; +test all fonts in the order of appearance in the last @code{fspecial} +call if appropriate. @item -Check all fonts given with the @code{special} request, in the order -of appearance in @code{special} calls (inclusively the special fonts -defined in the @file{DESC} file, which come first). +If the symbol has been defined with the @code{fschar} request for the +current font, use it. @item -As a last resort, consult all fonts loaded up to now (in the order they -have been called the first time) for special fonts and check them. -@end itemize +Check all fonts in the order of appearance in the last @code{special} +call. -@xref{Font Files}, and @ref{Special Fonts}, for more details. +@item +If the symbol has been defined with the @code{schar} request, use it. -@DefescList {\\, @lparen{}, nm, } -@DefescListEnd {\\, @lbrack{}, name, @rbrack} -Insert a symbol @var{name} (two-character name @var{nm}). There is no -special syntax for one-character names -- the natural form -@samp{\@var{n}} would collide with escapes.@footnote{Note that a -one-character symbol is not the same as an input character, i.e., the -character @code{a} is not the same as @code{\[a]}. By default, -@code{groff} defines only a single one-character symbol, @code{\[-]}; -it is usually accessed as @code{\-}. On the other hand, @code{gtroff} -has the special feature that @code{\[char@var{XXX}]} is the same as the -input character with character code @var{XXX}. For example, -@code{\[char97]} is identical to the letter @code{a} if @acronym{ASCII} -encoding is active.} +@item +As a last resort, consult all fonts loaded up to now for special fonts +and check them, starting with the lowest font number. Note that this can +sometimes lead to surprising results since the @code{fonts} line in the +@file{DESC} file often contains empty positions which are filled later +on. For example, consider the following: -If @var{name} is undefined, a warning of type @samp{char} is generated, -and the escape is ignored. @xref{Debugging}, for information about -warnings. +@Example +fonts 3 0 0 FOO +@endExample + +@noindent +This mounts font @code{foo} at font position@tie{}3. We assume that +@code{FOO} is a special font, containing glyph @code{foo}, +and that no font has been loaded yet. The line + +@Example +.fspecial BAR BAZ +@endExample + +@noindent +makes font @code{BAZ} special only if font @code{BAR} is active. We +further assume that @code{BAZ} is really a special font, i.e., the font +description file contains the @code{special} keyword, and that it +also contains glyph @code{foo} with a special shape fitting to font +@code{BAR}. After executing @code{fspecial}, font @code{BAR} is loaded at +font position@tie{}1, and @code{BAZ} at position@tie{}2. + +We now switch to a new font @code{XXX}, trying to access glyph @code{foo} +which is assumed to be missing. There are neither font-specific special +fonts for @code{XXX} nor any other fonts made special with the +@code{special} request, so @code{gtroff} starts the search for special +fonts in the list of already mounted fonts, with increasing font +positions. Consequently, it finds @code{BAZ} before @code{FOO} even for +@code{XXX} which is not the intended behaviour. +@end itemize + +@xref{Font Files}, and @ref{Special Fonts}, for more details. @cindex list of available glyphs (@cite{groff_char(7)} man page) @cindex available glyphs, list (@cite{groff_char(7)} man page) @cindex glyphs, available, list (@cite{groff_char(7)} man page) The list of available symbols is device dependent; see the -@cite{groff_char(7)} man page for a complete list for the given output -device. For example, say +@cite{groff_char(7)} man page for a complete list of all glyphs. For +example, say @Example man -Tdvi groff_char > groff_char.dvi @@ -8101,7 +8604,130 @@ must be called directly: groff -Tdvi -mec -man groff_char.7 > groff_char.dvi @endExample -@c XXX list of common symbols +@cindex composite glyph names +@cindex glyph names, composite +@cindex groff glyph list (GGL) +@cindex GGL (groff glyph list) +@cindex adobe glyph list (AGL) +@cindex AGL (adobe glyph list) +Glyph names not listed in groff_char(7) are derived algorithmically, +using a simplified version of the Adobe Glyph List (AGL) algorithm +described in +@uref{http://partners.adobe.com/asn/developer/typeforum/unicodegn.html}. +The (frozen) set of glyph names which can't be derived algorithmically +is called @dfn{groff glyph list (GGL)}. + +@itemize @bullet +@item +A glyph for Unicode character U+@var{XXXX}[@var{X}[@var{X}]] which is +not a composite character will be named +@code{u@var{XXXX}@r{[}@var{X}@r{[}@var{X}@r{]]}}. @var{X} must be an +uppercase hexadecimal digit. Examples: @code{u1234}, @code{u008E}, +@code{u12DB8}. The largest Unicode value is 0x10FFFF. There must be at +least four @code{X} digits; if necessary, add leading zeroes (after the +@samp{u}). No zero padding is allowed for character codes greater than +0xFFFF. Surrogates (i.e., Unicode values greater than 0xFFFF +represented with character codes from the surrogate area U+D800-U+DFFF) +are not allowed too. + +@item +A glyph representing more than a single input character will be named + +@display +@samp{u} @var{component1} @samp{_} @var{component2} @samp{_} @var{component3} @dots{} +@end display + +@noindent +Example: @code{u0045_0302_0301}. + +For simplicity, all Unicode characters which are composites must be +decomposed maximally (this is normalization form@tie{}D in the Unicode +standard); for example, @code{u00CA_0301} is not a valid glyph name +since U+00CA (@sc{latin capital letter e with circumflex}) can be +further decomposed into U+0045 (@sc{latin capital letter e}) and U+0302 +(@sc{combining circumflex accent}). @code{u0045_0302_0301} is thus the +glyph name for U+1EBE, @sc{latin capital letter e with circumflex and +acute}. + +@item +groff maintains a table to decompose all algorithmically derived glyph +names which are composites itself. For example, @code{u0100} (@sc{latin +letter a with macron}) will be automatically decomposed into +@code{u0041_0304}. Additionally, a glyph name of the GGL is preferred +to an algorithmically derived glyph name; groff also automatically does +the mapping. Example: The glyph @code{u0045_0302} will be mapped to +@code{^E}. + +@item +glyph names of the GGL can't be used in composite glyph names; for +example, @code{^E_u0301} is invalid. +@end itemize + +@DefescList {\\, @lparen{}, nm, } +@DefescItem {\\, @lbrack{}, name, @rbrack} +@DefescListEnd {\\, @lbrack{}, component1 component2 @dots{}, @rbrack} +Insert a symbol @var{name} (two-character name @var{nm}) or a composite +glyph with component glyphs @var{component1}, @var{component2}, +@enddots{} There is no special syntax for one-character names -- the +natural form @samp{\@var{n}} would collide with escapes.@footnote{Note +that a one-character symbol is not the same as an input character, i.e., +the character @code{a} is not the same as @code{\[a]}. By default, +@code{groff} defines only a single one-character symbol, @code{\[-]}; it +is usually accessed as @code{\-}. On the other hand, @code{gtroff} has +the special feature that @code{\[char@var{XXX}]} is the same as the +input character with character code @var{XXX}. For example, +@code{\[char97]} is identical to the letter @code{a} if @acronym{ASCII} +encoding is active.} + +If @var{name} is undefined, a warning of type @samp{char} is generated, +and the escape is ignored. @xref{Debugging}, for information about +warnings. + +groff resolves @code{\[...]} with more than a single component as +follows: + +@itemize @bullet +@item +Any component which is found in the GGL will be converted to the +@code{u@var{XXXX}} form. + +@item +Any component @code{u@var{XXXX}} which is found in the list of +decomposable glyphs will be decomposed. + +@item +The resulting elements are then concatenated with @samp{_} inbetween, +dropping the leading @samp{u} in all elements but the first. +@end itemize + +No check for the existence of any component (similar to @code{tr} +request) will be done. + +Examples: + +@table @code +@item \[A ho] +@samp{A} maps to @code{u0041}, @samp{ho} maps to @code{u02DB}, thus the +final glyph name would be @code{u0041_02DB}. Note this is not the +expected result: The ogonek glyph @samp{ho} is a spacing ogonek, but for +a proper composite a non-spacing ogonek (U+0328) is necessary. Looking +into the file @file{composite.tmac} one can find @w{@samp{.composite ho +u0328}} which changes the mapping of @samp{ho} while a composite glyph +name is constructed, causing the final glyph name to be +@code{u0041_0328}. + +@item \[^E u0301] +@itemx \[^E aa] +@itemx \[E a^ aa] +@itemx \[E ^ '] +@samp{^E} maps to @code{u0045_0302}, thus the final glyph name is +@code{u0045_0302_0301} in all forms (assuming proper calls of the +@code{composite} request). +@end table + +It is not possible to define glyphs with names like @w{@samp{A ho}} +within a groff font file. This is not really a limitation; instead, you +have to define @code{u0041_0328}. @endDefesc @Defesc {\\C, ', xxx, '} @@ -8114,15 +8740,27 @@ that it is compatible with newer versions of @acronym{AT&T} @code{troff} and is available in compatibility mode. @endDefesc +@Defreq {composite, from to} +@pindex composite.tmac +Map glyph name @var{from} to glyph name @var{to} if it is used in +@code{\[...]} with more than one component. See above for examples. + +This mapping is based on glyph names only; no check for the existence of +either glyph is done. + +A set of default mappings for many accents can be found in the file +@file{composite.tmac} which is loaded at start-up. +@endDefreq + @Defesc {\\N, ', n, '} @cindex numbered glyph (@code{\N}) @cindex glyph, numbered (@code{\N}) @cindex @code{char} request, used with @code{\N} @cindex Unicode -Typeset the glyph with code@w{ }@var{n} in the current font -(@code{n}@w{ }is @strong{not} the input character code). The -number @var{n}@w{ }can be any non-negative decimal integer. Most devices -only have glyphs with codes between 0 and@w{ }255; the Unicode +Typeset the glyph with code@tie{}@var{n} in the current font +(@code{n}@tie{}is @strong{not} the input character code). The +number @var{n}@tie{}can be any non-negative decimal integer. Most devices +only have glyphs with codes between 0 and@tie{}255; the Unicode output device uses codes in the range 0--65535. If the current font does not contain a glyph with that code, special fonts are @emph{not} searched. The @code{\N} escape sequence can be @@ -8141,6 +8779,8 @@ description file after the @code{charset} command. It is possible to include unnamed glyphs in the font description file by using a name of @samp{---}; the @code{\N} escape sequence is the only way to use these. + +No kerning is applied to glyphs accessed with @code{\N}. @endDefesc Some escape sequences directly map onto special glyphs. @@ -8193,7 +8833,7 @@ this property). @cindex @code{hy} glyph, and @code{cflags} @cindex @code{em} glyph, and @code{cflags} Lines can be broken after the character (initially the character -@samp{-} and the symbols @samp{\(hy} and @samp{\(em} have this property). +@samp{-} and the symbols @samp{\[hy]} and @samp{\[em]} have this property). @item 8 @cindex overlapping characters @@ -8201,12 +8841,15 @@ Lines can be broken after the character (initially the character @cindex @code{ul} glyph, and @code{cflags} @cindex @code{rn} glyph, and @code{cflags} @cindex @code{ru} glyph, and @code{cflags} +@cindex @code{radicalex} glyph, and @code{cflags} +@cindex @code{sqrtex} glyph, and @code{cflags} The character overlaps horizontally (initially the symbols -@samp{\(ul\(rn\(ru} have this property). +@samp{\[ul]}, @samp{\[rn]}, @samp{\[ru]}, @samp{\[radicalex}, and +@samp{\[sqrtex]} have this property). @item 16 @cindex @code{br} glyph, and @code{cflags} -The character overlaps vertically (initially symbol @samp{\(br} has +The character overlaps vertically (initially symbol @samp{\[br]} has this property). @item 32 @@ -8224,15 +8867,20 @@ this property is treated as the end of a sentence if followed by a newline or two spaces; in other words the character is @dfn{transparent} for the purposes of end-of-sentence recognition -- this is the same as having a zero space factor in @TeX{} (initially -characters @samp{"')]*} and the symbols @samp{\(dg\(rq} have this -property). +characters @samp{"')]*} and the symbols @samp{\[dg]} and @samp{\[rq]} have +this property). @end table @endDefreq @DefreqList {char, g [@Var{string}]} -@DefreqListEnd {fchar, g [@Var{string}]} +@DefreqItem {fchar, g [@Var{string}]} +@DefreqItem {fschar, f g [@Var{string}]} +@DefreqListEnd {schar, g [@Var{string}]} @cindex defining character (@code{char}) +@cindex defining fallback character (@code{fchar}, @code{fschar}, @code{schar}) @cindex character, defining (@code{char}) +@cindex character, defining fallback (@code{fchar}, @code{fschar}, @code{schar}) +@cindex fallback character, defining (@code{fchar}, @code{fschar}, @code{schar}) @cindex creating new characters (@code{char}) @cindex defining symbol (@code{char}) @cindex symbol, defining (@code{char}) @@ -8249,9 +8897,9 @@ property). @cindex @code{\&}, and glyph definitions @cindex @code{\e}, and glyph definitions @cindex @code{hcode} request, and glyph definitions -Define a new glyph@w{ }@var{g} to be @var{string} (which can be +Define a new glyph@tie{}@var{g} to be @var{string} (which can be empty).@footnote{@code{char} is a misnomer since an output glyph is -defined.} Every time glyph@w{ }@var{g} needs to be printed, +defined.} Every time glyph@tie{}@var{g} needs to be printed, @var{string} is processed in a temporary environment and the result is wrapped up into a single object. Compatibility mode is turned off and the escape character is set to @samp{\} while @var{string} is being @@ -8259,7 +8907,7 @@ processed. Any emboldening, constant spacing or track kerning is applied to this object rather than to individual characters in @var{string}. -A glyph defined by this request can be used just +A glyph defined by these requests can be used just like a normal glyph provided by the output device. In particular, other characters can be translated to it with the @code{tr} or @code{trin} requests; it can be made the leader character by the @@ -8291,23 +8939,42 @@ The @code{fchar} request defines a fallback glyph: @code{gtroff} only checks for glyphs defined with @code{fchar} if it cannot find the glyph in the current font. @code{gtroff} carries out this test before checking special fonts. + +@code{fschar} defines a fallback glyph for font@tie{}@var{f}: @code{gtroff} +checks for glyphs defined with @code{fschar} after the list of fonts +declared as font-specific special fonts with the @code{fspecial} request, +but before the list of fonts declared as global special fonts with the +@code{special} request. + +Finally, the @code{schar} request defines a global fallback glyph: +@code{gtroff} checks for glyphs defined with @code{schar} after the list +of fonts declared as global special fonts with the @code{special} request, +but before the already mounted special fonts. + +@xref{Using Symbols}, for a detailed description of the glyph +searching mechanism in @code{gtroff}. @endDefreq -@Defreq {rchar, c1 c2 @dots{}} -@cindex removing glyph definition (@code{rchar}) -@cindex glyph, removing definition (@code{rchar}) -Remove the definitions of glyphs @var{c1}, @var{c2},@w{ -}@enddots{} This undoes the effect of a @code{char} or @code{fchar} -request. +@DefreqList {rchar, c1 c2 @dots{}} +@DefreqListEnd {rfschar, f c1 c2 @dots{}} +@cindex removing glyph definition (@code{rchar}, @code{rfschar}) +@cindex glyph, removing definition (@code{rchar}, @code{rfschar}) +@cindex fallback glyph, removing definition (@code{rchar}, @code{rfschar}) +Remove the definitions of glyphs @var{c1}, @var{c2},@tie{}@enddots{} +This undoes the effect of a @code{char}, @code{fchar}, or +@code{schar} request. It is possible to omit the whitespace between arguments. + +The request @code{rfschar} removes glyph definitions defined with +@code{fschar} for glyph@tie{}f. @endDefreq @xref{Special Characters}. @c --------------------------------------------------------------------- -@node Special Fonts, Artificial Fonts, Using Symbols, Fonts +@node Special Fonts, Artificial Fonts, Using Symbols, Fonts and Symbols @subsection Special Fonts @cindex special fonts @cindex fonts, special @@ -8322,25 +8989,29 @@ searching mechanism in @code{gtroff}. Usually, only non-TTY devices have special fonts. -@DefreqList {special, s1 s2 @dots{}} -@DefreqListEnd {fspecial, f s1 s2 @dots{}} +@DefreqList {special, [@Var{s1} @Var{s2} @dots{}]} +@DefreqListEnd {fspecial, f [@Var{s1} @Var{s2} @dots{}]} @kindex fonts @pindex DESC -Use the @code{special} request to define special fonts. They are -appended to the list of global special fonts in the given order. -The first entries in this list are the fonts defined with the -@code{fonts} command in the @file{DESC} file which are marked as -special in the corresponding font description files. - -Use the @code{fspecial} request to designate special fonts -only when font@w{ }@var{f} font is active. They are appended to the -list of special fonts for @var{f} in the given order. Initially, this +Use the @code{special} request to define special fonts. Initially, this list is empty. + +Use the @code{fspecial} request to designate special fonts only when +font@tie{}@var{f} is active. Initially, this list is empty. + +Previous calls to @code{special} or @code{fspecial} are overwritten; +without arguments, the particular list of special fonts is set to empty. +Special fonts are searched in the order they appear as arguments. + +All fonts which appear in a call to @code{special} or @code{fspecial} are +loaded. + +@xref{Using Symbols}, for the exact search order of glyphs. @endDefreq @c --------------------------------------------------------------------- -@node Artificial Fonts, Ligatures and Kerning, Special Fonts, Fonts +@node Artificial Fonts, Ligatures and Kerning, Special Fonts, Fonts and Symbols @subsection Artificial Fonts @cindex artificial fonts @cindex fonts, artificial @@ -8352,8 +9023,9 @@ did not have a wide variety of fonts, and when @code{nroff} and necessary in GNU @code{troff}. Nevertheless, they are supported. @DefescList {\\H, ', height, '} -@DefescItem {\\H, ', @t{+}@Var{height}, '} -@DefescListEnd {\\H, ', @t{-}@Var{height}, '} +@DefescItem {\\H, ', @t{+}height, '} +@DefescItem {\\H, ', @t{-}height, '} +@DefregListEnd {.height} @cindex changing the font height (@code{\H}) @cindex font height, changing (@code{\H}) @cindex height, font, changing (@code{\H}) @@ -8361,6 +9033,9 @@ Change (increment, decrement) the height of the current font, but not the width. If @var{height} is zero, restore the original height. Default scaling indicator is @samp{z}. +The read-only number register @code{.height} contains the font height as +set by @code{\H}. + Currently, only the @option{-Tps} device supports this feature. Note that @code{\H} doesn't produce an input token in @code{gtroff}. @@ -8388,11 +9063,15 @@ points larger than the current font size). @endDefesc @DefescList {\\S, ', slant, '} +@DefregListEnd {.slant} @cindex changing the font slant (@code{\S}) @cindex font slant, changing (@code{\S}) @cindex slant, font, changing (@code{\S}) Slant the current font by @var{slant} degrees. Positive values slant -to the right. +to the right. Only integer values are possible. + +The read-only number register @code{.slant} contains the font slant as +set by @code{\S}. Currently, only the @option{-Tps} device supports this feature. @@ -8449,7 +9128,7 @@ well (if a TTY output device is used). @cindex underline font (@code{uf}) @cindex font for underlining (@code{uf}) Set the underline font (globally) used by @code{ul} and @code{cu}. By -default, this is the font at position@w{ }2. @var{font} can be either +default, this is the font at position@tie{}2. @var{font} can be either a non-negative font position or the name of a font. @endDefreq @@ -8511,7 +9190,7 @@ an integer. @c --------------------------------------------------------------------- -@node Ligatures and Kerning, , Artificial Fonts, Fonts +@node Ligatures and Kerning, , Artificial Fonts, Fonts and Symbols @subsection Ligatures and Kerning @cindex ligatures and kerning @cindex kerning and ligatures @@ -8528,6 +9207,10 @@ supported `ff', `ffi', and `ffl' ligatures. Advanced typesetters or `expert' fonts may include ligatures for `ft' and `ct', although GNU @code{troff} does not support these (yet). +Only the current font is checked for ligatures and kerns; neither special +fonts nor entities defined with the @code{char} request (and its siblings) +are taken into account. + @DefreqList {lg, [@Var{flag}]} @DefregListEnd {.lg} @cindex activating ligatures (@code{lg}) @@ -8536,9 +9219,9 @@ supported `ff', `ffi', and `ffl' ligatures. Advanced typesetters or Switch the ligature mechanism on or off; if the parameter is non-zero or missing, ligatures are enabled, otherwise disabled. Default is on. The current ligature mode can be found in the read-only number register -@code{.lg} (set to 1 or@w{ }2 if ligatures are enabled, 0@w{ }otherwise). +@code{.lg} (set to 1 or@tie{}2 if ligatures are enabled, 0@tie{}otherwise). -Setting the ligature mode to@w{ }2 enables the two-character ligatures +Setting the ligature mode to@tie{}2 enables the two-character ligatures (fi, fl, and ff) and disables the three-character ligatures (ffi and ffl). @endDefreq @@ -8560,8 +9243,8 @@ have the same width don't use kerning. @cindex kerning enabled register (@code{.kern}) Switch kerning on or off. If the parameter is non-zero or missing, enable pairwise kerning, otherwise disable it. The read-only number -register @code{.kern} is set to@w{ }1 if pairwise kerning is enabled, -0@w{ }otherwise. +register @code{.kern} is set to@tie{}1 if pairwise kerning is enabled, +0@tie{}otherwise. @cindex zero width space character (@code{\&}) @cindex character, zero width space (@code{\&}) @@ -8584,8 +9267,8 @@ typography if the reader notices the effect. @Defreq {tkf, f s1 n1 s2 n2} @cindex activating track kerning (@code{tkf}) @cindex track kerning, activating (@code{tkf}) -Enable track kerning for font@w{ }@var{f}. If the current font is@w{ -}@var{f} the width of every glyph is increased by an amount +Enable track kerning for font@tie{}@var{f}. If the current font +is@tie{}@var{f} the width of every glyph is increased by an amount between @var{n1} and @var{n2} (@var{n1}, @var{n2} can be negative); if the current point size is less than or equal to @var{s1} the width is increased by @var{n1}; if it is greater than or equal to @var{s2} the @@ -8615,8 +9298,8 @@ with this. Increase the width of the preceding glyph so that the spacing between that glyph and the following glyph is correct if the following glyph is a roman glyph. For example, if an -italic@w{ }@code{f} is immediately followed by a roman right -parenthesis, then in many fonts the top right portion of the@w{ }@code{f} +italic@tie{}@code{f} is immediately followed by a roman right +parenthesis, then in many fonts the top right portion of the@tie{}@code{f} overlaps the top left of the right parenthesis. Use this escape sequence whenever an italic glyph is immediately followed by a roman glyph without any intervening space. This small amount of @@ -8738,7 +9421,7 @@ This is a test. @c ===================================================================== -@node Sizes, Strings, Fonts, gtroff Reference +@node Sizes, Strings, Fonts and Symbols, gtroff Reference @section Sizes @cindex sizes @@ -8757,11 +9440,11 @@ are @emph{not} related to its type size! For example, the standard output, the size of `Helvetica' has to be reduced by one point, and the size of `Courier' must be increased by one point.} @dfn{Vertical spacing} is the amount of space @code{gtroff} allows for a line of -text; normally, this is about 20%@w{ }larger than the current type +text; normally, this is about 20%@tie{}larger than the current type size. Ratios smaller than this can result in hard-to-read text; larger than this, it spreads the text out more vertically (useful for -term papers). By default, @code{gtroff} uses 10@w{ }point type on -12@w{ }point spacing. +term papers). By default, @code{gtroff} uses 10@tie{}point type on +12@tie{}point spacing. @cindex leading The difference between type size and vertical spacing is known, by @@ -8788,7 +9471,7 @@ typesetters, as @dfn{leading} (this is pronounced `ledding'). Use the @code{ps} request or the @code{\s} escape to change (increase, decrease) the type size (in points). Specify @var{size} as either an absolute point size, or as a relative change from the current size. -The size@w{ }0, or no argument, goes back to the previous size. +The size@tie{}0, or no argument, goes back to the previous size. Default scaling indicator of @code{size} is @samp{z}. If @code{size} is zero or negative, it is set to 1@dmn{u}. @@ -8817,23 +9500,23 @@ and the text begins. Any of the following forms are valid: @table @code @item \s@var{n} -Set the point size to @var{n}@w{ }points. @var{n}@w{ }must be either -0 or in the range 4 to@w{ }39. +Set the point size to @var{n}@tie{}points. @var{n}@tie{}must be either +0 or in the range 4 to@tie{}39. @item \s+@var{n} @itemx \s-@var{n} -Increase or decrease the point size by @var{n}@w{ }points. @var{n}@w{ -}must be exactly one digit. +Increase or decrease the point size by @var{n}@tie{}points. +@var{n}@tie{}must be exactly one digit. @item \s(@var{nn} -Set the point size to @var{nn}@w{ }points. @var{nn} must be exactly +Set the point size to @var{nn}@tie{}points. @var{nn} must be exactly two digits. @item \s+(@var{nn} @itemx \s-(@var{nn} @itemx \s(+@var{nn} @itemx \s(-@var{nn} -Increase or decrease the point size by @var{nn}@w{ }points. @var{nn} +Increase or decrease the point size by @var{nn}@tie{}points. @var{nn} must be exactly two digits. @end table @@ -8862,7 +9545,7 @@ the @code{sizescale} line in the @file{DESC} file for the output device provides the scaling factor. For example, if the scaling factor is 1000, -then the value 12000 is 12@w{ }points. +then the value 12000 is 12@tie{}points. Each argument can be a single point size (such as @samp{12000}), or a range of sizes (such as @samp{4000-72000}). @@ -8884,7 +9567,7 @@ reset to the previous value before the last call to @code{vs}. @cindex @code{.V} register, and @code{vs} @code{gtroff} creates a warning of type @samp{range} if @var{space} is -zero or negative; the vertical spacing is then set to the vertical +negative; the vertical spacing is then set to the vertical resolution (as given in the @code{.V} register). The read-only number register @code{.v} contains the current vertical @@ -8951,7 +9634,6 @@ post-vertical spacing; it is associated with the current environment (@pxref{Environments}). @endDefreq - @c --------------------------------------------------------------------- @node Fractional Type Sizes, , Changing Type Sizes, Sizes @@ -8972,7 +9654,7 @@ post-vertical spacing; it is associated with the current environment @cindex @code{\H}, with fractional type sizes @cindex @code{\s}, with fractional type sizes A @dfn{scaled point} is equal to @math{1/@var{sizescale}} points, -where @var{sizescale} is specified in the @file{DESC} file (1@w{ }by +where @var{sizescale} is specified in the @file{DESC} file (1@tie{}by default). There is a new scale indicator @samp{z} which has the effect of multiplying by @var{sizescale}. Requests and escape sequences in @code{gtroff} interpret arguments that represent a point @@ -8984,10 +9666,10 @@ arguments to the @code{tkf} request, the argument to the @code{\H} escape sequence, and those variants of the @code{\s} escape sequence that take a numeric expression as their argument (see below). -For example, suppose @var{sizescale} is@w{ }1000; then a scaled point +For example, suppose @var{sizescale} is@tie{}1000; then a scaled point is equivalent to a millipoint; the request @w{@samp{.ps 10.25}} is equivalent to @w{@samp{.ps 10.25z}} and thus sets the point size to -10250@w{ }scaled points, which is equal to 10.25@w{ }points. +10250@tie{}scaled points, which is equal to 10.25@tie{}points. @code{gtroff} disallows the use of the @samp{z} scale indicator in instances where it would make no sense, such as a numeric @@ -9036,7 +9718,7 @@ fractional type sizes: @table @code @item \s[@var{n}] @itemx \s'@var{n}' -Set the point size to @var{n}@w{ }scaled points; @var{n}@w{ }is a numeric +Set the point size to @var{n}@tie{}scaled points; @var{n}@tie{}is a numeric expression with a default scale indicator of @samp{z}. @item \s[+@var{n}] @@ -9047,8 +9729,8 @@ expression with a default scale indicator of @samp{z}. @itemx \s'-@var{n}' @itemx \s+'@var{n}' @itemx \s-'@var{n}' -Increase or or decrease the point size by @var{n}@w{ }scaled points; -@var{n}@w{ }is a numeric expression with a default scale indicator of +Increase or or decrease the point size by @var{n}@tie{}scaled points; +@var{n}@tie{}is a numeric expression with a default scale indicator of @samp{z}. @end table @@ -9076,13 +9758,13 @@ even this is a read-write string variable). @cindex expansion of strings (@code{\*}) @cindex string arguments @cindex arguments, of strings -Define and access a string variable @var{name} (one-character name@w{ -}@var{n}, two-character name @var{nm}). If @var{name} already exists, -@code{ds} overwrites the previous definition. Only the syntax form +Define and access a string variable @var{name} (one-character +name@tie{}@var{n}, two-character name @var{nm}). If @var{name} already +exists, @code{ds} overwrites the previous definition. Only the syntax form using brackets can take arguments which are handled identically to macro arguments; the single exception is that a closing bracket as an -argument must be enclosed in double quotes. @xref{Request Arguments}, -and @ref{Parameters}. +argument must be enclosed in double quotes. @xref{Request and Macro +Arguments}, and @ref{Parameters}. Example: @@ -9290,12 +9972,12 @@ requests. @Defreq {substring, str n1 [@Var{n2}]} @cindex substring (@code{substring}) Replace the string named @var{str} with the substring -defined by the indices @var{n1} and@w{ }@var{n2}. The first character -in the string has index@w{ }0. If @var{n2} is omitted, it is taken to +defined by the indices @var{n1} and@tie{}@var{n2}. The first character +in the string has index@tie{}0. If @var{n2} is omitted, it is taken to be equal to the string's length. If the index value @var{n1} or @var{n2} is negative, it is counted from the end of the -string, going backwards: The last character has index@w{ }@minus{}1, the -character before the last character has index@w{ }@minus{}2, etc. +string, going backwards: The last character has index@tie{}@minus{}1, the +character before the last character has index@tie{}@minus{}2, etc. @Example .ds xxx abcdefgh @@ -9314,7 +9996,7 @@ number register @var{reg}. If @var{reg} doesn't exist, it is created. @Example .ds xxx abcd\h'3i'efgh -.length yyy \n[xxx] +.length yyy \*[xxx] \n[yyy] @result{} 14 @endExample @@ -9434,7 +10116,7 @@ match,@footnote{The created output nodes must be identical. font requests. In the previous example, @samp{|} and @samp{\fR|\fP} both result in a roman @samp{|} glyph with the same point size and at the same location on the page, so the strings are equal. If -@samp{.ft@w{ }I} had been added before the @samp{.ie}, the result +@samp{.ft@tie{}I} had been added before the @samp{.ie}, the result would be ``false'' because (the first) @samp{|} produces an italic @samp{|} rather than a roman one. @@ -9512,7 +10194,7 @@ more info. @Defreq{nop, anything} Executes @var{anything}. -This is similar to @code{.if@w{ }1}. +This is similar to @code{.if@tie{}1}. @endDefreq @DefreqList {ie, expr anything} @@ -9575,7 +10257,7 @@ request, which is used much like the @code{if} (and related) requests. @Defreq {while, expr anything} Evaluate the expression @var{expr}, and repeatedly execute @var{anything} (the remainder of the line) until @var{expr} evaluates -to@w{ }0. +to@tie{}0. @Example .nr a 0 1 @@ -9631,7 +10313,7 @@ instead which is parsed only once during its definition. @endExample @noindent -Note that the number of available recursion levels is set to@w{ }1000 +Note that the number of available recursion levels is set to@tie{}1000 (this is a compile-time constant value of @code{gtroff}). @item @@ -9769,13 +10451,13 @@ Note that macro identifiers are shared with identifiers for strings and diversions. @endDefreq -@DefreqList {am, xx} -@DefreqItem {am1, xx} -@DefreqListEnd {ami, xx yy} +@DefreqList {am, name [@Var{end}]} +@DefreqItem {am1, name [@Var{end}]} +@DefreqListEnd {ami, name [@Var{end}]} @cindex appending to a macro (@code{am}) @cindex macro, appending (@code{am}) Works similarly to @code{de} except it appends onto the macro named -@var{xx}. So, to make the previously defined @samp{P} macro actually +@var{name}. So, to make the previously defined @samp{P} macro actually do indented instead of block paragraphs, add the necessary code to the existing macro like this: @@ -9793,7 +10475,7 @@ the end. The @code{ami} request appends indirectly, meaning that @code{gtroff} expands strings whose names -are @var{xx} or @var{yy} before performing the append. +are @var{name} or @var{end} before performing the append. @pindex trace.tmac Using @file{trace.tmac}, you can trace calls to @code{am} and @code{am1}. @@ -9841,7 +10523,7 @@ evaluated (either at copy-in time or at the time of use) by insulating the escapes with an extra backslash. Compare this to the @code{\def} and @code{\edef} commands in @TeX{}. -The following example prints the numbers 20 and@w{ }10: +The following example prints the numbers 20 and@tie{}10: @Example .nr x 20 @@ -9880,17 +10562,17 @@ escapes: Retrieve the @var{n}@dmn{th}, @var{nn}@dmn{th} or @var{nnn}@dmn{th} argument. As usual, the first form only accepts a single number (larger than zero), the second a two-digit number (larger or equal -to@w{ }10), and the third any positive integer value (larger +to@tie{}10), and the third any positive integer value (larger than zero). Macros and strings can have an unlimited number of arguments. Note that due to copy-in mode, use two backslashes on these in actual use to prevent interpolation until the macro is actually invoked. @endDefesc @Defreq {shift, [@Var{n}]} -Shift the arguments 1@w{ }position, or as +Shift the arguments 1@tie{}position, or as many positions as specified by its argument. After executing this -request, argument@w{ }@var{i} becomes argument @math{@var{i}-@var{n}}; -arguments 1 to@w{ }@var{n} are no longer available. Shifting by +request, argument@tie{}@var{i} becomes argument @math{@var{i}-@var{n}}; +arguments 1 to@tie{}@var{n} are no longer available. Shifting by negative amounts is currently undefined. @endDefreq @@ -9902,7 +10584,7 @@ escape concatenates all the arguments separated by spaces. A similar escape is @code{\$@@}, which concatenates all the arguments with each surrounded by double quotes, and separated by spaces. If not in compatibility mode, the input level of double quotes -is preserved (see @ref{Request Arguments}). +is preserved (see @ref{Request and Macro Arguments}). @endDefesc @Defesc {\\$0, , , } @@ -9925,7 +10607,7 @@ The @code{als} request can make a macro have more than one name. @endExample @endDefesc -@xref{Request Arguments}. +@xref{Request and Macro Arguments}. @c ===================================================================== @@ -10030,7 +10712,7 @@ The following escapes give fine control of movements about the page. @cindex motion, vertical (@code{\v}) Move vertically, usually from the current location on the page (if no absolute position operator @samp{|} is used). The -argument@w{ }@var{e} specifies the distance to move; positive is +argument@tie{}@var{e} specifies the distance to move; positive is downwards and negative upwards. The default scaling indicator for this escape is @samp{v}. Beware, however, that @code{gtroff} continues text processing at the point where the motion ends, so you should always @@ -10044,15 +10726,15 @@ indicate continuation of a footnote or something similar. There are some special-case escapes for vertical motion. @Defesc {\\r, , , } -Move upwards@w{ }1@dmn{v}. +Move upwards@tie{}1@dmn{v}. @endDefesc @Defesc {\\u, , , } -Move upwards@w{ }.5@dmn{v}. +Move upwards@tie{}.5@dmn{v}. @endDefesc @Defesc {\\d, , , } -Move down@w{ }.5@dmn{v}. +Move down@tie{}.5@dmn{v}. @endDefesc @Defesc {\\h, ', e, '} @@ -10062,9 +10744,12 @@ Move down@w{ }.5@dmn{v}. @cindex horizontal motion (@code{\h}) @cindex motion, horizontal (@code{\h}) Move horizontally, usually from the current location (if no absolute -position operator @samp{|} is used). The expression@w{ }@var{e} +position operator @samp{|} is used). The expression@tie{}@var{e} indicates how far to move: positive is rightwards and negative leftwards. The default scaling indicator for this escape is @samp{m}. + +This horizontal space is not discarded at the end of a line. To insert +discardable space of a certain length use the @code{ss} request. @endDefesc There are a number of special-case escapes for horizontal motion. @@ -10135,7 +10820,8 @@ The highest and lowest point of the baseline, respectively, in @var{text}. @itemx rsb Like the @code{st} and @code{sb} registers, but takes account of the heights and depths of glyphs. With other words, this gives the -highest and lowest point of @var{text}. +highest and lowest point of @var{text}. Values below the baseline are +negative. @item ct Defines the kinds of glyphs occurring in @var{text}: @@ -10174,7 +10860,7 @@ over that glyph. @cindex position, horizontal input line, saving (@code{\k}) @cindex line, input, horizontal position, saving (@code{\k}) Store the current horizontal position in the @emph{input} line in -number register with name @var{position} (one-character name@w{ }@var{p}, +number register with name @var{position} (one-character name@tie{}@var{p}, two-character name @var{ps}). Use this, for example, to return to the beginning of a string for highlighting or other decoration. @endDefesc @@ -10196,7 +10882,7 @@ A read-only number register containing the current horizontal output position. @endDefreg -@Defesc {\\o, ', @Var{a}@Var{b}@Var{c}, '} +@Defesc {\\o, ', abc, '} @cindex overstriking glyphs (@code{\o}) @cindex glyphs, overstriking (@code{\o}) Overstrike glyphs @var{a}, @var{b}, @var{c}, @dots{}; the glyphs @@ -10249,8 +10935,8 @@ information. All drawing is done via escapes. -@DefescList {\\l, ', @Var{l}, '} -@DefescListEnd {\\l, ', @Var{l}@Var{g}, '} +@DefescList {\\l, ', l, '} +@DefescListEnd {\\l, ', lg, '} @cindex drawing horizontal lines (@code{\l}) @cindex horizontal line, drawing (@code{\l}) @cindex line, horizontal, drawing (@code{\l}) @@ -10268,7 +10954,7 @@ Default scaling indicator is @samp{m}. @cindex glyph, underscore (@code{\[ru]}) @cindex line drawing glyph @cindex glyph, for line drawing -The optional second parameter@w{ }@var{g} is a glyph to draw the line +The optional second parameter@tie{}@var{g} is a glyph to draw the line with. If this second argument is not specified, @code{gtroff} uses the underscore glyph, @code{\[ru]}. @@ -10295,8 +10981,8 @@ beginning of the @emph{input} line -- this works because the line length is negative, not moving the current point. @endDefesc -@DefescList {\\L, ', @Var{l}, '} -@DefescListEnd {\\L, ', @Var{l}@Var{g}, '} +@DefescList {\\L, ', l, '} +@DefescListEnd {\\L, ', lg, '} @cindex drawing vertical lines (@code{\L}) @cindex vertical line drawing (@code{\L}) @cindex line, vertical, drawing (@code{\L}) @@ -10335,7 +11021,8 @@ of the available drawing functions. The default scaling indicator for all subcommands of @code{\D} is @samp{m} for horizontal distances and @samp{v} for vertical ones. Exceptions are @w{@code{\D'f @dots{}'}} and @w{@code{\D't @dots{}'}} -which use @code{u} as the default. +which use @code{u} as the default, and @w{@code{\D'F@var{x} @dots{}'}} +which arguments are treated similar to the @code{defcolor} request. @table @code @item \D'l @var{dx} @var{dy}' @@ -10371,28 +11058,31 @@ containing the largest height and depth of the whole string. @item \D'c @var{d}' @cindex circle, drawing (@w{@code{\D'c @dots{}'}}) @cindex drawing a circle (@w{@code{\D'c @dots{}'}}) -Draw a circle with a diameter of@w{ }@var{d} with the leftmost point at the -current position. +Draw a circle with a diameter of@tie{}@var{d} with the leftmost point at the +current position. After drawing, the current location is positioned at the +rightmost point of the circle. @item \D'C @var{d}' @cindex circle, solid, drawing (@w{@code{\D'C @dots{}'}}) @cindex drawing a solid circle (@w{@code{\D'C @dots{}'}}) @cindex solid circle, drawing (@w{@code{\D'C @dots{}'}}) -Draw a solid circle with the same parameters as an outlined circle. No -outline is drawn. +Draw a solid circle with the same parameters and behaviour as an outlined +circle. No outline is drawn. @item \D'e @var{x} @var{y}' @cindex drawing an ellipse (@w{@code{\D'e @dots{}'}}) @cindex ellipse, drawing (@w{@code{\D'e @dots{}'}}) Draw an ellipse with a horizontal diameter of @var{x} and a vertical diameter of @var{y} with the leftmost point at the current position. +After drawing, the current location is positioned at the rightmost point of +the ellipse. @item \D'E @var{x} @var{y}' @cindex ellipse, solid, drawing (@w{@code{\D'E @dots{}'}}) @cindex drawing a solid ellipse (@w{@code{\D'E @dots{}'}}) @cindex solid ellipse, drawing (@w{@code{\D'E @dots{}'}}) -Draw a solid ellipse with the same parameters as an outlined ellipse. -No outline is drawn. +Draw a solid ellipse with the same parameters and behaviour as an +outlined ellipse. No outline is drawn. @item \D'a @var{dx1} @var{dy1} @var{dx2} @var{dy2}' @cindex arc, drawing (@w{@code{\D'a @dots{}'}}) @@ -10401,38 +11091,51 @@ Draw an arc clockwise from the current location through the two specified relative locations (@var{dx1},@var{dy1}) and (@var{dx2},@var{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. +relative to the first point. After drawing, the current position is moved +to the final point of the arc. @item \D'~ @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}' @cindex drawing a spline (@w{@code{\D'~ @dots{}'}}) @cindex spline, drawing (@w{@code{\D'~ @dots{}'}}) Draw a spline from the current location to the relative point (@var{dx1},@var{dy1}) and then to (@var{dx2},@var{dy2}), and so on. +The current position is moved to the terminal point of the drawn curve. @item \D'f @var{n}' @cindex gray shading (@w{@code{\D'f @dots{}'}}) @cindex shading filled objects (@w{@code{\D'f @dots{}'}}) -Set the shade of gray to be used for filling solid objects to@w{ -}@var{n}; @var{n}@w{ }must be an integer between 0 and@w{ }1000, where 0 +Set the shade of gray to be used for filling solid objects to@tie{}@var{n}; +@var{n}@tie{}must be an integer between 0 and@tie{}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@tie{}@var{n}. + +@cindex @w{@code{\D'f @dots{}'}} and horizontal resolution +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 @code{hor} keyword in the @file{DESC} file). Use +@code{\M} (@pxref{Colors}) or @w{@code{\D'Fg @dots{}'}} instead. + @item \D'p @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}' @cindex drawing a polygon (@w{@code{\D'p @dots{}'}}) @cindex polygon, drawing (@w{@code{\D'p @dots{}'}}) Draw a polygon from the current location to the relative position (@var{dx1},@var{dy1}) and then to (@var{dx2},@var{dy2}) and so on. When the specified data points are exhausted, a line is drawn back -to the starting point. +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. @item \D'P @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}' @cindex polygon, solid, drawing (@w{@code{\D'P @dots{}'}}) @cindex drawing a solid polygon (@w{@code{\D'P @dots{}'}}) @cindex solid polygon, drawing (@w{@code{\D'P @dots{}'}}) -Draw a solid polygon with the same parameters as an outlined polygon. -No outline is drawn. +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 @@ -10459,10 +11162,32 @@ text completely. @item \D't @var{n}' @cindex line thickness (@w{@code{\D't @dots{}'}}) @cindex thickness of lines (@w{@code{\D't @dots{}'}}) -Set the current line thickness to @var{n}@w{ }machine units. A value of +Set the current line thickness to @var{n}@tie{}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 @acronym{AT&T} @code{troff}). + +Despite of being silly, the current point is moved horizontally to the +right by@tie{}@var{n}. + +@item \D'F@var{scheme} @var{color_components}' +@cindex unnamed fill colors (@code{\D'F@dots{}'}) +@cindex fill colors, unnamed (@code{\D'F@dots{}'}) +@cindex colors, fill, unnamed (@code{\D'F@dots{}'}) +Change current fill color. @var{scheme} is a single letter denoting the +color scheme: @samp{r} (rgb), @samp{c} (cmy), @samp{k} (cmyk), @samp{g} +(gray), or @samp{d} (default color). The color components use exactly +the same syntax as in the @code{defcolor} request (@pxref{Colors}); the +command @code{\D'Fd'} doesn't take an argument. + +@emph{No} position changing! + +Examples: + +@Example +@endExample +\D'Fg .3' \" same gray as \D'f 700' +\D'Fr #0000ff' \" blue @end table @endDefesc @@ -10557,10 +11282,12 @@ 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 @code{.vpt} read-only number register. + +Note that a page can't be ejected if @code{vpt} is set to zero. @endDefreq @Defreq {wh, dist [@Var{macro}]} -Set a page location trap. Positive values for @var{dist} set +Set a page location trap. Non-negative values for @var{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 @samp{v}. @@ -10601,7 +11328,8 @@ 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 @code{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 @code{bp} request are omitted): +position (the many empty lines caused by the @code{bp} request are omitted +in the following example): @Example .de a @@ -10645,15 +11373,15 @@ integer which can be represented in @code{groff}) if there are no diversion traps. @endDefreg -@Defreq {ch, macro dist} +@Defreq {ch, macro [@Var{dist}]} @cindex changing trap location (@code{ch}) @cindex trap, changing location (@code{ch}) 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 the opposite of the @code{wh} -request). This is useful for building up footnotes in a diversion to -allow more space at the bottom of the page for them. +(note that the parameters are specified in opposite order as in the +@code{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 @var{dist} is @samp{v}. If @var{dist} is missing, the trap is removed. @@ -10672,6 +11400,9 @@ The read-only number register @code{.ne} contains the amount of space that was needed in the last @code{ne} request that caused a trap to be sprung. Useful in conjunction with the @code{.trunc} register. @xref{Page Control}, for more information. + +Since the @code{.ne} register is only set by traps it doesn't make +much sense to use it outside of trap macros. @endDefreg @Defreg {.trunc} @@ -10684,8 +11415,50 @@ produced by the @code{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 @code{.trunc} register is only set by traps and it doesn't make +much sense to use it outside of trap macros. +@endDefreg + +@Defreg {.pe} +@cindex @code{bp} request, and traps (@code{.pe}) +@cindex traps, sprung by @code{bp} request (@code{.pe}) +@cindex page ejecting register (@code{.pe}) +A read-only register which is set to@tie{}1 while a page is ejected with +the @code{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@tie{}@code{x} is caused by @code{bp}. + +@Example +.de x +\&.pe=\\n[.pe] +.br +.. +.wh 1v x +.wh 4v x +A line. +.br +Another line. +.br + @result{} A line. + .pe=0 + Another line. + + .pe=1 +@endExample @endDefreg +@cindex diversions, and traps +@cindex traps, and diversions +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 @code{\!} or +@code{\?}) since the data in the diversion is already formatted. In most +cases, this is not the expected behaviour. + @c --------------------------------------------------------------------- @node Diversion Traps, Input Line Traps, Page Location Traps, Traps @@ -10700,7 +11473,7 @@ actually is. @cindex trap, diversion, setting (@code{dt}) Set a trap @emph{within} a diversion. @var{dist} is the location of the trap -(identical to the @code{.wh} request; default scaling indicator is +(identical to the @code{wh} request; default scaling indicator is @samp{v}) and @var{macro} is the name of the macro to be invoked. The number register @code{.t} still works within diversions. @xref{Diversions}, for more information. @@ -10719,12 +11492,12 @@ number register @code{.t} still works within diversions. @cindex input line trap, setting (@code{it}) @cindex trap, input line, setting (@code{it}) Set an input line trap. -@var{n}@w{ }is the number of lines of input which may be read before +@var{n}@tie{}is the number of lines of input which may be read before springing the trap, @var{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 @var{n}@w{ }lines in a bold font. +next @var{n}@tie{}lines in a bold font. @Example .de B @@ -10741,9 +11514,9 @@ next @var{n}@w{ }lines in a bold font. @cindex interrupted lines and input line traps (@code{itc}) @cindex traps, input line, and interrupted lines (@code{itc}) @cindex lines, interrupted, and input line traps (@code{itc}) -The @code{itc} request is identical, -except that a line interrupted with @code{\c} -counts as one input line. +The @code{itc} request is identical +except that an interrupted text line (ending with @code{\c}) +is not counted as a separate line. Both requests are associated with the current environment (@pxref{Environments}); switching to another environment disables the @@ -10889,7 +11662,7 @@ Diversions may be nested. The read-only number register @code{.z} contains the name of the current diversion (this is a string-valued register). The read-only number register @code{.d} contains the current vertical place in the diversion. If not in a diversion it is the same -as the register @code{nl}. +as register @code{nl}. @endDefreg @Defreg {.h} @@ -10920,8 +11693,16 @@ in the return value of the @code{.h} register. @DefregList {dn} @DefregListEnd {dl} +@cindex @code{dn} register, and @code{da} (@code{boxa}) +@cindex @code{dl} register, and @code{da} (@code{boxa}) +@cindex @code{da} request, and @code{dn} (@code{dl}) +@cindex @code{boxa} request, and @code{dn} (@code{dl}) After completing a diversion, the read-write number registers @code{dn} and @code{dl} contain the vertical and horizontal size of the diversion. +Note that only the just processed lines are counted: For the computation +of @code{dn} and @code{dl}, the requests @code{da} and @code{boxa} are +handled as if @code{di} and @code{box} had been used -- lines which have +been already stored in a macro are not taken into account. @Example .\" Center text both horizontally & vertically @@ -10963,19 +11744,19 @@ and @code{dl} contain the vertical and horizontal size of the diversion. @endDefreg @DefescList {\\!, , , } -@DefescListEnd {\\?, , @Var{anything}, \\?} +@DefescListEnd {\\?, , anything, \\?} @cindex transparent output (@code{\!}, @code{\?}) @cindex output, transparent (@code{\!}, @code{\?}) Prevent requests, macros, and escapes from being -interpreted when read into a diversion. This takes the given text -and @dfn{transparently} embeds it into the diversion. This is useful for +interpreted when read into a diversion. Both escapes take the given text +and @dfn{transparently} embed it into the diversion. This is useful for macros which shouldn't be invoked until the diverted text is actually output. The @code{\!} escape transparently embeds text up to and including the end of the line. The @code{\?} escape transparently embeds text until the next -occurrence of the @code{\?} escape. For example: +occurrence of the @code{\?} escape. Example: @Example \?@var{anything}\? @@ -10986,7 +11767,7 @@ occurrence of the @code{\?} escape. For example: newlines in a diversion. The escape sequence @code{\?} is also recognized in copy mode and turned into a single internal code; it is this code that terminates @var{anything}. Thus the following example -prints@w{ }4. +prints@tie{}4. @Example .nr x 1 @@ -11027,7 +11808,7 @@ at all; its argument is simply ignored. @cindex @code{output} request, and @code{\!} @Defreq {output, string} Emit @var{string} directly to the @code{gtroff} intermediate output -(subject to copy-mode interpretation); this is similar to @code{\!} used +(subject to copy-mode interpretation); this is similar to @code{\!} used at the top level. An initial double quote in @var{string} is stripped off to allow initial blanks. @@ -11038,7 +11819,7 @@ Without argument, @code{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 @code{string} again. +the output device, filtering out @var{string} again. @endDefreq @Defreq {asciify, div} @@ -11050,7 +11831,7 @@ in such a way that @acronym{ASCII} characters, characters translated with the @code{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@w{ }@code{n} to@w{ }1. +hacks; for example, the following sets register@tie{}@code{n} to@tie{}1. @Example .tr @@. @@ -11090,7 +11871,7 @@ a trap invoked macro to print headers and footers. To solve this @code{gtroff} processes text in @dfn{environments}. An environment contains most of the parameters that control text processing. It is possible to switch amongst these environments; by -default @code{gtroff} processes text in environment@w{ }0. The +default @code{gtroff} processes text in environment@tie{}0. The following is the information kept in an environment. @itemize @bullet @@ -11194,24 +11975,42 @@ The number of consecutive hyphenated lines (set to zero). @end itemize @endDefreq -@DefregList {.cht} +@DefregList {.w} +@DefregItem {.cht} @DefregItem {.cdp} @DefregListEnd {.csk} -@cindex environment, last glyph +@cindex environment, dimensions of last glyph (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk}) +@cindex width, of last glyph (@code{.w}) +@cindex height, of last glyph (@code{.cht}) +@cindex depth, of last glyph (@code{.cdp}) +@cindex skew, of last glyph (@code{.csk}) +@cindex last glyph, dimensions (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk}) +@cindex glyph, last, dimensions (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk}) +The @code{\n[.w]} register contains the +width of the last glyph added to the current environment. + The @code{\n[.cht]} register contains the -maximum extent (above the baseline) -of the last glyph added to the current environment. +height of the last glyph added to the current environment. The @code{\n[.cdp]} register contains the -maximum extent (below the baseline) -of the last glyph added to the current environment. +depth of the last glyph added to the current environment. +It is positive for glyphs extending below the baseline. The @code{\n[.csk]} register contains the @dfn{skew} (how far to the right of the glyph's center -that @code{gtroff} shold place an accent) +that @code{gtroff} should place an accent) of the last glyph added to the current environment. @endDefreg +@Defreg {.n} +@cindex environment, previous line length (@code{.n}) +@cindex line length, previous (@code{.n}) +@cindex length of previous line (@code{.n}) +@cindex previous line length (@code{.n}) +The @code{\n[.n]} register contains the +length of the previous output line in the current environment. +@endDefreg + @c ===================================================================== @@ -11273,7 +12072,7 @@ End a nesting level. This escape is @code{grohtml} specific. Provided that this escape occurs at the outer nesting level write the @code{filename} to @code{stderr}. The position of the image, @var{P}, must be specified -and must be one of @code{l}, @code{r}, @code{c}, or@w{ }@code{i} (left, +and must be one of @code{l}, @code{r}, @code{c}, or@tie{}@code{i} (left, right, centered, inline). @var{filename} will be associated with the production of the next inline image. @end table @@ -11290,8 +12089,8 @@ production of the next inline image. If @var{n} is missing or non-zero, activate colors (this is the default); otherwise, turn it off. -The read-only number register @code{.color} is@w{ }1 if colors are active, -0@w{ }otherwise. +The read-only number register @code{.color} is@tie{}1 if colors are active, +0@tie{}otherwise. Internally, @code{color} sets a global flag; it does not produce a token. Similar to the @code{cp} request, you should use it at the beginning of @@ -11302,7 +12101,7 @@ Colors can be also turned off with the @option{-c} command line option. @Defreq {defcolor, ident scheme color_components} Define color with name @var{ident}. @var{scheme} can be one of the -following values: @code{rgb} (three components), @code{cym} (three +following values: @code{rgb} (three components), @code{cmy} (three components), @code{cmyk} (four components), and @code{gray} or @code{grey} (one component). @@ -11312,7 +12111,7 @@ 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 @code{#} or @code{##}; the former specifies hex values in the range -0--255 (which are internally multiplied by@w{ }257), the latter in the +0--255 (which are internally multiplied by@tie{}257), the latter in the range 0--65535. Examples: @code{#FFC0CB} (pink), @code{##ffff0000ffff} (magenta). The default color name @c{default} can't be redefined; its value is device-specific (usually black). It is possible that the @@ -11320,9 +12119,9 @@ default color for @code{\m} and @code{\M} is not identical. @cindex @code{f} unit, and colors @cindex unit, @code{f}, and colors -A new scaling indicator@w{ }@code{f} has been introduced which multiplies +A new scaling indicator@tie{}@code{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@w{ }1 (1f equals 65536u). Example: +as fractions in the range 0 to@tie{}1 (1f equals 65536u). Example: @Example .defcolor darkgreen rgb 0.1f 0.5f 0.2f @@ -11448,7 +12247,7 @@ Transparently output the contents of @var{file}. Each line is output as if it were preceded by @code{\!}; however, the lines are not subject to copy mode interpretation. If the file does not end with a newline, then a newline is added (@code{trf} only). For example, to define a -macro@w{ }@code{x} containing the contents of file@w{ }@file{f}, use +macro@tie{}@code{x} containing the contents of file@tie{}@file{f}, use @Example .di x @@ -11605,7 +12404,7 @@ document: @pindex perl @Example .sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\ - (localtime(time))[2,1,0]' > /tmp/x\n[$$] + (localtime(time))[2,1,0]' > /tmp/x\n[$$] .so /tmp/x\n[$$] .sy rm /tmp/x\n[$$] \nH:\nM:\nS @@ -11708,7 +12507,7 @@ Here a simple macro to write an index entry. @DefescItem {\\V, @lparen{}, ev, } @DefescListEnd {\\V, @lbrack{}, env, @rbrack} Interpolate the contents of the specified environment variable -@var{env} (one-character name@w{ }@var{e}, two-character name @var{ev}) +@var{env} (one-character name@tie{}@var{e}, two-character name @var{ev}) as returned by the function @code{getenv}. @code{\V} is interpreted in copy-in mode. @endDefesc @@ -11758,7 +12557,7 @@ Additionally, the backslash is represented as @code{\\}. @DefescItem {\\Y, @lparen{}, nm, } @DefescListEnd {\\Y, @lbrack{}, name, @rbrack} This is approximately equivalent to @samp{\X'\*[@var{name}]'} -(one-character name@w{ }@var{n}, two-character name @var{nm}). +(one-character name@tie{}@var{n}, two-character name @var{nm}). However, the contents of the string or macro @var{name} are not interpreted; also it is permitted for @var{name} to have been defined as a macro and thus contain newlines (it is not permitted for the @@ -11786,8 +12585,8 @@ categorized elsewhere in this manual. Print line numbers. @var{start} is the line number of the @emph{next} output line. @var{inc} indicates which line numbers are printed. -For example, the value@w{ }5 means to emit only line numbers which -are multiples of@w{ }5; this defaults to@w{ }1. @var{space} is the +For example, the value@tie{}5 means to emit only line numbers which +are multiples of@tie{}5; this defaults to@tie{}1. @var{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 @var{space} and @var{indent} are @@ -11850,7 +12649,7 @@ And here the result: @Defreq {nn, [@Var{skip}]} Temporarily turn off line numbering. The argument is the number -of lines not to be numbered; this defaults to@w{ }1. +of lines not to be numbered; this defaults to@tie{}1. @endDefreq @Defreq {mc, glyph [@Var{dist}]} @@ -11953,7 +12752,7 @@ are valid input. @xref{Identifiers}, for more on this topic. For example, the input string @samp{fi\[:u]} is converted into a character token @samp{f}, a character token @samp{i}, and a special -token @samp{:u} (representing u@w{ }umlaut). Later on, the character +token @samp{:u} (representing u@tie{}umlaut). Later on, the character tokens @samp{f} and @samp{i} are merged to a single output node representing the ligature glyph @samp{fi} (provided the current font has a glyph for this ligature); the same happens with @samp{:u}. All @@ -11994,7 +12793,7 @@ It contains these elements. @cindex @code{\v}, internal representation @noindent -Elements 1, 7, and@w{ }8 are inserted by @code{gtroff}; the latter two +Elements 1, 7, and@tie{}8 are inserted by @code{gtroff}; the latter two (which are always present) specify the vertical extent of the last line, possibly modified by @code{\x}. The @code{br} request finishes the current partial line, inserting a newline input token which is @@ -12049,22 +12848,26 @@ of the fallback glyph. Anyway, the translation is still active; @code{gtroff} is not easy to debug, but there are some useful features and strategies for debugging. -@Defreq {lf, line filename} +@Defreq {lf, line [@Var{filename}]} @pindex soelim @cindex multi-file documents @cindex documents, multi-file @cindex setting input line number (@code{lf}) @cindex input line number, setting (@code{lf}) @cindex number, input line, setting (@code{lf}) -Change the line number and the file name @code{gtroff} shall use for -error and warning messages. @var{line} is the input line number of the -@emph{next} line. +Change the line number and optionally the file name @code{gtroff} shall +use for error and warning messages. @var{line} is the input line number +of the @emph{next} line. Without argument, the request is ignored. This is a debugging aid for documents which are split into many files, then put together with @code{soelim} and other preprocessors. Usually, it isn't invoked manually. + +Note that other @code{troff} implementations (including the original +@acronym{AT&T} version) handle @code{lf} differently. For them, +@var{line} changes the line number of the @emph{current} line. @endDefreq @DefreqList {tm, string} @@ -12196,7 +12999,7 @@ this request on each error and warning. @cindex input stack, setting limit Use the @code{slimit} number register to set the maximum number of objects on the input stack. -If @code{slimit} is less than or equal to@w{ }0, +If @code{slimit} is less than or equal to@tie{}0, there is no limit set. With no limit, a buggy recursive macro can exhaust virtual memory. @@ -12336,7 +13139,7 @@ for each name. @cindex @code{\R}, and warnings @cindex @code{\n}, and warnings Use of undefined number registers. When an undefined number register is -used, that register is automatically defined to have a value of@w{ }0. +used, that register is automatically defined to have a value of@tie{}0. So, in most cases, at most one warning is given for use of a particular name. @@ -12437,8 +13240,8 @@ interpreted as the start of a long name. In compatibility mode GNU If @var{n} is missing or non-zero, turn on compatibility mode; otherwise, turn it off. -The read-only number register @code{.C} is@w{ }1 if compatibility mode is -on, 0@w{ }otherwise. +The read-only number register @code{.C} is@tie{}1 if compatibility mode is +on, 0@tie{}otherwise. Compatibility mode can be also turned on with the @option{-C} command line option. @@ -12490,6 +13293,7 @@ Hallo! \fB.xx\fP @endExample +@noindent prints @samp{Hallo!} in bold face if in compatibility mode, and @samp{.xx} in bold face otherwise. @@ -12530,8 +13334,8 @@ indicators and thus @endExample @noindent -sets the point size to 10@w{ }points, whereas in GNU @code{troff} it -sets the point size to 10@w{ }scaled points. @xref{Fractional Type +sets the point size to 10@tie{}points, whereas in GNU @code{troff} it +sets the point size to 10@tie{}scaled points. @xref{Fractional Type Sizes}, for more information. @cindex @code{bd} request, incompatibilities with @acronym{AT&T} @code{troff} @@ -12716,7 +13520,7 @@ A free implementation of @code{grap}, written by Ted Faber, is available as an extra package from the following address: @display -@url{http://www.lunabase.org/~faber/Vault/software/grap/} +@uref{http://www.lunabase.org/~faber/Vault/software/grap/} @end display @@ -13065,7 +13869,7 @@ postprocessors. This parser is smarter on whitespace and implements obsolete elements for compatibility, otherwise both formats are the same.@footnote{The parser and postprocessor for intermediate output can be found in the file@* -@file{@var{groff-source-dir}/src/libs/libdriver/input.cc}.} +@file{@var{groff-source-dir}/src/libs/libdriver/input.cpp}.} The main purpose of the intermediate output concept is to facilitate the development of postprocessors by providing a common programming @@ -13279,15 +14083,15 @@ position; the glyph's size is read from the font file. The print position is not changed. @item c @var{g} -Print glyph@w{ }@var{g} at the current print position;@footnote{@samp{c} +Print glyph@tie{}@var{g} at the current print position;@footnote{@samp{c} is actually a misnomer since it outputs a glyph.} the glyph's size is read from the font file. The print position is not changed. @item f @var{n} -Set font to font number@w{ }@var{n} (a non-negative integer). +Set font to font number@tie{}@var{n} (a non-negative integer). @item H @var{n} -Move right to the absolute vertical position@w{ }@var{n} (a +Move right to the absolute vertical position@tie{}@var{n} (a non-negative integer in basic units @samp{u} relative to left edge of current page. @@ -13308,7 +14112,7 @@ These commands are a @code{gtroff} extension. @table @code @item mc @var{cyan} @var{magenta} @var{yellow} -Set color using the CMY color scheme, having the 3@w{ }color components +Set color using the CMY color scheme, having the 3@tie{}color components @var{cyan}, @var{magenta}, and @var{yellow}. @item md @@ -13320,37 +14124,37 @@ Set color to the shade of gray given by the argument, an integer between 0 (black) and 65536 (white). @item mk @var{cyan} @var{magenta} @var{yellow} @var{black} -Set color using the CMYK color scheme, having the 4@w{ }color components +Set color using the CMYK color scheme, having the 4@tie{}color components @var{cyan}, @var{magenta}, @var{yellow}, and @var{black}. @item mr @var{red} @var{green} @var{blue} -Set color using the RGB color scheme, having the 3@w{ }color components +Set color using the RGB color scheme, having the 3@tie{}color components @var{red}, @var{green}, and @var{blue}. @end table @item N @var{n} -Print glyph with index@w{ }@var{n} (a non-negative integer) of the +Print glyph with index@tie{}@var{n} (a non-negative integer) of the current font. This command is a @code{gtroff} extension. @item n @var{b} @var{a} Inform the device about a line break, but no positioning is done by this command. In @acronym{AT&T} @code{troff}, the integer arguments -@var{b} and@w{ }@var{a} informed about the space before and after the +@var{b} and@tie{}@var{a} informed about the space before and after the current line to make the intermediate output more human readable without performing any action. In @code{groff}, they are just ignored, but they must be provided for compatibility reasons. @item p @var{n} Begin a new page in the outprint. The page number is set -to@w{ }@var{n}. This page is completely independent of pages formerly +to@tie{}@var{n}. This page is completely independent of pages formerly processed even if those have the same page number. The vertical -position on the outprint is automatically set to@w{ }0. All +position on the outprint is automatically set to@tie{}0. All positioning, writing, and drawing is always done relative to a page, so a @samp{p} command must be issued before any of these commands. @item s @var{n} -Set point size to @var{n}@w{ }scaled points (this is unit @samp{z}). +Set point size to @var{n}@tie{}scaled points (this is unit @samp{z}). @acronym{AT&T} @code{troff} used the unit points (@samp{p}) instead. @xref{Output Language Compatibility}. @@ -13374,18 +14178,18 @@ file contains the @code{tcommand} keyword (@pxref{DESC File Format}). Print word with track kerning. This is the same as the @samp{t} command except that after printing each glyph, the current horizontal position is increased by the sum of the width of that -glyph and@w{ }@var{n} (an integer in basic units @samp{u}). +glyph and@tie{}@var{n} (an integer in basic units @samp{u}). This command is a @code{gtroff} extension; it is only used for devices whose @file{DESC} file contains the @code{tcommand} keyword (@pxref{DESC File Format}). @item V @var{n} -Move down to the absolute vertical position@w{ }@var{n} (a +Move down to the absolute vertical position@tie{}@var{n} (a non-negative integer in basic units @samp{u}) relative to upper edge of current page. @item v @var{n} -Move @var{n}@w{ }basic units @samp{u} down (@var{n} is a non-negative +Move @var{n}@tie{}basic units @samp{u} down (@var{n} is a non-negative integer). The original @acronym{UNIX} troff manual allows negative values for @var{n} also, but @code{gtroff} doesn't use this. @@ -13422,9 +14226,8 @@ negative left. The arguments called @var{v1}, @var{v2}, @dots{}, negative up. All these distances are offsets relative to the current location. -Unless indicated otherwise, each graphics command directly corresponds -to a similar @code{gtroff} @code{\D} escape sequence. @xref{Drawing -Requests}. +Each graphics command directly corresponds to a similar @code{gtroff} +@code{\D} escape sequence. @xref{Drawing Requests}. Unknown @samp{D} commands are assumed to be device-specific. Its arguments are parsed as strings; the whole information is then @@ -13450,27 +14253,27 @@ of the arc. @item DC @var{d}@angles{line break} @itemx DC @var{d} @var{dummy-arg}@angles{line break} Draw a solid circle using the current fill color with -diameter@w{ }@var{d} (integer in basic units @samp{u}) with leftmost +diameter@tie{}@var{d} (integer in basic units @samp{u}) with leftmost point at the current position; then move the current position to the rightmost point of the circle. An optional second integer argument is ignored (this allows the formatter to generate an even number of arguments). This command is a @code{gtroff} extension. @item Dc @var{d}@angles{line break} -Draw circle line with diameter@w{ }@var{d} (integer in basic units +Draw circle line with diameter@tie{}@var{d} (integer in basic units @samp{u}) with leftmost point at the current position; then move the current position to the rightmost point of the circle. @item DE @var{h} @var{v}@angles{line break} Draw a solid ellipse in the current fill color with a horizontal -diameter of@w{ }@var{h} and a vertical diameter of@w{ }@var{v} (both +diameter of@tie{}@var{h} and a vertical diameter of@tie{}@var{v} (both integers in basic units @samp{u}) with the leftmost point at the current position; then move to the rightmost point of the ellipse. This command is a @code{gtroff} extension. @item De @var{h} @var{v}@angles{line break} -Draw an outlined ellipse with a horizontal diameter of@w{ }@var{h} -and a vertical diameter of@w{ }@var{v} (both integers in basic units +Draw an outlined ellipse with a horizontal diameter of@tie{}@var{h} +and a vertical diameter of@tie{}@var{v} (both integers in basic units @samp{u}) with the leftmost point at current position; then move to the rightmost point of the ellipse. @@ -13488,7 +14291,7 @@ is a @code{gtroff} extension. @table @code @item DFc @var{cyan} @var{magenta} @var{yellow}@angles{line break} Set fill color for solid drawing objects using the CMY color scheme, -having the 3@w{ }color components @var{cyan}, @var{magenta}, and +having the 3@tie{}color components @var{cyan}, @var{magenta}, and @var{yellow}. @item DFd@angles{line break} @@ -13501,17 +14304,17 @@ the argument, an integer between 0 (black) and 65536 (white). @item DFk @var{cyan} @var{magenta} @var{yellow} @var{black}@angles{line break} Set fill color for solid drawing objects using the CMYK color scheme, -having the 4@w{ }color components @var{cyan}, @var{magenta}, @var{yellow}, +having the 4@tie{}color components @var{cyan}, @var{magenta}, @var{yellow}, and @var{black}. @item DFr @var{red} @var{green} @var{blue}@angles{line break} Set fill color for solid drawing objects using the RGB color scheme, -having the 3@w{ }color components @var{red}, @var{green}, and @var{blue}. +having the 3@tie{}color components @var{red}, @var{green}, and @var{blue}. @end table @item Df @var{n}@angles{line break} -The argument@w{ }@var{n} must be an integer in the range @math{-32767} +The argument@tie{}@var{n} must be an integer in the range @math{-32767} to 32767. @table @asis @@ -13521,7 +14324,7 @@ where 0 corresponds to solid white, 1000 (the default) to solid black, and values in between to intermediate shades of gray; this is obsoleted by command @samp{DFg}. -@item @math{@var{n} @LT 0} or @math{@var{n} @LT 1000} +@item @math{@var{n} < 0} or @math{@var{n} > 1000} Set the filling color to the color that is currently being used for the text and the outline, see command @samp{m}. For example, the command sequence @@ -13568,7 +14371,7 @@ No position changing. This command is a @code{gtroff} extension. @item Dt @var{n}@angles{line break} -Set the current line thickness to@w{ }@var{n} (an integer in basic +Set the current line thickness to@tie{}@var{n} (an integer in basic units @samp{u}) if @math{@var{n}>0}; if @math{@var{n}=0} select the smallest available line thickness; if @math{@var{n}<0} set the line thickness proportional to the point size (this is the default before @@ -13616,13 +14419,13 @@ not changed by this command. This command is a @code{gtroff} extension. @item xf @var{n} @var{s}@angles{line break} The @samp{f} stands for @var{font}. -Mount font position@w{ }@var{n} (a non-negative integer) with font -named@w{ }@var{s} (a text word). @xref{Font Positions}. +Mount font position@tie{}@var{n} (a non-negative integer) with font +named@tie{}@var{s} (a text word). @xref{Font Positions}. @item xH @var{n}@angles{line break} The @samp{H} stands for @var{Height}. -Set glyph height to@w{ }@var{n} (a positive integer in scaled +Set glyph height to@tie{}@var{n} (a positive integer in scaled points @samp{z}). @acronym{AT&T} @code{troff} uses the unit points (@samp{p}) instead. @xref{Output Language Compatibility}. @@ -13643,7 +14446,7 @@ pause device, can be restarted @item xr @var{n} @var{h} @var{v}@angles{line break} The @samp{r} stands for @var{resolution}. -Resolution is@w{ }@var{n}, while @var{h} is the minimal horizontal +Resolution is@tie{}@var{n}, while @var{h} is the minimal horizontal motion, and @var{v} the minimal vertical motion possible with this device; all arguments are positive integers in basic units @samp{u} per inch. This is the second command of the prologue. @@ -13651,7 +14454,7 @@ per inch. This is the second command of the prologue. @item xS @var{n}@angles{line break} The @samp{S} stands for @var{Slant}. -Set slant to@w{ }@var{n} (an integer in basic units @samp{u}). +Set slant to@tie{}@var{n} (an integer in basic units @samp{u}). @item xs@angles{line break} The @samp{s} stands for @var{stop}. @@ -13676,8 +14479,8 @@ command of the prologue. @item xu @var{n}@angles{line break} The @samp{u} stands for @var{underline}. -Configure underlining of spaces. If @var{n} is@w{ }1, start -underlining of spaces; if @var{n} is@w{ }0, stop underlining of spaces. +Configure underlining of spaces. If @var{n} is@tie{}1, start +underlining of spaces; if @var{n} is@tie{}0, stop underlining of spaces. This is needed for the @code{cu} request in nroff mode and is ignored otherwise. This command is a @code{gtroff} extension. @@ -13702,12 +14505,12 @@ In @acronym{AT&T} @code{troff} output, the writing of a single glyph is mostly done by a very strange command that combines a horizontal move and a single character giving the glyph name. It doesn't have a command code, but is represented by a 3-character -argument consisting of exactly 2@w{ }digits and a character. +argument consisting of exactly 2@tie{}digits and a character. @table @asis @item @var{dd}@var{g} Move right @var{dd} (exactly two decimal digits) basic units @samp{u}, -then print glyph@w{ }@var{g} (represented as a single character). +then print glyph@tie{}@var{g} (represented as a single character). In @code{gtroff}, arbitrary syntactical space around and within this command is allowed to be added. Only when a preceding command on the @@ -13818,7 +14621,7 @@ document. @item @acronym{AT&T} @code{troff} output Since a computer monitor has a very low resolution compared to modern -printers the intermediate output for the X@w{ }Window devices can use +printers the intermediate output for the X@tie{}Window devices can use the jump-and-write command with its 2-digit displacements. @example @@ -13847,7 +14650,7 @@ x stop @noindent This output can be fed into @code{xditview} or @code{gxditview} -for displaying in@w{ }X. +for displaying in@tie{}X. Due to the obsolete jump-and-write command, the text clusters in the @acronym{AT&T} @code{troff} output are almost unreadable. @@ -13934,11 +14737,11 @@ The @code{gtroff} font format is roughly a superset of the @code{ditroff} font format (as used in later versions of @acronym{AT&T} @code{troff} and its descendants). Unlike the @code{ditroff} font format, there is no associated binary format; all files are text -files.@footnote{Plan@w{ }9 @code{troff} has also abandoned the binary +files.@footnote{Plan@tie{}9 @code{troff} has also abandoned the binary format.} The font files for device @var{name} are stored in a directory @file{dev@var{name}}. There are two types of file: a device description -file called @file{DESC} and for each font@w{ }@var{f} a font file -called@w{ }@file{@var{f}}. +file called @file{DESC} and for each font@tie{}@var{f} a font file +called@tie{}@file{@var{f}}. @menu * DESC File Format:: @@ -13961,19 +14764,27 @@ order of the lines is not important. @table @code @item res @var{n} @kindex res -There are @var{n}@w{ }machine units per inch. +@cindex device resolution +@cindex resolution, device +There are @var{n}@tie{}machine units per inch. @item hor @var{n} @kindex hor -The horizontal resolution is @var{n}@w{ }machine units. +@cindex horizontal resolution +@cindex resolution, horizontal +The horizontal resolution is @var{n}@tie{}machine units. All horizontal +quantities are rounded to be multiples of this value. @item vert @var{n} @kindex vert -The vertical resolution is @var{n}@w{ }machine units. +@cindex vertical resolution +@cindex resolution, vertical +The vertical resolution is @var{n}@tie{}machine units. All vertical +quantities are rounded to be multiples of this value. @item sizescale @var{n} @kindex sizescale -The scale factor for point sizes. By default this has a value of@w{ }1. +The scale factor for point sizes. By default this has a value of@tie{}1. One scaled point is equal to one point/@var{n}. The arguments to the @code{unitwidth} and @code{sizes} commands are given in scaled points. @xref{Fractional Type Sizes}, for more information. @@ -13981,7 +14792,7 @@ One scaled point is equal to one point/@var{n}. The arguments to the @item unitwidth @var{n} @kindex unitwidth Quantities in the font files are given in machine units for fonts whose -point size is @var{n}@w{ }scaled points. +point size is @var{n}@tie{}scaled points. @item prepro @var{program} @kindex prepro @@ -14008,13 +14819,13 @@ intermediate output commands. @item sizes @var{s1} @var{s2} @dots{} @var{sn} 0 @kindex sizes This means that the device has fonts at @var{s1}, @var{s2}, @dots{} -@var{sn} scaled points. The list of sizes must be terminated by@w{ }0 +@var{sn} scaled points. The list of sizes must be terminated by@tie{}0 (this is digit zero). Each @var{si} can also be a range of sizes @var{m}-@var{n}. The list can extend over more than one line. @item styles @var{S1} @var{S2} @dots{} @var{Sm} @kindex styles -The first @var{m}@w{ }font positions are associated with styles +The first @var{m}@tie{}font positions are associated with styles @var{S1} @dots{} @var{Sm}. @item fonts @var{n} @var{F1} @var{F2} @var{F3} @dots{} @var{Fn} @@ -14022,7 +14833,7 @@ The first @var{m}@w{ }font positions are associated with styles Fonts @var{F1} @dots{} @var{Fn} are mounted in the font positions @var{m}+1, @dots{}, @var{m}+@var{n} where @var{m} is the number of styles. This command may extend over more than one line. A font name -of@w{ }0 means no font is mounted on the corresponding font position. +of@tie{}0 means no font is mounted on the corresponding font position. @item family @var{fam} @kindex family @@ -14085,7 +14896,6 @@ Here a list of obsolete keywords which are recognized by @code{groff} but completely ignored: @code{spare1}, @code{spare2}, @code{biggestfont}. - @c --------------------------------------------------------------------- @node Font File Format, , DESC File Format, Font Files @@ -14104,15 +14914,15 @@ key. @table @code @item name @var{f} @kindex name -The name of the font is@w{ }@var{f}. +The name of the font is@tie{}@var{f}. @item spacewidth @var{n} @kindex spacewidth -The normal width of a space is@w{ }@var{n}. +The normal width of a space is@tie{}@var{n}. @item slant @var{n} @kindex slant -The glyphs of the font have a slant of @var{n}@w{ }degrees. +The glyphs of the font have a slant of @var{n}@tie{}degrees. (Positive means forward.) @item ligatures @var{lig1} @var{lig2} @dots{} @var{lign} [0] @@ -14120,7 +14930,7 @@ The glyphs of the font have a slant of @var{n}@w{ }degrees. Glyphs @var{lig1}, @var{lig2}, @dots{}, @var{lign} are ligatures; possible ligatures are @samp{ff}, @samp{fi}, @samp{fl}, @samp{ffi} and @samp{ffl}. For backwards compatibility, the list of ligatures may be -terminated with a@w{ }0. The list of ligatures may not extend over more +terminated with a@tie{}0. The list of ligatures may not extend over more than one line. @item special @@ -14171,8 +14981,8 @@ tabs. The format is input, characters, and output, glyphs, is not clearly separated in the terminology of @code{groff}; for example, the @code{char} request should be called @code{glyph} since it defines an output entity.}: -If @var{name} is a single character@w{ }@var{c} then it corresponds -to the @code{gtroff} input character@w{ }@var{c}; if it is of the form +If @var{name} is a single character@tie{}@var{c} then it corresponds +to the @code{gtroff} input character@tie{}@var{c}; if it is of the form @samp{\@var{c}} where @var{c} is a single character, then it corresponds to the special character @code{\[@var{c}]}; otherwise it corresponds to the special character @samp{\[@var{name}]}. If it @@ -14184,9 +14994,9 @@ is identical to @code{\[-]}. @code{gtroff} supports 8-bit input characters; however some utilities have difficulties with eight-bit characters. For this reason, there is a convention that the entity name @samp{char@var{n}} is equivalent to -the single input character whose code is@w{ }@var{n}. For example, -@samp{char163} would be equivalent to the character with code@w{ }163 -which is the pounds sterling sign in the @w{ISO Latin-1} character set. +the single input character whose code is@tie{}@var{n}. For example, +@samp{char163} would be equivalent to the character with code@tie{}163 +which is the pounds sterling sign in the ISO@tie{}@w{Latin-1} character set. You shouldn't use @samp{char@var{n}} entities in font description files since they are related to input, not output. Otherwise, you get hard-coded connections between input and output encoding which @@ -14239,7 +15049,7 @@ The @var{metrics} field has the form: @noindent There must not be any spaces between these subfields (it has been split here into two lines for better legibility only). Missing subfields are -assumed to be@w{ }0. The subfields are all decimal integers. Since +assumed to be@tie{}0. The subfields are all decimal integers. Since there is no associated binary format, these values are not required to fit into a variable of type @samp{char} as they are in @code{ditroff}. The @var{width} subfield gives the width of the glyph. The @var{height} @@ -14279,8 +15089,8 @@ sequence of lines of the form: @noindent This means that when glyph @var{c1} appears next to glyph @var{c2} -the space between them should be increased by@w{ }@var{n}. Most -entries in the kernpairs section have a negative value for@w{ }@var{n}. +the space between them should be increased by@tie{}@var{n}. Most +entries in the kernpairs section have a negative value for@tie{}@var{n}. @@ -14354,7 +15164,7 @@ emits a warning, printing glyph @var{X}. The macro package or program a specific register belongs to is appended in brackets. -A register name@w{ }@code{x} consisting of exactly one character can be +A register name@tie{}@code{x} consisting of exactly one character can be accessed as @samp{\nx}. A register name @code{xx} consisting of exactly two characters can be accessed as @samp{\n(xx}. Register names @code{xxx} of any length can be accessed as @samp{\n[xxx]}. @@ -14385,7 +15195,7 @@ They appear without the leading control character (normally @samp{.}). The macro package or program a specific string belongs to is appended in brackets. -A string name@w{ }@code{x} consisting of exactly one character can be +A string name@tie{}@code{x} consisting of exactly one character can be accessed as @samp{\*x}. A string name @code{xx} consisting of exactly two characters can be accessed as @samp{\*(xx}. String names @code{xxx} of any length can be accessed as @samp{\*[xxx]}. |
