[bug #63046] [mdoc] handle rendering option strings and registers as man(7) does

[G. Branden Robinson]

URL:
  <https://savannah.gnu.org/bugs/?63046>

                 Summary: [mdoc] handle rendering option strings and registers
as man(7) does
                 Project: GNU troff
               Submitter: gbranden
               Submitted: Sun 11 Sep 2022 11:57:31 AM UTC
                Category: Macro mdoc
                Severity: 3 - Normal
              Item Group: Feature change
                  Status: In Progress
                 Privacy: Public
             Assigned to: gbranden
             Open/Closed: Open
         Discussion Lock: Any
         Planned Release: None


    _______________________________________________________

Follow-up Comments:


-------------------------------------------------------
Date: Sun 11 Sep 2022 11:57:31 AM UTC By: G. Branden Robinson <gbranden>
Over in bug #62926, Ingo had the following exchange.

[me:]
> I would also add that your use of "API" here is open to equivocation.
> 
> There are two materially relevant interfaces here.
> 
> 1. That between the man page author and the macro package.
> 2. That between the man page reader and the macro package.
> 
> Man page authors are explicitly discouraged from using `MF`, as they are
_all other_ strings and registers.

[quotation of groff_man(7) omitted; the key point is that it says "*man pages
should never use them* (emphasis added)]

> There is therefore no reason to catastrophize the addition of `MF` to a set
that already includes (strings) `AD` and `HF` and registers `cR`, `C`, `CS`,
`CT`, `D`, `FT`, `HY`, `IN`, `LL`, `LT`, `P`, `S`, `SN`, `U`, and `X`.
> 
> groff mdoc does not yet support all of these, but I would like it if it did.
 These are _all_ rendering options, and if an implementation wants to remove
these degrees of freedom, it can do so without impacting how man pages using
either package are _written_.

[comment #6 comment #6:]
> It seems CS, CT, D, HY, LL, LT, and S are GNU only, but cR already appeared
in 4.4BSD.
> So indeed, the horse is barely in sight of the barn any longer, let alone
inside of it.  No, i wasn't aware of that.
> 
> In this situation, while MF does add even more noise to the manual page
(noise which authors don't need and users will not usually even look at), it
does not seem to make the situation that much worse than it already is, it
merely continues one more step down the declining slope, as long as you don't
break .Nm.

Well, I got stuck in the tar pit that was groff_mdoc(7) and have starting
revising it, heavily.

I have found that I cannot stand the overuse of Courier and bold, but that
these mostly stem from use of two macros: `Nm` and `Pa`.  So I plan to add
`NF` and `PF` strings to manage how they render their arguments.  _man_(7) has
no astrings) `AD` and `HF` and registers `cR`, `C`, `CS`, `CT`, `D`, `FT`,
`HY`, `IN`, `LL`, `LT`, `P`, `S`, `SN`, `U`, and `X`.nalogues for these.

> P.S.
> My concept of API is quite simple: it's the syntax and semantics described
in the manual page - because that's what users of the language need to
review.

I must apparently take greater pains to clarify.  I distinguish two
communities of users: those who render man pages and those who write them.

Those who write man pages need not know anything about, and should not meddle
with, strings `AD`, `HF`, and `MF`, nor registers `cR`, `C`, `CS`, `CT`, `D`,
`FT`, `HY`, `IN`, `LL`, `LT`, `P`, `S`, `SN`, `U`, and `X`.

Those who _read_ (or at least _render_) man pages on the other hand, could
find them useful.  I do, at any rate.

My understanding is that you, as _mandoc_ maintainer, look darkly upon user
control of rendering.  Until recently, I guess (I've lost track of the mail
where you said this changed), even the line length was not subject to user
control.

That is manifestly not the _groff_ approach.  Maybe it's a GNU thing: knobs
for everything!

Anyway, this ticket is to track an ongoing project to align _groff_ _man_ and
_mdoc_ in this respect.







    _______________________________________________________

Reply to this item at:

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

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