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

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 3903 bytes --]

[looping in linux-man@, as we discuss about improvements in the Linux
 man pages' PDF book]

Hi Paul,

On Sun, Mar 17, 2024 at 09:59:41PM -0700, Paul Eggert wrote:
> On 2024-03-17 15:20, Alejandro Colomar wrote:
> 
> > In case you want to have a quick look at how it looks, here's an example
> > from the Linux man-pages:
> > 
> > <https://www.alejandro-colomar.es/share/dist/man-pages/git/HEAD/man-pages-HEAD.pdf#pdf%3Abm12325>
> 
> Yes, unfortunately that looks subpar to me. There's too much space between
> the bullets and the text they're bulleting. For example, in the last page of
> man-pages(7) the bullets should be indented with respect to the parent text,
> and there should be less space between the bullets and the text. Much better
> is what tzfile(5) does now (see attached); this is particularly important
> when something is nested under the bullet level, as it is in tzfile(5). The
> current tzfile(5) bulleting approach is closer to how Joe Ossanna used
> bullets in section 7.2 of the Nroff/Troff User's Manual (1976)[1], which is
> what I learned troff from. (Ossanna doesn't subindent so his larger indents
> are not that much of a problem in the manual, but tzfile(5) needs to
> subindent.)

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.
Maybe you being used to programs with 2 spaces and me with 1 tab means
we have our brains hard-wired for different indentation width
preferences.  But 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.

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

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

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.

When I first saw the PDF book, I had a feeling that lines were too long,
and that a larger/better font might be necessary.

> Indents are too large in general. The PDF
> man pages should be formatted for smaller pages, or with tons more margin,
> or two-column, or something. Of course I realize we can't fix all this, as
> there's long tradition of hasty and/or bad formatting dating back to 7th
> Edition Unix man pages. Still, if someone wants to make little improvements
> we should let them.

Sure.  I do accept improvements for that.  If you have more specific
suggestions, or even patches, they're welcome!

> > Surprising as it may be, Debian's man2html(1) could
> > handle (probably by ignoring them; I didn't really check) previous uses
> > of \w, but started crashing with \w in IP.  Did you receive a copy of
> > the Debian bug report?
> 
> I followed up separately to that. In short, that man2html appears to be
> unmaintained upstream and should be retired, but I sent in a patch anyway.

Thanks.

Have a lovely day!
Alex

> [1]: https://www.tuhs.org/Archive/Documentation/Manuals/Unix_4.0/Volume_1/C.1.2_NROFF_TROFF_Users_Manual.pdf



-- 
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.

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