|
From: | Steffen Nurpmeso |
Subject: | [Groff] mdocmx(7), III.: reference extension for the mdoc(7) semantic markup language |
Date: | Thu, 30 Apr 2015 16:36:38 +0200 |
User-agent: | s-nail v14.7.11-414-g41649a5 |
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
[Prev in Thread] | Current Thread | [Next in Thread] |