Re: [PATCH 10/19] man/{curs_variables.3x,infocmp.1m}: Drop adjustment requests.

[G. Branden Robinson]

[looping in groff list because...typography!]

At 2024-09-21T13:39:44-0400, Thomas Dickey wrote:
> On Sat, Sep 21, 2024 at 11:46:08AM -0500, G. Branden Robinson wrote:
> > Drop `na` and `ad` requests, recalling rationale from January
> > revision of the capability tables in terminfo(5).
> 
> I added those because the result looks poor with manpages.  Here's
> what it looks like from last week's changes:
> 
> SEE ALSO
>        [UAX #29] “Unicode Standard Annex #29: Unicode Text Segmentation”
>        ⟨https://unicode.org/reports/tr29/⟩
> 
>        curses(3X),   curs_color(3X),    curs_opaque(3X),    curs_terminfo(3X),
>        curs_threads(3X), term_variables(3X), terminfo(5)
> 
> and without that, the title is stretched:
> 
> SEE ALSO
>        [UAX  #29]  “Unicode  Standard  Annex  #29:  Unicode Text Segmentation”
>        ⟨https://unicode.org/reports/tr29/⟩

That should improve with the added (in another patch in the series) use
of the new `:` string to use, where available, the groff extension for
hyphenless break points, `\:`.

> Actually this would be still more readable:
> 
> SEE ALSO
>        [UAX #29] “Unicode Standard Annex #29: Unicode Text Segmentation”
>        ⟨https://unicode.org/reports/tr29/⟩

I think you may be suggesting not only adjustment disablement, but
measurement of the hyperlink (when it is formatted as output, which
doesn't always happen) to put a (line) break before it if it won't
completely fit on the same line as the preceding link text.

If so, I took a crack at that back in 2021, but it didn't work out.

https://git.savannah.gnu.org/cgit/groff.git/commit/?id=c7efb5fd40aae5293d9de87092b7a4b2be89df91
https://git.savannah.gnu.org/cgit/groff.git/commit/?id=b5461ca30b0f91a3efdead93aa7d5c2dca112d27

I wouldn't say it's not possible, but (1) it's not likely to appear in
groff before version 1.25, and (2) probably no non-groff formatter will
ever support it.  Maybe mandoc(1).

Worse, to get this done would require formatting the hyperlink into a
diversion so that it could be measured, and people might balk at
including a macro complicated enough to manipulate diversions in the
preambles of their man pages (for portability to non-groff, or old
groff, formatters).  (And portability to mandoc(1) is unlikely anyway;
it doesn't support diversions at all.[1])

>        curses(3X), curs_color(3X), curs_opaque(3X), curs_terminfo(3X),
>        curs_threads(3X), term_variables(3X), terminfo(5)

Long lists of cross references in "See also" sections are a pain point;
they seem to present a formatting problem that appears nowhere else in
man pages: people want filling, but not hyphenation or adjustment.[2]

> Perhaps a troff/nroff macro to disable adjustment in nroff would be
> helpful.

That's existed essentially forever, in the form of the `na` and `ad`
requests.  Unfortunately, `ad` sort of...accreted functionality early in
its history and as a result, as soon as one takes a single step off the
beaten track, it behaves as no novice (or even many experts) can
reliably predict.

A big problem is terminological.  Do "adjustment" and "alignment" mean
the same thing?  I think they don't, but *roff documentary history is
replete with vigorous interchange of these ideas.  And because the `na`
and `ad` requests manipulate their combination, the formatter language
has been no help in clarify people's thinking.

For more detail than most people can likely stomach, there is this.

https://lists.gnu.org/archive/html/groff/2024-06/msg00053.html

I have reforms in mind that might still be able to land for groff 1.24,
but I don't expect them to ever have an impact on man pages; they will
benefit the smaller population of groff users that use the program for
typesetting.[3]

I think the crux of the problem is that `ad` and `na` are
presentational, not semantic.  Sometimes, left-alignment without
adjustment is a matter of preference, and sometimes it isn't really, as
when we see stuff that spreads ugly like this:

>        curses(3X),   curs_color(3X),    curs_opaque(3X),    curs_terminfo(3X),
>        curs_threads(3X), term_variables(3X), terminfo(5)

I have not given priority to resolving this case for two reasons.

A.  A pair of macros to bracket a list of man page cross references
    seems like a pretty heavy addition to the man(7) macro language for
    a small application domain and little benefit.  I have a pair of
    list macros in mind for other purposes to propose, `LS`/`LE`, that
    would reduce the inter-paragraph distance to zero (so nobody needs
    to mess with `PD`) and _maybe_ turn off adjustment (configured with
    an argument to `LS`).  But they wouldn't help here because the man
    page cross references aren't itemized one per line.  If they were,
    they'd already be on the way to another solution.

    That point dovetails into the other reason...

B.  I've decided for groff's own man pages that a list of man page cross
    references so long that it spans multiple output lines and spreads
    like this is indicative of a problem with the text.  Why are we
    throwing the reader so many other things to read without any
    specific motivation?

    My rule of thumb has thus been, if the list of cross references
    exceeds one output line, I need to reformat it with explanations.

Here's an example.

See also
...
     groff(1)
            documents the -Z option and contains pointers to further
            groff documentation.

     groff(7)
            describes the groff language, including its escape sequences
            and system of units.

     groff_font(5)
            details the device scaling parameters of device DESC files.

     troff(1)
            generates the language documented here.

     roff(7)
            presents historical aspects and the general structure of
            roff systems.


At 2024-09-21T13:45:14-0400, Thomas Dickey wrote:
> The relevant part of the MKterminfo.sh change was this:
> 
>    * man/MKterminfo.sh: Revise sed substitution to add an `.ad l` request
>      at the beginning of every text block generated in the capability
>      tables.  Because the adjustment mode within a text block is discarded
>      by tbl(1), this works to left-align text blocks, permit them to break
>      (as desired by use of a text block in the first place), and doesn't
>      interfere with the alignment/adjustment of text outside the table.
> 
> However, the indicated ".ad l" doesn't appear (to me) to apply to
> suppressing adjustment in a paragraph (which isn't the same sort of
> block).

That change wasn't intended to affect anything outside of a table, if
that's what you're saying.  (I see that I could have been clearer about
when tbl(1) "discards" the adjustment mode.)

`.ad l` certainly does, or _should_ work.  If, for example, I stick such
a request into the middle of a paragraph in the curs_beep.3x page...

$ git diff
diff --git a/man/curs_beep.3x b/man/curs_beep.3x
index bc90da919..2c3990b87 100644
--- a/man/curs_beep.3x
+++ b/man/curs_beep.3x
@@ -50,6 +50,7 @@ .SH DESCRIPTION
 Commonly,
 a terminal implements a visual bell by momentarily reversing the
 character foreground and background colors on the entire display;
+.ad l
 even a monochrome device can do this.
 These functions each attempt the other alert type if the one requested
 is unavailable.

...I get the following.

     beep and flash alert the terminal user: the former by sound‐
     ing the terminal’s audible alarm, and the latter by  visibly
     attracting attention.  Commonly, a terminal implements a vi‐
     sual  bell by momentarily reversing the character foreground
     and background colors on the entire display; even a mono‐
     chrome device can do this.  These functions each attempt the
     other alert type if the one requested is unavailable.  If
     neither is available, curses performs no action.  Nearly all
     terminals have an audible alert mechanism such as a bell or
     piezoelectric buzzer, but only some can flash the screen.

We can see above that _adjustment_, as groff documentation defines it,
shuts off partway through the paragraph.

Does that example work with your formatter?

At 2024-09-21T14:09:33-0400, Thomas Dickey wrote:
> With the suggested patch, it's still stretched:
> 
> SEE ALSO
>        [UAX  #29]  “Unicode  Standard  Annex  #29:  Unicode Text Segmentation”
>        ⟨https://unicode.org/reports/tr29/⟩
> 
>        curses(3X),   curs_color(3X),    curs_opaque(3X),    curs_terminfo(3X),
>        curs_threads(3X), term_variables(3X), terminfo(5)

I guess I'm luckier in that I get less ugly results.

SEE ALSO
     [UAX #29] “Unicode Standard Annex #29: Unicode Text Segmentation” ⟨https://
     unicode.org/reports/tr29/⟩

     ncurses(3NCURSES), color(3NCURSES),  opaque(3NCURSES),  terminfo(3NCURSES),
     threads(3NCURSES), terminfo_variables(3NCURSES), terminfo(5)

Along with the effect of the `:` string newly defined in the page, it
looks like I happen to benefit from one or both of a couple of changes
expected in groff 1.24.0.

* The an (man) and doc (mdoc) macro packages now support a `BP` register
  to configure the ("base") paragraph inset amount; that is the amount
  used by man(7) for paragraphs not within an `RS`/`RE` relative inset,
  and in mdoc(7) for all paragraphs.  Formerly, the `IN` register
  configured this amount with other indentation and inset amount
  parameters used by man(7).  (In mdoc(7), it had no other purpose.)
  The base paragraph indentation default is now 5n, corresponding to
  that used by historical man(7) and mdoc(7) implementations going back
  to Unix Version 7 (1979) and 4.3BSD-Reno (1990), respectively.

* The an (man), doc (mdoc), and doc-old (mdoc-old) macro packages have
  changed the default line length when formatting on terminals from 78n
  to 80n.  The latter is a vastly more common device configuration, but
  that line length had been avoided for decades (perhaps as long as
  groff has existed), for an undocumented reason.  That reason appears
  to have been the interaction of bugs in GNU tbl(1) with an aspect of
  grotty(1)'s design.  Those bugs have been resolved.  A man(1) program
  can still instruct groff to format for any desired line length by
  setting the `LL` register on {g,n,t}roff's command line.

> (the last pararaph also is stretched in a postscript view - the first
> paragraph happens to fit on one line so that no stretching is
> noticeable).

Right.  Adjustment does not occur when an output line is explicitly, as
opposed to automatically, broken.  A major function of any paragraphing
macro in *roff is to invoke the `br` request to force a break.

Some people hate adjustment of text in man pages with a passion, and
others don't.  That is why I petition man page authors to not manipulate
it, as a rule.  There is no unambiguous historical precedent to follow;
in 1979, the man(7) package of Seventh Edition Unix enabled adjustment
for typesetters (`.if t`), but not terminals (`.if n`).

However, in the late 1980s, Sun Microsystems changed their man(7)
default to adjust text regardless of device, and when James Clark
implemented groff, he followed Sun's man(7) implementation very closely,
including their extensions to McIlroy's 1979 base.  Subsequently, groff
lacked rivals (outside of commercial Unices, which treated their troffs
with increasing neglect) for 15 years or so.

Hence my decision to add an `AD` string to groff 1.23.0's man(7).

groff_man(7):

Options
     The following groff options set registers (with -r) and strings
     (with -d) recognized and used by the man macro package.  To ensure
     rendering consistent with output device capabilities and reader
     preferences, man pages should never manipulate them.

     -dAD=adjustment‐mode
              Set line adjustment to adjustment‐mode, which is typically
              “b” for adjustment to both margins (the default), or “l”
              for left alignment (ragged right margin).  Any valid
              argument to groff’s “.ad” request may be used.  See
              groff(7) for less‐common choices.

Readers of the ncurses man pages are going to do so on terminals of
varying widths.  Sometimes adjustment will look terrible and sometimes
it won't.  There is no way I know of to encode enough hints in the man
page source to ensure an attractive result in all cases given the
diversity of rendering environments the pages will face.  And even if
there were, I would expect it to be fragile to textual revisions, and to
clutter the source.

But if I may venture a guess, you have a special concern with the
renderings to HTML that you maintain at invisible-island.net.

https://invisible-island.net/ncurses/man/

That's a more restricted domain.  If you could articulate the
constraints you want to impose for that rendering, I might be able to
offer useful advice.  Would you like to shut off adjustment generally,
or preserve it?  What output line length are you using--the default, or
one you have chosen?

One thing I've noticed is that these pages sometimes look bad on my
Android tablet (under Firefox) because for whatever reason, the bold
font is wider than the roman one, and so ugly breaks sometimes occur
because lines overrun the right margin where you didn't expect.  (I can
send you some screenshots if that would be helpful.)  I don't know a lot
about WOFF (or even CSS, for that matter), but I don't expect a web page
to have much control over the fonts used to render it.

What tool do you use to produce the HTML renderings of the ncurses man
pages?

Regards,
Branden

[1] https://lists.gnu.org/archive/html/groff/2023-08/msg00080.html

[2] Some people want neither hyphenation nor adjustment, ever, but I
    distinguish that preference because it's so categorical.  People who
    otherwise tolerate (or even prefer) both are understandably
    discomfited by the "SEE ALSO" example you present.

[3] https://savannah.gnu.org/bugs/?65954

signature.asc
Description: PGP signature