On Thu, 2002-10-24 at 10:37, Geoffrey Talvola wrote: > I kinda like just using HTML with simple styles for documentation, as we are > now. It works, it's easy to edit by hand, and it's just one less thing to > learn.
Yeah, reST is little weird to learn thoroughly, though the basic structure is simple enough. But I really found while doing the documentation for FFK and SQLObject that using it made the entire experience much more pleasant -- it still takes a long time to write documentation, but it felt a bit less burdensome. Previously for FFK I had styled it after the Webware documentation, and there was a certain relief I felt deleting all the HTML markup. I also found navigating the source (for updating) to be much easier -- reST is entirely readable as text, while HTML is not so great, and updating is our real problem. There are some annoying parts about reST -- for one thing there doesn't seem to be any HTML escape, so you can't include arbitrary HTML in your page (though of course arbitrary HTML source is easy enough). I like to be able to do that for some examples, though I'm more likely to include source than rendered HTML. Or you can do like Aaron did, and use screenshots -- but if I hate writing with all the markup, I *really* hate dealing with screenshots. It would be neat to have an automatic screenshot generator, though... maybe using htmldoc. But that's an aside. Ian ------------------------------------------------------- This sf.net email is sponsored by: Influence the future of Java(TM) technology. Join the Java Community Process(SM) (JCP(SM)) program now. http://ads.sourceforge.net/cgi-bin/redirect.pl?sunm0003en _______________________________________________ Webware-devel mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/webware-devel
