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

[G. Branden Robinson]

Update of bug #66174 (group groff):

              Item Group:           Documentation => Incorrect behaviour    
                  Status:             In Progress => Invalid                
             Open/Closed:                    Open => Closed                 

    _______________________________________________________

Follow-up Comment #4:

Oh, I'm wrong!  Or, rather, _groff_mdoc_(7) is less poorly documented than I
thought.

The information is there.  It's just buried under bad pedagogy.

But it *is* there.


     -width ⟨string⟩   If ⟨string⟩ starts with a ‘.’ (dot)
immediately
                       followed by a valid mdoc macro name, interpret
                       ⟨string⟩ and use the width of the result.  Almost
                       all lists in this document use this option.

                       Example:

                             .Bl -tag -width ".Fl test Ao Ar string Ac"
                             .It Fl test Ao Ar string Ac
                             This is a longer sentence to show how the
                             .Fl width
                             flag works in combination with a tag list.
                             .El

                       gives:

                       -test ⟨string⟩  This is a longer sentence to show
                                       how the -width flag works in
                                       combination with a tag list.

                       (Note that the current state of mdoc is saved
                       before ⟨string⟩ is interpreted; afterward, all
                       variables are restored again.  However, boxes
                       (used for enclosures) can’t be saved in GNU
                       troff(1); as a consequence, arguments must always
                       be balanced to avoid nasty errors.  For example,
                       do not write ‘.Ao Ar string’ but ‘.Ao Ar string
                       Xc’ instead if you really need only an opening
                       angle bracket.)

                       Otherwise, if ⟨string⟩ is a valid numeric
                       expression (with a scaling indicator other than
                       ‘u’), use that value for indentation.  The most
                       useful scaling indicators are ‘m’ and ‘n’,
                       specifying the so‐called Em and En square.  This
                       is approximately the width of the letters ‘m’ and
                       ‘n’ respectively of the current font (for nroff
                       output, both scaling indicators give the same
                       values).  If ⟨string⟩ isn’t a numeric
expression,
                       it is tested whether it is an mdoc macro name,
                       and the default width value associated with this
                       macro is used.  Finally, if all tests fail, the
                       width of ⟨string⟩ (typeset with a fixed‐width
                       font) is taken as the width.

                       If a width is not specified for the tag list
                       type, ‘6n’ is used.


If you can get through all that, then _groff_ is rendering the _erb3.1_(1) man
page exactly as documented.

So I was also wrong that the "string" argument to the "-width" option can be
interpreted as two different things.

It's actually three.

Whee!

<facepalm>

Yeah, it's *so unfair* that _mdoc_ didn't just eat all of _man_'s lunch and
leave it whimpering on the schoolroom floor.

Whatever.

Considering design decisions like this, the world dodged a bullet.

I'd like to do editorial violence to the _groff_mdoc_(7) page but that will
have to wait for _groff_ 1.25 at the earliest.

Closing as invalid.  I ask again that your report this problem to the Ruby
developers.

They could, ya know, switch to _man_(7)... 😈


    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?66174>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/

signature.asc
Description: PGP signature