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:
OpenPGP_signature
Description: OpenPGP digital signature
