Re: [Webware-devel] Re: [Webware-discuss] Webware documentation

[Ian B. <ia...@co...>]

On Thu, 2002-10-24 at 09:06, Aaron Held wrote:
> >>Anyway, I've been writing lots of documentation lately, and I've been
> >>using reStructuredText (http://docutils.sourceforge.net/rst.html).  It's
> >>worked pretty well for me -- the output looks decent, but more
> >>importantly it's comfortable to write.  Keeping the documentation
> >>up-to-date is the most essential part.
> 
> I agree, we need more documentation and reStrucText is an easy-fast way 
> to get started.  Personally I like using XML.  I use the XML for some 
> internal documenetation, and it is also very fast to write.  I have been 
> using to doc layout of the gentoo linux project, becuase it is easy and 
> well supported. Take a look at http://www.gentoo.org/doc/xml-guide.html 
> and http://www.gentoo.org/projects/xml.html  I used it to generate 
> http://webware.metrony.com/tutorials/calPopUp.html
> 
> But I would go w/ reStruct to get some documentation going and we can 
> always convert from reStruct -> xml if we need to later.

The Gentoo markup doesn't look so bad -- how does the whole generation
process feel?  I was just looking at docbook, and just *looking* at the
source made me feel tired and sad.  Horrible, horrible, horrible... and
it's been around forever, but there still doesn't seem to be a good
authoring environment for it (though maybe I just don't know where to
look).

Anyway, Geoff's right about the Windows thing... do you know if the
Gentoo stuff can work on Windows?  I couldn't find the source in my
brief search.

I might be able to get over my annoyance with XML if I look deeper into
Emacs -- I'm sure there's something in there to make it more pleasant
(maybe abbrev...)

  Ian