On Sat, Mar 31, 2007 at 06:22:43PM +0200, haad wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> Martin S. Weber wrote:
> > On Sat, Mar 31, 2007 at 02:24:21PM +0200, Zafer Aydogan wrote:
> >> Yes, NetBSD documentation has always been a pain.
> > 
> > Well, it was okay some time back.
> > 
> >> And trying to help improving is a pain too. You need to send xml diffs !
> you preffer .doc diffs or what ? AFAIK freebsd has documentation written in
> docbook too.

You're answering Zafer here.

I prefer the .list/.html files there were. Quite a mess but nothing compared
to the mess that is there now.

> > 
> > And that's where the project lost me as a contributor. You want XML?
> > Go find the people who want to edit that. Not me. 
> > (...)
> I use docbook and xml in day work and I love it:).

Sure, I didn't say there can't be people who like it. The contribution
to the docs has stagnated nevertheless. And if you like it that much
you'll most likely love to improve the NetBSD documentation. Have fun
and go ahead! You won't convince *me* to spend a second of my time
trying to learn ... wait that'll get insulting.

> > 
> > I still believe in the value of good documentation, I still love
> > NetBSD for being the system it is (although it seems technical decisions
> > partially went away in favor of political decisions), but I don't
> > love the system enough to fight XML.
> > 
> How do you want to write good netbsd project documentation? latex,openoffice ?
> latex is dead for me and openoffice is real pain. 

LaTeX isn't dead for me and docbook-xml is a real pain. But that's not 
the question. What docbook-xml brought us is a way to easily print the
guide and woohoo (parts of?) the website?. Yeah, I print my guides daily.
I suppose the ratio of quickly looking up something online in the guide
vs. maneuvering in a hundreds of pages PDF will clearly tell you that
the time and work invested in making that possible was worth it. (uh-huh...)

> from docbook you can generate
> html,pdf, man pages and more.. . I it can be possible I want also our manual
> pages written in xml/docbook :)) it's far more readable then nroff.

Great idea. Let's kick out roff and friends out of text.tgz and instead throw
in the toolchain to handle docbook-xml. Then we'll look at the majority of
machines targetted by NetBSD and find out that half of them don't have the
ram to display a manpage, and most of the other half is turned off by their
users before the info gets to display.

Oh wait. You want docbook-xml and then generate roff's from them. The daily
builds will finish weekly then, eh?




You seem to miss the picture of how it used to be. A sloppy, _well-known language_,
added to by a proprietary yet light-weight processing (lst2html) was replaced
by something as elephantine to learn as docbook-xml is.

Now, some time later, users begin to complain about the quality and outdatedness
of our documentation. Go find the links yourself. If you want manpages in docbook-
xml, I'm looking forward to see wrong and outdated information creeping into the
running system, too. The roff hackers will love to learn docbook-xml, I'm sure.

The point is that this great technical improvement has bought us nothing but
a print-ready guide (for those two dozen users who print the guide), driven off
contributors to documentation and an increasing share of outdated information.

Regards,

-Martin