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.
Attachment:
zdump.8.pdf
Description: Adobe PDF document
