Re: .RS

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

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/