[bug #63042] Enhancement: mdocmx(7) extension to mdoc(7)

[Steffen Nurpmeso]

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/