[bug #45034] mdoc(7): add support for the mdocmx(7) reference extension

[anonymous]

URL:
  <http://savannah.gnu.org/bugs/?45034>

                 Summary: mdoc(7): add support for the mdocmx(7) reference
extension
                 Project: GNU troff
            Submitted by: None
            Submitted on: Wed 06 May 2015 11:53:12 AM UTC
                Severity: 3 - Normal
              Item Group: None
                  Status: None
                 Privacy: Public
             Assigned to: None
             Open/Closed: Open
         Discussion Lock: Any
         Planned Release: None

    _______________________________________________________

Details:

The mdoc(7) manual semantic markup language doesn't support any kind of
anchoring: whereas you can exactly state what "x" is whenever you refer to it
-- variable, function etc. --, you have no option to define the exact place
where "x" is itself defined, or wether it is at all defined in a given manual
page.

Also, whereas mdoc(7) does support differentiation in between anchors and
references for headlines (.Sh/.Ss and .Sx, respectively), referencing a
headline is only of notational interest, the reference is in no way "active",
never.

mdocmx(7) extends mdoc(7) by adding all the missing functionality and (much)
more with a single new multiplexer command: .Mx.
The attached manual page mdocmx.7 documents in detail; the manual is itself
mdocmx(7)-enabled.

And because non-multipass troff(1) implementations are not capable to generate
forward references to anchors not yet defined there is a preprocessor
necessary to circumvent this problem: mdocmx(1), implemented in portable sh(1)
and awk(1).
(A nice property of mdocmx(7) is that it "knows" wether a document has been
preprocessed or not, therefore making it possible to distribute preprocessed
manuals and still being backward- and forward-compatible.)

For security reasons all parts of the usual manual pipeline require the
environment variable MDOCMX_ENABLE=1 to be set to a non-empty value (it must
be non-empty because of troff(1) deficiencies):

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

(The output devices -Tpdf and -Thtml may also be used, though i reiterate that
the same output as for TTY is necessarily created due to mdoc(7) deficiencies:
it is impossible to generate "<START>text</END>" but only "text[START-END]". 
A solution to gain the former is possible, but requires mdoc(7) itself to be
changed.)

mdocmx(7) as it is posted here is the result of a seven month evolution
following an idea on the GNU roff mailing-list [1,2,3].

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

Changes compared to [3]:
- a fix in mdoc(7) patch (re-add lost .nop's; was installed like that for
months, but not committed).
- the mandoc(1) originator asked for freely definable anchors and references
to them, which he needs for his texi2mdoc(1) etc. converters, so .Mx got new
-ix and -sx modes.

P.S.: since this form only allows four attachments i had to create a ball:
- groff-1_22_3.diff: add mdocmx(7) support to grotty(1) and mdoc(7).
- less-471.diff: add mdocmx(7) (in fact: "anchor") support to less(1) v471.
- mdocmx.tar.xz: a ball with mdocmx.tmac (the macros), mdocmx.7 (the .Mx
manual), mdocmx.sh (the preprocessor) and mdocmx.1 (preprocessor manual).
- mdocmx.7: the manual once again, but this time ball-less ;)



    _______________________________________________________

File Attachments:


-------------------------------------------------------
Date: Wed 06 May 2015 11:53:12 AM UTC  Name: groff-1_22_3.diff  Size: 26kB  
By: None

<http://savannah.gnu.org/bugs/download.php?file_id=33935>
-------------------------------------------------------
Date: Wed 06 May 2015 11:53:12 AM UTC  Name: mdocmx.tar.xz  Size: 18kB   By:
None

<http://savannah.gnu.org/bugs/download.php?file_id=33936>
-------------------------------------------------------
Date: Wed 06 May 2015 11:53:12 AM UTC  Name: less-471.diff  Size: 10kB   By:
None

<http://savannah.gnu.org/bugs/download.php?file_id=33937>
-------------------------------------------------------
Date: Wed 06 May 2015 11:53:12 AM UTC  Name: mdocmx.7  Size: 14kB   By: None

<http://savannah.gnu.org/bugs/download.php?file_id=33938>

    _______________________________________________________

Reply to this item at:

  <http://savannah.gnu.org/bugs/?45034>

_______________________________________________
  Message sent via/by Savannah
  http://savannah.gnu.org/