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,

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.

D'oh, yes. 7!

> 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.
> 
> In membarrier(2), however, life is simple because no code examples are
> being nested inside an indented paragraph (.IP).  I'm attaching a patch;
> it produces no visible difference in output, not even white space
> changes.
> 
> I should add that my suggestion is to _not_ specify precise indentation
> amounts in man pages, as this is a presentation matter and readers may
> prefer tighter or more generous indentation, which they can control via
> the IN register; that is, passing -rIN to the groff command.  (Or, more
> likely, by configuring it in their man.local file so all pages that
> respect the user's wishes are consistent.)
> 
> I've been improving the groff_man(7) page over the past few years to
> document all of this stuff much better, and recently in groff git[1]
> I've split out a groff_man_style(7) page.  The latter is (as near as
> makes no difference) a strict superset of the former.
> 
> Michael's site has a fairly recent snapshot of these pages:
>   https://man7.org/linux/man-pages/man7/groff_man.7.html
>   https://man7.org/linux/man-pages/man7/groff_man_style.7.html
> 
> Feedback is welcome.  For the latter page, I still need to write my
> grand introduction where I explain the real typesetting basics: filling,
> adjusting, breaking, and how these all relate to hyphenation.
> 
> In my opinion, .in requests are never necessary in idiomatic,
> well-written man pages and I'm happy to offer technical advice for how
> to achieve the desired result without using them.

So, I don't disagree with you. (And as ever, thank you for your
detailed input.) The pattern I use above (with ".in +4n/.in" was a
hack that I cam up with to get code blocks with a "suitable"
indent. Your suggestion of ".RS 4/.RE" (in your patch, which I've
quoted inline below), does seem better. I'm not averse to changing
things. But, there is a related question. I use a similar hack in
the SYNOPSIS of many pages (e.g., chmod.2), to undent a single
line:

[[
.PP
.in -4n
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.in
.PP
]]

Presumably, that could be replaced with ".RS -4/.RE", but is
there something even better?

Thanks,

Michael
> 
> I'm also happy to prepare patches for man-pages documents implementing
> my recommendations.  :)
> 
> Regards,
> Branden
> 
> [1] https://git.savannah.gnu.org/cgit/groff.git
> 

======

Use .RS/.RE man macros instead of .in requests.

diff --git a/man2/membarrier.2 b/man2/membarrier.2
index f65c6be5c..526bb3819 100644
--- a/man2/membarrier.2
+++ b/man2/membarrier.2
@@ -60,11 +60,11 @@ The key idea is to replace, for these matching
 barriers, the fast-side memory barriers by simple compiler barriers,
 for example:
 .PP
-.in +4n
+.RS 4
 .EX
 asm volatile ("" : : : "memory")
 .EE
-.in
+.RE
 .PP
 and replace the slow-side memory barriers by calls to
 .BR membarrier ().
@@ -285,7 +285,7 @@ very frequently, and where "slow_path()" is executed infrequently, the
 following code (x86) can be transformed using
 .BR membarrier ():
 .PP
-.in +4n
+.RS
 .EX
 #include <stdlib.h>
 
@@ -332,13 +332,13 @@ main(int argc, char **argv)
     exit(EXIT_SUCCESS);
 }
 .EE
-.in
+.RE
 .PP
 The code above transformed to use
 .BR membarrier ()
 becomes:
 .PP
-.in +4n
+.RS
 .EX
 #define _GNU_SOURCE
 #include <stdlib.h>
@@ -421,4 +421,4 @@ main(int argc, char **argv)
     exit(EXIT_SUCCESS);
 }
 .EE
-.in
+.RE

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