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