Hi Guillem, At 2026-07-10T00:30:58+0200, Guillem Jover wrote: > On Thu, 2026-07-09 at 10:29:27 -0500, G. Branden Robinson wrote: > > At 2026-06-19T03:07:34+0200, Guillem Jover wrote: > > > I tried my system pod2man with PERL5LIB pointing to the Pod > > > modules from git, and that didn't fix anything, so it appears like > > > this is not fixed yet (and might have never been reported > > > upstream?), but maybe I botched my testing process. I didn't see > > > anything obvious related to .IP in «git log» (besides the > > > justification fixes). > > > If by "upstream" you meant pod2man, it's worth exploring whether > > that tool is generating `TP` macros for things like definition > > lists, or `IP`. `TP` is a better choice and it is going to become > > increasingly important given changes expected in groff 1.25 and > > planned for the future. > > Ah, sorry, indeed by "upstream" I was referring here to podlators. > > Checking briefly now, I see multiple instances of «.IP». For example > for dpkg.pod, the source is: > > ,--- > =head2 Package selection states > > =over > > =item B<install> > > The package is selected for installation. > > =item B<hold> > > A package marked to be on B<hold> is kept on the same version, that > is, no automatic new installs, upgrades or removals will be performed > on them, unless these actions are requested explicitly, or are > permitted to be done automatically with the B<--force-hold> option. > > =item B<deinstall> > > […] > `--- > > And the generated troff is: > > ,--- > .SS "Package selection states" > .IX Subsection "Package selection states" > .IP \fBinstall\fR 4 > .IX Item "install" > The package is selected for installation. > .IP \fBhold\fR 4 > .IX Item "hold" > A package marked to be on \fBhold\fR is kept on the same version, that is, > no automatic new installs, upgrades or removals will be performed on them, > unless these actions are requested explicitly, or are permitted to be done > automatically with the \fB\-\-force\-hold\fR option. > .IP \fBdeinstall\fR 4 > .IX Item "deinstall" > […] > `--- > > With the rendered output from man being: > > ,--- > Package selection states > install > The package is selected for installation. > > holdA package marked to be on hold is kept on the same version, that is, > no automatic new installs, upgrades or removals will be performed on > them, unless these actions are requested explicitly, or are permitted > to be done automatically with the --force-hold option. > > deinstall > `--- > > Branden I guess you are in a getter position to file a bug to > podlators upstream, having more details and knowledge on the matter, > but if you are short on time, I could try to concoct some report > (where I'll need to read about the fine details about this I guess, > which I've kind of skipped up to now O:).
Right. I'll await guidance from Russ for the time being, but I have
some really good news.
perlpod already applies semantic analysis (DWIM) to the argument of its
`=item` command/directive/declarator.
"=over indentlevel"
"=item stuff..."
"=back"
Item, over, and back require a little more explanation:
"=over" starts a region specifically for the generation of a
list using "=item" commands, or for indenting (groups of)
normal paragraphs. At the end of your list, use "=back" to end
it. ... In the stuff in "=item stuff...", you may use
formatting codes, as seen here:
=item Using C<$|> to Control Buffering
Such commands are explained in the "Formatting Codes" section,
below.
Note also that there are some basic rules to using "=over" ...
"=back" regions:
...
• And perhaps most importantly, keep the items consistent:
either use "=item *" for all of them, to produce bullets;
or use "=item 1.", "=item 2.", etc., to produce numbered
lists; or use "=item foo", "=item bar", etc.--namely,
things that look nothing like bullets or numbers. (If you
have a list that contains both: 1) things that don’t look
like bullets nor numbers, plus 2) things that do, you
should preface the bullet- or number‐like items with "Z<>".
See Z<> below for an example.)
So despite the fact that I'm a bad person and didn't dig deeply into
perlpod before making the change to groff man(7)'s `IP` behavior,
this is a striking case of convergent evolution--I suspect because
typography has strong, stable, and longevous conventions.
perlpod _already_ parses the argument to `=item` for a "type": ordered/
enumerated, unordered/marked, or definitional. This trichotomy maps
perfectly to HTML, of course, and to the forthcoming groff 1.25's new
"advisory" `LS`/`LE` macros. The original man(7) language of 1979 did
not employ the same trichotomy, but, blissfully, organized a dichotomy
such that ordered/enumerated and unordered/marked lists were not
distinguished--I suspect because there was no point, as the macro
package did not maintain registers to manage list enumerators. McIlroy
might have thought it unnecessary for man(7) (and indeed you don't often
see it), even though such a feature was present in ms(7) at least as
early as Sixth Edition Unix (1975).
Schematically:
IP
+-- ordered/enumerated list item (HTML: <OL><LI>)
+-- unordered/marked list item (HTML: <UL><LI>)
TP
+-- definition list item (HTML: <DL><LI>)
Further, it was straightforward, before the advent of "man2html" tools
that reconceptualized man(7) as a declarative or markup language rather
than a layer of macros atop a Turing-complete language, to "punch
through the floor" and use raw *roff requests to set up registers to
automatically increment the marks of an enumerated list oneself.
Thus, if my analysis is correct, the groff 1.24 change to man(7)'s `IP`
macro indentation does not require _much_ of a change to perlpod
interpreters--indeed, if we take the foregoing as a specification, an
implementation might already be producing man(7) documents in the manner
I recommend. Because `TP` is strictly more flexible than `IP`, I can
imagine a perlpod interpreter that never generates `IP` calls at all.
On the bright side, I know of no man(7) generator that is so militant,
so, with a _little_ adaptation on their part, we can more strongly
semantically distinguish the purposes of `IP` and `TP`, and potentially
reap rich rewards in improving the searchability and navigability of
man(7) documents.
One of the possibilities we've discussed on the groff list is supporting
a rendering-time option so as to generate a ctags(1)-compatible tags
file when rendering man pages. A man(1) program could then pass that
tags file's name to less(1)'s `-T` option.
https://lists.gnu.org/archive/html/groff/2025-01/msg00108.html
Anyway, my suggested prescription for perlpod interpreters is simple:
If perlpod decides the `item` is bulleted or numbered, generate an `IP`
call; otherwise generate a `TP` call.
As seen above, pod2man (or some module it uses) already explicitly
declares a paragraph indentation.
> .IP \fBinstall\fR 4
> .IP \fBhold\fR 4
> .IP \fBdeinstall\fR 4
For enumerated and marked lists, 4 ens should be plenty. I've never
seen a man page that had more than 99 items in an enumerated list (which
is 3n wide including a trailing dot), or used a mark wider than 2n (an
em dash on a terminal).
I'm hopeful that Russ can correct any misconceptions I've stated above.
Regards,
Branden
signature.asc
Description: PGP signature
