[groff] 01/04: nroff(1): Fix style and content issues.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit b447d738fb65168ef8ccda2a89555425ebe6aa4a
Author: G. Branden Robinson <address@hidden>
Date:   Tue Nov 13 11:36:13 2018 -0500

    nroff(1): Fix style and content issues.
    
        * src/roff/nroff/nroff.1.man:
          + Recast .SH NAME summary to emphasize purpose, not
            implementation.
          + Add introductory sentence to Description for the same
            reason.
          + Stop identifying the implementation as a script.
          + Stop redefining an-ext's OP macro.
          + Correct synopsis markup to illustrate that whitespace
            between option flags and their arguments is prohibited.
            Unfortunately this means we face the three-font beast in all
            its fell glory.
          + Add sentence mentioning this prohibition; as Ingo notes,
            it's more efficient to explicate the exceptions to robust
            option parsing than the norm.
          + Set "@address@hidden", "groff", "grotty", and "locale"(1) in
            italics, not bold or roman.
          + Add man section cross references to the aforementioned on
            first inline occurrence, where absent.
          + Add locale and roff to See Also section.
          + Motivate nroff's acceptance of only a subset of output
            devices.
          + Move list of environment variable fallbacks to Environment
            section.
          + Make clear that nroff ultimately falls back to "ascii", not
            "ps".
          + Give full path to tty-char.tmac.
          + Note that tty-char.tmac offers replacements for
            glyphs unsupported by the output device, not visual
            emulations.
          + Note that --help, --version, -v all exit without doing real
            work.
          + Drop statement about being "basically intended for use by
            man".  man-db's man(1) is groff-aware, and this nroff should
            be suitable for any purpose classical nroff was.
          + Fix a comma splice.
          + Hyphenate attributive phrasal adjective.
    
    Signed-off-by: G. Branden Robinson <address@hidden>
---
 src/roff/nroff/nroff.1.man | 182 ++++++++++++++++++++++++++++-----------------
 1 file changed, 115 insertions(+), 67 deletions(-)

diff --git a/src/roff/nroff/nroff.1.man b/src/roff/nroff/nroff.1.man
index 1c0b6cd..a6e9c17 100644
--- a/src/roff/nroff/nroff.1.man
+++ b/src/roff/nroff/nroff.1.man
@@ -1,6 +1,6 @@
 .TH @address@hidden @MAN1EXT@ "@MDATE@" "groff @VERSION@"
 .SH NAME
address@hidden@nroff \- emulate nroff command with groff
address@hidden@nroff \- use groff to format documents for TTY devices
 .
 .
 .\" ====================================================================
@@ -29,25 +29,35 @@
 .SH SYNOPSIS
 .\" ====================================================================
 .
-.\" Redefine OP because no spaces are allowed after an option's argument.
-.de OP
-.  ie \\n(.$-1 \
-.    RI "[\fB\\$1\fP" "\\$2" "]"
-.  el \
-.    RB "[" "\\$1" "]"
-..
-
 .SY @address@hidden
-.OP \-CchipStUv
-.OP \-d cs
-.OP \-M dir
-.OP \-m name
-.OP \-n num
-.OP \-o list
-.OP \-r cn
-.OP \-T name
-.OP \-W warning
-.OP \-w warning
+.RB [ \-CchipStUv ]
+[\c
+.BI \-d cs\c
+]
+[\c
+.BI \-M dir\c
+]
+[\c
+.BI \-m name\c
+]
+[\c
+.BI \-n num\c
+]
+[\c
+.BI \-o list\c
+]
+[\c
+.BI \-r cn\c
+]
+[\c
+.BI \-T name\c
+]
+[\c
+.BI \-W warning\c
+]
+[\c
+.BI \-w warning\c
+]
 .RI [ file
 \&.\|.\|.\&]
 .YS
@@ -66,23 +76,36 @@
 .SH DESCRIPTION
 .\" ====================================================================
 .
-The
-.B @address@hidden
-script emulates the
-.B nroff
-command using groff.
-.
-Only
+.I @address@hidden
+formats documents written in the
+.IR roff (@MAN7EXT@)
+language for typewriter-like devices such as terminal emulators.
+.
+.P
+GNU
+.I @address@hidden
+emulates the traditional Unix
+.I nroff
+command using
+.IR groff (@MAN1EXT@).
+.
+.I @address@hidden
+generates output via
+.IR grotty (@MAN1EXT@),
+.IR groff 's
+TTY output device,
+which needs to know the character encoding scheme used by the terminal.
+.
+Consequently,
+acceptable arguments to the
+.B \-T
+option are
 .BR ascii ,
 .BR latin1 ,
 .BR utf8 ,
 and
-.B cp1047
-are devices accepted by
-.BR nroff
-to select the output encoding emitted by
-.BR grotty ,
-groff's TTY output device.
+.BR cp1047 ;
+any others are ignored.
 .
 If neither the
 .I GROFF_TYPESETTER
@@ -90,29 +113,30 @@ environment variable nor the
 .B \-T
 command-line option (which overrides the environment variable)
 specifies a (valid) device,
-.B @address@hidden
-checks the current locale to select a default output device.
+.I @address@hidden
+consults the locale to select an appropriate output device.
 .
 It first tries the
-.B locale
-program, then the environment variables
-.IR LC_ALL ,
-.IR LC_CTYPE ,
-and
-.IR LANG ,
-and finally the
-.I LESSCHARSET
-environment variable.
+.IR locale (1)
+program,
+then checks several locale-related environment variables;
+see \(lqENVIRONMENT\(rq, below.
+.
+If all of the foregoing fail,
+.B \-Tascii
+is implied.
+.
 .
+.P
+Whitespace is not permitted between an option and its argument.
 .
-.PP
 The
 .B \-h
 and
 .B \-c
 options
 are equivalent to
-.BR grotty 's
+.IR grotty 's
 options
 .B \-h
 (using tabs in the output) and
@@ -132,19 +156,19 @@ The
 and
 .B \-W
 options have the effect described in
-.BR @address@hidden (@MAN1EXT@).
+.IR @address@hidden (@MAN1EXT@).
 .
 In addition,
-.B @address@hidden
-silently ignores the options
+.I @address@hidden
+ignores
 .BR \-e ,
 .BR \-q ,
 and
 .BR \-s
 (which are not implemented in
-.BR @address@hidden ).
+.IR @address@hidden ).
 .
-Options
+The options
 .B \-p
 (pic),
 .B \-t
@@ -153,14 +177,16 @@ Options
 (safer), and
 .B \-U
 (unsafe) are passed to
-.BR groff .
+.IR groff .
 .
 .B \-v
 and
 .B \-\-version
-show the version number,
+show version information,
+while
 .B \-\-help
-prints a help message.
+displays a usage message;
+all exit afterward.
 .
 .
 .\" ====================================================================
@@ -169,36 +195,58 @@ prints a help message.
 .
 .TP
 .I GROFF_TYPESETTER
-The default device for
-.BR groff .
-If not set (which is the normal case), it defaults to \(oqps\(cq.
+specifies the default output device for
+.IR groff .
+.
 .
 .TP
 .I GROFF_BIN_PATH
-A colon separated list of directories in which to search for the
-.B groff
-executable before searching in PATH.
+is a colon-separated list of directories in which to search for the
+.I groff
+executable before searching in
+.IR PATH .
+.
+If unset,
+.I @BINDIR@
+is used.
 .
-If unset, \(address@hidden@\(cq is used.
+.
+.TP
+.I LC_ALL
+.TQ
+.I LC_CTYPE
+.TQ
+.I LANG
+.TQ
+.I LESSCHARSET
+are pattern-matched in this order for standard character encodings
+supported by
+.I groff
+in the event no
+.B \-T
+option is given and
+.I GROFF_TYPESETTER
+is unset.
 .
 .
 .\" ====================================================================
 .SH NOTES
 .\" ====================================================================
 .
-This shell script is basically intended for use with
-.BR man (1).
-nroff-style character definitions (in the file tty-char.tmac) are also
-loaded to emulate unrepresentable glyphs.
+Character definitions in the file
+.IR @MACRODIR@/\:tty\-char.tmac
+are loaded to replace unrepresentable glyphs.
 .
 .
 .\" ====================================================================
 .SH "SEE ALSO"
 .\" ====================================================================
 .
-.BR groff (@MAN1EXT@),
-.BR @address@hidden (@MAN1EXT@),
-.BR grotty (@MAN1EXT@)
+.IR groff (@MAN1EXT@),
+.IR @address@hidden (@MAN1EXT@),
+.IR grotty (@MAN1EXT@),
+.IR locale (1),
+.IR roff (@MAN7EXT@)
 .
 .
 .\" Local Variables: