[tz] Review incorrect man-pages commit

Sun Mar 20 17:07:20 UTC 2022

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/
http://www.alejandro-colomar.es/