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

[G. Branden Robinson]

[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:
> 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.

Depending on what you want, you can apply a scaling unit to the
measurement.  On terminals, 1 em equals 1 en, but on typesetters they're
different (1 en is one half em).

This doesn't work for Thomas Dickey's case, unfortunately, where he
wants _wider_ spacing on terminals than typesetters.

For example:

man/curs_addwstr.3x:.de bP
man/curs_addwstr.3x-.ie n  .IP \(bu 4
man/curs_addwstr.3x-.el    .IP \(bu 2
man/curs_addwstr.3x-..

> > > 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. So I have to use "\*-v" with the above code. And this means the
> "-" is in a different font than the "v".

Like Alex, I am curious why the PDF CMap isn't solving the
copy-and-paste part of this problem.

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

I'd say no.  For code _displays_, sure.  Inline?  That's less certain.
Used _judiciously_, the way Brian Kernighan does, it's fine.  mdoc
mavens like to pound the table, trumpeting the superiority of their
"semantic" macros.  The problem is that for many years, the coupling of
macros of code/literal semantic denotation to the Courier typeface led
to _horrible_ typography in groff, because things like the square
brackets in "synopsis language" weren't in Courier--logically enough,
because they're not "literal"--but this made it difficult to tell how
wide the spaces you were looking at were, or if space was even present
between a bracket and a semantically muscular adjacent code item.

I submit that mdoc advocates lost sight of basic readability.  I guess
it was more fun (and quite possibly more remunerative from an employer)
performing automated transformations on semantic tags than attending to
the basics of typesetting.  (I'm no great practitioner myself!  But I
assume I'm not alone in preferring to be able to tell whether a space is
present at a given location in the text, especially if it's showing me
how to type in a Unix command, which follow varying conventions.)

I recently drove a bulldozer through this nonsense in groff Git HEAD and
am steeling myself for a summons to the International Criminal Court on
charges of "semantic heresy" levied by people who don't even use groff
anyway, but mandoc(1).

(mandoc(1)'s solution to the typesetting problem is to format HTML and
then use a third-party tool to convert HTML to a PDF.)

https://lists.gnu.org/archive/html/groff/2024-03/msg00163.html

> 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). 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.

Not exactly.  With groff, you can remap these font names.  I recently
showed a groff mailing list subscriber who _hates_ monospaced fonts (and
especially Courier) how to customize the way it's rendered in his
system.

<https://lists.gnu.org/archive/html/groff/2024-03/msg00181.html>:
>>> ... I don't think many people hate monospaced fonts as much as you
>>> do.  I won't change the default but I will do my best to ensure that
>>> you can perform the font substitutions you desire.  In fact I think
>>> I have.
>>>
>>> Here's a recipe that works with groff 1.23.0 and Git HEAD.
>>> 
>>> $ git di tmac/
>>> diff --git a/tmac/man.local b/tmac/man.local
>>> index 8f75330bf..491bda1ee 100644
>>> --- a/tmac/man.local
>>> +++ b/tmac/man.local
>>> @@ -21,6 +21,12 @@
>>>  .\"   4: x-man-doc://1/groff   -- ManOpen (Mac OS X pre-2005)
>>>  .\" Set this register to configure which the `MR` macro uses.
>>>  .\" .nr an*MR-URL-format 1
>>> +.
>>> +.ftr CR AR
>>> +.ftr CB AB
>>> +.ftr CI AI
>>> +.ftr CBI ABI
>>> +.ds an*example-family A\"
>>>  .\"
>>>  .\" Local Variables:
>>>  .\" mode: nroff
>>> 
>>> (The `ftr` requests are necessary to snag "manual" font selections
>>> with `ft` requests or, more likely, `\f` escape sequences, and to
>>> handle tbl(1) tables using those font names.)
>>> 
>>> Apply the foregoing patch to wherever your man.local is installed.
>>> The "Files" section of groff_man(7) in groff 1.23.0 (or Git) should
>>> tell you where it is.

> Also, it should be ragged right, in both nroff and troff output.

This _also_ came up just in the past month or so on the groff list.

https://lists.gnu.org/archive/html/groff/2024-03/msg00079.html

Short version: historical practice in this area has been divergent with
respect to nroff output, and overwhelmingly against your preference with
respect to troff.  (That doesn't mean you're _wrong_.  But you might be
iconoclastic.)

> Right-adjusted text looks nicer but is less functional, and man pages
> should be all about function. (See the reference below.)

"All about" can be enlisted to do entirely too much work here, but I
agree with the principle.

> > > 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.)

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).

Incidentally, Eighth or Ninth Edition Unix man(7) did the foregoing,
with a "literal" font named "L" in the package.  (It mapped to Courier,
as I recall.)  Stepping up an abstraction level was good.  Growing
another dimension in the vector space of font macros was less good.  Not
being taken up anywhere else is neither good nor bad, but may be
suggestive.

However, that doesn't mean we must surrender to futility.  My idea for
attacking this is the user-definable "tag class".

https://lists.gnu.org/archive/html/groff/2023-10/msg00034.html

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

Regards,
Branden

signature.asc
Description: PGP signature