This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
Summary of "New to DocBook: XML or SGML, Clark or Open?"
- To: DocBook mailing list <docbook at lists dot oasis-open dot org>
- Subject: Summary of "New to DocBook: XML or SGML, Clark or Open?"
- From: "Prikryl,Petr" <PRIKRYLP at skil dot cz>
- Date: Thu, 29 Mar 2001 13:24:03 +0200
(This is a summary of my question with the original title
"New to DocBook: XML or SGML, Clark or Open?")
Hallo DocBookers,
Firstly, thanks to all who replied. The answers
of the following persons are summarized (I am
not mentioning them later explicitly, but my thanks
goes to them implicitly, no particular order):
Laurent Pointal [laurent.pointal@lure.u-psud.fr]
dkoschuetzki@gmx.de [Dirk.Koschuetzki@bonn.shuttle.de]
M. Wroth [mark@astrid.upland.ca.us]
Jirka Kosek [jirka@kosek.cz]
Juan R. Migoya [promo804@hsoft.es]
Ramon Casellas [casellas@infres.enst.fr]
You answers really helped me to decide. Sequences
from my original message are prefixed
by > on the left. The answers (presented rather
anonymously) may be cut of the context. Feel free to
complain ;-) My occasional remarks are placed as
[inlines] or separate paragraphs in parenthesis (you will
understand, I am sure :)
----------------------------------------------------------------
> Briefly first, more details below in the text:
>
> - Should I be oriented towards SGML or XML when starting
> with DocBook as a total greenhorn?
* I tried XML. For several reasons I remained loyal to
SGML. SGML is more oriented to printed documentation
than XML, and after all, you work the same way.
* XML is future of DocBook, SGML is past.
* SGML has the advantage of being more flexible in both
markup (i.e. the ability to minimize or omit tags --
useful if you're working in a text editor, less so if
you're using a good editor. XML has better tool support
(especially at the freeware level).
Printed documentation tends to move one more toward
DSSSL processors for output -- at least as far as I can
see. If you use that tool set, SGML or XML is not an
issue. If you use an XSL based tool set, that, of
course would favor an XML solution.
* I have had a great deal understanding the DSSSL [which
means orientation to SGML] from Norm Walsh. My advice
would be that if you have time to spend learning, the
effort will be compensated. I say this when actually I
haven't had time enough to make my stylesheet
customizations as good as I would like, but I have
"real" results and I'm sure I will get at a stable
point.
* In your situation I'd use SGML [...]. But the choice
of XML/SGML at the front end is not likely to be a big
deal for you (now), and XML seems to be direction most
of the tool development is headed.
(I think that this needs further clarification. I have
found the article "XML/SGML: On the Web and Behind the Web"
at "http://www.sgmltech.com/papers/aatphv1099.htm" which
seems to answer some of the questions. Reading that, I
personally incline towards SGML, while other sources say
that XML is the way.
What should be clarified is whether DocBook's future is
really XML or whether both XML/SGML branches are going to
be supported.)
----------------------------------------------------------------
> - Do I need a unicode capable editor for XML?
* You do not need unicode editor. From your domain, I
suppouse that you want write docs in Czech language
[good guess ;-)]. In this case, you can start DocBook
XML document with line
<?xml version="1.0" encoding="windows-1250"?>
or
<?xml version="1.0" encoding="iso-8859-2"?>
and then use appropriate single-byte encoding.
* [edited...] there is a problem when HTML is generated
from XML. The character encoding is not set inside the
generated HTML [...] Jade [...] SP_ENCODING=xml.
----------------------------------------------------------------
> - Notice: I am using Windows NT (I have no choice).
* Read the tutorial "SGML for Windows NT" on how to set
up a free SGML editing and publishing system for
Windows NT by Markus Hoenicka:
http://ourworld.compuserve.com/homepages/hoenicka_markus/ntsgml.html
(I did not follow exactly everything from inside, but I
found the tutorial really helpful.)
----------------------------------------------------------------
> Question on Clark vs. Open
> ==========================
>
> This question is not the basic one for me. I only would like to
> know, whether I should prefer Clark's SP and Jade or
> OpenSP and OpenJade (and why). Are these projects
> developed as competitors? Did Clark ever expressed
> his opinion on OpenSP and OpenJade?
* Jade works correctly.
* I switched to OpenJade some time ago, but I went back
to Jade because there was some problems with the
stylesheets I hadn't found in Jade. So now I work with
Jade. Some times in this list I have read "use Jade" in
order to avoid a specific problem, but I'm unable to
tell you if in this moment OpenJade is the right choice
or not.
* I use jade (tried openJade but get into problems - jade
has problems too at this time, which has been corrected
since, but i haven't re-tried openJade) and DSSSL. I
have tried to use the modern XSLT tools, but failed to
make one work correctly in a short time (maybe with
investigating more...).
* OpenJADE is the open source continuation of JADE,
started with James' blessing when he became too
involved in other projects to continue to update JADE.
There is additional functionality in OpenJade, which
may or may not be important to you (*I* haven't had any
particular need for it, processing DocBook and some
homegrown scripts, but YMMMV). On the other hand, I
have found the error messages from OpenJADE to be less
than informative... which makes a difference, especially
when you're trying to learn.
(This remains open for me, but I do not consider it a big
problem.)
----------------------------------------------------------------
> Question on JadeTeX
> ===================
>
> I am thinking about using (La)TeX for generating printable
> version of the documentation and also the PostScript
> and PDF versions. Is the TeX back-end the usual way
> for doing that?
* It is usual way, but not the only. Another way to
produce printed version is to use XSL stylesheets and
some FO processor (e.g. PassiveTeX). This tool-chain is
improving very rapidly.
* Please check http://www.infres.enst.fr/~casellas/docbook.html
and see if it fits your needs. [The alternative
conversion tool to LaTeX, probably better for
mathematics.]
* JadeTeX have some serious problems on longer documents.
For larger documents I personally generate RTF file by
Jade and then use Word and Distiller to get PDF.
* The TeX backend attempts to use a TeX macro package to
render the output of JADE, resulting in good quality
typesetting for the printed documentation. I like that
approach in theory, but haven't had much luck with it
in practice -- almost everything I print is done with
the RTF backend. (The TeX macros are built in LaTeX2e,
BTW -- but unless you really want to monkey around with
them, you edit in the SGML/XML and treat TeX as a black
box. Your previous LaTeX experience will probably help
in getting everything going, though.)
(Notice: there is LaTeX3 project oriented towards SGML/DSSSL
http://www.latex-project.org/guides/ltx3info/ltx3info.html)
(Can anybody else confirm such problems with JadeTeX? I
want to use it -- what should I expect when compared with
usual LaTeX styles?)
================================================================
Notice on an editor: I do use (also for other purposes)
the JED editor (http://space.mit.edu/~davis/jed/")
which emulates emacs. It does not use lisp as internal
language but it also has support for LaTeX, HTML, and
SGML for DocBook (some bugs as the DocBook support is
very young, but promissing ;-).
----------------------------------------------------------------
Notice on a project C++ source documentation: As I have
noticed also some remark about literate programming...
"I'll make the side plug that you might consider
using something like Nuweb / LaTex in a literate
programming environment if you're documenting code.
Unfortunately, I know of no stable SGML/XML literate
programming tools, although they should in principle
be straightforward."
I should mention that I do use Doxygen
(http://www.doxygen.org/) which produces HTML, LaTeX,
RTF and other formats (I think that it can be
considered a tool for literate programming). It uses
Graphviz
(http://www.research.att.com/sw/tools/graphviz/) for
generating inheritance diagrams, etc. The results are
appreciated well by the users.
What may be interesting for SGML/XML supporters is that
there is some interest in using XML (SGML?) in the
Doxygen comunity. I think that the Doxygen developers
would appreciate more help from SGML/XML experts (you
should know that you will not be paid by money for that
;-)
----------------------------------------------------------------
Thanks to all for now,
Petr
--
Petr Prikryl, SKIL, spol. s r.o., prikrylp@skil.cz
------------------------------------------------------------------
To unsubscribe from this elist send a message with the single word
"unsubscribe" in the body to: docbook-request@lists.oasis-open.org