Re: RS/RE and paragraphing macros

[Alejandro Colomar]

Hi Branden,

On 2/15/23 00:07, Alejandro Colomar wrote:
> "bar" is what I'd expect.  Now that I know what I was looking for,
> I could search it and find it.  Michael had this to say:
> <https://lore.kernel.org/linux-man/ab209b21-a93e-fd7c-e447-c8ff507cb062@gmail.com/>
> 
> Shouldn't RS/RE nest nicely in paragraphing macros?

There seems to be a reply of Michael to an email of yours
that didn't reach the list for some reason:
<https://lore.kernel.org/linux-man/7a366ad6-aee2-3139-dc8e-de2bd23cbb9c@gmail.com/>


Michael wrote:
> From: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
> To: "G. Branden Robinson" <g.branden.robinson@gmail.com>
> Cc: mtk.manpages@gmail.com,
>       "Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>,
>       linux-man@vger.kernel.org, colomar.6.4.3@gmail.com
> Subject: Re: .RS
> Date: Fri, 13 Nov 2020 11:02:19 +0100 [thread overview]
> Message-ID: <7a366ad6-aee2-3139-dc8e-de2bd23cbb9c@gmail.com> (raw)
> In-Reply-To: <20201113093846.jzxlkw3o3pqkkr47@localhost.localdomain>
> 
> Hi Branden,
> 
> On 11/13/20 10:38 AM, G. Branden Robinson wrote:
>> At 2020-11-13T09:52:06+0100, Michael Kerrisk (man-pages) wrote:
>>> Hmmm -- I don't know. I was going to ask, doesn't s/>RS 4/.RS +4n/
>>> fix the problem? But I see that it does not.
>> 
>> No, these should be synonymous.
>> 
>>> By the way, your comments (\") actually cause the rendered
>>> output to change, as far as I can see! In particular,
>>> the \" on the final .RE leads to some strangeness:
>> 
>> I can't reproduce that, apply Alex's changes as I understand them to the
>> actual man page from Git.
>> 
>> I'm attaching 3 versions.  The stock page, the "Alex" approach, and the
>> "Branden" approach, each tweaks only the indentation of these code
>> examples in the 2-cell-indented, starrred paragraphs, and adds a C
>> comment to the example to make it easy to distinguish them, since it's a
>> long page and the footer is far away.
>> 
>>> No indent at all on the final line!
>> 
>> That certainly seems bizarre based on the "lorem ipsum" stuff I saw.  I
>> think this may have been a patch-application error.
> 
> Hmmmm - I can't now reproduce, so I guess you are right. My bad, sorry.
> 
>> Here are my observations on the 3 attached versions.  My comparison
>> method was to give each page its own maximized terminal window, "man -l"
>> it, then forward-search in less(1) to "Reading results", and
>> Alt+backtick in my window manager to flip between the versions.
>> 
>> The surrounding context of all these examples is an .IP paragraph, so
>> the stock solution, and Alex's, are using .IP inside .IP.  This is not
>> discouraged in man(7); it just needs to be noted.
>> 
>> stock:   The code example is indented 6 cells from the asterisk in its
>>          parent paragraph.  Uses .IP/.in/.EX/.../.EE/.in.
>> 
>> alex:    The code example is indented 4 cells from the asterisk in its
>>          parent paragraph.  This is because of the semantics of .RS;
>>          its inset is offset from a _normal_ (.PP) paragraph, not an
>>          indented one.  It's my understanding that this is compatible
>>          with man(7) semantics all the way back to 1979, but it is has
>>          a source of frustration to me, you, and others, and that is why
>>          I have documented it so carefully in groff_man(7) and
>>          groff_man_style(7).  Uses .IP/.RS 4/.EX/.../.EE/.RE.
>> 
>> branden: The code example is indented 2 cells from the asterisk in its
>>          parent pargraph.  This may not be desirable, but on the bright
>>          side the preceding .RS call has no argument.  You could use
>>          another .RS/.RE pair to get further indentation, but that has
>>          the undesirable properties of increasing line count and of not
>>          being robust to relocation outside of an indented paragraph.
>>          Uses .RS/.PP/.EX/.../.EE/.RE.
> 
> But I want the code samples to be indented 4 cells from the paragraph 
> left margin (i.e., 6 cells from the asterisk in this case). So I prefer
> "stock" (status quo). The semantics of .RS are indeed unfortunate.
> 
> Thanks,
> 
> Michael
> 
> -- 
> Michael Kerrisk
> Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
> Linux/UNIX System Programming Training: http://man7.org/training/


So it seems a bug that we need to love because it traces back to 1979,
and so we call it a feature I guess.  But I don't really understand
the feature.  Why would anyone want to specify in a manual page the
indentation with respect to "normal" paragraphs?  One would normally
want to specify the indentation with respect to the running paragraph,
or the absolute indentation (I don't, but can understand why someone
might want that at some point, although I'd say that for such a thing,
roff is probably better suited than man(7)).

While I understand that this has little future, but may I suggest that
we declare it a bug?

To me, it doesn't make any sense that RS nests with itself, but doesn't
nest with other macros that produce indentation such as TP and IP.  In
fact, it's even more counter-intuitive that TP and IP semantics nest
_inside_ RS, but RS doesn't nest "inside" TP and IP.

Cheers,

Alex


-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

OpenPGP_signature
Description: OpenPGP digital signature