Re: man-pages.7: Simplify indentation of structure definitions, shell session logs, and so on

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

Hi Branden,

I want to circle back to a point you raised...

On 9/21/20 4:15 PM, G. Branden Robinson wrote:
> At 2020-09-21T09:49:11+0200, Michael Kerrisk (man-pages) wrote:
>> On Mon, 21 Sep 2020 at 09:32, Alejandro Colomar <colomar.6.4.3@gmail.com> wrote:
>>> Indentation of structure definitions, shell session logs, and so on
>>>
>>> When  structure definitions, shell session logs, and so on are included
>>> in running text, indent them by 4 spaces (i.e.,  a  block  enclosed  by
>>> .in +4n and .in), format them using the .EX and EE macros, and surround
>>> them with suitable paragraph markers (either .PP or .IP).  For example:
>>>
>>>                 .PP
>>>                 .in +4n
>>>                 .EX
>>>                 int
>>>                 main(int argc, char *argv[])
>>>                 {
>>>                     return 0;
>>>                 }
>>>                 .EE
>>>                 .in
>>>                 .PP
>>>
>>>
>>> That could be simplified to the following, right?:
>>>
>>>                 .IP
>>>                 .EX
>>>                 int
>>>                 main(int argc, char *argv[])
>>>                 {
>>>                     return 0;
>>>                 }
>>>                 .EE
>>>                 .PP
>>>
>>> Or is there any difference?
>>
>> .IP indents by 8 spaces by default, I think.
> 
> 7 "ens" on nroff devices (like terminals), 7.2n on troff devices.
> 
> An "en" is a traditional typesetting unit of measure, the width of a
> letter "n" in the font being used.  For monospaced fonts, including
> those used in character-cell terminals--barring the employment of CJK
> "fullwidth" code points--this is the same width as a space.
> 
>> Also, .IP won't indent further, if we are already in an area of
>> indented paragraphs.
> 
> This is true.  In my maintenance work on groff's man pages I have
> devised an idiom of calling .RS twice, putting in the desired material,
> and then calling .RE twice.

If I understand what you are saying, then iif we are at an indented
level (.TP, .IP), then we can use your idiom:

.RS
.RS n
...
.RE
.RE


But, this idiom won't work if we're not at an indented level (?).
In other words, at .PP level we should not use .RS/.RS n/.RE/.RE, 
right?

By contrast, ".in +n/.in" works regardless of whether we 
are at an indented level, right? (I'm not saying this recommend
the use of .in; I just want to clarify my understanding.)

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/