Re: mandoc(1) warning in tzfile(5) regarding //

[Alejandro Colomar <alx.manpages@gmail.com>]

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

Hi Paul,

On 3/8/23 22:54, Paul Eggert wrote:
> On 3/8/23 11:44, Alejandro Colomar wrote:>> I still see the warning.
> 
> Oh well. Looks like a mandoc bug; maybe it can't tell that we're in a 
> macro so '\\' is OK, indeed expected.

I'll report this in mandoc(1) then.  Thanks for confirming.  Although
maybe this is expected of mandoc(1), since it's not a generic roff(7)
interpreter...  I CCd Ingo (mandoc(1) maintainer) in case he's interested
in the bug.


>>> -.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
> 
> That's the Linux man page's .TH line not the tzdb .TH line.

I know :)

> I merely 
> used the format that was already there. The tzdb .TH line is merely ".TH 
> TZFILE 5". So you can edit the man-pages .TZ line any way you like.

I prefer if we come up with some good upstream TH line that I can keep.  :)

> 
> Come to think of it, the tzdb man pages aren't systematic about .TH line 
> capitalization. Some use uppercase (the style in 7th Edition Unix), some 
> lowercase (more common in recent decades). Let's go with lowercase. 
> Proposed tzdb patch attached, and installed in the development 
> repository.

That patch looks good to me.  If you use these:

Reviewed-by: Alejandro Colomar <alx@kernel.org>


>  If mandoc complains about this, that's mandoc's problem not 
> ours.

Indeed.  It complains, but Ingo was in favor of removing that warning, and
modifying their own pages to use lowercase too.

In the Linux man-pages I'm ignoring that warning with:

! (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

> 
> 
>>     Would you mind specifying your own project and version upstream
>>     so I could keep them untouched?
> 
> I can see problems with that. First, it's tzdb commit 
> 12b48faf10c265ee3ea1aad8cdb5c8239eea65a0 and I doubt whether man page 
> readers want to see that. We do have a mechanism for converting that 
> commit ID to the quasi version number "2022g-64-g12b48fa" but this quasi 
> version number depends on development history not merely on current 
> state, so it has its own issues.

Makes sense.  In that case, I suggest using the project name without a
version.  How about the following?

.TH tzfile 5 "" tzdb

(or alternatively:)

.TH tzfile 5 "" "Time Zone Database"

The "" (3rd field) is for the date, which we don't want to be updating.
The 4th field has only the project name, but not the version, since it
would also be complicated to update.  (You could use 'tzbd' or "Time
Zone Database", whatever you prefer.)  The 5th field is also missing,
since the default value is good enough (for section 5 it's "File Formats
Manual").

If you use that line upstream, I'd keep it untouched in the Linux man-pages.

> 
> Another way the files differ is in the lack of 
> "%%%LICENSE_START(PUBLIC_DOMAIN)" and "%%%LICENSE_END" boilerplate 
> upstream.

I removed it in most pages.  Most pages now use SPDX-License-Identifier.
If that's the only remaining difference from upstream, I'd also remove it, 

> I've been reluctant to do that upstream since I expect each 
> downstream user has its own format for comments regarding licensing, 
> SBOM, SSDF, SCA, and so forth (and if you don't know what those acronyms 
> mean then I envy you :-).

I don't :-)

$ wtf is SBOM
Gee...  I don't know what SBOM means...
$ wtf is SSDF
Gee...  I don't know what SSDF means...
$ wtf is SCA
Gee...  I don't know what SCA means...
$ dict SBOM
No definitions found for "SBOM", perhaps you mean:
gcide:  Bom  Swom
wn:  som
vera:  bom  som  sbod
foldoc:  bsom  som  sbm
$ dict SSDF
No definitions found for "SSDF", perhaps you mean:
vera:  sdf  ssf  ssd  sadf  sidf  srdf  sscf  ssrf  ssda  ssdc
  ssdd  ssdp  ssdu
foldoc:  sdf  ssd


There's a dict(1) entry for SCA, but I don't think it's related to
this :).

Cheers,

Alex

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

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