Subject: Re: Musing about the state of NetBSD's documentation...
To: None <email@example.com>
From: James K. Lowden <firstname.lastname@example.org>
Date: 11/15/2006 23:51:13
Hubert Feyrer wrote:
> The problem with the current situation
> is that the toolchain to handle the DocBook/XML docs is to heavy: it
> requires htdocs being checked out, a proper set of tools installed in a
> version that actually does work, plus DocBook/XML formatting knowhow. As
> a result, I see many people being reluctant about updating
> documentation, pushing things on the NetBSD www team or not doing it at
> all. Plus, adding/updating documentation is only available to people
> with NetBSD CVS (write) access.
If anything besides time and ignorance has prevented me from contributing
documentation, it's not XML; it's everything not XML. I know SGML
DocBook. It evolves slowly, and anything I learn about it will remain
useful for a long time. Probably into the era of an intelligent
wysiwyg-ish editor. That even applies, to a lesser degree, to toolchain
Here's another suggestion: set up a machine with the tools installed, and
submit the XML to it via ssh. A script on that box reads XML on stdin and
writes HTML/pdf on stdout.
The author doesn't need tools installed locally. He can work
independently. When he's ready to submit something, he can send the XML
and the HMTL to someone who has write access. The burden on the committer
would be small.