Update of bug #66174 (group groff):
Item Group: Warning/Suspicious behaviour => Documentation
Status: None => In Progress
Assigned to: None => gbranden
Summary: [mdoc] wrong interpretation of '.Bl ... -width "long
string"' => [mdoc] `Bl` macro's `-width` option poorly documented
_______________________________________________________
Follow-up Comment #2:
_mdoc_(7)'s `Bl` macro is poorly documented.
It says that the `-width` "option" takes an argument of type "<string>".
That is not correct. _mdoc_(7) is a DWIM system; it attempts to parse that
argument as a numeric expression, and if that fails, _then_ falls back to
interpreting it as a string whose formatted width is to be measured with the
`\w` escape sequence.
"1234567890123" *is* a valid numeric expression. It is a large integer.
Integer overflow no longer renders a numeric expression erroneous in GNU
_troff_, so the `\B` test passes even though the magnitude is too large (it
clamps at the maximum representable integer).
https://git.savannah.gnu.org/cgit/groff.git/tree/tmac/doc.tmac?h=1.23.0#n3511
I'll update _groff_mdoc_(7) and maybe add an attempt at a helpful warning to
the package.
I further note that none of this is _groff_-istic; formatting the page with
4.4BSD-Lite2's _mdoc_ is a horror show, too.
Moreover, _groff_mdoc_(7) itself and the _mandoc_ project led by Ingo Schwarze
also exhibit these semantics.
Observe:
$ grep -- '-width [0-9]' *.[0-9]
apropos.1:.Bl -tag -width 3n -offset 3n -compact
man.7:.Bl -tag -width 3n
man.cgi.3:.Bl -tag -width 1n
man.cgi.3:.Bl -tag -width 1n
man.cgi.3:.Bl -tag -width 1n
man.cgi.3:.Bl -tag -width 1n
man.options.1:.Bl -tag -width 3n
mandoc.1:.Bl -dash -offset 2n -width 2n -compact
mandoc.db.5:.Bl -dash -compact -offset 2n -width 1n
mandoc.db.5:.Bl -dash -compact -offset 2n -width 1n
mandoc.db.5:.Bl -dash -compact -offset 2n -width 1n
mandoc.db.5:.Bl -dash -compact -offset 2n -width 1n
mandoc.db.5:.Bl -dash -compact -offset 2n -width 1n
mandoc.db.5:.Bl -dash -compact -offset 2n -width 1n
mandoc.db.5:.Bl -dash -compact -offset 2n -width 1n
mandoc.db.5:.Bl -dash -compact -offset 2n -width 1n
mandoc.db.5:.Bl -dash -compact -offset 2n -width 1n
mandoc_dbg_init.3:.Bl -tag -width 1n
mandoc_escape.3:.Bl -dash -compact -width 2n
mandoc_escape.3:.Bl -tag -width 2n
mandoc_escape.3:.Bl -dash -compact -width 2n
mandoc_escape.3:.Bl -tag -width 2n
mandoc_escape.3:.Bl -bullet -width 2n
mandoc_escape.3:.Bl -tag -width 2n
mandoc_html.3:.Bl -tag -width 1n -offset indent
mdoc.7:.Bl -tag -width 3n
mdoc.7:.Bl -tag -width 13n -offset indent
mdoc.7:.Bl -tag -width 13n -offset indent
mdoc.7:.Bl -tag -width 12n -offset indent
mdoc.7:.Bl -tag -width 1n
roff.7:.Bl -tag -width ".Bl -tag -width 2i" -offset indent -compact
roff.7:.It Li \&.Bl -tag -width 2i
roff.7:.Bl -tag -width 2n -compact
tbl.7:.Bl -tag -width 2n
tbl.7:.Bl -tag -width 2n
It may need to be explained to non-_roff_ experts that putting an integer in
quotation marks doesn't type-convert it to a string.
The following patch fixes the page. Please consider passing it along to the
Ruby package maintainers (or Ruby's upstream team).
$ diff -u ATTIC/erb2.7.1.old ATTIC/erb2.7.1
--- ATTIC/erb2.7.1.old 2024-10-14 15:36:59.690753390 -0500
+++ ATTIC/erb2.7.1 2024-10-14 15:17:40.968047074 -0500
@@ -31,7 +31,7 @@
.Nm Ruby .
.Pp
.Sh OPTIONS
-.Bl -tag -width "1234567890123" -compact
+.Bl -tag -width "\&1234567890123" -compact
.Pp
.It Fl -version
Prints the version of
Alternatively, since that string appears nowhere in the page text, the page
authors appear to be taking the long way around to get this outcome:
$ diff -u ATTIC/erb2.7.1.old ATTIC/erb2.7.1
--- ATTIC/erb2.7.1.old 2024-10-14 15:36:59.690753390 -0500
+++ ATTIC/erb2.7.1 2024-10-14 15:41:23.369518041 -0500
@@ -31,7 +31,7 @@
.Nm Ruby .
.Pp
.Sh OPTIONS
-.Bl -tag -width "1234567890123" -compact
+.Bl -tag -width 13n -compact
.Pp
.It Fl -version
Prints the version of
_______________________________________________________
Reply to this item at:
<https://savannah.gnu.org/bugs/?66174>
_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
signature.asc
Description: PGP signature
