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.
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.
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
Attachment:
signature.asc
Description: PGP signature
