[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:
signature.asc
Description: PGP signature
