[PATCH] mmap.2: ffix

[PATCH] mmap.2: ffix

[Jakub Wilk]

'" type of behavior:' was incorrectly formatted in bold.

Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
---
 man2/mmap.2 | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/man2/mmap.2 b/man2/mmap.2
index 96b7444b0..f6e406ed5 100644
--- a/man2/mmap.2
+++ b/man2/mmap.2
@@ -289,8 +289,7 @@ Note that older kernels which do not recognize the
 .BR MAP_FIXED_NOREPLACE
 flag will typically (upon detecting a collision with a preexisting mapping)
 fall back to a "non-\c
-.B MAP_FIXED\c
-" type of behavior:
+.BR MAP_FIXED "\(dq type of behavior:"
 they will return an address that is different from the requested address.
 Therefore, backward-compatible software
 should check the returned address against the requested address.
-- 
2.33.1

Re: [PATCH] mmap.2: ffix

[Alejandro Colomar]

Hi, Jakub and Branden!

On 11/12/21 11:39, Jakub Wilk wrote:
> '" type of behavior:' was incorrectly formatted in bold.

Thanks for the report!

> 
> Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
> ---
>  man2/mmap.2 | 3 +--
>  1 file changed, 1 insertion(+), 2 deletions(-)
> 
> diff --git a/man2/mmap.2 b/man2/mmap.2
> index 96b7444b0..f6e406ed5 100644
> --- a/man2/mmap.2
> +++ b/man2/mmap.2
> @@ -289,8 +289,7 @@ Note that older kernels which do not recognize the
>  .BR MAP_FIXED_NOREPLACE
>  flag will typically (upon detecting a collision with a preexisting mapping)
>  fall back to a "non-\c
> -.B MAP_FIXED\c
> -" type of behavior:

Branden, why is that?  Is a leading '"' special here?

> +.BR MAP_FIXED "\(dq type of behavior:"

I'll apply a slightly simpler patch (removing \c):

diff --git a/man2/mmap.2 b/man2/mmap.2
index 30756f078..d0291be8e 100644
--- a/man2/mmap.2
+++ b/man2/mmap.2
@@ -271,9 +271,9 @@ one thread will succeed; all others will report failure.
 Note that older kernels which do not recognize the
 .BR MAP_FIXED_NOREPLACE
 flag will typically (upon detecting a collision with a preexisting mapping)
-fall back to a "non-\c
-.B MAP_FIXED\c
-" type of behavior:
+fall back to a
+.RB \(dqnon- MAP_FIXED \(dq
+type of behavior:
 they will return an address that is different from the requested address.
 Therefore, backward-compatible software
 should check the returned address against the requested address.



>  they will return an address that is different from the requested address.
>  Therefore, backward-compatible software
>  should check the returned address against the requested address.

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: [PATCH] mmap.2: ffix

[G. Branden Robinson]

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

Hi, Alex!

At 2022-02-27T18:09:51+0100, Alejandro Colomar wrote:
> > @@ -289,8 +289,7 @@ Note that older kernels which do not recognize the
> >  .BR MAP_FIXED_NOREPLACE
> >  flag will typically (upon detecting a collision with a preexisting mapping)
> >  fall back to a "non-\c
> > -.B MAP_FIXED\c
> > -" type of behavior:
> 
> Branden, why is that?  Is a leading '"' special here?

Nope.  I think you correctly surmised what the original input was doing.

> > +.BR MAP_FIXED "\(dq type of behavior:"
> 
> I'll apply a slightly simpler patch (removing \c):
[...]
> -fall back to a "non-\c
> -.B MAP_FIXED\c
> -" type of behavior:
> +fall back to a
> +.RB \(dqnon- MAP_FIXED \(dq
> +type of behavior:

This is indeed an improvement.  your change should make no _visible_
change to the rendered document.

I wouldn't use \(dq, though--these quotation marks are for prose, not
code.  I would use left and right double quotation marks.

fall back to a
.RB \(lqnon- MAP_FIXED \(rq
type of behavior:

Regards,
Branden

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

Re: [PATCH] mmap.2: ffix

[Alejandro Colomar (man-pages)]

Hi, Branden!

On 2/27/22 19:57, G. Branden Robinson wrote:
> Hi, Alex!
> 
> At 2022-02-27T18:09:51+0100, Alejandro Colomar wrote:
>>> @@ -289,8 +289,7 @@ Note that older kernels which do not recognize the
>>>  .BR MAP_FIXED_NOREPLACE
>>>  flag will typically (upon detecting a collision with a preexisting mapping)
>>>  fall back to a "non-\c
>>> -.B MAP_FIXED\c
>>> -" type of behavior:
>>
>> Branden, why is that?  Is a leading '"' special here?
> 
> Nope.  I think you correctly surmised what the original input was doing.

Then, should I report a bug in groff?

I could reproduce the incorrect formatted output with
GNU groff version 1.23.0.rc1.1931-35c9b

> 
>>> +.BR MAP_FIXED "\(dq type of behavior:"
>>
>> I'll apply a slightly simpler patch (removing \c):
> [...]
>> -fall back to a "non-\c
>> -.B MAP_FIXED\c
>> -" type of behavior:
>> +fall back to a
>> +.RB \(dqnon- MAP_FIXED \(dq
>> +type of behavior:
> 
> This is indeed an improvement.  your change should make no _visible_
> change to the rendered document.
> 
> I wouldn't use \(dq, though--these quotation marks are for prose, not
> code.  I would use left and right double quotation marks.
> 
> fall back to a
> .RB \(lqnon- MAP_FIXED \(rq
> type of behavior:

Okay, I'll fix that.

Cheers,

Alex

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: [PATCH] mmap.2: ffix

[G. Branden Robinson]

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

Hi, Alex!

> Then, should I report a bug in groff?
> 
> I could reproduce the incorrect formatted output with
> GNU groff version 1.23.0.rc1.1931-35c9b

I didn't even see the run-on bold at first; I was looking for
breaking/spacing problems.

No, groff is behaving correctly as I understand it (and consistently
with Heirloom Doctools troff--I didn't fire up the PDP-11 simulator for
this).

> Okay, I'll fix that.

I'm looking forward to seeing a PDF-hyperlinked rendition of the next
Linux man-pages release, as I've done with the 384-page
"groff-man-pages.pdf".  :)

Regards,
Branden

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

Re: [PATCH] mmap.2: ffix

[Alejandro Colomar (man-pages)]

Hi, Branden!

On 2/28/22 14:18, G. Branden Robinson wrote:
> Hi, Alex!
> 
>> Then, should I report a bug in groff?
>>
>> I could reproduce the incorrect formatted output with
>> GNU groff version 1.23.0.rc1.1931-35c9b
> 
> I didn't even see the run-on bold at first; I was looking for
> breaking/spacing problems.
> 
> No, groff is behaving correctly as I understand it (and consistently
> with Heirloom Doctools troff--I didn't fire up the PDP-11 simulator for
> this).
> 

Ahh, I thought I knew \c.  It seems I didn't.  I thought it was as
simple as "remove any spaces between this line and the next, but
consider them separate in terms of formatting".  But it continues
formatting too.

$ cat c.man
.TH \ec 7 $TODAY alx experiments
.SH NAME
\ec \- experiment
.SH TEST
foo\c
.B bar\c
baz
$ man ./c.man | cat
\c(7)                      experiments                     \c(7)

NAME
       \c - experiment

TEST
       foobarbaz

alx                          $TODAY                        \c(7)


"barbaz" is bold.  I thought only "bar" would be bold.


>> Okay, I'll fix that.
> 
> I'm looking forward to seeing a PDF-hyperlinked rendition of the next
> Linux man-pages release, as I've done with the 384-page
> "groff-man-pages.pdf".  :)

Might be :)
Maybe you release groff-1.23 before we (I?) release man-pages-next (if
it's me releasing, I may delay it until linux-6.0).  If that's the case,
and most distros ship it by that time, I may introduce .MR.

BTW, have you seen the changes I introduced this week?  I'd like to know
your opinion about them, if you have one, since there are quite a lot
of them:

$ git shortlog  --since 'last week' | wc -l
499


They reduce to 3 kinds of changes:

- Add LIBRARY section.  Similar in FreeBSD and NetBSD,
  but I used lowercase for everything but the first letter.

- Remove most of the license texts (all except those that don't have a
  SPDX license tag), and replace them by the license tag.  Add the
  licenses to <LICENSES/>.

- Move types out of system_data_types to separate pages, that are
  much more manageable.  system_data_types(7) was becoming something
  huge like queue(3) once was.  I also wonder if we should inaugurate
  a new subsection of man3 (maybe 3types?).


Regards,
Alex


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/