Re: New to DocBook: XML or SGML, Clark or Open?

["M. Wroth" <mark at astrid dot upland dot ca dot us>]

As with many things, there's a strong element of personal preference in all 
of this -- the following are my opinions.  FWIW, I have much the same 
background in that I came to SGML/XML after much TeX experience.

At 12:59 PM 3/28/01 +0200, Prikryl,Petr wrote:

>I have no experience with it and with SGML/XML
>tools.  I have read some FAQs, HTML  and XML
>specifications, I know passively also the basics of SGML
>and basic principles of style sheet languages. I have read
>also the "DocBook: The Definitive Guide" by Norman Walsh
>and Leonard Muellner (not the Reference part yet).
>
>I am still very new to DocBook, and to SGML/XML tools.
>In the company, where I work as a programmer, I strugle for
>a solid way of writing a documentation (MS Word is simply
>not the way).  The time has come just now.

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.

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.

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?


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.


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

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

In your situation I'd use SGML, edited with emacs/PSGML, and processed for 
output with Jade (possibly into pdfjadetex, but more likely into RTF.  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.

Mark B. Wroth
<mark@astrid.upland.ca.us>


------------------------------------------------------------------
To unsubscribe from this elist send a message with the single word
"unsubscribe" in the body to: docbook-request@lists.oasis-open.org