Cyrus IMAPd 2.1.10 Released

[David H. Lynch Jr.]

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: owner-info-cyrus at lists.andrew.cmu.edu
[mailto:owner-info-cyrus at lists.andrew.cmu.edu] On Behalf Of Dennis K
Sent: Saturday, November 16, 2002 6:25 PM
To: 'Oleksandr Firsov'
Cc: info-cyrus at lists.andrew.cmu.edu
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: owner-info-cyrus at lists.andrew.cmu.edu
[mailto:owner-info-cyrus at lists.andrew.cmu.edu] On Behalf Of Oleksandr
Firsov
Sent: Friday, November 15, 2002 9:56 AM
To: Rob Siemborski; Andrew McNamara
Cc: info-cyrus at lists.andrew.cmu.edu
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" <andrewm at object-craft.com.au>
To: "Rob Siemborski" <rjs3 at andrew.cmu.edu>
Cc: <info-cyrus at lists.andrew.cmu.edu>
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/
>
>