And by the way, this is actually installed as a man page on target systems.
Most of my struggles were in the area of halfway decent HTML conversion. To that end, I started with a very hacky C program calld man2html, which actually contains a mini-troff implementation, and improved it quite a bit. I cloned that program here:
This had numerous issues, among the main ones being not handling loops and conditionals and so on for complex macros.
I still do quite a bit of post-processing on the output of this program, still, to do things like re-arrange its order, add internal hyper-links, and create a Java-scripted table of contents:
I don't like the approaches you have to take in troff for defining multiple ways of doing the same thing, based on whether it is juxtaposed to something else or followed by whitespace. This is fundamentally broken.
For instance if you want foobar such that foo is italic, but bar is regular, you have to use .IR foo bar, rather than the .I macro. I'm sorry, but a markup language should have the scoping/delimiting wherewithal not to have to do stupid things like this.
I have a more or less fixed (non-growing) set of such redundant macros in the document and so it doesn't bother me that much any more.
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.
And by the way, this is actually installed as a man page on target systems.
Most of my struggles were in the area of halfway decent HTML conversion. To that end, I started with a very hacky C program calld man2html, which actually contains a mini-troff implementation, and improved it quite a bit. I cloned that program here:
http://www.kylheku.com/cgit/man/log/
This had numerous issues, among the main ones being not handling loops and conditionals and so on for complex macros.
I still do quite a bit of post-processing on the output of this program, still, to do things like re-arrange its order, add internal hyper-links, and create a Java-scripted table of contents:
http://www.nongnu.org/txr/txr-manpage.html
(Almost the same URL as before, s/pdf/html/).
That post-processing is done by:
http://www.kylheku.com/cgit/txr/tree/genman.txr
I don't like the approaches you have to take in troff for defining multiple ways of doing the same thing, based on whether it is juxtaposed to something else or followed by whitespace. This is fundamentally broken.
For instance if you want foobar such that foo is italic, but bar is regular, you have to use .IR foo bar, rather than the .I macro. I'm sorry, but a markup language should have the scoping/delimiting wherewithal not to have to do stupid things like this.
I have a more or less fixed (non-growing) set of such redundant macros in the document and so it doesn't bother me that much any more.