[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: DOCBOOK-APPS: Summary 2 for"New to DocBook: XML or SGML, Clark or Open?"
(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 <firstname.lastname@example.org> > David Johnson <email@example.com> > Dave Brooks, BCS Systems <firstname.lastname@example.org> > Jirka Kosek <email@example.com> > Juan R. Migoya <firstname.lastname@example.org> > Laurent Pointal <email@example.com> > M. Wroth <firstname.lastname@example.org> > Norman Walsh <email@example.com> > Ramon Casellas <firstname.lastname@example.org> > Robert Withrow <email@example.com> > firstname.lastname@example.org > email@example.com <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 <firstname.lastname@example.org> > Subject: Re: DOCBOOK: Okay, why? > In-reply-to: <01040519241304.00175@weathertop> > To: email@example.com > Message-id: <firstname.lastname@example.org> > > [...] 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., email@example.com >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC