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    chet@case.edu    http://tiswww.cwru.edu/~chet/

OpenPGP_signature.asc
Description: OpenPGP digital signature