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

[Alejandro Colomar]

Hi Paul, Branden,

On Sun, Apr 07, 2024 at 11:33:38PM -0700, Paul Eggert wrote:
> 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.

Yeah, I was thinking only of the typeset version.  And I agree in not
wanting the complexity of a conditional.

> > 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.

I'll think about it.  Maybe I add some preindent to the Linux man-pages.

> > > 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.

Hmmm.  I use "\-v" in the Linux man-pages, and it works, in the sense
that you can search for "-v" with ^F in the PDF viewer.

See
<https://kernel.org/pub/linux/docs/man-pages/book/man-pages-6.7.pdf#ldconfig.8>

It works for me in all the readers I tried, which are firefox(1),
atril(1), and okular(1).  In what systems does it not work for you?

> 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).

Hmmm, with a set of macros C CR RC CI and IC to use them it could be a
good idea.  Branden, how does it look to you?  I don't think CB and BC
would be necessary.

> 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.)

You can probably configure that in man.local, no?  I know at least you
can disable hyphenation, which solves most of the functional problems.

> > > 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).

Completely agree.  CC += groff.  Branden, do you think we can fix that
somehow?  Literally, the first thing I thought about the Linux man-pages
PDF when I saw it was "Lines are so long that it's hard for me to read
them.".  Well, it was the second; I first saw the front page, which was
beautiful; that thought was the first one when I say the first page
after the front.

> 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

Hmmmm.  Very interesting.

> > 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.

Yup.

Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es/>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <https://mm.icann.org/pipermail/tz/attachments/20240408/04254b72/signature.asc>