'\" m -- preprocess: mdocmx(1)
.\"@ mdocmx.7 - mdoc .Mx anchor reference manual.
.\"
.\" Written 2014 by Steffen (Daode) Nurpmeso <address@hidden>.
.\" Public Domain
.
.Dd November 11, 2014
.Dt MDOCMX 7
.Os
.Mx -enable
.
.Sh NAME
.Nm .Mx
.Nd Reference extension for the mdoc semantic markup language
.
.Sh SYNOPSIS
.Nm
.Ar -enable
.Pp
.Nm
.Nm
.Ar macro
.Nm
.Ar macro Ar key
.Pp
.Nm
.Ar -toc
.
.Mx -toc
.
.Sh DESCRIPTION
.Nm
introduces creation of referenceable manual index anchors.
To enable this extension the standard
.Xr mdoc 7
document prologue \(en
.Ic \&Dd ,
.Ic \&Dt
and
.Ic \&Os
\(en is augmented with the new command
.Nm
.Ar -enable .
Because macros driven by single-pass troff implementations cannot
create forward references
.Xr mdoc 7
documents which use this extension need to be preprocessed with the
.Xr mdocmx 1
preprocessor, which is a regular part of
.Xr mdocmx 7
and implemented in portable
.Xr sh 1
and
.Xr awk 1 .
Specialized manual formatters and macros driven by multi-pass troff
interpreters may not require a preprocessor to support this extension.
It is also possible to preprocess the manual once and distribute the
resulting document \(en refer to the
.Sx COMPATIBILITY
section for more on that.
.
.Ss Creating referenceable anchors
After the extension was
.Ar -enable Ns
d in the document prologue the second group of
.Nm
usage forms can be used to enqueue index anchor requests.
These requests form a stack which will be consumed (popped) by the
later occurrence of a (corresponding)
.Xr mdoc 7
.Ar macro
which supports referenceable index entries.
The indices are managed with distinct namespaces for each supported
.Ar macro ,
meaning that, e.g., `\&.Mx Ic sendmail' and `\&.Mx Va sendmail'
will create distinct index anchors.
.Pp
Using the plain macro
.Nm
without arguments creates a stack entry for which both,
the name of the
.Ar macro
as well as the
.Ar key
will be taken from the document content.
.Nm
.Ar macro
will create a stack entry that will be consumed by the next occurrence of
.Ar macro
only, then taking the
.Ar key
off the document content, whereas
.Nm
.Ar macro Ar key
creates a stack entry that also has its
.Ar key
defined, and which will be consumed once an exactly matching macro / key
pair is seen in the document only.
(The
.Sx EXAMPLES
section gives a use case for this form.)
.Pp
Using the
.Xr mdocmx 1
preprocessor will also create referenceable anchors for the
.Xr mdoc 7
section header macros
.Ic .Sh
and
.Ic .Ss ,
so that a
.Xr mdoc 7
macro package which supports the
.Xr mdocmx 7
extension will be enabled to actually create references with the
.Ic .Sx
macro.
The following macros gain support for referenceable anchors via
.Nm :
.Bl -tag -width ".It Ic .Dv"
.Mx
.It Ic .Ar
Command argument.
.Mx
.It Ic .Cm
Command modifier.
.Mx
.It Ic .Dv
Defined variable or preprocessor constant.
.Mx
.It Ic .Er
Error constant.
.Mx
.It Ic .Ev
Environment variable.
.Mx
.It Ic .Fl
Command line option (flag).
.Mx
.It Ic .Fn
Function name.
.Mx
.It Ic .Fo
Function name (in function block syntax).
This is mapped to
.Ic .Fn ,
.Ic .Fo
has no index by itself.
.Mx
.It Ic .Ic
Internal or interactive command.
.Mx
.It Ic .Pa
File system path.
.Mx
.It Ic .Va
Variable name.
.El
.
.Ss Creating a table of contents
The final group of usage forms of the
.Xr mdocmx 7
reference extension allows the creation of a document table of content,
which is of special interest when converting a
.Xr mdoc 7
document into formats such as HTML, XHTML and PDF.
If so desired the
.Xr mdocmx 1
preprocessor will replace any occurrence of `.Mx -toc' in the document
with a table of contents (see
.Sx IMPLEMENTATION NOTES
for an example), otherwise `.Mx -toc' lines will remain a vivid part of
the document text and thus target of interpretation of the actual
document formatter, which ought to ignore such commands (except when it
directly supports the
.Xr mdocmx 7
extension and the document target format is one of the mentioned, in
which case it may create a regulary table of content in place).
.
.Sh IMPLEMENTATION NOTES
The
.Nm
request cannot share a line with other macros, neither in the document
prologue nor in its content.
Be aware that the content of the
.Fl width
argument to
.Xr mdoc 7
lists etc. is evaluated as if it were normal document content, e.g.,
in `.Bl -tag -width ".It Fn _atexit"' the `Fn _atexit' will be evaluated
and may thus get used by
.Nm .
.Pp
When developing a manual it may be helpful to increase verbosity of the
preprocessor on its standard error I/O channel by using the
.Fl v
command line flag in order to get a notion on what is going on:
.Bd -literal -offset indent
$ mdocmx -vv -t Sh < mdocmx.7 2> stderr.txt | \e
  groff -Tascii -mdoc | less
$ cat stderr.txt
.Ed
.Pp
The
.Xr mdocmx 1
preprocessor is implemented in standard
.Xr sh 1
and
.Xr awk 1
and relies on the latter utilities' input field splitting capabilities.
This means that whitespace in between fields is lost on input and
reinstantiated as a single space character on output.
With verbosity enabled a warning is issued in cases where this could
actually be a problem.
.Pp
The preprocessor also doesn't handle escaped whitespace well, e.g.,
"White\e Space" isn't well supported; arguments with embedded whitespace
should instead be enclosed in quotation marks.
.
.Sh EXAMPLES
A complete, but completely fanciful
.Xr mdoc 7
document that uses the
.Xr mdocmx 7
extension would for example be:
.Bd -literal -offset indent
\&.Dd November 8, 2014
\&.Dt MDOCMX-EXAMPLE 7
\&.Os
\&.Mx -enable
\&.Sh NAME
\&.Nm mdocmx-example
\&.Nd An example for the mdocmx mdoc reference extension
\&.Mx -toc
\&.Sh DESCRIPTION
Sors salutis et virtutis michi nunc contraria.
\&.Bl -tag -width ".It Fn _a_e_i_"
\&.Mx
\&.It Ic .Ar
This will create an anchor for a macro `Ic', key `.Ar'.
\&.Mx
\&.It Ic .Cm
Anchor for `Ic', key `.Cm'.
\&.Mx
\&.It Ic .Dv
And an anchor for `Ic', key `.Dv'.
\&.Mx Ic
\&.Mx Ic "final anchor"
\&.Mx Fn _atexit
\&.It Fn exit
No anchor here.
\&.It Fn at_quick_exit , Fn _atexit
Not for the first, but for the second `Fn' there will be an
anchor with the key `_atexit'.
\&.It Ic "no anchor here"
\&.It Ic "final anchor"
Pops the pushed `Ic' / `final anchor' macro / key pair.
\&.It Ic ciao
Pops the `Ic' and assigns the key `Ciao'.
\&.El
.Ed
.
.Sh COMPATIBILITY
Using the
.Xr mdocmx 7
extension in
.Xr mdoc 7
manual pages should not cause any compatibility problems in sofar as
all tested environments silently ignore the unknown commands by default.
Because of this, and due to the nature of this extension, an
interesting, backward as well as forward compatible approach to use
.Xr mdocmx 7
may be to preprocess manuals on developer machines and instead
distribute the resulting documents.
.
.Sh SEE ALSO
.Xr awk 1 ,
.Xr mandoc 1 ,
.Xr mdocmx 1 ,
.Xr sh 1 ,
.Xr troff 1 ,
.Xr mdoc 7
.
.Sh HISTORY
The
.Nm
environment appeared in 2014.
.
.Sh AUTHORS
Original idea and draft implementation by
.An Steffen Po Daode Pc Nurpmeso Aq Mt address@hidden .
Command design by
.An Ingo Schwarze Aq Mt address@hidden .
.\" s-ts-mode