Re: Review incorrect man-pages commit

Alejandro Colomar (man-pages)
2022-03-20T17:07:26Z

Hi, Branden!

On 3/20/22 11:52, G. Branden Robinson wrote:
>
> Sure! The punctuation does get a bit bewildering.
>
[...]

Thanks for the great explanation!

>
> Now, for the part people actually care about, which is how to fix it:
> take the escape character off of that `.
>
> You thus want
>
> +to "\fI[a\('a\(`a\(:a\(^a]\fP", that is,

I applied a patch with this.

>
> If you wanted to write this without using any aliases, you could adopt
> groff syntax.
>
> +to "\fI[a\[a aa]\[a ga]\[a ad]\[a a^]\fP", that is,

I'm going to hold this for later, so that we decide globally how to
format all pages, and not just this one. I prefer global consistency here.

>
> I don't know if people regard that as more or less impenetrable. It is
> more _flexible_, and admits usage of diacritics/combining characters not
> envisioned by AT&T troff or ISO Latin-1. groff supports a baker's
> dozen. They are in a table titled "Accents" in groff_char(7) (1.22.4).
>
>> diff --git a/man8/zic.8 b/man8/zic.8
>> index 940d6e814..aeca0e726 100644
>> --- a/man8/zic.8
>> +++ b/man8/zic.8
>> @@ -293,7 +293,7 @@ nor
>> .q + .
>> To allow for future extensions,
>> an unquoted name should not contain characters from the set
>> -.q !$%&'()*,/:;<=>?@[\e]^`{|}\(ti .
>> +.q !$%&'()*,/:;<=>?@[\e]^\`{|}\(ti .
>
> You didn't proffer any complaints about the foregoing, so I assume it
> was just for context (to include the whole commit, maybe).

Yep

> Nevertheless I think it can be further improved.
>
> That neutral apostrophe and caret/circumflex should be changed as well,
> to ensure that they don't render as a directional closing (right) single
> quote, ’ U+2019 and modifier letter circumflex ˆ U+02C6. This advice is
> also in groff 1.22.4's groff_man(7) page.
>
> +.q !$%&\(aq()*,/:;<=>?@[\e]\(ha\`{|}\(ti .
>
> Moreover, as partly noted in our discussion about double quotes in macro
> arguments, there were no special characters for the double quote or
> neutral apostrophe in Unix troff. Since we're not getting 50 years of
> backward compatibility anyway, for the Linux man-pages project I
> recommend going ahead and using groff-style escape sequences for these.
>
> +.q !$%&\[aq]()*,/:;<=>?@[\[rs]]\[ha]\`{|}\[ti] .
>
> Are you willing to settle for 30 years of backward compatibility? ;-)

I do :)

However, I'm not going to fix this page, according to MAINTAINER_NOTES:

$ cat MAINTAINER_NOTES
Externally generated pages
==========================

A few pages come from external sources. Fixes to the pages should really
go to the upstream source.

tzfile(5), zdump(8), and zic(8) come from the tz project
(https://www.iana.org/time-zones).

bpf-helpers(7) is autogenerated from the kernel sources using scripts.
See man-pages commit 53666f6c30451cde022f65d35a8d448f5a7132ba for
details.

So now I wonder why this commit was written in the first place, since it
breaks one page, and fixes another that shouldn't be fixed.
I CCd the tz mailing list in case they want to fix the upstream page
(which I couldn't find, BTW).

>
> In my opinion it is more helpful in dense contexts like this to have the
> paired delimiters [ ] to demarcate the glyph identifier then to achieve
> portability to systems that don't support identifiers you need anyway.

Yes, I agree with that.

>
> (I note that `q` is a page-local macro and therefore bad style for
> portability reasons. That said, I have been _sorely_ tempted to add a
> `Q` macro for this precise purpose to groff man(7). I have hopes that
> it would give people something to reach for besides bold and italics for
> every damn thing.)
>
> Most--I hope all--of the above is discussed comprehensively in the
> current version of groff_char(7)[2], which I have rewritten completely
> since groff 1.22.4 and substantially modified even since the last Linux
> man-pages snapshot at
> <https://man7.org/linux/man-pages/man7/groff_char.7.html>. I now know
> the answers to many questions of the form "why the **** is {groff,troff}
> this way?", and have endeavored to share them. The "History" section is
> completely new.
>
> Regards,
> Branden
>
> [1] groff's own man pages are not without sin in this regard. I have
> cleaned them up a lot since 1.22.4, but a few adventurous stragglers
> remain that define and use page-local macros pervasively. All are
> on the long side.
>
> [2] https://git.savannah.gnu.org/cgit/groff.git/tree/man/groff_char.7.man
>
> I recommend that for source perusal only; do not try to render it
> with man-db man(1) or groff 1.22.4, because groff 1.23.0 will be
> adding a new macro, `MR`, for man page cross references[3] and its
> own pages have already been ported to use it. (This is where I
> flagellate myself for not having a groff 1.23.0-rc2 out yet. :( )
>
> [3] https://git.savannah.gnu.org/cgit/groff.git/tree/NEWS#n165

I like your references usually containing other references themselves.
It's funny :-)

Cheers,

Alex

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