"Clark C . Evans" <[EMAIL PROTECTED]> wrote: >> >> 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.
Compared to TeX, XML-FO is not, in my opinion or as far as I have seen with the Apache implementation, ready for production use. [EMAIL PROTECTED] (Mike Orr) wrote: > >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. For documentation about software systems, HTML seems adequate, although there are certain ambiguities about the way one might write certain things which may make conversion or processing of documents more difficult subsequently. For example, I tend to use "code" elements to annotate variable names and filenames, although someone could choose another visually equivalent way of writing them. Also, it takes discipline to write good enough HTML for subsequent processing - one can be inconsistent and forget to follow one's own conventions. Despite HTML's lack of expressive capabilities in the set of elements it offers, it could be possible for processors to use style information to learn more about any given document. >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). And for many things which are likely to be more common in software documentation, HTML and its relatives offer much better syntax and ready-made solutions than LaTeX. Take tables as an example: last time I did any serious LaTeX, working with tables was a real inconvenience because there are many classes which appear to do something interesting, but none of them seem to do something as desirable as HTML's implementation. Interestingly, I put a fair amount of work in with LaTeX to produce the paper version of my CV, but I then found that potential employers were happy to print the HTML version and put that on file... Paul -- Get your firstname@lastname email for FREE at http://Nameplanet.com/?su _______________________________________________ Webware-discuss mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/webware-discuss
