URL:
<https://savannah.gnu.org/bugs/?63042>
Summary: Enhancement: mdocmx(7) extension to mdoc(7)
Project: GNU troff
Submitter: sdaoden
Submitted: Fri 09 Sep 2022 10:14:30 PM UTC
Category: Macro mdoc
Severity: 3 - Normal
Item Group: None
Status: None
Privacy: Public
Assigned to: None
Open/Closed: Open
Discussion Lock: Any
Planned Release: None
_______________________________________________________
Follow-up Comments:
-------------------------------------------------------
Date: Fri 09 Sep 2022 10:14:30 PM UTC By: Steffen Nurpmeso <sdaoden>
Hello.
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
https://github.com/gwsw/less/pull/251
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.
Ciao!
P.S.: hihihi, now that i explicitly added an account, Savannah allows
notification Cc: specification!
_______________________________________________________
File Attachments:
-------------------------------------------------------
Date: Fri 09 Sep 2022 10:14:30 PM UTC Name: groff-1_22_3-mdocmx.mbox Size:
89KiB By: sdaoden
<http://savannah.gnu.org/bugs/download.php?file_id=53672>
_______________________________________________________
Reply to this item at:
<https://savannah.gnu.org/bugs/?63042>
_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
