Subject: On more flavorful markup for NetBSD software documentation
To: innerworkings <>
From: Christopher Reid Palmer <>
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
  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