MDOCMX(7) BSD Miscellaneous Information Manual MDOCMX(7) NAME]8;id=1;\]8;;\ .Mx — Reference extension for the mdoc semantic markup language SYNOPSIS]8;id=2;\]8;;\ .Mx -enable [output-formats] .Mx -disable .Mx .Mx macro .Mx macro key .Mx -ix [category] key .Mx -sx [category] .Mx -toc [output-formats] [-tree output-formats] TABLE OF CONTENTS]8;id=3;\]8;;\ NAME[]8;;#1\1]8;;\] SYNOPSIS[]8;;#2\2]8;;\] TABLE OF CONTENTS[]8;;#3\3]8;;\] DESCRIPTION[]8;;#4\4]8;;\] Creating referenceable anchors[]8;;#5\5]8;;\] String cleanup and reference prevention[]8;;#6\6]8;;\] Freely definable anchors and references[]8;;#7\7]8;;\] Creating table of contents[]8;;#8\8]8;;\] Strings that affect mdocmx[]8;;#9\9]8;;\] IMPLEMENTATION NOTES[]8;;#10\10]8;;\] Internal extended synopsis[]8;;#11\11]8;;\] ENVIRONMENT[]8;;#12\12]8;;\] EXAMPLES[]8;;#13\13]8;;\] COMPATIBILITY[]8;;#14\14]8;;\] SEE ALSO[]8;;#15\15]8;;\] HISTORY[]8;;#16\16]8;;\] AUTHORS[]8;;#17\17]8;;\] CAVEATS[]8;;#18\18]8;;\] DESCRIPTION]8;id=4;\]8;;\ mdocmx(7)[]8;id=43;man://mdocmx.7\43]8;;\] introduces referenceable index anchors to the mdoc(7)[]8;id=44;man://mdoc.7\44]8;;\] semantic markup language that is used for UNIX manual pages by defining a single new multiplexer command: .Mx. Users can truly enable this exten‐ sion by setting the environment variable MDOCMX_ENABLE[]8;;#42\42]8;;\] to a non-empty value (non-empty is a troff(1)[]8;id=45;man://troff.1\45]8;;\] requirement). The mdocmx(7)[]8;id=46;man://mdocmx.7\46]8;;\] reference extension augments the standard mdoc(7)[]8;id=47;man://mdoc.7\47]8;;\] document prologue – .Dd, .Dt and .Os – with the new command ‘.Mx -enable’. It can be restricted to specific output formats by adding those troff(1)[]8;id=48;man://troff.1\48]8;;\] output devices for which expansion is desired as fur‐ ther arguments to ‘-enable’; for convenience all typewriter-like devices can be addressed via ‘tty’. It is not an error to specify a device for which no special mdocmx(7)[]8;id=49;man://mdocmx.7\49]8;;\] support is available, but such requests are simply ignored. Because macros driven by single-pass troff implementations cannot create forward references mdoc(7)[]8;id=50;man://mdoc.7\50]8;;\] documents which use this extension need to be preprocessed with the mdocmx(1)[]8;id=51;man://mdocmx.1\51]8;;\] preprocessor, which is a regular part of mdocmx(7)[]8;id=52;man://mdocmx.7\52]8;;\] and implemented in portable sh(1)[]8;id=53;man://sh.1\53]8;;\] and awk(1)[]8;id=54;man://awk.1\54]8;;\]. 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 dis‐ tribute the resulting document – refer to the COMPATIBILITY[]8;;#14\14]8;;\] section for more on that. Sometimes it may be desirable to actively suppress any processing of the mdocmx(7)[]8;id=55;man://mdocmx.7\55]8;;\] reference extension: this can either be accomplished by using .Mx with the ‘-disable’ argument or by defining the string ‘mx-disable[]8;;#36\36]8;;\]’, as in $ MDOCMX_ENABLE=anyval; export MDOCMX_ENABLE $ < xy.z mdocmx.sh | troff -Tutf8 -mdoc -a -dmx-disable=1 Creating referenceable anchors]8;id=5;\]8;;\ After the extension was ‘-enable’d in the document prologue the third group of .Mx usage forms can be used to enqueue index anchor requests. These requests form a last–in — first–out stack which will be consumed (popped) by the later occurrence of a (corresponding) mdoc(7)[]8;id=56;man://mdoc.7\56]8;;\] macro which supports referenceable index entries. The indices are managed with distinct namespaces for each supported macro, meaning that, e.g., ‘.Mx Ic sendmail’ and ‘.Mx Va sendmail’ will create distinct index anchors. Using the plain macro .Mx without arguments creates a stack entry for which both, the name of the macro as well as the key will be taken from the document content. ‘.Mx macro’ will create a stack entry that will be consumed by the next occurrence of macro only, then taking the key off the document content, whereas ‘.Mx macro key’ creates a stack entry that also has its key defined, and which will be consumed once an exactly matching macro / key pair is seen in the document only. (The EXAMPLES[]8;;#13\13]8;;\] section gives a use case for this form.) Using the mdocmx(1)[]8;id=57;man://mdocmx.1\57]8;;\] preprocessor will also create referenceable anchors for the mdoc(7)[]8;id=58;man://mdoc.7\58]8;;\] section header commands .Sh and .Ss automati‐ cally, so that a mdoc(7)[]8;id=59;man://mdoc.7\59]8;;\] macro package which supports the mdocmx(7)[]8;id=60;man://mdocmx.7\60]8;;\] extension will be enabled to actually create references with the .Sx command, and, dependent on the output device, cross-refer‐ ences defined via the command .Xr will also be backed with functionality. The following macros gain support for referenceable anchors via .Mx: .Ar]8;id=19;\]8;;\ Command argument. .Cd]8;id=20;\]8;;\ Configuration declaration. .Cm]8;id=21;\]8;;\ Command modifier. .Dv]8;id=22;\]8;;\ Defined variable or preprocessor constant. .Er]8;id=23;\]8;;\ Error constant. .Ev]8;id=24;\]8;;\ Environment variable. .Fl]8;id=25;\]8;;\ Command line option (flag). .Fn]8;id=26;\]8;;\ Function name. .Fo]8;id=27;\]8;;\ Function name (in function block syntax). This is mapped to .Fn[]8;;#26\26]8;;\], .Fo has no index by itself. .Ic]8;id=28;\]8;;\ Internal or interactive command. .In]8;id=29;\]8;;\ An ‘include’ file for, e.g., the C programming language. .Pa]8;id=30;\]8;;\ File system path. .Va]8;id=31;\]8;;\ Variable name. .Vt]8;id=32;\]8;;\ Variable type, type reference. String cleanup and reference prevention]8;id=6;\]8;;\ Before strings get used for anchor creation or reference look up any sur‐ rounding whitespace will be removed, as well as any preceding ‘\&’, ‘\%’ and postposed ‘\&’, ‘\%’, ‘\/’, and ‘\c’ escape characters. Yet, prefix‐ ing a command with two zero-width glyphs (after possible whitespace), as in ‘\&\&’, has the special meaning that reference lookup will be actively prevented for all remaining arguments of the command. For example, in the hypothetic ‘.Ic if , elif , else , endif’ all four commands would be linked, but in ‘.Ic \&\&if , elif , else , endif’ none of them; if that is not desired, a new command needs to be started: ‘.Ic \&\&if , .Ic elif , else , endif’. Freely definable anchors and references]8;id=7;\]8;;\ Via the ‘.Mx -ix category key’ and ‘.Mx -ix key’ usage forms anchors can be defined almost anywhere, e.g., ‘.Mx -ix subsubsection "An interesting topic"’ defines the anchor ‘An interesting topic’ for the “key” ‘subsubsection’. The form without a specified category will use the builtin name ]8;id=33;\]8;;\‘ixsx’ instead. References to anchors that have been created via -ix can be made by acti‐ vating the .Sx search extension via ‘.Mx -sx category’ (or ‘.Mx -sx’ for the builtin ‘ixsx[]8;;#33\33]8;;\]’ category) followed by a normal local reference lookup: .Mx -sx subsubsection .Sx "An interesting topic" It should be noted that these usage forms are mostly ment for automated conversion tools rather than for human manual creators: their use is non- trivial (which is owed to the implementation of mdoc(7)[]8;id=61;man://mdoc.7\61]8;;\]) and the resulting visual output should always be verified! As a rule of thumb anchors should always be created inside some “normal” text so that they can be attached to something “physical”. Creating table of contents]8;id=8;\]8;;\ The final usage form of the mdocmx(7)[]8;id=62;man://mdocmx.7\62]8;;\] reference extension allows the creation of a document table of contents, which is of special interest when converting a mdoc(7)[]8;id=63;man://mdoc.7\63]8;;\] document into formats such as HTML, XHTML or PDF. To restrict the creation of the table of contents to special output formats, add the names of those troff(1)[]8;id=64;man://troff.1\64]8;;\] output devices for which expansion is desired as further arguments to ‘-toc’; for conve‐ nience all typewriter-like devices can be addressed via ‘tty’. By default only .Sh section headers are a vivid part of the TOC; in order to include .Ss subsections also add a ‘-tree’ argument. Note that if ‘-tree’ is used in conjunction with output-device restrictions it will only affect those devices that appear later on the line. In the first of the following examples a table of contents will be gener‐ ated for PDF and typewriter-like devices. In the second example a tree of contents will instead be generated for the output formats PDF and HTML, whereas typewriter-like devices will see a flat table of contents with only section headers. .Mx -toc pdf tty .Mx -toc tty -tree html pdf Strings that affect mdocmx]8;id=9;\]8;;\ Note that due to deficiencies in some implementations of troff(1)[]8;id=65;man://troff.1\65]8;;\] strings given on the command line (via option ‘-d’) have to be given an argument in order to be perceived on the macro level. mx-debug]8;id=34;\]8;;\ If defined mdocmx(7)[]8;id=66;man://mdocmx.7\66]8;;\] macros will offer some ver‐ bosity. In addition not only references will produce visual output, but also anchors. mx-anchor-dump]8;id=35;\]8;;\ If this is set to a filename then the list of anchors is dumped to it. mx-disable]8;id=36;\]8;;\ Has the same effect as ‘.Mx -disable’. mx-toc-disable]8;id=37;\]8;;\ Forcefully turn off any table of contents creation. mx-toc-emerged]8;id=38;\]8;;\ Normally compact display is used for the table of contents, but when this string is set an emerged dis‐ play is used for the first level that lists the head‐ ings. mx-toc-force]8;id=39;\]8;;\ Defining this string can be used to enforce the cre‐ ation of a table of contents as specified, even if the documents ‘-toc’ configuration would not create one for the targeted output device. A flat table of contents will be generated unless the string value is ‘tree’. mx-toc-name]8;id=40;\]8;;\ If defined its content is used as the headline of the table of contents, which can be used for, e.g., localization purposes. The default is “TABLE OF CONTENTS”. (Note that if the table of contents has instead been generated by the mdocmx(1)[]8;id=67;man://mdocmx.1\67]8;;\] pre‐ processor then the resulting document already includes a definition of this string to ensure com‐ patibility with, at least, mandoc(1)[]8;id=68;man://mandoc.1\68]8;;\].) mx-toc-numbered]8;id=41;\]8;;\ If defined the first level of the table of contents will be numbered. IMPLEMENTATION NOTES]8;id=10;\]8;;\ The .Mx request cannot share a line with other macros, neither in the document prologue nor in its content. Whereas that is mostly owed to the necessity of ensuring (backward) compatibility with environments that do not support mdocmx(7)[]8;id=69;man://mdocmx.7\69]8;;\], it also simplified implementation of the pre‐ processor. Internal extended synopsis]8;id=11;\]8;;\ In addition to those usage forms that have been described above the .Mx multiplexer command also understands further flags and arguments which are of possible interest for formatter and macro implementors. These further flags and arguments are only generated by the mdocmx(1)[]8;id=70;man://mdocmx.1\70]8;;\] pre‐ processor and are solely ment to communicate the preprocessed state of the document to the actual consumers. For one a ‘-preprocessed’ flag is appended to the single ‘-enable’ com‐ mand in the document prologue. And then an additional ‘-anchor-spass’ form is introduced, which takes two or three arguments – the macro (name of the command) for which this defines an anchor as well as its key, pos‐ sibly followed by a numeric argument that describes the relationship in between section headings: for .Sh commands it defines a running one-based index count of section headers, for .Ss commands it instead specifies the index of the section header they belong to, therefore creating the possi‐ bility to generate TOCs. ENVIRONMENT]8;id=12;\]8;;\ Only if the environment variable ‘MDOCMX_ENABLE]8;id=42;\]8;;\’ is set to a non-empty value will the mdocmx(7)[]8;id=71;man://mdocmx.7\71]8;;\] macros generate the necessary information that the chosen output device of troff(1)[]8;id=72;man://troff.1\72]8;;\] can, sufficient support provided, use to generate table of contents, internal as well as external references. EXAMPLES]8;id=13;\]8;;\ A complete, but completely fanciful mdoc(7)[]8;id=73;man://mdoc.7\73]8;;\] document that uses the mdocmx(7)[]8;id=74;man://mdocmx.7\74]8;;\] extension would for example be: .Dd April 22, 2015 .Dt MDOCMX-EXAMPLE 7 .Os .Mx -enable tty . .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 .Ql \&Ic , key .Ql .Ar . .Mx .It Ic .Cm Anchor for .Ql \&Ic , key .Ql .Cm . .Mx .It Ic .Dv And an anchor for .Ql \&Ic , key .Ql .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 .Ql \&Fn there will be an anchor with the key .Ql _atexit . .It Ic "no anchor here" .It Ic "final anchor" Pops the pushed .Ql \&Ic / .Ql final anchor macro / key pair. .It Ic ciao Pops the .Ql \&Ic and assigns the key .Ql Ciao . .El COMPATIBILITY]8;id=14;\]8;;\ Using the mdocmx(7)[]8;id=75;man://mdocmx.7\75]8;;\] extension in mdoc(7)[]8;id=76;man://mdoc.7\76]8;;\] 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 mdocmx(7)[]8;id=77;man://mdocmx.7\77]8;;\] may be to preprocess manuals with mdocmx(1)[]8;id=78;man://mdocmx.1\78]8;;\] on developer machines and instead distribute the resulting documents. SEE ALSO]8;id=15;\]8;;\ awk(1)[]8;id=79;man://awk.1\79]8;;\], mandoc(1)[]8;id=80;man://mandoc.1\80]8;;\], mdocmx(1)[]8;id=81;man://mdocmx.1\81]8;;\], sh(1)[]8;id=82;man://sh.1\82]8;;\], troff(1)[]8;id=83;man://troff.1\83]8;;\], mdoc(7)[]8;id=84;man://mdoc.7\84]8;;\] HISTORY]8;id=16;\]8;;\ The .Mx environment appeared in 2014. AUTHORS]8;id=17;\]8;;\ Idea and implementation by Steffen Nurpmeso <steffen@sdaoden.eu>. CAVEATS]8;id=18;\]8;;\ Be aware that the content of the ‘-width’ argument to mdoc(7)[]8;id=85;man://mdoc.7\85]8;;\] lists etc. is evaluated as if it were normal document content; e.g., in the following example the ‘Fn _atexit’ will be evaluated and may thus get used by .Mx: .Bl -tag -width ".It Fn _atexit" When developing a manual it may be helpful to increase verbosity of the mdocmx(1)[]8;id=86;man://mdocmx.1\86]8;;\] preprocessor on its standard error I/O channel by using the ‘-v’ command line flag in order to get a notion on what is going on: $ MDOCMX_ENABLE=1; export MDOCMX_ENABLE $ mdocmx.sh -vv < mdocmx.7 2> stderr.txt | \ groff -Tutf8 -mdoc -dmx-toc-force=tree -dmx-debug=1 | \ less -R $ cat stderr.txt BSD May 25, 2021 BSD