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

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

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 3829 bytes --]

From 25d379c486d28357a8341b0cfbce1b43b82e177f Mon Sep 17 00:00:00 2001
From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Date: Wed, 19 Jul 2023 17:59:27 -0500
Subject: [PATCH 1/2] man*/: ffix (use `\%`)

Protect instances of some literals from hyphenation.  These are only
those necessary to improve analyzability of a large-scale (500+ file),
sed-driven change to improve adjustment and hyphenation enablement
management around tables.

* man2/getrlimit.2: Protect some instances of `RLIMIT_MSGQUEUE`,
  `RLIMIT_SIGPENDING`, `RLIMIT_FSIZE`, and `getrlimit` from hyphenation.
* man2/sigaltstack.2: Protect an instance of `setrlimit` from
  hyphenation.
* man3/gethostbyname.3: Protect an instance of `endhostent` from
  hyphenation.
* man3/getmntent.3: Protect an instance of `getmntinfo` from
  hyphenation.
---
 man2/getrlimit.2     | 10 +++++-----
 man2/sigaltstack.2   |  2 +-
 man3/gethostbyname.3 |  2 +-
 man3/getmntent.3     |  2 +-
 4 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/man2/getrlimit.2 b/man2/getrlimit.2
index 21f919fdc..5d4e428d1 100644
--- a/man2/getrlimit.2
+++ b/man2/getrlimit.2
@@ -577,12 +577,12 @@ .SH STANDARDS
 .B RLIMIT_RSS
 derives from BSD and is not specified in POSIX.1;
 it is nevertheless present on most implementations.
-.BR RLIMIT_MSGQUEUE ,
+.BR \%RLIMIT_MSGQUEUE ,
 .BR RLIMIT_NICE ,
 .BR RLIMIT_RTPRIO ,
 .BR RLIMIT_RTTIME ,
 and
-.B RLIMIT_SIGPENDING
+.B \%RLIMIT_SIGPENDING
 are Linux-specific.
 .SH HISTORY
 .TP
@@ -747,7 +747,7 @@ .SS Representation of """large""" resource limit values on 32-bit platforms
 .\" https://bugzilla.kernel.org/show_bug.cgi?id=5042
 .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=12201
 The most pertinent limit here is
-.BR RLIMIT_FSIZE ,
+.BR \%RLIMIT_FSIZE ,
 which specifies the maximum size to which a file can grow:
 to be useful, this limit must be represented using a type
 that is as wide as the type used to
@@ -769,13 +769,13 @@ .SS Representation of """large""" resource limit values on 32-bit platforms
 Since glibc 2.13,
 .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=12201
 glibc works around the limitations of the
-.BR getrlimit ()
+.BR \%getrlimit ()
 and
 .BR setrlimit ()
 system calls by implementing
 .BR setrlimit ()
 and
-.BR getrlimit ()
+.BR \%getrlimit ()
 as wrapper functions that call
 .BR prlimit ().
 .SH EXAMPLES
diff --git a/man2/sigaltstack.2 b/man2/sigaltstack.2
index 6ae8a612c..b42149541 100644
--- a/man2/sigaltstack.2
+++ b/man2/sigaltstack.2
@@ -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.
 If the standard stack is exhausted, the kernel sends
 the thread a \fBSIGSEGV\fP signal.
 In these circumstances the only way to catch this signal is
diff --git a/man3/gethostbyname.3 b/man3/gethostbyname.3
index 492e22d69..b467e92d9 100644
--- a/man3/gethostbyname.3
+++ b/man3/gethostbyname.3
@@ -377,7 +377,7 @@ .SH ATTRIBUTES
 .BR gethostent (),
 .BR gethostent_r (),
 or
-.BR endhostent ()
+.BR \%endhostent ()
 are used in parallel in different threads of a program,
 then data races could occur.
 .SH STANDARDS
diff --git a/man3/getmntent.3 b/man3/getmntent.3
index 5c0cfde0a..37e7225bd 100644
--- a/man3/getmntent.3
+++ b/man3/getmntent.3
@@ -249,7 +249,7 @@ .SH HISTORY
 .I /etc/mnttab
 is used.
 4.4BSD and Digital UNIX have a routine
-.BR getmntinfo (),
+.BR \%getmntinfo (),
 a wrapper around the system call
 .BR getfsstat ().
 .SH SEE ALSO
-- 
2.30.2


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

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

[Alejandro Colomar]

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

Hi Branden,

On 2023-07-20 04:04, G. Branden Robinson wrote:
> From 25d379c486d28357a8341b0cfbce1b43b82e177f Mon Sep 17 00:00:00 2001
> From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
> Date: Wed, 19 Jul 2023 17:59:27 -0500
> Subject: [PATCH 1/2] man*/: ffix (use `\%`)
> 
> Protect instances of some literals from hyphenation.  These are only
> those necessary to improve analyzability of a large-scale (500+ file),
> sed-driven change to improve adjustment and hyphenation enablement
> management around tables.
> 
> * man2/getrlimit.2: Protect some instances of `RLIMIT_MSGQUEUE`,
>   `RLIMIT_SIGPENDING`, `RLIMIT_FSIZE`, and `getrlimit` from hyphenation.
> * man2/sigaltstack.2: Protect an instance of `setrlimit` from
>   hyphenation.
> * man3/gethostbyname.3: Protect an instance of `endhostent` from
>   hyphenation.
> * man3/getmntent.3: Protect an instance of `getmntinfo` from
>   hyphenation.
> ---
>  man2/getrlimit.2     | 10 +++++-----
>  man2/sigaltstack.2   |  2 +-
>  man3/gethostbyname.3 |  2 +-
>  man3/getmntent.3     |  2 +-
>  4 files changed, 8 insertions(+), 8 deletions(-)
> 
> diff --git a/man2/getrlimit.2 b/man2/getrlimit.2
> index 21f919fdc..5d4e428d1 100644
> --- a/man2/getrlimit.2
> +++ b/man2/getrlimit.2
> @@ -577,12 +577,12 @@ .SH STANDARDS
>  .B RLIMIT_RSS
>  derives from BSD and is not specified in POSIX.1;
>  it is nevertheless present on most implementations.
> -.BR RLIMIT_MSGQUEUE ,
> +.BR \%RLIMIT_MSGQUEUE ,
>  .BR RLIMIT_NICE ,
>  .BR RLIMIT_RTPRIO ,
>  .BR RLIMIT_RTTIME ,
>  and
> -.B RLIMIT_SIGPENDING
> +.B \%RLIMIT_SIGPENDING
>  are Linux-specific.
>  .SH HISTORY
>  .TP
> @@ -747,7 +747,7 @@ .SS Representation of """large""" resource limit values on 32-bit platforms
>  .\" https://bugzilla.kernel.org/show_bug.cgi?id=5042
>  .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=12201
>  The most pertinent limit here is
> -.BR RLIMIT_FSIZE ,
> +.BR \%RLIMIT_FSIZE ,
>  which specifies the maximum size to which a file can grow:
>  to be useful, this limit must be represented using a type
>  that is as wide as the type used to
> @@ -769,13 +769,13 @@ .SS Representation of """large""" resource limit values on 32-bit platforms
>  Since glibc 2.13,
>  .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=12201
>  glibc works around the limitations of the
> -.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?
Makes sense.

>  as wrapper functions that call
>  .BR prlimit ().
>  .SH EXAMPLES
> diff --git a/man2/sigaltstack.2 b/man2/sigaltstack.2
> index 6ae8a612c..b42149541 100644
> --- a/man2/sigaltstack.2
> +++ b/man2/sigaltstack.2
> @@ -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.
Do you prefer it in this order?

Also, it seem this one is wrong: it should be I, as it's code.

Cheers,
Alex

>  If the standard stack is exhausted, the kernel sends
>  the thread a \fBSIGSEGV\fP signal.
>  In these circumstances the only way to catch this signal is
> diff --git a/man3/gethostbyname.3 b/man3/gethostbyname.3
> index 492e22d69..b467e92d9 100644
> --- a/man3/gethostbyname.3
> +++ b/man3/gethostbyname.3
> @@ -377,7 +377,7 @@ .SH ATTRIBUTES
>  .BR gethostent (),
>  .BR gethostent_r (),
>  or
> -.BR endhostent ()
> +.BR \%endhostent ()
>  are used in parallel in different threads of a program,
>  then data races could occur.
>  .SH STANDARDS
> diff --git a/man3/getmntent.3 b/man3/getmntent.3
> index 5c0cfde0a..37e7225bd 100644
> --- a/man3/getmntent.3
> +++ b/man3/getmntent.3
> @@ -249,7 +249,7 @@ .SH HISTORY
>  .I /etc/mnttab
>  is used.
>  4.4BSD and Digital UNIX have a routine
> -.BR getmntinfo (),
> +.BR \%getmntinfo (),
>  a wrapper around the system call
>  .BR getfsstat ().
>  .SH SEE ALSO

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


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

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

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 2738 bytes --]

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...

> > @@ -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.

> 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.

Regards,
Branden

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

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

[Alejandro Colomar]

[-- 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 --]

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

[Alejandro Colomar]

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

On 2023-07-20 04:04, G. Branden Robinson wrote:
> From 25d379c486d28357a8341b0cfbce1b43b82e177f Mon Sep 17 00:00:00 2001
> From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
> Date: Wed, 19 Jul 2023 17:59:27 -0500
> Subject: [PATCH 1/2] man*/: ffix (use `\%`)
> 
> Protect instances of some literals from hyphenation.  These are only
> those necessary to improve analyzability of a large-scale (500+ file),
> sed-driven change to improve adjustment and hyphenation enablement
> management around tables.
> 
> * man2/getrlimit.2: Protect some instances of `RLIMIT_MSGQUEUE`,
>   `RLIMIT_SIGPENDING`, `RLIMIT_FSIZE`, and `getrlimit` from hyphenation.
> * man2/sigaltstack.2: Protect an instance of `setrlimit` from
>   hyphenation.
> * man3/gethostbyname.3: Protect an instance of `endhostent` from
>   hyphenation.
> * man3/getmntent.3: Protect an instance of `getmntinfo` from
>   hyphenation.

I added a S-o-b for you.

Patch applied.

Cheers,
Alex

> ---
>  man2/getrlimit.2     | 10 +++++-----
>  man2/sigaltstack.2   |  2 +-
>  man3/gethostbyname.3 |  2 +-
>  man3/getmntent.3     |  2 +-
>  4 files changed, 8 insertions(+), 8 deletions(-)
> 
> diff --git a/man2/getrlimit.2 b/man2/getrlimit.2
> index 21f919fdc..5d4e428d1 100644
> --- a/man2/getrlimit.2
> +++ b/man2/getrlimit.2
> @@ -577,12 +577,12 @@ .SH STANDARDS
>  .B RLIMIT_RSS
>  derives from BSD and is not specified in POSIX.1;
>  it is nevertheless present on most implementations.
> -.BR RLIMIT_MSGQUEUE ,
> +.BR \%RLIMIT_MSGQUEUE ,
>  .BR RLIMIT_NICE ,
>  .BR RLIMIT_RTPRIO ,
>  .BR RLIMIT_RTTIME ,
>  and
> -.B RLIMIT_SIGPENDING
> +.B \%RLIMIT_SIGPENDING
>  are Linux-specific.
>  .SH HISTORY
>  .TP
> @@ -747,7 +747,7 @@ .SS Representation of """large""" resource limit values on 32-bit platforms
>  .\" https://bugzilla.kernel.org/show_bug.cgi?id=5042
>  .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=12201
>  The most pertinent limit here is
> -.BR RLIMIT_FSIZE ,
> +.BR \%RLIMIT_FSIZE ,
>  which specifies the maximum size to which a file can grow:
>  to be useful, this limit must be represented using a type
>  that is as wide as the type used to
> @@ -769,13 +769,13 @@ .SS Representation of """large""" resource limit values on 32-bit platforms
>  Since glibc 2.13,
>  .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=12201
>  glibc works around the limitations of the
> -.BR getrlimit ()
> +.BR \%getrlimit ()
>  and
>  .BR setrlimit ()
>  system calls by implementing
>  .BR setrlimit ()
>  and
> -.BR getrlimit ()
> +.BR \%getrlimit ()
>  as wrapper functions that call
>  .BR prlimit ().
>  .SH EXAMPLES
> diff --git a/man2/sigaltstack.2 b/man2/sigaltstack.2
> index 6ae8a612c..b42149541 100644
> --- a/man2/sigaltstack.2
> +++ b/man2/sigaltstack.2
> @@ -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.
>  If the standard stack is exhausted, the kernel sends
>  the thread a \fBSIGSEGV\fP signal.
>  In these circumstances the only way to catch this signal is
> diff --git a/man3/gethostbyname.3 b/man3/gethostbyname.3
> index 492e22d69..b467e92d9 100644
> --- a/man3/gethostbyname.3
> +++ b/man3/gethostbyname.3
> @@ -377,7 +377,7 @@ .SH ATTRIBUTES
>  .BR gethostent (),
>  .BR gethostent_r (),
>  or
> -.BR endhostent ()
> +.BR \%endhostent ()
>  are used in parallel in different threads of a program,
>  then data races could occur.
>  .SH STANDARDS
> diff --git a/man3/getmntent.3 b/man3/getmntent.3
> index 5c0cfde0a..37e7225bd 100644
> --- a/man3/getmntent.3
> +++ b/man3/getmntent.3
> @@ -249,7 +249,7 @@ .SH HISTORY
>  .I /etc/mnttab
>  is used.
>  4.4BSD and Digital UNIX have a routine
> -.BR getmntinfo (),
> +.BR \%getmntinfo (),
>  a wrapper around the system call
>  .BR getfsstat ().
>  .SH SEE ALSO

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


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