URL: <https://savannah.gnu.org/bugs/?67363>
Summary: [man] give perlpod/podlators a way to set a page's
adjustment mode without overriding user preferences
Group: GNU roff
Submitter: gbranden
Submitted: Sun 27 Jul 2025 07:23:00 PM GMT
Category: Macro package man
Severity: 1 - Wish
Item Group: Feature change
Status: In Progress
Privacy: Public
Assigned to: gbranden
Open/Closed: Open
Discussion Lock: Any
Planned Release: None
_______________________________________________________
Follow-up Comments:
-------------------------------------------------------
Date: Sun 27 Jul 2025 07:23:00 PM GMT By: G. Branden Robinson <gbranden>
[https://lists.gnu.org/archive/html/groff/2024-03/msg00137.html Background
discussion from the _groff_ mailing list in March 2024]:
... The Perl 5.40 release is coming up,
and I'd like to get the next release of podlators into it, with the hope
that Debian will go to Perl 5.40 before the trixie release.
I think I have two options for the upcoming podlators 6.0.0 release:
* Do nothing. Justification will be broken with groff 1.23 and fixed with
groff 1.24, which will hopefully make it into the trixie release.
* Add ".if n .ds AD l" to the preamble, and leave ".if n .ad l" after .TH
as is. This will make the formatting work everywhere the way that it
historically has (although will get pod2man output no closer to
supporting AD properly) and means that the time frame for groff 1.24
becomes irrelevant to podlators, at the cost of an additional line in
every generated man page.
I think I'm leaning towards the second option because it's simpler and
provides the maximum decoupling of timelines, and one additional line in
the preamble isn't too much of a price. But I could be talked out of it
if anyone thinks that's the wrong approach. Note that this will mean the
creation of a whole lot of man pages in the wild that override the AD
register, which will probably be with us for many years to come. (But
this is already true of all the man pages with ".if n .ad l", which is
arguably an even bigger hammer.)
I can then revisit and potentially add more complicated code should we
figure out a way for pod2man to change the nroff default justification but
still honor AD if set.
I think Russ went with option (2), which is good because sure enough _groff_
1.24.0 is not available for inclusion in Debian trixie (scheduled for 9 August
2025).
I think I have finally worked out a mechanism for the user's adjustment
preference and that of podlators to coexist, with the former dominating _if
made explicit_, and with no further _man_(7) API changes. It's also very
little extra work to expose an analogous mechanism for hyphenation
disablement.
And all this without requiring any further changes/adaptation on the part of
podlators.
Requoting the meaty bits of Russ's solution...
Add ".if n .ds AD l" to the preamble, and leave ".if n .ad l" after .TH as
is.
I think podlators will want to retain both of these lines--the former, to tell
_groff_ 1.24 _man_ that the "document's preferred adjustment mode" is "l", and
the latter to configure adjustment for all other _man_ interpreters.
My plan is for (1) _groff_'s _man_ (and _mdoc_) packages to check at package
initialization time for defined `AD` string (and defined `HY` register). **If
these exist**, they necessarily represent the user's preferences (since they
weren't read from a document) and are each copied to a shared private name
(prefixed with "andoc*" to communicate this shared status; (2) upon
encountering any new _man_ document at a `TH` macro call, or new _mdoc_
document at a `Dd` macro call, these saved user preferences are reasserted to
configure the document's rendering, and existing `AD` and `HY` objects
removed; (3) page-local assignments of `AD` and `HY` continue to be honored as
before, and (4) at every new section, subsection, and paragraph, adjustment
and hyphenation modes are reset to the page's preference if configured and the
user's otherwise.
The consequences are:
(A) _podlators_ gets what it wants;
(B) users can override the preferences of _podlators_ (and other _man_ pages I
term "meddlesome" in this respect) with their own;
(C) documents targeting _groff_ have a more reliable mechanism of configuring
adjustment and hyphenation; as I've documented at length elsewhere, neither
the idioms `.na/.../.ad` nor `.nh/.../.hy` work as most _man_ authors
expect;[1] and
(D) a document can still meddle with adjustment and hyphenation using
low-level requests as they always have, on the occasions where this is truly
necessary (that is, when a _man_(7) expert has no better suggestion, but
(E) we obviate the insoluble problem of **portably** restoring the adjustment
and hyphenation modes when a document no longer requires their alteration.[2]
I'm uncertain how prominently I want to document the last fact. My own
preference regarding man page authorship practices is that documents refrain
from trying to manipulate these formatting parameters.
I hope to push these changes to Git today.
[1] Excerpt from comments in "tmac/an.tmac" in preparation:
.\" Resetting the adjustment mode is a complicated dance.
.\" 1. Man pages sometimes disable adjustment--when they do, they
.\" often forget to put it back the way it was.
.\" 2. When they do remember do put it back, they often fail to do
.\" so correctly because of the `ad` request's quirky semantics
.\" starting from Seventh Edition Unix troff/nroff. Briefly, the
.\" `ad` request without arguments turns adjustment back on after
.\" an `na` even if the previous adjustment mode was `l` (align to
.\" the left with NO adjustment).
.\" 3. The default adjustment mode historically has not been
.\" predictable; it can depend on nroff vs. troff mode and on the
.\" vendor of the *roff system in use.
.\" 4. It's possible (and portable) to obtain the previous adjustment
.\" mode via the `.j` register so that it can be saved prior to
.\" meddling and restored later, but in practice man page authors
.\" neglect to do so.
.\" 5. groff man(7)'s `AD` string isn't supported everywhere.
.\" 6. We want user preferences, if expressed, to override the page
.\" author's.
.\" 7. Even if we didn't want (6), one page author's can override
.\" another's when formatting multiple man(7) documents in
.\" sequence--we thus keep track of the initial adjustment mode.
.\"
.\" So we recover the "page's" preferred adjustment mode, if expressed
.\" via `AD`, at every paragraph (and (sub)sectioning) macro call; and
.\" recover the user's preferred adjustment mode at each new document by
.\" accepting it as an argument (see the `TH` macro definition). Also
.\" see the initialization logic below.
...
.\" Resetting the hyphenation mode is a complicated dance.
.\" 1. Man pages sometimes disable automatic hyphenation--when they
.\" do, they nearly always forget to put it back the way it was.
.\" 2. In AT&T troff there was no register exposing the hyphenation
.\" mode (nor the enablement status of automatic hyphenation), so
.\" no idioms for performing such restoration have arisen.
.\" 3. groff man(7)'s `HY` register isn't supported everywhere.
.\" 4. We want user preferences, if expressed, to override the page
.\" author's.
.\" 5. Even if we didn't want (4), one page author's can override
.\" another's when formatting multiple man(7) documents in
.\" sequence--we thus keep track of the initial hyphenation mode.
.\"
.\" So we recover the "page's" preferred hyphenation mode, if expressed
.\" via `HY`, at every paragraph (and (sub)sectioning macro call; and
.\" recover the user's preferred hyphenation mode at each new document
.\" by accepting it as an argument (see the `TH` macro definition).
.\" Also see the initialization logic below.
[2] This is why having the _man_(7) package configure the adjustment and
hyphenation modes as it (or the user) wants and then _deleting the requests_
(as I think _man-db_ used to do when given certain options) is too aggressive
a solution. Sometimes you really do want these features, for instance to
disable adjustment inside text blocks in _tbl_(1) tables.
_______________________________________________________
Reply to this item at:
<https://savannah.gnu.org/bugs/?67363>
_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
signature.asc
Description: PGP signature
