[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-HEA...>
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-HEA...> 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_N...
-- <https://www.alejandro-colomar.es/> Looking for a remote C programming job at the moment.