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

[G. Branden Robinson]

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.

C> The return status is the exit status of the last command that executes.
C> If there are no items in the expansion of
C> .IR words ,
C> no commands are executed, and the return status is zero.

If I selected the latter, I'd then alter the breaking of the Texinfo
manual to match:

D> The return status is the exit status of the last command that executes.
D> If there are no items in the expansion of
D> @var{words},
D> no commands are executed, and the return status is zero.

Personally, I lobby for C+D because groff will give you italic
corrections for free (there's no portable way to express them, but groff
man(7) tucks them inside its `IR` macro definition and so can achieve
them anyway).  But I know not everyone shares my preferences.

groff_man(7):
     Unlike the above font style macros, the font style alternation
     macros below set no input traps; they must be given arguments to
     have effect.  They apply italic corrections as appropriate.

     .BI bold‐text italic‐text ...
            Set each argument in bold and italics, alternately.

     .BR bold‐text roman‐text ...
            Set each argument in bold and roman, alternately.

     .IB italic‐text bold‐text ...
            Set each argument in italics and bold, alternately.

     .IR italic‐text roman‐text ...
            Set each argument in italics and roman, alternately.

     .RB roman‐text bold‐text ...
            Set each argument in roman and bold, alternately.

     .RI roman‐text italic‐text ...
            Set each argument in roman and italics, alternately.

What's your preference?  I'll hew to it in future submissions.

Regards,
Branden

signature.asc
Description: PGP signature