The critical question is what do you want to accomplish ? If all you are after is a plain ASCII text copy of the documentation, then yes plain text is the easiest to maintain. I think pretty much anything can be maintained at a distance. I am not sure how one is superior to the other there. But the moment you start talking about wanting it in multiple formats you better seriously look at something else. There are other choices besides SGML/XML/DOCBook, and a religious war could ensue over trying to compare them. The easiest to use is always the one you already know. But assuming that you do not have allot of knowledge invested in one, then I would suggest DocBook. It is SGML/XML compliant, there are lots of tools, it can be easily translated to anything, And from what I can see it is getting very heavily used.
But if somebody will actually maintain the documentation, I would not care what they used. -----Original Message----- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED]] On Behalf Of Dennis K Sent: Saturday, November 16, 2002 6:25 PM To: 'Oleksandr Firsov' Cc: [EMAIL PROTECTED] Subject: RE: Cyrus IMAPd 2.1.10 Released Correct me if I'm wrong, SGML and XML were interrelated, closely, Plus, XSLT transformations are a pain in themselves altogether, to the point where plain text wins in terms of maintenance and production. I believe a set of plaintext documentation can be maintained with RCS, CVS or SCCS without problems by a distanced dev team, while XSLT will require proper usage by the author manuals etc... LaTex (Tex) are not stone age, XML has been around for a while as well, just not used, but around. (All this IMHO of course) - DK -----Original Message----- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED]] On Behalf Of Oleksandr Firsov Sent: Friday, November 15, 2002 9:56 AM To: Rob Siemborski; Andrew McNamara Cc: [EMAIL PROTECTED] Subject: Re: Cyrus IMAPd 2.1.10 Released Guys/girls What do You talking about? doc tool, LaTex, etc... That is stone age terms. I am not familiar with product discussed above, but for structured data exist de-facto standard which used for such purposes. This is XML( kind of SGML ) and some technology around. In few words, for such kind of docs you need DTD (structure definition file ) , XML -formatted document and XSL transformation files. If noone familiar with DTD, there are tools to create it from sample XML. Then there are bunch of XML editors, which can use DTD for making edition much easy. Depend of target format (text, HTML, PDF, DOC, etc), should be created XSL transformations. For HTML and text, it is better to do it manually. But you can use automated tools as well. We are using this technology for web site and applications configuration. I can tell more... SunS ----- Original Message ----- From: "Andrew McNamara" <[EMAIL PROTECTED]> To: "Rob Siemborski" <[EMAIL PROTECTED]> Cc: <[EMAIL PROTECTED]> Sent: Thursday, November 14, 2002 9:44 PM Subject: Re: Cyrus IMAPd 2.1.10 Released > >I feel that moving back to only plaintext is a step backwards. I don't > >know much about SGML myself, so I'm not sure I'd want to be stuck > >maintaining that, but it sounds interesting enough (and it would be nice > >to have general tools for keeping the documentation formatted, instead of > >worrying when htmlstrip would next break). > > You could do worse than look at the Python documentation. The production > doco is current LaTeX with a bunch of custom macros. HTML, PDF, etc are > generated off the master LaTex markup. There is a background project to > use SGML (I think), but it's not there yet. > > Our company (not me personally) looked at doco tools a while back and came > to the conclusion that LaTeX was still the best choice out of a bad lot - > SGML was the next closest, although the tools were still rather imature. > > -- > Andrew McNamara, Senior Developer, Object Craft > http://www.object-craft.com.au/ > >