Subject: On more flavorful markup for NetBSD software documentation
To: innerworkings <ls-innerworkings@dusk.bitstream.net>
From: Christopher Reid Palmer <chrisp@dusk.bitstream.net>
List: tech-kern
Date: 07/19/2000 14:15:36
On Wed, 19 Jul 2000, Tino Wildenhain wrote:
> I'm sure there is a DTD for technical documentation. If not,
> we could commit to one main standard here, which would be
> easyly extendable.
>
> Then, who likes man output (s)he can it get from xml2man or such,
[...]
I could not agree more. Furthermore, I will volunteer to work on the
project of getting the NetBSD docs into the new format, if the Powers that
Be(tm) give the idea the thumbs-up.
In one of my more addle-brained moments, I schemed to build a Linux
distribution (I hear your groans) that did precisely this, although I was
vacillating between DocBook and LaTeX (I still love LaTeX best). I began
work on the distro but ceased for a number of reasons. There is no
particular reason I did not consider XML; I regard it as a viable choice.
Here is a (possibly incomplete) list of tasks for which I am volunteering
myself (and anyone else who is interested):
1. Decide on a document format
LaTeX
DocBook
Some pre-existing XML DTD
Some new XML DTD
2. Find and/or develop software
For converting from (1) to online and printable docs, either
interactively (xml2man, a CGI script, et c.), as a batch job, or
both. This might entail programs like man(1) becoming
wrappers/front-ends to the translator(s)
3. QA/Testing
How bad does it suck? In what ways could it be made to suck less?
Find willing testers
4. Refine per (3)
5. Repeat (2-4) until happy
5. Ship
Commit to CVS
..
Thoughts?
--
Chris
www.innerfireworks.com