[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH] repair recent, ill-conceived man page changes
|
From: |
Bjarni Ingi Gislason |
|
Subject: |
Re: [PATCH] repair recent, ill-conceived man page changes |
|
Date: |
Mon, 16 Oct 2023 21:16:23 +0000 |
On Wed, Oct 11, 2023 at 04:08:55AM -0500, G. Branden Robinson wrote:
> 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
>
That is your interpretation (imagination).
Patches from an non-committer are simply suggestions.
I am offering another view (opinion) of the cited content.
> 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
> +.\}
>
Where and how did I suggest this?
Look at my email
"https://lists.gnu.org/archive/html/bug-bas/2023-09/msg00152.html";.
(Sun, 24 Sep 2023 12.32:42 +0000)
> 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.
>
Yes, \n[.lg] could be tested and code added.
That is just not a minimal change in the source.
People, that do such extra typesetting commands outside the source,
also bear the reponsibility that it functions.
Some man pages are produced with no hyphanation (.nh) and no
adjustment to both margins (.ad l).
As the words are reserved ones, a better choice could be to use
constant width type.
> @@ -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 missed
\fIPortable Operating System Interface (POSIX) Part 2: Shell and
Utilities\fP, IEEE --"
as it was not in the remarks part about ' -- '.
1) '--' is a symbol for an en-dash in LaTeX (TeX).
2) Using an en-dash or an em-dash for a dash (in typography) depends on
what typesetting tradition the writer had to learn and use.
If en-dash, then spaces ("air" around the dash),
if em-dash, then no space.
Typesetters, that found an em-dash to be too long, used (use) a three
fourth of an em-dash (PostScript Expert Character Set,
threequartersemdash)
en- and em-dash are a part of the Standard Roman Character Set in
PostScript Language, second edition, 1990.
So there is no need to avoid the use of en-dashes (are also used for a
range, 1\(en10).
Typesetting software, that does not have an en-dash, is simply out of
date.
> 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