URL: <https://savannah.gnu.org/bugs/?68165>
Summary: [mdoc] indentation behavior differs between groff's
-mdoc and mandoc(1)
Group: GNU roff
Submitter: None
Submitted: Sun 22 Mar 2026 05:02:32 AM UTC
Category: Macro package mdoc
Severity: 3 - Normal
Item Group: Incorrect behaviour
Status: None
Privacy: Public
Assigned to: None
Open/Closed: Open
Discussion Lock: Unlocked
Planned Release: None
_______________________________________________________
Follow-up Comments:
-------------------------------------------------------
Date: Sun 22 Mar 2026 05:02:32 AM UTC By: Anonymous
From Ingo in http://lists.gnu.org/r/groff/2025-10/msg00098.html :
> doc-get-arg-type (without the asterisk) seems to be called only
> by the internals of a one other macro, `doc-do-Bl-args`.
Not quite, i briefly looked at the code and my impression is it is used for
.Bd -offset .T
.Bl -offset .T
.Bl -width .T
-Bl -column ..T
As far as i read the code (confirmed by quick testing), the first three of the
above cases get interpreted as
a 1u display indentation
a 1u list indentation
a 2n+1u list item indentation
The (IMHO correct) results produced by mandoc are:
a 2n display indentation
a 2n list indentation
a 2n+2n list item indentation
The fourth of the above cases is very weird.
in .Bl -column, a macro argument that is not an option keyword (like -offset
or -width) appears to get interpreted as follows:
Usually, the string length of the argument gets used as the column width in
units of n. But there is one weird exception. If the argument starts with a
dot and doc-get-arg-type classifies the rest of the argument as a macro name,
then the width of that rest (when set in a diversion) gets used as the column
width instead.
Mandoc does not implement that special case.
So with mandoc, ".Er" results in a column width of 3n because the string
length of ".Er" is 3, whereas groff appears to interpret it as a width of 2u
(not 2n!) because the length of the string "Er" is 2. I'm not sure i got this
entirely right, but since the apparent behaviour near the end of
doc-do-Bl-args makes no sense to me, i suspect some other behaviour was
intended, and no one ever noticed the bug because few - if any - real world
manual pages actually specify .Bl -column column withs by providing macro
arguments starting with dots. For example, the intended behaviour might be
for "-column .macro" to use the so-called default width of the macro as the
column with, but that clearly doesn't work in groff_mdoc(7) and isn't
implemented in mandoc either.
In general, i think the whole concept of "default widths" isn't a particularly
useful feature. Admittedly, it does see quite a bit of real-world use in the
form of ".Bl -tag -width Er" in ".Sh ERRORS" sections, but i fear very few
people understand how that really works and it mostly gets carried forward by
the faithful like a cargo cult would (except that this incantation actually
works :-).
Whatever may be going on with -column, i do believe that doc-do-Bl-args
contains the same bug [bug #67646] that doc-do-Bl-args* did, given how it
results in the presumably wrong behaviour described for -offset and -width
above.
_______________________________________________________
Reply to this item at:
<https://savannah.gnu.org/bugs/?68165>
_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
signature.asc
Description: PGP signature
