Re: [PATCH 9/9] doc/bash.1: Resync w/ lib/readline/doc/readline.3.

[G. Branden Robinson]

At 2024-12-31T13:05:30-0500, Chet Ramey wrote:
> On 12/30/24 8:16 PM, G. Branden Robinson wrote:
> Since I maintain six separate documents, the style I choose usually
> depends on the style for the document where a particular piece of text
> originates.

Fair, but having different line breaking practices for different
documents where their text will be parallel makes side-by-side
comparisons more difficult.

Also, in my experience (it may not be yours), the somewhat break-happy
approach of man(7), especially when font macros are favored over font
escape sequences, lends itself well to diffs.

> I put two documents into two separate windows in my
> editor and view them together.

What I've started to do once I learned how much parallelism was intended
between doc/bash.1 and doc/bashref.texi, was to open them in adjacent
vertical windows in vim.  Of course I know Emacs can do the same.

> Most of the time, that's the texinfo style, or the troff inline format
> change style, since it's most flexible.

I steer people away from *roff font selection escape sequences in man
pages for a few reasons.

1.  In their classical, portable form, they abut words and elicit false
    positives from any spell checker that doesn't know about weird old
    *roff syntax.

    So in a phrase like:

    runs in a \fBseperate\fP process

    ...people get conditioned to ignore their spell checker (or give up
    using it), because it trips on all \fBthis \fIstuff.  They then
    overlook the actual spelling error ("seperate" [sic]).

2.  People somewhat reasonably get the idea that if they can ask for
    fonts "B", and "I", they can ask for others.  "C" is popular--boy
    do people crave inline Courier.  They especially love busily
    interleaving Courier with Times so you can't tell where spaces are.
    But `C` is not a portable font name and doesn't work on terminals
    anyway.

3.  Much usage of \f comes from automatically generated rather than
    hand-crafted man(7).  That in turn is because it is generally
    simpler for generators to write typeface changes this way.  To know
    whether you should use `B` vs. `BI` requires scanning ahead or
    maintaining more state.  People who write man(7) generators seem
    consistently to (a) overestimate how easy it will be and (b) not
    bother learning much about troff or even man(7) in the first place,
    and therefore (c) select the crudest solutions they can.  Then
    man(7) novices use such generated documents as models to imitate.
    Every novice's favorite source of inspiration is always the output
    of docbook-to-man, no matter how many examples of less horrible
    output from just about _every_ other generator (pandoc, asciidoctor,
    docutils, pod2man) you put in front of them.

    This is the true "worse is better" principle.  Without mentorship,
    software developers invariably gravitate to the worst solution to
    any problem--even when a better solution is _easier_, both to
    understand and to write.  Something about our industry fuels a
    craving for wretched work product.

    At one place I worked, we had a custom bug tracking system upon
    which we unleashed interns every semester.  You could follow the
    seasons not just by the changing of the leaves but with the
    performance of the bug tracker.  Fresh batch of interns comes in,
    they pick some revision requests (on the tracker itself) to work on,
    implement some O(e^n) algorithms, and over the next four months we
    watch as performance for reports creeps back to its previous nominal
    level.  Then they cycle back out to university, we get a fresh batch
    of interns, they implement some O(e^n) algorithms...

4.  Italic corrections for free, as I noted.

> For an example of this flexibility, even the .BI macro can't reproduce
> the existing formatting of an array assignment without some more
> inline formatting changes:
> 
> \fBdeclare \-a\fP \fIname\fP[\fIsubscript\fP]

That's true.  On the groff list we know this as "the three-font
problem".  There is no good solution.  You have to learn either `\f` or
`\c`.  And since for a few situations you need to learn `\c` anyway, I
try to steer people toward that.  But I'm fighting many years of inertia
and fear.  *roff documentation has traditionally done an outright
miserable job of explaining what `\c` does.  I've tried to make groff's
documentation clear.

groff_man_style(7):
     •  The output line continuation escape sequence \c is used with
        font style alternation macros to allow all three font styles to
        be set without (breakable) space among them; see subsection
        “Portability” below.
[...]
     \c        End a text line without inserting space or attempting a
               break.  Normally, if filling is enabled, the end of a
               text line is treated like a space; an output line may
               break there (if it does not, troff inserts an adjustable
               space); if filling is disabled, the line will break
               there, as in .EX/.EE examples.  The next line is
               interpreted as usual and can include a macro call
               (contrast with \newline).  \c is useful when three font
               styles are needed in a single word, as in a command
               synopsis.

                      .RB [ \-\-stylesheet=\c
                      .IR name ]

               It also helps when changing font styles in .EX/.EE
               examples, since they are not filled.

                      .EX
                      $ \c
                      .B groff \-T utf8 \-Z \c
                      .I file \c
                      .B | grotty \-i
                      .EE

Ingo Schwarze has expressed concern that `\c` is less portable than `\f`
but I have found no evidence of this being the case.  Maybe he was
hedging against bugs in mandoc(1), which he maintains.

> I guess I don't see that stuff as broken or needing to be changed,
> since the output renders the way I want. (Yes, I realize that the
> texinfo output isn't quite like that, either. There's a limit to
> how much fiddling I want to do.)

I don't mind helping with the fiddling; I just need to know which format
should lead, and which should follow.

Combining what you said above with a repeated statement in "NEWS", it
seems like you regard bash.1 as authoritative for content but
bashref.texi authoritative for textual styling.  This seems like a
somewhat delicate situation to me, but if you could write it down
explicitly somewhere, that would help (aspiring) contributors to the
Bash documentation--like me.

> Is there any benefit besides getting the italic corrections groff
> gives you?

I think it leads to better compositional practices, easier acquisition
of the man(7) language, and simpler reasoning about how the document
will format.  For example, it's unspecified what happens if you select a
nonexistent font with `\f`.  Does that clobber the previous font to
which you could have returned with `\fP`, or not?  Russ Allbery, the
pod2man guy, said he had to research this point to write a generator
that would produce consistent renderings across implementations.

https://lists.gnu.org/archive/html/groff/2022-11/msg00162.html

If you misspell a macro name, the failure is more obvious (generally,
the words disappear) and people seem not to assume they can just replace
letters in macro name at random to get exciting new typefaces.

Regards,
Branden

signature.asc
Description: PGP signature