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@xxxxxxxxxx> 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@xxxxxxxxxxx> Suggested-by: "G. Branden Robinson" <branden@xxxxxxxxxx> Cc: "Thomas E. Dickey" dickey@xxxxxxx Signed-off-by: Alejandro Colomar <alx@xxxxxxxxxx> 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/>
Attachment:
signature.asc
Description: PGP signature
