Greg A. Woods said on 7/4/07 13:34:
> At Mon, 2 Apr 2007 16:25:25 -0700, John Nemeth wrote:
> Subject: Re: Proposition for Releases page changes
>>      As has been explained before, you don't have to use XML, you can
>> submit documentation updates in pretty much any reasonable form (i.e.
>> XML, HTML, plain text, a simple description of what needs updating,
>> etc), so how exactly are the tools chosen by the people charged with
>> maintaining the documention hindering your ability to contribute?
> 
> Well that's all fine and good, but it still makes it nearly impossible
> for anyone who wants to also _use_ their own changes but who doesn't
> work well with XML sources.
> 
> Sure I can manually edit the plain text output and lock myself into
> never reformatting the entire document from source again, and thus give
> up ever using other changes with my own, at least until the original
> incorporates my own in a suitable way.
> 
> I.e. the approach you suggest is totally unworkable in the real world,
> at least for someone such as myself who uses NetBSD as a third-party
> developer and not just as an end user.
> 

I feel the same way about NetBSD being almost exclusively written in C.
If only the developers had read my mind and used BCPL instead - how dare
they try and write stuff in a widely understood and flexible format.
With the source code of NetBSD itself it's even worse than the
documentation - they've never offered to convert patches from languages
like FORTRAN or BASIC.

More seriously though, what is so hard about XML? Yes, the docbook DTDs
are pretty large, but everything I see written in them uses a smallish
subset. It's a format that's designed to avoid lock in, with a wealth of
tools for converting to other formats. It also tries to separate
structure from presentation, something that is very important because it
removes assumptions about the way the document will be rendered (by an
audio device for example).

Regards,

Chris