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

[Steffen Nurpmeso]

Hello,

today i'm presenting "the first release" of mdocmx(7).
Shall no comments arise i'll open a bug ticket with exactly the
same content in the near future.
It will also be included in my fork of GPLv2 groff, S-roff.  (But
that will take quite some time.)

To reiterate what this thread [1,2] was about: i terribly missed
any kind of interactivity in mdoc(7) (*any* Unix manual that is)
and suggested extending mdoc(7) with some commands to make
references, indexing etc. at all possible, i.e., by being able to
specify anchors that can be referenced.

  [1] http://lists.gnu.org/archive/html/groff/2014-09/msg00145.html
  [2] http://lists.gnu.org/archive/html/groff/2014-12/msg00045.html

Ingo Schwarze responded with a much better solution, using
a single multiplexer command, so i jumped on that train and
developed an almost release-candidate prototype until christmas
2014.  Since then it matured even more.  (The most notable changes
are that the macros have been outsourced into their own file and
that all parts of the pipeline now require $MDOCMX_ENABLE to be
set and nonempty in order to understand mdocmx(7), instead of the
other way 'round.)

As a goody i've added PDF (via pdfmark) and HTML support today:
just like i said real support requires mdoc(7) to be rewritten [2].
Real is "appealing to me" in that respect.
But nothing prevented us to support the very same kind of output
that we use on the TTY also for PDF.  (And HTML, but i don't
mention that because what the HTML driver generates is.. a pity.)

So, what can mdocmx(7) do to improve manuals?
The answer can be found in mdocmx.7 that is attached.
A large manual that makes use of it is that of the MUA i maintain,
to be included in the next release that will happen in a few
minutes from now, v14.8 ("Albatros").

The following components are attached:

  . groff-1_22_3-mdocmx.diff:
    Adds support to grotty(1) and mdoc(7).

  . groff-rel-to-head.diff:
    For users of [master], patch this into
    groff-1_22_3-mdocmx.diff.

  . less-v471-mdocmx.diff:
    Adds support to less(1) v471 [3], the latest development
    version.  Iirc it applies to the last official release [4]
    with a very simple conflict that even non-programmers should
    be able to resolve.
    Inside less(1) the new command ^A (hold control-key and press
    a) will prompt for a destination anchor.

    [3] http://www.greenwoodsoftware.com/less/less-471.tar.gz
    [4] http://www.greenwoodsoftware.com/less/less-458.tar.gz

  . mdocmx.sh:
    mdocmx(1), the preprocessor, written in sh(1) and awk(1).
    This is necessary because troff(1) doesn't support multipass.
    (In fact mdocmx(7)-enabled manuals can be preprocessed and the
    result can be shipped, so that it is _not_ necessary, then.)

  . mdocmx.tmac:
    mdocmx(7), the actual macro package.

  . mdocmx.7, mdocmx.1:
    Manual pages for mdocmx(7) and mdocmx(1).

I personally use the following shell functions:

  mdoc() {
          ( export MDOCMX_ENABLE=1 
            mdocmx.sh "${1}" |
            groff -Tutf8 -mdoc -dmx-toc-force=tree |
            LESS= less --RAW-CONTROL-CHARS --ignore-case --no-init ) 
  } 
  mdocdbg() {
          ( export MDOCMX_ENABLE=1 
            mdocmx.sh -vv "${1}" |
            groff -Tutf8 -mdoc -dmx-toc-force=tree -dmx-debug=1 |
            LESS= less --RAW-CONTROL-CHARS --ignore-case --no-init ) 
  } 

--steffen

groff-1_22_3-mdocmx.diff
Description: Text Data

groff-rel-to-head.diff
Description: Text Data

less-v471-mdocmx.diff
Description: Text Data

mdocmx.sh
Description: Bourne shell script

mdocmx.tmac
Description: Text Data

mdocmx.7
Description: Text Data

mdocmx.1
Description: Text Data