'\" -- preprocess: mdocmx(1)
.\"@ mdocmx.1 - mdocmx(7) preprocessor for single-pass troff.
.\"@ mdocmx(7) extends the mdoc(7) semantic markup language by references,
.\"@ allowing it to create anchors and table of contents.
.\"
.\" Written 2014 - 2022 Steffen Nurpmeso <steffen@sdaoden.eu>.
.\" Public Domain
.
.Dd Nov 23, 2022
.Dt MDOCMX 1
.Os
.Mx -enable
.
.
.Sh NAME
.Nm mdocmx
.Nd mdocmx reference extension mdoc manual preprocessor
.
.
.eo
.de mx-xr-url-create
. ie 'pdf'\*[.T]' \{\
.  ie 'mdocmx'\$3' \
.   pdfhref W -D "https://www.sdaoden.eu/code-mdocmx-\$2.html" -P "\%" -A "\c" "[\$1]"
.  el \
.   pdfhref W -D "https://man.archlinux.org/man/\$3.\$2" -P "\%" -A "\c" "[\$1]"
. \}
. el \{\
.  ie 'mdocmx'\$3' \
.   URL "https://www.sdaoden.eu/code-mdocmx-\$2.html" "[\$1]"
.  el \
.   URL "https://man.archlinux.org/man/\$3.\$2" "[\$1]"
. \}
..
.ec
.
.
.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
is a preprocessor for
.Xr mdocmx 7
that extends the
.Xr mdoc 7
semantic markup language with references, allowing it to create anchors
and table of contents.
It is needed because single-pass troff implementations cannot create
forward references, and so it collects all referenceable anchors in a
.Xr mdoc 7
document.
The result is itself a valid, compatible and distributable
.Xr mdoc 7
document, but which will be fully interactive if the local formatter is
.Xr mdocmx 7
enabled.
.
.Bl -tag -width ".Fl _[9] Ar _"
.Mx
.It Fl c
In conjunction with
.Fl t
or
.Fl T
a compact display for the first level of the generated table of contents
is used (deeper levels are always compact).
.
.Mx
.It Fl t
Replace any
.Ql .Mx -toc
command in the document with a table of content of only section headers.
The result does not require further
.Xr mdocmx 7
processing (but which would create interactivity).
.
.Mx
.It Fl T Ar \&Sh | sh | \&Ss | ss
Replace any
.Ql .Mx -toc
command 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 ) .
The result does not require further
.Xr mdocmx 7
processing (but which would create interactivity).
.
.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 langouage have to offer.
A future multi-pass
.Xr troff 1
will not require any preprocessor at all.
.
.
.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 AUTHORS
.
.An Steffen Nurpmeso Aq Mt steffen@sdaoden.eu .
.
.\" s-ts-mode