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

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

[Alejandro Colomar]

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

[looping in linux-man@, as we discuss about improvements in the Linux
 man pages' PDF book]

Hi Paul,

On Sun, Mar 17, 2024 at 09:59:41PM -0700, Paul Eggert wrote:
> On 2024-03-17 15:20, Alejandro Colomar wrote:
> 
> > In case you want to have a quick look at how it looks, here's an example
> > from the Linux man-pages:
> > 
> > <https://www.alejandro-colomar.es/share/dist/man-pages/git/HEAD/man-pages-HEAD.pdf#pdf%3Abm12325>
> 
> Yes, unfortunately that looks subpar to me. There's too much space between
> the bullets and the text they're bulleting. For example, in the last page of
> man-pages(7) the bullets should be indented with respect to the parent text,
> and there should be less space between the bullets and the text. Much better
> is what tzfile(5) does now (see attached); this is particularly important
> when something is nested under the bullet level, as it is in tzfile(5). The
> current tzfile(5) bulleting approach is closer to how Joe Ossanna used
> bullets in section 7.2 of the Nroff/Troff User's Manual (1976)[1], which is
> what I learned troff from. (Ossanna doesn't subindent so his larger indents
> are not that much of a problem in the manual, but tzfile(5) needs to
> subindent.)

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.
Maybe you being used to programs with 2 spaces and me with 1 tab means
we have our brains hard-wired for different indentation width
preferences.  But 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.

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

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

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.

When I first saw the PDF book, I had a feeling that lines were too long,
and that a larger/better font might be necessary.

> Indents are too large in general. The PDF
> man pages should be formatted for smaller pages, or with tons more margin,
> or two-column, or something. Of course I realize we can't fix all this, as
> there's long tradition of hasty and/or bad formatting dating back to 7th
> Edition Unix man pages. Still, if someone wants to make little improvements
> we should let them.

Sure.  I do accept improvements for that.  If you have more specific
suggestions, or even patches, they're welcome!

> > Surprising as it may be, Debian's man2html(1) could
> > handle (probably by ignoring them; I didn't really check) previous uses
> > of \w, but started crashing with \w in IP.  Did you receive a copy of
> > the Debian bug report?
> 
> I followed up separately to that. In short, that man2html appears to be
> unmaintained upstream and should be retired, but I sent in a patch anyway.

Thanks.

Have a lovely day!
Alex

> [1]: https://www.tuhs.org/Archive/Documentation/Manuals/Unix_4.0/Volume_1/C.1.2_NROFF_TROFF_Users_Manual.pdf



-- 
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.

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

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

[Paul Eggert]

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

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.


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


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

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


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


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

[-- Attachment #2: zdump.8.pdf --]
[-- Type: application/pdf, Size: 35028 bytes --]

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

[Alejandro Colomar]

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

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 #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[G. Branden Robinson]

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

[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

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

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

[Alejandro Colomar]

[-- 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 --]

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

[Paul Eggert]

On 2024-04-08 01:31, Alejandro Colomar wrote:

> Hmmm.  I use "\-v" in the Linux man-pages, and it works

Ha! I just checked and it works for me too. It did not work in 2014. 
Apparently since 2014 PDF and HTML viewers have gotten smarter about 
searching, so that "-" matches any form of dash. So perhaps I should 
remove this \- complication from the TZDB man pages.


> You can probably configure that in man.local, no?  I know at least you
> can disable hyphenation, which solves most of the functional problems.

Fine, but that should be the default. Users shouldn't have to fiddle 
with man.local to tailor output format to be good for the usual case. 
man.local should be for the unusual cases.

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

[Paul Eggert]

On 2024-04-08 10:46, Paul Eggert via tz wrote:
> On 2024-04-08 01:31, Alejandro Colomar wrote:
> 
>> Hmmm.  I use "\-v" in the Linux man-pages, and it works
> 
> Ha! I just checked and it works for me too. It did not work in 2014. A

Unfortunately I spoke too quickly, as this does not work with Solaris 10 
troff. On that platform, this command:

   printf ' - \\- \\(mi\n' | troff | dpost

outputs a .ps file that, when converted to PDF, gives you U+002D 
(HYPHEN-MINUS), U+2013 (EN DASH), U+2212 (MINUS SIGN). So if TZDB wants 
to play nicely even on this obsolescent platform, it still needs to play 
its game with \*- instead. Oh well.