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@xxxxxxxxx> 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/
