'\" m -- preprocess: mdocmx(1)
.\"@ mdocmx.1 - mdocmx(7) preprocessor for single-pass troff.
.\"@ mdocmx(7) extends the mdoc(7) semantic markup language by references,
.\"@ allowing mdoc(7) to create anchors and table of contents.
.\"
.\" Written 2014 by Steffen (Daode) Nurpmeso <address@hidden>.
.\" Public Domain
.
.Dd December 22, 2014
.Dt MDOCMX 1
.Os
.Mx -enable
.
.Sh NAME
.Nm mdocmx
.Nd Preprocessor for the mdoc semantic markup language reference extension
.
.Sh SYNOPSIS
.Nm
.Op Fl t | Fl T Ar \&Sh | sh | \&Ss | ss
.Op Fl v
.
.Mx -toc html xhtml pdf ps
.
.Sh DESCRIPTION
.Nm
can be used to overcome the restriction that single-pass troff
implementations cannot create forward references.
It will collect all referenceable anchors in a
.Xr mdoc 7
document, i.e.,
.Ic .Sh
and
.Ic .Ss
section headers as well as the anchors of the
.Xr mdocmx 7
reference extension.
The resulting
.Xr mdoc 7
document is itself distributable.
It will be displayed normally unless
.Xr mdocmx 7
enabled
.Xr mdoc 7
macros or special formatter programs with
.Xr mdocmx 7
support are used which can make use of the generated anchors.
.
.Bl -tag -width ".Fl _[9] Ar _"
.Mx
.It Fl t
Replace any
.Sq .Mx -toc
command line in the document with a table of content that consists of
section headers only.
.Mx
.It Fl T Ar \&Sh | sh | \&Ss | ss
Replace any
.Sq .Mx -toc
command line in the document with a table of contents that either
consists of only section headers
.Ns ( Sq sh Ns )
or the full tree of headers and their subsections
.Ns ( Sq ss Ns ) .
.It Fl v
Enable warning messages.
Use multiple times for more verbosity.
Verbosity is highly recommendet when developing
.Xr mdocmx 7
enabled
.Xr mdoc 7
documents.
.El
.
.Sh IMPLEMENTATION NOTES
.Nm
is not ment to be able to deal with all the possibilities that the
.Xr mdoc 7
semantic markup language has to offer.
I.e., it is not capable to deal with heavily interlocked macro usage.
A future multi-pass
.Xr troff 1
will not require any preprocessor at all, nor do specialized formatters
already today.
It works good enough for most real-life
.Xr mdoc 7
documents in existence, though.
Note that these restrictions should apply to
.Xr mdocmx 7
enabled documents that make use of anchors created by the extension
command
.Ic .Mx
only \(en normal
.Xr mdoc 7
command based anchors should always be parsed correctly in all cases.
.
.Sh COMPATIBILITY
.Nm
is implemented in portable
.Xr sh 1
and
.Xr awk 1 .
.
.Sh SEE ALSO
.Xr awk 1 ,
.Xr sh 1 ,
.Xr troff 1 ,
.Xr mdoc 7 ,
.Xr mdocmx 7
.
.Sh HISTORY
The
.Nm
environment appeared in 2014.
.
.Sh AUTHORS
Written by
.An Steffen Nurpmeso Aq Mt address@hidden .
.
.\" s-ts-mode