documentation effort

[Chad Miller]

To clear up a misconception I think some might have, I'm not suggesting
more dependencies for the server.  Just like autoconf and pals isn't
_necessary_ to build the server, neither will any SGML tools be.  

_If_ you update the docs, _and_if_ you want immediate results, then you
would have to have Clark's jade tools and the debiandoc.dtd .  I was
envisioning this for releases only -- the only time docs need to be exactly
in sync with source.

(It would even be trivial to have the CVS server render the output at 
commit (and put the HTML output in the web root), but I didn't want to
speak for anyone without asking, and didn't want to ask without feedback.)



On Thu, May 24, 2001 at 11:52:04AM -0500, Chris Parker wrote:
> I dunno, maybe I'm old fashioned, but plain-text works for me, and
> is a lot more cross-platform.

Plain text _is_ nice for small docs, but for anything larger than a
specific README, it's difficult for a newbie to find and for authors to 
update coherently.  Using an SGML language allows for structure that plain
text can't have without a lot of effort.  (There's also something to be
said for being able to hand your PHB a pretty PDF.)

This is an excellent position, btw.  It's the strongest argument against
something as complicated as what I suggest.

> I think a better organization would be to have each module in a separate
> directory undor /doc, and all of the readme's/examples for that module
> are placed in that directory.

And, this does indeed provide some structure.  I think an SGML is easier,
though.

						- chad

-- 
Chad Miller <cmiller@surfsouth.com>  | If you keep your mind sufficiently 
unix brujo, shutterbug, bookworm     | open, people will throw a lot of 
URL: http://web.chad.org/home/       | rubbish into it.  --William Orton