Re: [PATCH v2] mount_setattr.2: New manual page documenting the mount_setattr() system call

["Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>]

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/