'\" -- 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 - 2015 by Steffen (Daode) Nurpmeso <address@hidden>.
.\" Public Domain
.
.Dd April 22, 2015
.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 c
.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 any explicitly set anchor 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 c
In conjunction with
.Fl t
or
.Fl T
this will request compact display for the first level of the generated
table of contents (the level covering
.Ic .Ss
subsections will always be displayed in compact format).
.
.Mx
.It Fl t
Replace any
.Ql .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
.Ql .Mx -toc
command line in the document with a table of contents that either
consists of only section headers
.Pf ( Sq \&Sh Ns )
or the full tree of headers and their subsections
.Pf ( Sq \&Ss Ns ) .
.
.Mx
.It Fl v
Enable warning messages.
Use multiple times to gain processing verbosity, too.
Verbosity is highly recommendet when developing
.Xr mdocmx 7
enabled
.Xr mdoc 7
documents.
.El
.
.
.Sh IMPLEMENTATION NOTES
.
.Nm
works without any ado for any tested real-life
.Xr mdoc 7
document, but its capabilities can be exceeded by making heavy use of
all the possibilities that
.Xr troff 1
and the
.Xr mdoc 7
semantic markup language have to offer.
A future multi-pass
.Xr troff 1
will not require any preprocessor at all, nor do specialized formatters
already today.
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.
Use verbosity on the preprocessor and enable debug on the macro side
when developing manuals.
.
.
.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