OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Subject: Summary 2 for "New to DocBook: XML or SGML, Clark or Open?"

(was "New to DocBook: XML or SGML, Clark or Open?")

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).

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>
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

* 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,


  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

* 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"?>
     <?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;

  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:


(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, but I do not consider it a big

> 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

(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

That's all for now,


Petr Prikryl, SKIL, spol. s r.o., prikrylp@skil.cz

Odchozí zpráva neobsahuje viry.
Zkontrolováno antivirovým systémem AVG (http://www.grisoft.cz).
Verze: 6.0.237 / Virová báze: 115 - datum vydání: 7.3.2001

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Powered by eList eXpress LLC