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
> submission.
>
> 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.
> Nothing.

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@


Greetings, Mark

-- 
Mark Weinem
Jabber: weinem@jabber.cz
PGP-Key available