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

[Chet Ramey]

On 12/31/24 8:33 PM, G. Branden Robinson wrote:

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.

Sure. That's why I use inline font selection commands in groff -- because
the texinfo markup is inline (e.g., @code{...} vs \fB...\fP).

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 tend to eyeball the diffs, since I'm usually only changing one thing
at a time.

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.

I don't use vim or emacs, but we're on the same page here (heh).

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.

I am most concerned with content: fixing awkward phrasing, reducing the
use of the passive voice, making sure the information is accurate.

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.

Kind of. They each have their own textual styling, with a lot of overlap.
Historically, the texinfo doc has been subjected to more scrutiny ("no,
use @option and @env, you fool!"), so it `leads' and I make the man page
styling conform.

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.

I am primarily interested in getting better content, as above.

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`.

I'm less concerned about that last one, since I ship formatted
documentation with releases, and I can test various man implementations.

Chet

--
``The lyf so short, the craft so long to lerne.'' - Chaucer
                 ``Ars longa, vita brevis'' - Hippocrates
Chet Ramey, UTech, CWRU    c...@case.edu    http://tiswww.cwru.edu/~chet/

OpenPGP_signature.asc
Description: OpenPGP digital signature