This "mandoc" naming of a project that was previously called "mdocml" is terribly confusing.
"mandoc" is the name of a newer troff/nroff macro package for writing man pages which replaced one called "man". (nroff -man versus nroff -mandoc).
The renamed "mandoc" project provides a processor which understands a "mdoc" language, a set of macros used on BSD Unixes. It's not a full processor for the roff language. The mdoc language has macros that resemble mandoc, like .SH, .TH and others.
In the TXR man-page-like reference manual, I'm using real roff macros (some of which output mandoc macros as their target, in the original sense of mandoc).
I don't think these macros could run in under the mandoc system, where you have to use a canned repertoire of macros.
For instance, I have a macro like this.
.coNP Functions @, boundp @, fboundp and @ mboundp
This parses its arguments. Any word preceded by @, is typeset in a typewriter font, immediately followed by a comma. A word preceded by @ is typeset typewriter, not followed by a comma. Other material is in the regular font.
Another complicated thing:
.mets (replace-list < list < item-sequence >> [ from <> [ to ]])
IN this syntax "< word" means typeset word as a meta-identifier. "<< word1 word2" means, typeset word as a meta-identifier, immediately juxtaposed with word2 (no whitespace) which is ordinary. >> word1 word2 reverses the relationship, and <> w1 w2 w3 means w1 and w2 are ordinary , surrounding meta-syntax w2 without space.
When you render this with a man reader, the macro puts out angle-bracket notation, exactly like this:
in the paragraphs which describe this, this notation is consistently used. In HTML and PDF output, these angle-bracket notation is replaced by italics.
Ah, I didn't realize you were making full use of roff. I don't think mandoc (mdocml) supports that; you're correct in saying that it's a canned version of man/mdoc.
> I'm sorry, but a markup language should have the scoping/delimiting wherewithal not to have to do stupid things like this.
(btw, mdoc has this and is widely supported, having been around for about 2 decades... having discovered it, I'll never write a manpage in man again)