Subject: Re: why XML?
To: None <netbsd-users@NetBSD.org, netbsd-docs@NetBSD.org>
From: Mark Weinem <firstname.lastname@example.org>
Date: 04/01/2007 21:18:37
On Sun, 1 Apr 2007, Greg A. Woods wrote:
> There's also the minor problem that some developers seem to be able to
> push in changes and new features without accompanying documentation.
> IMNSHO no code is worth committing until it is _fully_ documented, but
> at the very least those that are apparently reviewing it could at least
> call for minimal manual page entries and extensive, complete,
> cross-reference updates. I'm not saying everything goes in without
> documentation, but it happens far too often it seems.
["XML is pain"]
> For example I had some edits to the pkgsrc guide document that I thought
> would be useful and interesting to everyone, but when it went XML I
> found it impossible to even continue to merge my changes from one
> quarterly branch to the next, let alone get them in shape for
> I thought mdoc(7) provided all the necessary features for simultaneous
> publication of documentation in various forms, and in my estimation it
> is (luckily still) the most common way of authoring NetBSD
> documentation. (perhaps even without counting the "man" pages)
> If folks want more structured (and truly structured) documentation then
> I could only recommend Lout (pkgsrc/textproc/lout) as it is light years
> beyond anything-TeX or troff-like and still light years beyond
> anything-ML too.
> I'd personally be happier with raw troff or even raw TeX than
> anything-ML. There's nothing in the textual/documentation world more
> difficult and more complex to read, parse, or manage than *ML files.
Improvements are always possible and I think that the netbsd
documentation being docbook/xml is not set in stone.
But let's include netbsd-docs@