You jumped lists from cheetahtemplate-discuss to webware-discuss.
For webware-discuss readers, the question is whether to change the
Webware documentation source format from HTML to Structured Text, LaTeX,
DocBook et all, etc. A flexible format such as LaTeX or an XML/SGML
format (DocBook, LinuxDoc, etc) would allow easy processing by tools for
those languages, conversion to HTML or multiple other formats, etc.
On Mon, Nov 05, 2001 at 02:38:23PM -0500, Clark C . Evans wrote:
> On Mon, Nov 05, 2001 at 09:27:24AM -0800, Mike Orr wrote:
> | Chuck Esterbrook wrote:
> | > I ask because it's an interesting question for any project. Webware
> | > currently uses plain HTML, but I would consider going to a Wiki syntax
> | > and either using one of the existing Python modules for this
> | > (StructuredText?) or rolling my own.
> | Rolling your own would be reinventing the wheel. Using one of the
> | existing ones -- maybe, if it does everything you want, including robust
> | formatting and convertable to HTML/PS/PDF. (*I* don't care about PDF,
> | but I know you do. :)
> I've found that plain ole HTML (sticking to structural
> markup only) is usually good enough for me. To make it
> look pretty, one can use CSS. And if you really get
> fancy, you can use XSLT-FO to convert into PDF. Although
> TeX is very good... most developers don't know it and
> thus can't easily contribute to documentation.
HTML is fine to get something out the door quickly, but it's not as
suitable for a long-term maintenance and storage. The tags are not
quite precise enough for word-processor-like formatting, but not general
enough to make the logical units individually extractable, or for
putting in hints HTML doesn't need but another format might.
Yes, LaTeX's syntax is a major problem. I have to feel my way around it
for the Cheetah documentation. I refuse to buy a TeX reference because
it feels like throwing money away on a format that is obsolete (except
for documents with extensive mathematical formulas).
-Mike (Iron) Orr, iron@... (if mail problems: mso@...)
http://iron.cx/ English * Esperanto * Russkiy * Deutsch * Espan~ol