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: weinemjabber.cz
PGP-Key available
|
