[PATCH] repair recent, ill-conceived man page changes

[G. Branden Robinson]

Hi Chet,

Please consider reverting the following recent changes to the bash man
page.  Bjarni should have run them by the groff list first, because some
of them are ill-considered.

Bjarni,

I regret that I must repeat myself.[1]

Please do not offer yourself as an authority on correct man page
composition when you don't know what you're talking about and have filed
bug reports complaining of that fact.

https://savannah.gnu.org/bugs/?64238

You got some things right here, and some wrong; please stick to those
you got right.

diff --git a/doc/bash.1 b/doc/bash.1
index 0f23d480..24170efe 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -5,14 +5,19 @@
 .\"    Case Western Reserve University
 .\"    chet.ramey@case.edu
 .\"
-.\"    Last Change: Wed Sep 13 15:39:24 EDT 2023
+.\"    Last Change: Fri Oct  6 16:41:20 EDT 2023
 .\"
+.\" suggested by Bjarni Ingi Gislason <bjarniig@simnet.is>
+.if n \{\
+.kern 0
+.ss 12 0
+.\}

The above change is half pointless and half intrusive.

A) No formatter for terminal output devices ("nroff mode", which is
   tested by "if n" performs kerning.  So that's a no-op.

B) The amount of intersentence spacing, for man pages, is matter of the
   _reader's_ taste and should be left to them.  mandoc(1) ignores this
   request and I'm glad it does.  So that, too, is a no-op with that
   formatter.

@@ -511,8 +516,13 @@ .SH "RESERVED WORDS"
 .if t .RS
 .PP
 .B
-.if n ! case  coproc  do done elif else esac fi for function if in select then 
until while { } time [[ ]]
-.if t !    case    coproc    do    done    elif    else    esac    fi    for   
 function    if    in    select    then    until    while    {    }    time    
[[    ]]
+.if n ! case  coproc  do done elif else esac fi for function if in select \
+then until while { } time [[ ]]
+.if t \{\
+.lg 0
+ !    case    coproc    do    done    elif    else    esac    fi    for    
function    if    in    select    then    until    while    {    }    time    
[[    ]]
+.lg 1
+.\}

This change is pointless because no ligatures are defined for any of the
letter pairs in the text in any known formatter (the ligature for "ct",
like that for "st" [not seen here] is archaic in English typography and
seldom seen in digital fonts).  Moreover, this request sequence clobbers
the user's selected ligature mode, which might have been 2 prior to the
".lg 0" control line.  This hunk should be reverted.

@@ -11629,7 +11638,7 @@ .SH "SHELL COMPATIBILITY MODE"
 .BR compat41 ,
 and so on).
 There is only one current
-compatibility level -- each option is mutually exclusive.
+compatibility level \(en each option is mutually exclusive.
 The compatibility level is intended to allow users to select behavior
 from previous versions that is incompatible with newer versions
 while they migrate scripts to use current features and

An en-dash is not the correct glyph: an em-dash is.  As it happens, the
"en" special character identifier is less portable than "em" to boot.
See section "History" of groff_char(7).

Authorities differ on whether space should surround em dashes; from what
I have seen, a majority favor omitting them, and that is what I do in
the groff man pages, but I cannot say it is more than a matter of taste.

(A man page's "Name" section is a special case, and the "-", "--",
"\(en", or "\(em" that separates the page's topic(s) from the summary
description _must_ be bracketed by spaces for makewhatis(8) and mandb(8)
to reliably interpret them.)

@@ -11940,7 +11983,7 @@ .SH "SEE ALSO"
 \fIPortable Operating System Interface (POSIX) Part 2: Shell and Utilities\fP, 
IEEE --
 http://pubs.opengroup.org/onlinepubs/9699919799/
 .TP
-http://tiswww.case.edu/\(tichet/bash/POSIX -- a description of posix mode
+http://tiswww.case.edu/\(tichet/bash/POSIX \(en a description of posix mode
 .TP
 \fIsh\fP(1), \fIksh\fP(1), \fIcsh\fP(1)
 .TP

As with the previous \(en -> \(em remark.  Also we can see that another
double-hyphen in the context was carelessly left inconsistent.

I find nothing amiss with the other changes.

Chet, I'm happy to prepare a patch reflecting the above recommendations
(against the "devel" branch at git.sv.gnu.org:/srv/git/bash.git).  Let
me know.

Regards,
Branden

[1] https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1036826#33

signature.asc
Description: PGP signature