[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 05/31: [docs]: Fix content, style, and markup nits.
From: |
G. Branden Robinson |
Subject: |
[groff] 05/31: [docs]: Fix content, style, and markup nits. |
Date: |
Wed, 17 Aug 2022 01:26:03 -0400 (EDT) |
gbranden pushed a commit to branch master
in repository groff.
commit acae9d3827237c702ea5fc3315a7f35273f757e0
Author: G. Branden Robinson <g.branden.robinson@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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 05/31: [docs]: Fix content, style, and markup nits.,
G. Branden Robinson <=