Re: [PATCH 1/2] man*/: ffix (use `\%`)

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1.1: Type: text/plain, Size: 3767 bytes --]

On 2023-07-20 11:10, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2023-07-20T10:18:15+0200, Alejandro Colomar wrote:
>>> -.BR getrlimit ()
>>> +.BR \%getrlimit ()
>>>  and
>>>  .BR setrlimit ()
>>>  system calls by implementing
>>>  .BR setrlimit ()
>>>  and
>>> -.BR getrlimit ()
>>> +.BR \%getrlimit ()
>>
>> So, you don't want MR in these cases, right?
> 
> Right.  These functions are documented in the same page, so it's not
> sensible to mark them up with a man:getrlimit(3) hyperlink.
> 
> Yes, it is possible to conceive ctags-like internal linkage, but let's
> storm one Bastille at a time...

Agree.  Let's kill ctags another day ;)

> 
>>> @@ -230,7 +230,7 @@ .SH NOTES
>>>  expects that it may exhaust its standard stack.
>>>  This may occur, for example, because the stack grows so large
>>>  that it encounters the upwardly growing heap, or it reaches a
>>> -limit established by a call to \fBsetrlimit(RLIMIT_STACK, &rlim)\fP.
>>> +limit established by a call to \fB\%setrlimit(RLIMIT_STACK, &rlim)\fP.
>>
>> I think I would fix those \f thingies before messing with them.
> 
> I'm pretty sure you know I'm not fond of them either.  ;-)
> 
>> Do you prefer it in this order?
> 
> Yes, because it enables a larger, more impactful change that fixes a
> problem with ghastly amounts of noise when regression-testing changes to
> Linux man-pages.  When adjustment and hyphenation churn, the results are
> ugly, and often irrelevant to the work being done.  With the gzipped
> change that followed this one applied, that should stop being a problem,
> for the reasons explained in its lengthy commit message.

Okay, I'll try to apply this set as early as possible.

Thanks,
Alex

> 
>> Also, it seem this one is wrong: it should be I, as it's code.
> 
> That decision is above my pay grade; I'm not the style czar for the
> Linux man-pages project.  ;-)
> 
> FWIW, I prefer italics myself for 2 reasons:
> 
> 1.  The general typographic rule which says to use the least garish for
>     of emphasis that gets the job done.  That means bold is nearly a
>     last resort, before full capitals.
> 
> 2.  It's an inline code example and I'm accustomed to seeing these in
>     italics (or Courier) in well-known Unix software engineering texts.
> 
> A counterargument is that "setrlimit" is a topic of the page in
> question.  groff_man_style(7) says:
> 
>         Use bold for literal portions of syntax synopses, for command‐
>         line options in running text, and for literals that are major
>         topics of the subject under discussion; for example, this page
>         uses bold for macro, string, and register names.  In an .EX/.EE
>         example of interactive I/O (such as a shell session), set only
>         user input in bold.
> 
> ...but one could well counter that in that case only "setrlimit" itself,
> not the entire function call with parameters, should be boldfaced.

The below applies here:

man-pages(7):
   Formatting conventions (general)
	[...]

       If the command is short, then it can be included inline in  the
       text,  in italic format, for example, man 7 man‐pages.  In this
       case, it may be worth using nonbreaking spaces (\[ti]) at suit‐
       able places in the command.  Command options should be  written
       in italics (e.g., -l).

       Expressions, if not written on a separate indented line, should
       be  specified in italics.  Again, the use of nonbreaking spaces
       may be appropriate if the expression  is  inlined  with  normal
       text.

> 
> Regards,
> Branden

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]