Hi Branden!
On 8/1/21 12:02 PM, G. Branden Robinson wrote:
[CC list brutally trimmed]
Hi, Alex!
At 2021-07-31T13:20:59+0200, Alejandro Colomar (man-pages) wrote:
On 7/31/21 3:42 AM, G. Branden Robinson wrote:
[...]
I recommend:
.BI MOUNT_ATTR_SIZE_VER number\c
\&.
I also prefer your way (at least in cases like this one (maybe in the
synopsis \f would be more appropriate)). It is more consistent with
our current style of placing each identifier in a line of its own, and
normal text separately (punctuation is placed wherever it's simpler,
but in this case I think it's simpler in a separate line).
Another benefit of using the font escapes that I was reminded of today
while doing a big revision pass on groff_man_style(7)[1] is that you get
italic corrections for free with them. This was already true to some
extent in groff 1.22.4, but I refactored the implementation of the
macros earlier this year to be brutally consistent[2].
I would say that I like being able to tell man page authors that they
need not learn the italic correction escapes, but I'd probably hear from
many of them that they had no intention of doing so in the first place.
I might get threatened with defections to RST and Sphinx just for
bringing it up. 🤣
What are "font escapes" and "italic correction escapes"? I don't know
those technical terms.
[...]
groff -man -rCHECKSTYLE=n
[...]
I'll try it. Thanks!
Cool!
+.BR open_tree (2)
+with the
+.I OPEN_TREE_CLONE
+flag and it must not already have been visible in the filesystem.
+.RE
+.IP
.IP here doesn't mean anything, if I'm not mistaken.
It certainly _should_--it should cause the insertion of vertical
space. (It would also cause a break, but .RE already did that.)
The interaction of .IP and .RS/.RE is tricky and can probably be
blamed, back in 2017, for irritating me to the point that I became a
groff developer. I've documented it as extensively as I am able in
groff_man_style(7)[1].
Yes, indeed there are 2 consecutive blank lines, which is incorrect
most likely.
That sounds like a bug in your man(7) renderer, and it sounds badly
violative of the semantics of these macros in _any_ implementation.
(You can't stack adjacent paragraph macros to make additional blank
space; you just get the one.[3]) This stuff has been stable since 1979.
I do not get _2_ blank lines after the paragraph ending "visible in the
filesystem." Just one. None of groff 1.22.4 (Debian), groff Git HEAD,
nor mandoc 1.14.4 misrender for me in that way. What's your tool set?
If it's groff, I'm intensely curious to know how it's screwing this up.
I can likely help you root-cause it.
Ahh, I used mgroff(1) (mental groff). I should debug my mental parser.
So, as I suspected, that .IP is ignored, if my mental groff is working
correctly now.
Probably a glitch of copying and pasting without really understanding
what each macro does (not to blame Christian, but that the
groff_man(7) language (or dialect actually) is not something familiar
to programmers, and most of them legitimately don't have time to learn
it well).
There is a wealth of terrible examples to follow, which make the
language seem harder than it is. A large part of my work on groff's man
pages has been to make them good examples to follow--but as, at my last
count, groff's ~60 man pages produce 364 pages of type on U.S. letter
paper, this is a process that is taking some time.
I acknowledge that you and Michael are wrestling an even bigger bear. :)
Yup. Since almost when I started here, I'm trying to have the man-pages
be consistent across all of the pages, both in terms of source code and
rendered output. Not an easy thing...
I hope that when I finish this (if it can ever be finished), reading and
writing man-pages is a simpler task for newbies :)
Regards,
Alex
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
