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/
