From: <ir...@ms...> - 2001-11-05 19:39:05
|
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, ir...@ms... (if mail problems: ms...@ji...) http://iron.cx/ English * Esperanto * Russkiy * Deutsch * Espan~ol |