Hi Paul!
[reordered quotes for my reply]
On 3/8/23 06:19, Paul Eggert wrote:
>
> Come to think of it, we should resync tzfile.5 and tzselect.8 from
> upstream for other reasons. Proposed patch to manpages attached. If this
> generates more mandoc warnings, I suppose we can adjust the calls to mandoc.
Yes, I like having them as synced as possible (ideally, we would just
hold a simple copy in the Linux man-pages). I've applied your patch.
BTW, I have some comments to make about the patch, and it would be
easier to make them if the patch was not attached, but rather inline
in the mail. (IIRC, I also have a few comments about your other patch
submitted recently, and I haven't answered so far because I find it
cumbersome to copy from the attachment into the email to do a proper
reply; but I'm not ignoring it; just finding some time for it ;)
Would you mind sending your patches inline, if it's not much
cumbersome to you? But I guess you may have your customs though,
so if you prefer sending them attached, that's fine; it'll just
take me a bit more time to reply, but I appreciate your contributions
anyway :-)
> I suggest reverting all those changes to
> tzfile.5, since the upstream tzfile.5 continues to use \(lq etc. for
> compatibility with traditional troff, which is still a thing upstream.
Yup, no problem with that. I applied the patch to tz* pages by
accident. It wasn't my intention to deviate from upstream. I
just applied the scripted changes to all pages blindly, and forgot
to keep the external pages out of the patches.
> On 2023-03-07 15:54, Alejandro Colomar wrote:
>> mandoc: man5/tzfile.5:15:19: WARNING: undefined escape, printing literally: \\
>> mandoc: man5/tzfile.5:15:10: WARNING: undefined escape, printing literally: \\
>
> My guess is that this is fallout from last month's changes to use \[lq]
> instead of \(lq and so forth.
It seems not. I still see the warning.
alx@debian:~/src/linux/man-pages/man-pages/main$ grep -n '\\\\' man5/tzfile.5
15:\\$3\*(lq\\$1\*(rq\\$2
alx@debian:~/src/linux/man-pages/man-pages/main$ make lint-man-mandoc V=1
LINT (mandoc) tmp/lint/man5/tzfile.5.lint-man.mandoc.touch
! (mandoc -man -Tlint man5/tzfile.5 2>&1 \
| grep -v 'STYLE: lower case character in document title:' \
| grep -v 'UNSUPP: ignoring macro in table:' \
| grep -v 'WARNING: cannot parse date, using it verbatim: TH (date)' \
| grep -v 'WARNING: empty block: UR' \
||:; \
) \
| grep '.' >&2
mandoc: man5/tzfile.5:15:18: WARNING: undefined escape, printing literally: \\
mandoc: man5/tzfile.5:15:9: WARNING: undefined escape, printing literally: \\
make: *** [lib/lint-man.mk:88: tmp/lint/man5/tzfile.5.lint-man.mandoc.touch] Error 1
I don't run these tests often, so I'm not saying this is a new warning.
It has been there probably since forever. It's just that previously
there were many other pages that gave warnings, but now I've cleaned
most of those, and your pages are the only ones --together with
bpf-helpers(7)-- that trigger warnings from `make lint-man-mandoc`.
And now some question about the patch itself (I've applied it, but
there's something itching me):
> commit bab8324d213362bbb59434748797a0cddcbefecd (HEAD -> master, korg/master)
> Author: Paul Eggert <eggert@xxxxxxxxxxx>
> Date: Tue Mar 7 21:11:38 2023 -0800
>
> tzfile.5, tzselect.8: sync from tzdb upstream
>
> This makes tzfile.5 and tzselect.8 a copy of the tzdb develoment
> version (commit 12b48faf10c265ee3ea1aad8cdb5c8239eea65a0), except that
> man-pages boilerplate surrounds the copyright notice, and the .TH line
> uses man-pages format.
I guess you referred to the TH line in the tzselect.8 page, which
doesn't show a date, has the project and (unreleased) version in
the 4th field, and has no 5th field.
>
> Signed-off-by: Alejandro Colomar <alx@xxxxxxxxxx>
>
> diff --git a/man5/tzfile.5 b/man5/tzfile.5
> index aa2170479..e94aaaad6 100644
> --- a/man5/tzfile.5
> +++ b/man5/tzfile.5
> @@ -1,21 +1,21 @@
> .\" %%%LICENSE_START(PUBLIC_DOMAIN)
> .\" This file is in the public domain, so clarified as of
> -.\" 1996-06-05 by Arthur David Olson <arthur_david_olson@xxxxxxx>.
> +.\" 1996-06-05 by Arthur David Olson.
> .\" %%%LICENSE_END
> .\"
> -.TH tzfile 5 2022-09-09 Linux "Linux Programmer's Manual"
> +.TH tzfile 5 2023-03-07 Linux "Linux Programmer's Manual"
I don't like this TH line, because:
- The 4th argument is supposed to specify the project and version
of the upstream manual page. That should be your project and
version (similar to how the Linux man-pages pages have in the
latest release "Linux man-pages 6.03"). For example, another
page that is synced from upstream is bpf-helpers.7. It has the
following:
$ grep '\.TH' man7/bpf-helpers.7
.TH "BPF-HELPERS" 7 "2022-09-26" "Linux v6.1"
Would you mind specifying your own project and version upstream
so I could keep them untouched?
I'd also like if you specified the last-modified date when you
make a release, but if we sync the page from git HEAD that's less
important. You could do something similar to the placeholder
'(date)' that we use, and somehow update it at release time.
> .SH NAME
> tzfile \- timezone information
> .SH DESCRIPTION
[...]
> diff --git a/man8/tzselect.8 b/man8/tzselect.8
> index 2319c6158..3b69587f3 100644
> --- a/man8/tzselect.8
> +++ b/man8/tzselect.8
> @@ -1,53 +1,128 @@
> .\" %%%LICENSE_START(PUBLIC_DOMAIN)
> -.\" This page is in the public domain
> +.\" This file is in the public domain, so clarified as of
> +.\" 2009-05-17 by Arthur David Olson.
> .\" %%%LICENSE_END
> .\"
> .TH tzselect 8 (date) "Linux man-pages (unreleased)"
And don't really like this one either, since it looks like
the Linux man-pages is the upstream of the page, and it's not.
I probably changed this also by accident in some scripted patch.
I realized and avoided it for tzfile.5, but forgot about this
one :/.
> .SH NAME
> tzselect \- select a timezone
> .SH SYNOPSIS
Cheers,
Alex
--
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
Attachment:
OpenPGP_signature
Description: OpenPGP digital signature
