[Groff] mdocmx(7), II.: reference extension for the mdoc(7) semantic markup language

[Steffen Nurpmeso]

Hello Ingo and the list,

here is the second round of mdocmx(7), the reference extension for
the mdoc(7) semantic markup language that you all awaiting so
eagerly.  ;)

This is almost near a "release candidate", but in particular
i think the "protocol" of .Mx itself is mature now.
Again, after patching grotty(1) and the mdoc(7) macros a command
line like

  $ ./mdocmx.sh -T ss mdocmx.7 | groff -Tutf8 -mdoc | less

will bring you a new manual usage experience, assumed you are
using normal utilities on the command line for this.
This time i am also able to attach two instrumented large manuals,
nail.1.xz is the manual of the MUA i maintain, and
tmac-mdoc.7.in.xz is the mdoc(7) manual itself.  It is really
worth trying the above command line with those examples and have
a look.

Again i'll attach some files as .mbox: these are generated by
git(1) format-patch but can also be applied via patch(1), just
like a normal patch can.

  - mdocmx.7: almost done.
    The manual, attached as such.
    At the very moment i fail to see what could be missing from
    making mdocmx(7) and .Mx more useful.
    Note that '-dmdocmx-debug=1' is not yet documented.

  - mdocmx.sh, mdocmx.1: ? (in practice, done?)
    Dramatically improved.  Supports "quot ""ation"" rules", no
    longer leaks temporary files because of broken pipes (but
    adding a trap would improve things even more), for example.
    Command line has changed, see the manual for more.
    Both files attached as such.

  - mdocmx-mdoc.mbox: almost release-candidate.
    Patch against the mdoc(7) macros of GNU troff, v1.22.3.
    It misses dynamic table-of-content creation.  (But the
    mdocmx(7) preprocessor protocol is now _capable_).

    Note it is almost as good as it can get beside that -- good
    enough for all manuals tried sofar (without generating _any_
    error!?!), which is almost too good to be true!

    For more, including the envisaged support for other output
    devices, most notably HTML and PDF, mdoc(7) itself has to be
    adjusted.  It should be doable: it already pre-parses all
    macro arguments and then walks the generated array.  That very
    mechanism had to be used for output, too, i.e., a new
    'put-output-node TYPE [DATA]' had to be used instead of
    directly writing data, so that we could walk something in its
    entirety after the recursion returns to the top level, then
    injecting something wherever we need it.  Currently we know
    what we work on only after recursion is done and output has
    already been produced, so that it is not possible to
    encapsulate something in a HTML or PDF anchor.  (Of course,
    the very same syntax that is used for TTY output could also be
    used, but that is really shitty.)

  - grotty(1): done (except missing documentation).
    (Maybe missing an environment variable to suppress
    interpretation of \X sequences via a simple global switch).
    Attached as mdocmx-grotty.mbox (patch(1)able) against 1.22.3.

    Doesn't yet document the protocol that we generate.

  - less(1): done.
    Changes: using ^A not ^X^R, and supporting "''" command to go
    back to the last mark (with the empty input after ^A being an
    alias for that), don't leak on systems without strstr(3),
    added documentation.

    Attached as mdocmx-less-speedy.mbox against less(1) v471 [1].
    The patch applies with a single failure also to the current
    stable less(1) release, v458 [2].

      [1] http://www.greenwoodsoftware.com/less/less-471.tar.gz
      [2] http://www.greenwoodsoftware.com/less/less-458.tar.gz

--steffen

mdocmx.7
Description: Text document

mdocmx.sh
Description: Bourne shell script

mdocmx.1
Description: Text document

mdocmx-mdoc.mbox
Description: application/mbox

mdocmx-grotty.mbox
Description: application/mbox

mdocmx-less-speedy.mbox
Description: application/mbox

nail.1.xz
Description: application/xz

tmac-mdoc.7.in.xz
Description: application/xz