[groff] 06/07: doc/groff.texi, groff_diff(7): Tweak example.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 3afcaf0ed409093626c3a9fe346bd33afec60f29
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Sep 6 04:54:06 2020 +1000

    doc/groff.texi, groff_diff(7): Tweak example.
    
    It's like bathing a cat to get programmers to punctuate inset examples
    that are grammatically part of a sentence, as if they were part of a
    sentence.  People love to just trail off with "the following:", blitz
    the user with 1-100 lines of block-quoted literal, and then pretend they
    ended a sentence.  (This is suggestive of the console jockey ethos; once
    one has thrown code at you, they're done with you.)
    
    Mathematical literature is more careful.
    
    However, the man macros make doing the right thing difficult; in nroff
    mode there just aren't many font styles to go around, and while one
    could ".if t" around that problem, a miniature BSD daemon materializes
    on my shoulder and pokes me with a pitchfork if I even consider it.  And
    doing so doesn't help the likely majority of people who _only_ read man
    pages in a terminal window.
    
    In the end the best solution is to just recast.  Our man pages are
    already overrun with lazy "sentences" ending in "the following:" and
    similar constructions anyway, so it's no burden to scrub out one more.
    
    tl;dr: A colon does not relieve you of your duty to finish a sentence.
---
 doc/groff.texi       |  9 +++++----
 man/groff_diff.7.man | 14 +++++++-------
 2 files changed, 12 insertions(+), 11 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 60ca92b..c015ac5 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -14753,19 +14753,20 @@ before being added to the output, they act as input 
entities;
 afterwards, they denote glyphs.  A glyph node does not behave like an
 input character for the purposes of macro processing; it does not
 inherit any of the special properties that the input character from
-which it was constructed might have had.  The following example,
+which it was constructed might have had.  Consider the following
+example.
 
 @Example
 .di x
 \\\\
 .br
 .di
-.x@r{,} @c Only mathematical typographers will appreciate this comma.
+.x
 @endExample
 
 @noindent
-prints @samp{\\} in GNU @code{troff}; each pair of input backslashes is
-turned into one output backslash and the resulting output backslashes
+It prints @samp{\\} in GNU @code{troff}; each pair of input backslashes
+is turned into one output backslash and the resulting output backslashes
 are not interpreted as escape characters when they are reread.
 @acronym{AT&T} @code{troff} would interpret them as escape characters
 when they were reread and would end up printing one @samp{\}.
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 0ad794b..4e2a7b7 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -4778,19 +4778,19 @@ macro processing;
 it does not inherit any of the special properties that the input
 character from which it was constructed might have had.
 .
-The following example,
+Consider the following example.
 .
 .RS
 .EX
-.B .di x
-.B \[rs]\[rs]\[rs]\[rs]
-.B .br
-.B .di
-.BR .x ,\" Only mathematical typographers will appreciate this comma.
+\&.di x
+\[rs]\[rs]\[rs]\[rs]
+\&.br
+\&.di
+\&.x
 .EE
 .RE
 .
-prints
+It prints
 .RB \[lq] \[rs]\[rs] \[rq]
 in
 .IR groff ;