Re: [PATCH v2] tzfile.5: Fix indentation

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 5634 bytes --]

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/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]