[bug #66174] [mdoc] `Bl` macro's `-width` option poorly documented

[G. Branden Robinson]

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