bugGNU roff - Bugs: bug #63042, want mdocmx(7) extension to mdoc(7)


bug #63042: want mdocmx(7) extension to mdoc(7)

Submitter:  Steffen Nurpmeso <sdaoden>
Submitted:  Fri 09 Sep 2022 10:14:30 PM UTC
Category:  General Severity:  1 - Wish
Item Group:  Feature change Status:  Duplicate
Privacy:  Public Assigned to:  None
Open/Closed:  Closed Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup

Thu 30 Mar 2023 10:59:29 PM UTC, comment #5: 

Dropping patch annotation from duplicate ticket.

As Dave noted in comment #4, this duplicates bug #45034.

G. Branden Robinson <gbranden>
Group administrator
Sat 10 Sep 2022 07:39:31 PM UTC, comment #4: 

This appears to be an updated version of bug #45034.

Dave <barx>
Group Member
Sat 10 Sep 2022 12:33:24 PM UTC, comment #3: 

..but feel free to simply take it and integrate as a regular groff thing!

It was just that the 2014/5 patch i think never was integrated in a build system, and this thing now just integrates into the groff build system.


Fri 09 Sep 2022 10:53:54 PM UTC, comment #2: 

I reckon this would be something new for the contrib directory; updating Category, Item Group, and Severity accordingly.

G. Branden Robinson <gbranden>
Group administrator
Fri 09 Sep 2022 10:15:33 PM UTC, comment #1: 

630 42.  Why not.

Steffen Nurpmeso <sdaoden>
Fri 09 Sep 2022 10:14:30 PM UTC, original submission:  


Another try to establish the mdocmx(7) reference+ extension at groff(1)'s mdoc(7), after the failed attempt in 2015, which, granted, was based on a pretty crude grotty(1) extension.

But in 1.23 with the OSC 8 extension to grotty(1) groff delivers out of the box, and less(1) also at least ignores OSC 8 for a while.  With the now fully-featured less(1) enhancement request


the combination of groff(1)/mdoc(7)/mdocmx(7)/grotty(1) plus less(1) delivers a fully referenced manual experience, with optional table of contents and more.

The attached file contains a git(1) mail-patch MBOX to be used with git(1) am.

The first changeset hooks mdocmx(7) into mdoc(7).  The largest change needs to happen in doc-print-recursive, which will henceforth know who its caller was.
These changes do not change functionality of plain mdoc(7).
A mdoc(7) file must make explicit use of the extension in order to load the actual mdocmx contribution.

The second adds contrib/mdocmx.

In general mdocmx requires a new sh(1)/awk(1) based preprocessor in order to provide its functionality, as troff(1) is single-pass, and therefore forward references cannot be created.
However, the mdocmx preprocessor will put a cookie so that the actual mdocmx macros know what to do (to be upward compatible with a two-pass troff(1) that may spring into existence in a future time).  Therefore preprocessed manuals can be distributed.
(I release them like that for the programs i maintain since i think 2015, and they become interactive in the second where there is a capable roff.)

mdocmx(7) has one problem left, described in the BUGS section of the contained mdocmx.7 manual.  Only a rewrite of mdoc(7) as such can fix this.  (A survey in 2015 has shown that some BSD manuals indeed do use referenceable and formatting macros in header lines, these would have to adapted to be compatible with mdocmx.  But since you must write for mdocmx anyway, this is a hypothetical issue.)

Conclusion: with the MBOX applied to 1.23, and with a less(1) including the pull request, one should be able to go up up and away like

  groff -Tutf8 -mdoc mdocmx.7 | less -R

Note the manuals mdocmx.7 and mdocmx.1 are installed in a preprocessed way for groff, so "man 7 mdocmx" should also rock.
And "MDOCMX_FLAGS=64 man 7 mdocmx" should also produce a table of contents.


P.S.: hihihi, now that i explicitly added an account, Savannah allows notification Cc: specification!

Steffen Nurpmeso <sdaoden>


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

Attach Files:

Attached Files
file #53672:  groff-1_22_3-mdocmx.mbox added by sdaoden (89KiB - application/octet-stream)


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 (Posted a comment)
  • -email is unavailable- added by sdaoden (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 8 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2023-03-30 gbranden StatusNone Duplicate
        Open/ClosedOpen Closed
        Summary[PATCH] Enhancement: mdocmx(7) extension to mdoc(7) want mdocmx(7) extension to mdoc(7)
    2022-09-10 barx SummaryEnhancement: mdocmx(7) extension to mdoc(7) [PATCH] Enhancement: mdocmx(7) extension to mdoc(7)
    2022-09-09 gbranden CategoryMacro package mdoc General
        Severity3 - Normal 1 - Wish
        Item GroupNone Feature change
    2022-09-09 sdaoden Attached File- Added groff-1_22_3-mdocmx.mbox, #53672

    Back to the top

    Powered by Savane 3.13-4b48.
    Corresponding source code