gbranden pushed a commit to branch master in repository groff. commit acae9d3827237c702ea5fc3315a7f35273f757e0 Author: G. Branden Robinson <g.branden.robin...@gmail.com> AuthorDate: Thu Aug 11 17:32:11 2022 -0500
[docs]: Fix content, style, and markup nits. * man/groff_font.5.man: - Tighten wording. - Use RS/RE macro pairs to inset syntax synopsis within a paragraph instead of `IP`, which starts a new one. * src/roff/groff/groff.1.man: - Mention the "pager problem"; these programs often do violence to the terminal escape sequences emitted by grotty(1). Tell the reader where to find more information. - Update example to use installed groff command names. - Recast to avoid using examples as a hatch to escape sentence-terminal puncutation. - Fix man page rendering example to remove ".man" suffix, an artifact of the groff source tree. - Tighten wording. * doc/groff.texi (Invocation Examples): Sync with content of "Examples" section of groff(1), and annotate synchrony. (Font Description File Format): Sync with groff_font(5) changes. (Invoking groff): Mark chapter as reviewed for quotation mark usage. --- doc/groff.texi | 97 +++++++++++++++++++++++++++------------------- man/groff_font.5.man | 27 ++++++------- src/roff/groff/groff.1.man | 23 ++++++----- 3 files changed, 83 insertions(+), 64 deletions(-) diff --git a/doc/groff.texi b/doc/groff.texi index 073fa98b3..b79f7655a 100644 --- a/doc/groff.texi +++ b/doc/groff.texi @@ -846,6 +846,9 @@ contributed much of the material on the @file{ms} macro package. @c ===================================================================== @c ===================================================================== +@codequotebacktick on +@codequoteundirected on + @node Invoking groff, Tutorial for Macro Users, Introduction, Top @chapter Invoking @code{groff} @cindex invoking @code{groff} @@ -1307,9 +1310,6 @@ Do not postprocess the output of @code{gtroff}. Normally @code{groff} automatically runs the appropriate postprocessor. @end table -@codequotebacktick off -@codequoteundirected off - @c ===================================================================== @@ -1581,57 +1581,73 @@ groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps @c ===================================================================== +@c BEGIN Keep parallel with groff(1), section "Examples". @node Invocation Examples, , Paper Size, Invoking groff @section Invocation Examples @cindex invocation examples @cindex examples of invocation -This section lists several common uses of @code{groff} and the -corresponding command lines. +@code{roff} systems are best known for formatting man pages. Once a +@command{man} librarian program has located a man page, it may execute +a @code{groff} command much like the following. @Example -groff file +groff -t -man -Tutf8 /usr/share/man/man1/groff.1 @endExample -@noindent -This command processes @file{file} without a macro package or a -preprocessor. The output device is the default, @samp{ps}, and the -output is sent to @code{stdout}. +The librarian will also pipe the output through a pager, which might not +interpret the SGR terminal escape sequences @command{groff} emits for +boldface, underlining, or italics; see the @cite{grotty@r{(1)}} man page +for a discussion. + +To process a @code{roff} input file using the preprocessors +@command{gtbl} and @command{gpic} and the @file{me} macro package in the +way to which AT&T @code{troff} users were accustomed, one would type (or +script) a pipeline. @Example -groff -t -mandoc -Tascii file | less +gpic foo.me | gtbl | gtroff -me -Tutf8 | grotty @endExample -@noindent -This is basically what a call to the @code{man} program does. GNU -@code{troff} processes the man page @file{file} with the @file{mandoc} -macro file (which in turn loads either the @file{man} or the @file{mdoc} -macro package), using the @command{tbl} preprocessor and the -@code{ascii} output device. Finally, the @command{less} pager displays -the result. +Using @command{groff}, this pipe can be shortened to an equivalent +command. + +@Example +groff -p -t -me -T utf8 foo.me +@endExample + +An even easier way to do this is to use @command{grog} to guess the +preprocessor and macro options and execute the result by using the +command substitution feature of the shell. @Example -groff -X -m me file +$(grog -Tutf8 foo.me) +@endExample + +Each command-line option to a postprocessor must be specified with any +required leading dashes @samp{-} +@c No GNU roff postprocessor uses long options for anything except +@c --help or --version. +@c or @samp{--} +because @command{groff} passes the arguments as-is to the postprocessor; +this permits arbitrary arguments to be transmitted. For example, to +pass a title to the @command{gxditview} postprocessor, +the shell commands + +@Example +groff -X -P -title -P 'trial run' mydoc.t @endExample @noindent -Preview @file{file} with @code{gxditview}, using the @file{me} macro -package. Since no @option{-T} option is specified, use the default -device (@samp{ps}). You can say either @w{@samp{-m me}} or -@w{@samp{-me}}; the latter is an anachronism from the early days of -Unix.@footnote{The same is true for the other major macro packages that -come with @code{groff}: @file{man}, @file{mdoc}, @file{ms}, @file{mm}, -and @file{mandoc}. This won't work in general; for example, to load -@file{trace.tmac}, either @samp{-mtrace} or @w{@samp{-m trace}} must be -used.} +and @Example -groff -man -rD1 -z file +groff -X -Z mydoc.t | gxditview -title 'trial run' - @endExample @noindent -Check @file{file} with the @file{man} macro package, forcing -double-sided printing---don't produce any output. +are equivalent. +@c END Keep parallel with groff(1), section "Examples". @menu * grog:: @@ -1680,6 +1696,9 @@ As this example shows, it is still necessary to redirect the output to something meaningful (i.e., either a file or a pager program like @code{less}). +@codequotebacktick off +@codequoteundirected off + @c ===================================================================== @@ -18168,8 +18187,8 @@ featural description of the glyph: it is a bit mask recording whether the glyph is an ascender, descender, both, or neither. When a @code{\w} escape sequence is interpolated, these values are bitwise or-ed together for each glyph and stored in the @code{nr} register. In font -descriptions for @code{nroff}-mode output devices (terminals), all -glyphs might have a type of zero. +descriptions for terminal devices, all glyphs might have a type of zero, +regardless of their appearance. @table @code @item 0 @@ -18205,20 +18224,20 @@ For efficiency, these data are now compiled directly into arrays for PostScript fonts containing more than 256 glyphs. Anything on the line after the @var{entity-name} field or @samp{--} is ignored. -A line in the @code{charset} section can also have the following format. +A line in the @code{charset} section can also have the form @Example @var{name} " @endExample @noindent -This notation indicates that @var{name} is another name for the glyph -named on the preceding line. Such aliases can be chained. +identifying @var{name} as another name for the glyph mentioned in the +preceding line. Such aliases can be chained. @kindex kernpairs -The word @code{kernpairs} starts a list of kerning adjustments to be -made to adjacent glyph pairs from this font. It contains a sequence of -lines formatted as follows. +The directive @code{kernpairs} starts a list of kerning adjustments to +be made to adjacent glyph pairs from this font. It contains a sequence +of lines formatted as follows. @Example @var{g1} @var{g2} @var{n} diff --git a/man/groff_font.5.man b/man/groff_font.5.man index 94b81e5bf..afcf52bd0 100644 --- a/man/groff_font.5.man +++ b/man/groff_font.5.man @@ -874,10 +874,9 @@ and stored in the .B ct register. . -In font descriptions for -.IR nroff -mode \" generic -output devices (terminals), -all glyphs might have a type of zero. +In font descriptions for terminal devices, +all glyphs might have a type of zero, +regardless of their appearance. . . .TP @@ -968,35 +967,31 @@ is ignored. .P A line in the .B charset -section can also have the following format. +section can also have the form . -. -.IP +.RS .IB name\~ \[dq] +.RE . -. -.P -This notation indicates that +identifying .I name -is another name for the glyph mentioned in the preceding line. +as another name for the glyph mentioned in the preceding line. . Such aliases can be chained. . . .P -The word +The directive .B \%kernpairs starts a list of kerning adjustments to be made to adjacent glyph pairs from this font. . It contains a sequence of lines formatted as follows. . -. -.IP +.RS .I g1 g2 n +.RE . -. -.P The foregoing means that when glyph .I g1 is typeset immediately before diff --git a/src/roff/groff/groff.1.man b/src/roff/groff/groff.1.man index c79ea5790..44fc97bbd 100644 --- a/src/roff/groff/groff.1.man +++ b/src/roff/groff/groff.1.man @@ -1794,25 +1794,30 @@ Once a librarian program has located a man page, it may execute a .I groff -command much like the following, -constructing a pipeline to page the output. -. +command much like the following. . .RS -.P .EX -groff \-t \-man \-Tutf8 /usr/share/man/man1/groff.1.man | less \-R +groff \-t \-man \-Tutf8 /usr/share/man/man1/groff.1 .EE .RE . +The librarian will also pipe the output through a pager, +which might not interpret the SGR terminal escape sequences +.I groff +emits for boldface, +underlining, +or italics; +see section \[lq]Limitations\[rq] below. +. . .P To process a .I roff input file using the preprocessors -.I tbl \" AT&T +.I @g@tbl and -.I pic \" AT&T +.I @g@pic and the .I me macro package in the way to which AT&T @@ -1825,14 +1830,14 @@ a pipeline. . .IP .EX -pic foo.me | tbl | troff \-me \-Tutf8 | grotty +@g@pic foo.me | @g@tbl | @g@troff \-me \-Tutf8 | grotty .EE . . .P Using .IR groff , -this pipe can be shortened to the equivalent command +this pipe can be shortened to an equivalent command. . .IP .EX _______________________________________________ Groff-commit mailing list Groff-commit@gnu.org https://lists.gnu.org/mailman/listinfo/groff-commit