This is the mail archive of the
docbook-apps@lists.oasis-open.org
mailing list .
Summary 2 for"New to DocBook: XML or SGML, Clark or Open?"
- To: DocBook-apps mailing list <docbook-apps at lists dot oasis-open dot org>
- Subject: DOCBOOK-APPS: Summary 2 for"New to DocBook: XML or SGML, Clark or Open?"
- From: "Prikryl,Petr" <PRIKRYLP at skil dot cz>
- Date: Wed, 11 Apr 2001 17:27:17 +0200
(was "New to DocBook: XML or SGML, Clark or Open?" in DOCBOOK list)
Sorry for bothering you with greenhorn questions, but after
subscribing to DOCBOOK-APPS I think that the most experienced
DocBookers read DOCBOOK-APPS more frequently than DOCBOOK.
As I would like to absorb the SGML/XML/DocBook spirit more
quickly, I dare to repost the summary below also in this mailing list.
If you have time and you are willing to share your experience, please do it.
Thanks
Petr
============================================
> Hallo DocBookers,
>
> This is the second version of the summary of answers to my
> original question (see the top of the message).
>
> Thanks to all who replied. The answers of the persons are
> included in the next list (sorted alphabetically -- if I
> did not forget to do it).
>
> From the second version of the summary, I have included
> also some information from other threads. The authors were
> added to the list. I tried to follow the problems, not the
> threads. I am planning to accumulate even more answers and
> then I will try to reduce them to the core. If you know
> sources with better answers, please, let me know.
>
>
> Adam Di Carlo <adam@onshore.com>
> David Johnson <david@usermode.org>
> Dave Brooks, BCS Systems <dave@bcs.co.nz>
> Jirka Kosek <jirka@kosek.cz>
> Juan R. Migoya <promo804@hsoft.es>
> Laurent Pointal <laurent.pointal@lure.u-psud.fr>
> M. Wroth <mark@astrid.upland.ca.us>
> Norman Walsh <ndw@nwalsh.com>
> Ramon Casellas <casellas@infres.enst.fr>
> Robert Withrow <bwithrow@nortelnetworks.com>
> chrisb@kippona.com
> dkoschuetzki@gmx.de <Dirk.Koschuetzki@bonn.shuttle.de>
>
>
> 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 :)
>
> I consider Norman Walsh notices to be exceptional in the
> sense that some people (including me) -- when undecided --
> want to accept his advices. For that purpose, I have
> marked his notices using inline [NW].
>
> ----------------------------------------------------------------
> > Briefly first, more details below in the text:
> >
> > - Should I be oriented towards SGML or XML when starting
> > with DocBook as a total greenhorn?
> >
> > [from other thread] Are there any benefits to XML over
> > SGML when it comes to DocBook? Is it worth my time to
> > learn Java and fix those XSLT engines, or is it better
> > spent learning scheme and DSSSL?
>
> * 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.
>
> [later] When I said XML is future, its more about tools
> and usage in the world (look at the quick developement
> of XML use in the Internet land, relatively to the slow
> growth of SGML due to its "lourdeur" (cumbersomeness)).
>
> * 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've seen some pretty outrageous typography from the
> current set of XML DocBook tools (like major widows and
> orphans), but I'm guessing much of that can be explained
> by their relative immaturity.
>
> [NW...] that depends on your formatter. DocBook is about
> content, not presentation.
>
> * SGML+DocBook(DSSSL)+jade+[jadetex,pdfjadetex]
> +Makefile+emacs(psgml) is a great, multiplatform
> toolchain which you can start using this afternoon.
>
> * [in reply to the upper the author writes] Surely,
>
> XML+DocBook(DSSSL)+jade+[jadetex,pdfjadetex]
> +Makefile+emacs(psgml)
>
> is also great multiplatform toolchain which also runs
> "out-of-the-box" [...]. My point is that Docbook/XML can be
> used for markup without having to go down the XLST path,
> while still leaving XLST as a future option.
>
> * Norman Walsh says in
>
> Date: Fri, 06 Apr 2001 09:51:00 -0400
> From: Norman Walsh <ndw@nwalsh.com>
> Subject: Re: DOCBOOK: Okay, why?
> In-reply-to: <01040519241304.00175@weathertop>
> To: docbook@lists.oasis-open.org
> Message-id: <87d7aqxhkr.fsf@nwalsh.com>
>
> [...] XML is the future. And reports of specific problems,
> especially with the DocBook XSL stylesheets are always
> appreciated.
>
> * XML may be the future, but I'm living in the present :-)
>
> (I think the topic 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 would personally incline towards SGML. The question is
> whether the conclusions make sense for DocBook.
>
> What should also be clarified is whether the DocBook's
> SGML branch is planned to be obsoleted one day or not.)
>
>
> ----------------------------------------------------------------
> > - 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 the 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.
>
> [from reply to the upper notice] This is problem for
> both SGML and XML sources. You can add following code
> into your DSSSL customization layer and proper <meta>
> tag will be included in generated HTML.
>
> (define %html-header-tags%
> '(("META" ("HTTP-EQUIV" "Content-Type") ("CONTENT" "text/html;
> charset=windows-1250"))))
>
> If you use XSL stylesheets (this implies usage of XML
> DocBook), this meta tag is inserted automatically by
> XSLT processor.
>
> ----------------------------------------------------------------
> > - 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. Is there a similar
> document for starting with XML?)
>
> ----------------------------------------------------------------
> > 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.
>
> [from reply] Running under Linux, OpenJade 1.3 / OpenSP
> 1.34 gives the correct error messages (ie.the same as
> Jade), which suggests that the problem is with the
> Windows build of OpenJade.
>
> (This remains open for me.)
>
> ----------------------------------------------------------------
> > 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 -- not tested by myself.]
>
> * 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.)
>
> * [NW] For fine typography, I'd go with PassiveTeX
> (XSL) or JadeTeX (DSSSL) and let TeX do the hard work.
>
>
>
> (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-like programming with
> some differences. It uses more code-centered approach
> where the text is added to the programming language
> comments.) 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 for your time,
>
> 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-apps-request@lists.oasis-open.org