Hi Branden! On Mon, Apr 08, 2024 at 10:59:25AM -0500, G. Branden Robinson wrote:
[Caveat lector: this is not a short email and I hyperlink to multiple longer ones]
Hi Paul & Alex,
At 2024-04-07T23:33:38-0700, Paul Eggert wrote:
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). There's no single answer here of course (opinions do differ), but the man page lines are pretty clearly too long in the PDFs.
One straightforward means of addressing this problem is simply to typeset the manual at a larger type size. Say, 11 or 12 points. groff's supported that for a couple of decades. For these sizes, Werner Lemberg even chose vertical spacing counterparts inspired by TeX.
groff_man(7): -rStype‐size Use type‐size for the document’s body text; acceptable values are 10, 11, or 12 points. See subsection “Font style macros” above for the default.
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
I've got this queued up to read during a doctor's appointment today. (More like a waiting room appointment.)
I have a personal shell function that exercises the new groff man `PO` register to use the default line length but center the man page in the terminal window, and have been enjoying it for months.
An inevitable problem we will face in trying to set man pages on narrower lines is the heavy use of tables and other means of filling disablement by page authors. No sooner did they get a feel for the additional 13n additional elbow room that groff gave them (over historical *roffs' 65n), than they started overrunning that limit too.
Documenters of C wanted function synopses to look just so, and turned off filling to get it. Other page authors wanted to depict what the terminal would look like, and ran roughshod over considerations of circumstances under which a man page might actually be typeset.
I wouldn't be at all averse to reimposing a 65n line length limit as a _style_ recommendation. And I think I know where to poke the formatter to get it to emit a warning diagnostic if the line length is overrun when filling is disabled. (This would be kin to TeX's notoriously discouraging "overfull hbox" warnings, but if I can't write a diagnostic message more intelligible than that, I'll put in for retirement.)
Since manual pages often have a few levels of indentation, lines need to be rather wide on the terminal (and using those levels of indentation, the actual length of the text isn't too much). I wouldn't narrow the line length in nroff(1) mode. I find troff(1) mode the one that's hardly readable by default.
At 2024-04-08T10:31:32+0200, Alejandro Colomar wrote:
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.
I don't like that idea at all. I don't want to add _any_ more font macros to man(7).
Okay.
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.
Pass `-rS11` (or -rS12) to the formatter when building and see if you like the result.
Hmm, that's much more pleasing! commit 5ba7ca38f758370c9cbfcb901aa0f0f1efb31f52 (HEAD -> contrib) Author: Alejandro Colomar <alx@kernel.org> Date: Mon Apr 8 19:15:35 2024 +0200 share/mk/: $TROFFFLAGS: Use a larger font size Link: <https://journals.uc.edu/index.php/vl/article/view/5765> Reported-by: Paul Eggert <eggert@cs.ucla.edu> Suggested-by: "G. Branden Robinson" <branden@debian.org> Cc: "Thomas E. Dickey" dickey@his.com Signed-off-by: Alejandro Colomar <alx@kernel.org> diff --git a/share/mk/configure/build-depends/groff-base/troff.mk b/share/mk/configure/build-depends/groff-base/troff.mk index 051172ce7..b9b7518cf 100644 --- a/share/mk/configure/build-depends/groff-base/troff.mk +++ b/share/mk/configure/build-depends/groff-base/troff.mk @@ -6,7 +6,9 @@ ifndef MAKEFILE_CONFIGURE_BUILD_DEPENDS_GROFF_BASE_TROFF_INCLUDED MAKEFILE_CONFIGURE_BUILD_DEPENDS_GROFF_BASE_TROFF_INCLUDED := 1 -DEFAULT_TROFFFLAGS := -wbreak +DEFAULT_TROFFFLAGS := \ + -wbreak \ + -rS12 EXTRA_TROFFFLAGS := TROFFFLAGS := $(DEFAULT_TROFFFLAGS) $(EXTRA_TROFFFLAGS) TROFF := troff
Regards, Branden
Have a lovely day! Alex -- <https://www.alejandro-colomar.es/>