bugGNU roff - Bugs: bug #63046, [mdoc] handle rendering option...

 
 

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

Submitter:  G. Branden Robinson <gbranden>
Submitted:  Sun 11 Sep 2022 11:57:31 AM UTC
   
 
Category:  Macro mdoc Severity:  3 - Normal
Item Group:  Feature change Status:  Fixed
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Closed Planned Release:  1.23.0
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Tue 19 Mar 2024 09:10:39 AM UTC, comment #9: 

comment #8:

> I'm punting MF and U to a subsequent release since there are
> thorny issues with PDF hotspots


Commit d06340293 took care of U.  I opened bug #65484 for MF.

Dave <barx>
Group Member
Tue 27 Dec 2022 09:27:29 AM UTC, comment #8: 

I'm punting MF and U to a subsequent release since there are thorny issues with PDF hotspots to work out for generalized hyperlink support.

Reconceptualizing this as bringing mdoc(7) into parity with man(7) as of groff 1.22.4, this is complete.


commit 78922cf9f39f6ebcd3a80aaab9c3a2931b8b0ad4
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Tue Dec 27 02:46:19 2022 -0600

    [mdoc]: Support `HF` string.

    * tmac/doc.tmac (initialization): Add logic supporting `HF` string just
      as our man(7) implementation does.  If the font name ends with `B` (as
      the default does), set `doc-remap-I-style-in-headings` register and
      extract font family, which can be empty (as is the default).
    * tmac/mdoc/doc-common (Sh, Ss): If `doc-remap-I-style-in-headings`
      register set, perform (and unwind) font remapping of italic to
      bold-italic face.
    * tmac/mdoc/doc-ditroff:
    * tmac/mdoc/doc-nroff: Define `doc-Sh-font` in terms of `HF`.

    * tmac/tests/doc_heading-font-remapping-works.sh: Test it.
    * tmac/tmac.am (tmac_TESTS): Run test.

    * tmac/groff_mdoc.7.man (Options): Document it.
    * NEWS: Update item.

    Fixes last part of <https://savannah.gnu.org/bugs/?63046>.


G. Branden Robinson <gbranden>
Group administrator
Mon 19 Dec 2022 01:44:14 AM UTC, comment #7: 

We're now down to HF, MF, and U.


commit d0ae281616da88d55134d877fdc3735df5cde8dc
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Sun Dec 18 13:41:44 2022 -0600

    [mdoc]: Support `FT` register.

    * tmac/doc.tmac (initialization): Add logic supporting `FT` register
      just as our man(7) implementation does.
    * tmac/mdoc/doc-common (doc-set-up-titles): Plant footer trap in
      validated user-requested location.
    * tmac/groff_mdoc.7.man (Options): Document it.
    * NEWS: Update item.

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


G. Branden Robinson <gbranden>
Group administrator
Thu 15 Dec 2022 02:16:33 AM UTC, comment #6: 


commit 88e89ebe9ce3931b49fb3cbd7fa20eacb03bf69f
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Wed Dec 14 19:28:07 2022 -0600

    [doc]: Support `X` register.

    * tmac/doc.tmac (initialization): Add logic supporting `X` register just
      as our man(7) implementation does.

    * tmac/groff_mdoc.7.man (Options): Document it.

    * NEWS: Update item.

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


G. Branden Robinson <gbranden>
Group administrator
Tue 13 Dec 2022 12:32:19 AM UTC, comment #5: 


commit 17477b26f5881117dd3f2c4df8db9420b2f3e9ae
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Sun Dec 11 15:31:31 2022 -0600

    [mdoc]: Support `P` register.

    * tmac/doc.tmac (initialization): Add logic supporting `P` register just
      as our man(7) implementation does.

    * tmac/groff_mdoc.7.man (Formatting with groff, troff, and nroff):
      Document it.

    * NEWS: Update item.

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


G. Branden Robinson <gbranden>
Group administrator
Wed 02 Nov 2022 11:27:05 AM UTC, comment #4: 


commit bb10a668e10e43f9ccb1727f9f82a1df1530e3b6
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Sat Oct 29 12:28:45 2022 -0500

    [mdoc]: Support `SN` register.

    * tmac/doc.tmac: Recognize `SN` register if set on command line and use
      groff man(7)-compatible default if it is not.
    * tmac/mdoc/doc-common (Ss): Use this register instead of a literal.
    * tmac/groff_mdoc.7.man (Formatting with groff, troff, and nroff):
      Document it.
    * NEWS: Update item.

    Fixes part of <https://savannah.gnu.org/bugs/?62926>.

commit 2134257877b8da28b6d225d99a1c6d81592d9043
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Sat Oct 29 12:09:26 2022 -0500

    [mdoc]: Support `IN` register.

    * tmac/doc.tmac: Recognize `IN` register if set on command line and use
      groff man(7)-compatible defaults if it is not.

    * tmac/mdoc/doc-common (Sh): Use this register instead of
      `doc-paragraph-indentation`.

    * tmac/mdoc/doc-ditroff:
    * tmac/mdoc/doc-nroff: Stop setting pargraph indentation defaults here.

    * tmac/groff_mdoc.7.man (Formatting with groff, troff, and nroff):
      Document it.

    * NEWS: Update item.

    * tmac/tests/doc_Mt-works.sh:
    * tmac/tests/doc_indents-correctly.sh: Update test expectations.

    Fixes part of <https://savannah.gnu.org/bugs/?62926>.


G. Branden Robinson <gbranden>
Group administrator
Wed 02 Nov 2022 11:25:52 AM UTC, comment #3: 

There is significant overlap between this bug and bug #62926.  They are distinguishable, but many of the command-line options supported by man(7) affect rendering.

Strictly, I reckon this ticket should get updated for any such options implemented in mdoc(7); those which affect the formatted appearance of man pages should also be logged in bug #62926, and those which aren't parameterized in options but affect rendering (like the typefaces used by the `Nm` and `Pa` macros, for instance), should be logged only in bug #62926.

It looks like only a handful of man(7) options remain to get mdoc(7) parity: HF, FT, P, X, and MF.

G. Branden Robinson <gbranden>
Group administrator
Sun 11 Sep 2022 12:26:28 PM UTC, comment #2: 


commit 952c2f75c25b70a6ebe4d457339b4fdcefd00f3a
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Fri Sep 9 05:12:17 2022 -0500

    [mdoc]: Support AD string; sets default adj mode.

    * tmac/mdoc/doc-common (Sh): Set adjustment mode to user-specified
      default, not troff's default (and not only in troff mode).

    * tmac/mdoc/doc-ditroff:
    * tmac/mdoc/doc-nroff: Process `AD` string setting from command line as
      man(7) does.

    * tmac/groff_mdoc.7.man (Formatting with groff, troff, and nroff):
      Document it.

    * NEWS: Add and update items.

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


G. Branden Robinson <gbranden>
Group administrator
Sun 11 Sep 2022 12:26:10 PM UTC, comment #1: 


commit 30115f3ba72801badda08cdbc0210cb0014ddc1e
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Wed Sep 7 21:53:34 2022 -0500

    [mdoc]: Support `C` register as man(7) does.

    * tmac/mdoc/doc-common (Dd): Reset page number to 1 upon new document
      only if not consecutively numbering.

    * tmac/mdoc/doc-ditroff:
    * tmac/mdoc/doc-nroff: Process `C` register setting from command line as
      man(7) does.

    * tmac/groff_mdoc.7.man (Formatting with groff, troff, and nroff):
      Document it.

    * NEWS: Expand existing item.

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


G. Branden Robinson <gbranden>
Group administrator
Sun 11 Sep 2022 11:57:31 AM UTC, original submission:  

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:

> 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.

G. Branden Robinson <gbranden>
Group administrator

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by barx (Posted a comment)
  • -email is unavailable- added by gbranden (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follow 3 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2022-12-27 gbranden StatusIn Progress Fixed
        Open/ClosedOpen Closed
    2022-11-02 gbranden Planned ReleaseNone 1.23.0

    Back to the top

    Powered by Savane 3.13-d3ae.
    Corresponding source code