Hi Russ, At 2024-03-16T12:32:44-0700, Russ Allbery wrote: > Okay, I think we've sorted out the way forward for groff that would > address the immediate issue. That leaves three questions: should I do > something in the next release of Pod::Man, should I assume that the > next release of groff will default to ragged right, and is there a way > for Pod::Man output to support the intent of the AD register.
In summary, I think the answers are, in order:
1. Probably, yes.
2. No. I have no plans to change it.
3. Not at present. I'd like to create one for groff 1.24.
> I think the logic that would correctly honor the intent of AD and also
> maintain backward compatibility would be something like this:
>
> 1. If groff before 1.23.0 or not-groff, add ".if n .ad l" after .TH.
Yes.
> 2. If groff 1.23.0, add ".if n .ds AD l" before .TH. Also having
> ".if n .ad l" after .TH would be harmless but insufficient.
Yes.
> 3. If groff after 1.23.0... it's not clear what I should do,
> particularly since Pod::Man releases get baked into Perl core and
> thus have a long effective lifetime. Ideally from my perspective
> groff would default to ragged right and then I should do nothing in
> that case, since then I would be honoring AD correctly.
I'm still gnawing on this. There are multiple constraints on the
problem's solution.
* It should work in or out of AT&T compatibility mode.
* It should work when encountering multiple `TH` requests in input.
* It should work when -mandoc causes "an.tmac" to be reloaded.
The first is easy (remember to use AT&T register interpolation syntax
and groff's `do` request). The others are harder.
> (I don't know off-hand how to express that logic in roff, so if it
> does seem warranted to go with version checks, I'll probably be asking
> for assistance in writing them portably, assuming that this is even
> something that groff exposes. Or maybe there's a better proxy for the
> version check, like seeing if the AD register is defined.)
Frustratingly, there is no portable *roff mechanism of seeing if a
register (or string, like `AD`) is defined! Generally, as soon as you
mention a register or string name, it springs into existence at once.
> There seem to be two groff development and release questions embedded
> in here:
>
> 1. Do you think you'll change the long-standing groff default from
> full justification to ragged right under nroff in the an macro set
> for the next release?
No. I'm glad to be better informed of early-onset divergent practices
among man(7) implementations in this respect, but I feel no urge to
restore alignment with AT&T and BSD Unix here.
Here are a few reasons.
A. GNU roff and Sun troff are, historically, heavyweights in terms of
users served. Apparently, man page users on these systems have been
accepting of adjustment ("full justification") for decades. While I
don't regard Sun practice as sacrosanct,[1] it is informative.
B. James Clark seems to have used emulation of a SunOS 4 troff as a
basis for his original work on GNU troff, right down to his
incorporation of the `SB` macro in groff's man(7) language,
unremarked as an extension when it was in fact a Sun innovation.[6]
C. GNU roff also seems to have a principle that formatting for the
terminal shall be done as similarly to that for typesetters as
possible, within the admittedly severe constraints of the former.
The adjustment of man pages is one example; another is that the GNU
ms(7) package uses the same default page footer arrangement for
terminals and typesetters, whereas Bell Labs ms(7) did not. An
example in the formatter itself is our handling of the `ss` request
for configuring the amount of inter-sentence space.[2] Personally,
I think this is a good principle from a design and maintenance
perspective.
D. For as long as factor (A) has been relevant, authors of man pages
have been writing them for a world where you didn't necessarily know
what adjustment mode would be in use at rendering time for any given
user. There may have been a stretch for about a decade (say,
1998-2008) where GNU roff enjoyed nearly uncontested supremacy as a
man page renderer at the terminal, except in dwindling non-Solaris
System V Unix deployments.[3] But that time passed. mandoc(1) uses
ragged-right formatting with no configurability otherwise, and
Heirloom Doctools uses the old AT&T default, probably because that's
what it's descended from, and it enjoys a user base that doesn't
require a troff whose properties include "active development".[4][5]
It's _good_ for man page authors to minimize their assumptions in
this respect.
> 2. Do you have an expected time frame for the next release, which
> controls whether it's worth bothering with the second piece of
> logic above.
I sent out a proposed release schedule a month ago, to no comment.
https://lists.gnu.org/archive/html/groff/2024-02/msg00054.html
I need to talk to Bertrand and see if he's willing to wear the official
GNU maintainer hat for another release, or if we should start the
handover procedure with GNU officials now.
Getting the next groff release into the next Debian stable release _is_
an objective of mine.
> I'd prefer to avoid releasing man pages that change justification
> partway through in the next stable release of Debian, but if a new
> release is coming before the next Debian stable release, it may not
> be worth embedding a fix for one specific groff version in every
> generated man page.
I'd prefer that too. As noted above, I'd like to get groff 1.24 out in
2024. Based on past experience I think that probably means I only have
3-4 months left to land big changes.
> For what it's worth, in over 20 years of maintaining Pod::Man with
> this design choice, I've never gotten a complaint about it, and
> multiple people noticed when it broke. Admittedly, the breakage is
> worse than always doing full justification, since it changes in the
> middle of the man page and thus looks more wrong,
Yes; that's exactly the sort of problem I was encountering in some Linux
man-pages documents. It does jump out at you.
> but my anecdotal experience is that people quite like this "feature"
> of Pod::Man and the advocates for full justification in nroff seem to
> be few and far between.
Part of that could be due to it being the status quo for GNU, and for
SunOS/Solaris users, going way back. People comfortable with the
current order tend not to spend effort celebrating or philosophically
justifying it.
We have a term for those who do: "movement conservatives".
Regards,
Branden
[1] (Warning: lengthy historical excursus)
https://lists.gnu.org/archive/html/groff/2023-08/msg00005.html
[2] groff_diff(7):
AT&T troff ignores the ss request if the output is a terminal
device; GNU troff rounds down the values of minimum inter‐word and
additional inter‐sentence space each to the nearest multiple of 12.
[3] And these, too, may have followed Sun's lead. I don't have concrete
evidence either way, and would appreciate it falling into my hands.
[4] https://github.com/n-t-roff/heirloom-doctools/commits/master/
[5] There are other free roffs, but they don't seem to weigh in here.
Plan 9 troff appears, to me, to have no ambition to render any
documents except those within the Plan 9 corpus (man pages and
technical white papers). Documenter's Workbench 3.3, the ancestor
of Heirloom Doctools troff, is no one's daily driver as far as I
know. (From experience, I can say that its terminal experience is
underwhelming.) neatroff doesn't supply its own man(7) package, but
can use those of other implementations, so it makes no independent
decision on this question.
[6] I've marked `SB` as deprecated in the forthcoming groff 1.24; it
does nothing that modern formatters can't achieve by combining `SM`
and `B`. I suspect Sun created it because the `it` *roff request
behaved inconsistently with other requests that took a line count as
an argument, like `ce` and `ul`, ignoring the `\c` escape sequence
as the latter two did not. (Skeptics may feel free to play with the
attachment, and to guess where I've tried it out.) That in turn is
why GNU troff has an `itc` request. Or such is my reconstruction of
past developers' decisions based purely on parsimony and measurable
program behavior, assuming rational decision making.
One of the things I'd like a DeLorean for is to go back to Murray
Hill in 1973 or so and yell, "Joe! Save the future! Make `it`
respect `\c`!"
The fiery balrog Ken Thompson would then implode me with his gaze...
signature.asc
Description: PGP signature
