DOCBOOK-APPS: Summary 2 for"New to DocBook: XML or SGML, Clark or Open?"

["Prikryl,Petr" <PRIKRYLP at skil dot cz>]

(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 &gt;
> 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