Nate Bargmann <n...@n0nb.us> wrote:
> I have long been involved with a project that has lacked good
> documentation for nearly all of its existence. We've had documentation,
> but it isn't in a good format for generating man, HTML, or PDF versions.
>
> Long ago I started with Docbook and then that got to a point no one else
> would touch it and I didn't want to either. XML was the "wave of the
> future" but I didn't jump on that wagon. …
At work, we’re in the first stages of moving our writers over to a DITA-based
CMS.
It’s horribly complex (and I should know, I’m in the vanguard), but does have a
pretty good way of producing both good PDF and decent HTML. I love when
people go “ooh, topic-based, shiny!” and I point out manpages have been around
for decades. :-D
BUT… if you want manpages, write manpages. I have not found anything yet
that does a good job of automatically creating manpages from any other kind
of format. DITA’s reference topic might be a reasonable basis for a conversion,
but writing that descriptive title is still beyond any AI. It has to look
natural to a
human reader, while containing all the keywords needed to find it in a search
(thus being both content and metadata).
Ingo’s mandoc solution is a good way to produce text/HTML output, and you
can use groff for PDF. The only thing I’d take issue with is his assertion that
-mdoc is easier to write than legacy -man. No doubt that -mdoc’s semantic
markup adds value, but I’ve always had trouble getting my head around the
syntax.
Larry
