[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[bug #45034] mdoc(7): add support for the mdocmx(7) reference extension
From: |
anonymous |
Subject: |
[bug #45034] mdoc(7): add support for the mdocmx(7) reference extension |
Date: |
Wed, 06 May 2015 11:53:14 +0000 |
User-agent: |
Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:37.0) Gecko/20100101 Firefox/37.0 |
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/
- [bug #45034] mdoc(7): add support for the mdocmx(7) reference extension,
anonymous <=
- [bug #45034] mdoc(7): add support for the mdocmx(7) reference extension, anonymous, 2015/05/06
- [bug #45034] mdoc(7): add support for the mdocmx(7) reference extension, Ingo Schwarze, 2015/05/06
- [bug #45034] mdoc(7): add support for the mdocmx(7) reference extension, anonymous, 2015/05/07
- [bug #45034] mdoc(7): add support for the mdocmx(7) reference extension, anonymous, 2015/05/08
- [bug #45034] mdoc(7): add support for the mdocmx(7) reference extension, Deri James, 2015/05/08
- [bug #45034] mdoc(7): add support for the mdocmx(7) reference extension, anonymous, 2015/05/08
- [bug #45034] mdoc(7): add support for the mdocmx(7) reference extension, anonymous, 2015/05/08
- [bug #45034] mdoc(7): add support for the mdocmx(7) reference extension, anonymous, 2015/05/12