[groff] 09/12: grotty(1): Fix content and style nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 469ef4fb84ac41a1db430dcf09ee52e9683332c3
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Nov 17 18:30:29 2021 +1100

    grotty(1): Fix content and style nits.
    
    Content:
    * Add Typefaces subsection, per <https://savannah.gnu.org/bugs/?60929>.
    * Refer to "stroke" and "fill" colors.  Explicitly describe how they are
      mapped to "foreground" and "background" colors for the character-cell
      devices targeted by this driver.
    * Tighten example to drop demonstration of nroff and to exercise groff's
      -P option instead of explicit pipelining through the output driver.
    * Clarify the primary consequence of not using SGR escape sequences.
    * Drop digressions regarding color enablement and alternative means of
      disabling SGR escape sequences from the discussion of legacy output.
    * Point out the inherent ambiguity of legacy output format.
    * Say "(drawing) escape sequences" instead of "(draw) commands".
    * Say "directive" instead of "command" when referring to font
      description file content.
    * Remove portability advice regarding man pages; groff_man_style(1)
      covers this material implicitly.
    
    Style:
    * Rename "Bugs" section to "Limitations".
    * Rename "Example" section to "Examples".
    * Convert items in "Limitations" section to a bulleted list.
    * Back away from sinful explicit use of bold italics in man page text.
    * Stop setting font (style) names in quotation marks.
    * Stop ending a sentence with a colon.
    * Perform a Kemper notectomy.
    * Use less Latin.
    * Tighten wording.
---
 src/devices/grotty/grotty.1.man | 144 +++++++++++++++++++---------------------
 1 file changed, 70 insertions(+), 74 deletions(-)

diff --git a/src/devices/grotty/grotty.1.man b/src/devices/grotty/grotty.1.man
index c023c38..2676993 100644
--- a/src/devices/grotty/grotty.1.man
+++ b/src/devices/grotty/grotty.1.man
@@ -180,7 +180,10 @@ and
 .I nroff
 were first developed but which are no longer in wide use.
 .
-SGR escape sequences are not emitted.
+SGR escape sequences are not emitted;
+bold,
+italic,
+and underlining character attributes are thus not manipulated.
 .
 Instead,
 .I grotty
@@ -203,14 +206,10 @@ BACKSPACE\~\c
 .I c
 BACKSPACE\~\c
 .IR c \[rq].
-Furthermore, color output is disabled.
 .
-The same effect can be achieved either by setting the
-.I GROFF_NO_SGR
-environment variable or by using a
-.I groff
-escape sequence within the document;
-see subsection \[lq]Device control commands\[rq] below.
+This rendering is inherently ambiguous when the character
+.I c
+is itself the underscore.
 .
 .
 .P
@@ -326,7 +325,7 @@ for more details.
 .
 .
 .P
-A font description file may contain a command
+A font description file may contain a directive
 .RB \[lq] internalname\~\c
 .IR n \[rq]
 where
@@ -352,6 +351,29 @@ then it is treated as a bold font.
 .
 .
 .\" ====================================================================
+.SS Typefaces
+.\" ====================================================================
+.
+.I grotty
+supports the standard four styles:
+.B R
+(roman),
+.B I
+(italic),
+.B B
+(bold),
+and
+.B BI
+(\f[BI]bold-italic\f[]).
+.
+Because the output driver operates in
+.I nroff
+mode,
+attempts to set or change the font family or type size are ignored.
+.
+.
+.
+.\" ====================================================================
 .SH Options
 .\" ====================================================================
 .
@@ -396,15 +418,13 @@ SGR and OSC escape sequences are not emitted.
 .B \-d
 Ignore all
 .B \[rs]D
-.I roff
-escapes
-(draw commands).
+drawing escape sequences in the input.
 .
 By default,
 .I grotty
 renders
 .BR \[rs]D\[aq]l \|.\|.\|.\& \[aq]
-commands that have at least one zero argument
+escape sequences that have at least one zero argument
 (and so are either horizontal or vertical)
 using Unicode box drawing characters
 (for the
@@ -418,19 +438,17 @@ and
 characters
 (for all other devices).
 .
-In a similar way,
 .I grotty
 handles
 .BR \[rs]D\[aq]p \|.\|.\|.\& \[aq]
-commands which consist entirely of horizontal and vertical lines.
+escape sequences which consist entirely of horizontal and vertical
+lines similarly.
 .
 .
 .TP
 .B \-f
-Use form feeds in the output.
-.
-A form feed is output at the end of each page that has no output on
-its last line.
+Emit a form feed at the end of each page having no output on its last
+line.
 .
 .
 .TP
@@ -457,8 +475,10 @@ Tabs are assumed to be set every 8 columns.
 .
 .TP
 .B \-i
-Render italic-styled text
-(fonts \[lq]I\[rq] and \[lq]BI\[rq])
+Render oblique-styled fonts
+.RB ( I
+and
+.BR BI )
 with the SGR attribute for italic text
 rather than underlined text.
 .
@@ -482,8 +502,10 @@ format is in use).
 .
 .TP
 .B \-r
-Render italic-styled text
-(fonts \[lq]I\[rq] and \[lq]BI\[rq])
+Render oblique-styled fonts
+.RB ( I
+and
+.BR BI )
 with the SGR attribute for reverse-video text
 .\" ECMA-48, 2nd edition (1979) calls it "negative image".
 rather than underlined text.
@@ -538,10 +560,12 @@ option were specified;
 see subsection \[lq]Legacy output format\[rq] above.
 .
 .
+.br
 .ne 3v \" Keep section heading and paragraph tag together.
 .\" ====================================================================
 .SH Files
 .\" ====================================================================
+.\"ne 3v \" Keep section heading and paragraph tag together.
 .
 .TP
 .I @FONTDIR@/devascii/DESC
@@ -629,53 +653,49 @@ Additional character definitions for use with
 .
 .
 .\" ====================================================================
-.SH Bugs
+.SH Limitations
 .\" ====================================================================
 .
 .I grotty
 is intended only for simple documents.
 .
 .
-.P
+.IP \[bu] 2n
 There is no support for fractional horizontal or vertical motions.
 .
 .
-.P
-There is no support for the
+.IP \[bu]
 .I roff
 .B \[rs]D
-escape sequence (draw command) other than horizontal and vertical lines.
+escape sequences producing anything other than horizontal and vertical
+lines are not supported.
 .
 .
-.P
+.IP \[bu]
 Characters above the first line
-(i.e., with a vertical position of\~0)
-cannot be printed.
+(that is,
+with a vertical drawing position of\~0)
+cannot be rendered.
 .
 .
-.P
-Color handling differs from
-.MR grops @MAN1EXT@ .
+.IP \[bu]
+Color handling differs from other output drivers.
 .
 The
 .I groff
-.B \[rs]M
-escape sequence doesn't set the fill color for closed graphic objects
-(which
-.I grotty
-doesn't support anyway)
-but instead changes the background color of the character cell,
-affecting all subsequent operations.
+requests and escape sequences that set the stroke and fill colors
+instead set the foreground and background character cell colors,
+respectively.
 .
 .
 .\" ====================================================================
-.SH Example
+.SH Examples
 .\" ====================================================================
 .
 The following
 .I groff
-document exercises several features,
-not all of which may be supported by a given output device:
+document exercises several features for which output device support
+varies:
 (1)\~bold style;
 (2)\~italic (underline) style;
 (3)\~bold-italic style;
@@ -701,51 +721,27 @@ Black on cyan can have a 
\eM[cyan]\em[black]prominent\em[]\eM[]
 .
 .
 .P
-Compare and contrast the output of the following:
+Given the foregoing input,
+compare and contrast the output of the following.
 .
 .
 .P
 .RS
 .EX
 $ \c
-.B nroff \c
-.I file
-$ \c
 .B groff \-T ascii \c
 .I file
 $ \c
-.B groff \-T utf8 \-Z \c
-.I file \c
-.B | grotty \-i
+.B groff \-T utf8 \-P \-i \c
+.I file
 $ \c
-.B groff \-T utf8 \-Z \c
+.B groff \-T utf8 \-P \-c \c
 .I file \c
-.B | grotty \-c | ul
+.B | ul
 .EE
 .RE
 .
 .
-.\" I wish this went without saying...
-.P
-Note that the example file above is a \[lq]raw\[rq]
-.I groff
-document,
-not a man page.
-.
-.\" Yes, using \f[BI] here is slightly hypocritical.
-Use of color escapes in man pages is \f[BI]strongly discouraged\f[].
-.
-Some implementations of
-.MR man 1
-.\" ...like man-db 2.8.5-2 on Debian Buster...
-completely disable them.
-.
-See subsection \[lq]Portability\[rq] of
-.MR groff_man_style @MAN7EXT@
-for guidance on writing man pages that are viewable by as many readers
-as possible.
-.
-.
 .\" ====================================================================
 .SH "See also"
 .\" ====================================================================