[groff] 02/16: [docs]: Update groff(1) examples.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 95f63689b3374bff81e35e02544f213ea22c8a88
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Sep 1 11:04:10 2023 -0500

    [docs]: Update groff(1) examples.
    
    Also start sneaking away from explicit mention of SGR escape sequences
    in anticipation of Lennart Jablonka's terminfo work on grotty.
---
 doc/groff.texi             | 11 +++++------
 src/roff/groff/groff.1.man | 23 ++++++++++++++---------
 2 files changed, 19 insertions(+), 15 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index d894382b1..2025002b1 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -1641,7 +1641,7 @@ $ groff -T ps -d paper=a4l -P -pa4 -P -l -ms foo.ms 
>foo.ps
 @cindex examples of invocation
 
 @code{roff} systems are best known for formatting man pages.  A
-@command{man} librarian program, having located a page, may render it
+@command{man} librarian program, having located a page, might render it
 with a @command{groff} command.
 
 @Example
@@ -1649,9 +1649,9 @@ groff -t -man -Tutf8 /usr/share/man/man1/groff.1
 @endExample
 
 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.
+interpret terminal escape sequences @command{groff} emits for boldface,
+underlining, italics, or hyperlining; 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
@@ -1662,8 +1662,7 @@ script) a pipeline.
 gpic foo.me | gtbl | gtroff -me -Tutf8 | grotty
 @endExample
 
-Using @command{groff}, this pipe can be shortened to an equivalent
-command.
+Shorten this pipeline to an equivalent command using @command{groff}.
 
 @Example
 groff -p -t -me -T utf8 foo.me
diff --git a/src/roff/groff/groff.1.man b/src/roff/groff/groff.1.man
index 16272b935..c13e3a10e 100644
--- a/src/roff/groff/groff.1.man
+++ b/src/roff/groff/groff.1.man
@@ -1902,15 +1902,17 @@ is used, it is always converted to human-readable form 
using UTC.
 .SH Examples
 .\" ====================================================================
 .
+.\" BEGIN Keep parallel with groff.texi node "Invocation Examples".
 .I roff
 systems are best known for formatting man pages.
 .
-Once a
+A
 .MR man 1
-librarian has located a man page,
-it may execute a
+librarian program,
+having located a page,
+might render it with a
 .I groff
-command much like the following.
+command.
 .
 .RS
 .EX
@@ -1919,11 +1921,12 @@ groff \-t \-man \-Tutf8 /usr/share/man/man1/groff.1
 .RE
 .
 The librarian will also pipe the output through a pager,
-which might not interpret the SGR terminal escape sequences
+which might not interpret terminal escape sequences
 .I groff
 emits for boldface,
 underlining,
-or italics;
+italics,
+or hyperlinking;
 see section \[lq]Limitations\[rq] below.
 .
 .
@@ -1951,9 +1954,9 @@ a pipeline.
 .
 .
 .P
-Using
-.IR groff ,
-this pipe can be shortened to an equivalent command.
+Shorten this pipeline to an equivalent command using
+.IR groff .
+.
 .
 .IP
 .EX
@@ -1981,6 +1984,7 @@ required leading dashes
 .\" --help or --version.
 .\"or
 .\".RB \[lq] \-\- \[rq]
+.\" XXX: grolbp does.
 because
 .I groff
 passes the arguments as-is to the postprocessor;
@@ -2007,6 +2011,7 @@ groff \-X \-Z mydoc.t | gxditview \-title \[aq]trial 
run\[aq] \-
 .RE
 .
 are equivalent.
+.\" END Keep parallel with groff.texi node "Invocation Examples".
 .
 .
 .\" ====================================================================