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

[Chet Ramey]

On 12/30/24 8:16 PM, G. Branden Robinson wrote:
> Hi Chet,
>
> At 2024-12-30T11:23:06-0500, Chet Ramey wrote:
> > On 12/16/24 12:48 PM, G. Branden Robinson wrote:
> >
> > > Favor man(7) font selection/alternation macros over roff(7) font
> > > selection escape sequences.
> >
> > In general, I don't do this when it makes the man page source and the
> > texinfo source lines align better. There are exceptions.
>
> There a couple of ways to achieve such alignment, since both *roff and
> Texinfo fill lines by default and are therefore flexible with respect to
> input line endings.
>
> In *roff, of course, you _have_ to break an input line to make a macro
> call, and in Texinfo you don't.
>
> Let me take an example at random from bashref.texi and bash.1.  I'll
> prefix them with letters to make them easier to talk about.
>
> A> The return status is the exit status of the last command that executes.
> A> If there are no items in the expansion of @var{words}, no commands are
> A> executed, and the return status is zero.
>
> In *roff, you can write that either with escape sequences or a macro
> call:
>
> B> The return status is the exit status of the last command that executes.
> B> If there are no items in the expansion of \fIwords\fP, no commands are
> B> executed, and the return status is zero.

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. I put two documents into two separate windows in my
editor and view them together. Most of the time, that's the texinfo
style, or the troff inline format change style, since it's most flexible.

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]

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

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

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