[tz] [PATCH v2] tzfile.5: Fix indentation

[Paul Eggert]

On 2024-03-18 01:35, Alejandro Colomar wrote:

> Hmm, while Ossana's indents might be a bit excessive, TZDB's might be
> too short.  Maybe I would RS 4 spaces instead of 2 before the tag.

That'd be too long for the nroff case. The nroff case is a bit too long 
already. It looks like the following in the current TZDB version:

  The goals of this section are:

    o  to  help  TZif  writers output files that avoid common pitfalls in
       older or buggy TZif readers,

    o  to help TZif readers avoid  common  pitfalls  when  reading  files
       generated by future TZif writers, and

... and if there were four spaces (instead of two) around the bullets, 
it'd be too much white space.

Of course we could indent more or less depending on whether it's nroff 
or troff, but that's complexity I'd rather avoid.


> I kind of do like pre-indenting bullets; in some cases
> I've felt that having the bullets not indented was sub-par, but wasn't
> convinced enough to go and pre-indent them, since that would add
> complexity, and also allow less room for text in terminals.

Glad you like preindenting. As you say, once one does it, one should use 
less white space.


>> There are other things not to like about the man page PDF output. The man
>> pages are confused about when to use constant-width fonts vs varying-width
>> fonts.
> 
> Can you please point to an example of this?  I try to be consistent, but
> probably there are still cases that I haven't fixed due to lack of time.

See the attached, which is the output of "groff -man -Tpdf zdump.8".

First, I had to do shenanigans like this:

   .ie \n(.g .ds - \f(CR-\fP
   .el .ds - \-

and later use \*- every time I wanted to specify a zdump option like -v.
Using plain "-v" in zdump.8 doesn't work, because it generates a hyphen 
in troff mode and hyphens are too narow. Using "\-v" doesn't work, 
because it generates a mathematical minus sign in the PDF, which differs 
from "-", which means you can't easily search for "-v" in the PDF. So I 
have to use "\*-v" with the above code. And this means the "-" is in a 
different font than the "v".

On page 2, there are some examples in constant width font to make things 
line up. But shouldn't we be using constant width font for all code? 
That's what the rest of the world is doing nowadays (or, if you want to 
be fancy, a sans serif font that stands out in a different way). But 
Linux man page fonts are still stuck with a style defined by the 
limitations of the 1970s C/A/T phototypesetter 
<https://en.wikipedia.org/wiki/CAT_(phototypesetter)> and are using 
Times Bold and Times Italic to refer to program and file names.

Also, it should be ragged right, in both nroff and troff output. 
Right-adjusted text looks nicer but is less functional, and man pages 
should be all about function. (See the reference below.)


>> The lines are too long to read comfortably; this is inherent to how a
>> good font squeezes in more text.
> 
> I'm not sure I understand this.  Do you mean there are too many letters
> in a line in the Linux man-pages PDF or too few?

Too many. I'm getting about 100 characters per line in the PDF, which is 
on the extreme high end of the usual recommendations (it should be 
closer to 60 characters per line). There's no single answer here of 
course (opinions do differ), but the man page lines are pretty clearly 
too long in the PDFs. See:

Nanavati AA, Bias RG. Optimal line length in reading - a literature 
review. Visible Language. 2005;39(2):120-44. 
https://journals.uc.edu/index.php/vl/article/view/5765


> If we compare
> <https://www.alejandro-colomar.es/share/dist/man-pages/git/HEAD/man-pages-HEAD.pdf#tzfile.5>
> with the PDF you attached to your email, you can see there are less
> words in a line in the Linux man-pages PDF than in yours.  Also, your
> PDF has slightly less margins.

They're pretty close, and both have too many characters per line.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: zdump.8.pdf
Type: application/pdf
Size: 35028 bytes
Desc: not available
URL: <https://mm.icann.org/pipermail/tz/attachments/20240407/2c881c3a/zdump.8-0001.pdf>