headers
Robert Krüger | 1 Sep 2002 13:40
Picon
Favicon

docbook vs latex


Hi,

I'm currently in the process of deciding which too to use for writing our 
software documentation and have been playing around with docbook for a while. 
The main goal is to have one source of text that is used to generate both 
printable and online documentation. I used to work with latex at university 
but must admit, I haven't touched it in a few years. So far comparing the two 
lead to the following impression.

- latex is by far more comprehensive and better documented (of course, it's 
been around much longer)
- docbook is simpler and therefore easier to use
- docbook-xsl is a very flexible mechanism to generate and customize 
html-output whereas latex2html doesn't seem to be maintained very well
- docbook has some strange concepts (e.g. xrefs to a section resolving to the 
"Sexction x.y" instead of just the number, making it unflexible for no real 
benefit)  
- working with large documents appears to require more thought and 
organization with docbook than with latex

At the moment I would probably go for latex if I had a good translator to HTML 
but on the other hand I feel I still know to little about docbook and might 
be missing something. 

I suppose many people have been in my situation and made a decision. can 
anyone share experience?

thanks in advance
(Continue reading)

Permalink | Reply | 22 comments |
headers
Robert Krüger | 1 Sep 2002 13:52
Picon
Favicon

newbie: partitioning docbook documents


Hi,

could someone point me to a tutorial or the part in the documentation that 
explains how to partition a document into many files? At the moment I would 
like to do two things:

- put each section of an article into a separate file
- and put code examples that I use as programlistings in a separate file

do I have to declare external entities for that? I have played around with 
that but ran into problems (CDATA section was not parsed when in a separate 
file). could anyone give me a working example for the two things I describe 
above.

thanks in advance,

robert
Permalink | Reply | 6 comments |
headers
Henrik Motakef | 1 Sep 2002 14:29
Picon

Re: newbie: partitioning docbook documents

Robert Krüger <krueger <at> signal7.de> writes:

> could someone point me to a tutorial or the part in the documentation that 
> explains how to partition a document into many files? At the moment I would 
> like to do two things:
> 
> - put each section of an article into a separate file
> - and put code examples that I use as programlistings in a separate file

External entities are not easily usable with non-XML data like
programlistings. You might want to look into XInclude, a W3C spec for
such things.

You will need a special XInclude processor for this, however -
inclusions are not processed automagically by the parser, as with
external entities. IIRC, both libxslt (and its command-line processor
xsltproc) and 4xslt from the Python 4Suite package can resolve
XIncludes before XSLT-processing.

Another possible drawback: I think that you can only include complete
XML documents, not "well-balanced" fragments, i.e. they have to have
one single root element.

> could anyone give me a working example for the two things I describe 
> above.

--- book.xml:

<?xml version="1.0"?>
<book xmlns:xi="http://www.w3.org/2001/XInclude">
(Continue reading)

Permalink | Reply | 2 comments |
headers
Robert Krüger | 1 Sep 2002 14:37
Picon
Favicon

Re: newbie: partitioning docbook documents


thanks a lot. that is exactly what I was looking for. I use ant's style task 
with jdk1.4. You don't happen to know how I can hook an XInclude processior 
into that combo? 

thanks again,

robert

On Sunday 01 September 2002 14:29, Henrik Motakef wrote:
> Robert Krüger <krueger <at> signal7.de> writes:
> > could someone point me to a tutorial or the part in the documentation
> > that explains how to partition a document into many files? At the moment
> > I would like to do two things:
> >
> > - put each section of an article into a separate file
> > - and put code examples that I use as programlistings in a separate file
>
> External entities are not easily usable with non-XML data like
> programlistings. You might want to look into XInclude, a W3C spec for
> such things.
>
> You will need a special XInclude processor for this, however -
> inclusions are not processed automagically by the parser, as with
> external entities. IIRC, both libxslt (and its command-line processor
> xsltproc) and 4xslt from the Python 4Suite package can resolve
> XIncludes before XSLT-processing.
>
> Another possible drawback: I think that you can only include complete
> XML documents, not "well-balanced" fragments, i.e. they have to have
(Continue reading)

Permalink | Reply | 1 comment |
headers
Norman Walsh | 1 Sep 2002 16:39
Favicon
Gravatar

Re: docbook vs latex

/ Robert Krüger <krueger <at> signal7.de> was heard to say:
| - latex is by far more comprehensive and better documented (of course, it's 
| been around much longer)

Perhaps. Have you read http://docbook.org/tdg/en/html/?

| - docbook is simpler and therefore easier to use
| - docbook-xsl is a very flexible mechanism to generate and customize 
| html-output whereas latex2html doesn't seem to be maintained very well
| - docbook has some strange concepts (e.g. xrefs to a section resolving to the 
| "Sexction x.y" instead of just the number, making it unflexible for no real 
| benefit)  

Just as there's no single LaTeX document class that would satisfy all
users, there's no single set of stylesheet parameters that would
satisfy all users. You can certainly make the section references
resolve to just "x.y" if you wish. I'd argue that it's not
'unflexible' at all, on the contrary, it's very flexible. But I'm
baised.

| - working with large documents appears to require more thought and 
| organization with docbook than with latex

There are a few XML "limitations" to consider, otherwise, I'd say that
the amount of thought required is roughly equivalent.

                                        Be seeing you,
                                          norm

--

--
(Continue reading)

Permalink | Reply | 4 comments |
headers
Norman Walsh | 1 Sep 2002 16:43
Favicon
Gravatar

Re: newbie: partitioning docbook documents

/ Robert Krüger <krueger <at> signal7.de> was heard to say:
| could someone point me to a tutorial or the part in the documentation that 
| explains how to partition a document into many files? At the moment I would 
| like to do two things:
|
| - put each section of an article into a separate file

You can use external entities for that.

<!DOCTYPE book PUBLIC "..." "..." [
<!ENTITY chap1 SYSTEM "chap1.xml">
<!ENTITY chap1s1 SYSTEM "chap1s1.xml">
<!-- etc -->
]>
<book>
&chap1;
</book>

Then in 'chap1.xml', you can say:

<chapter>
<title>...</title>
&chap1s1;
</chapter>

etc. Note that you must not put a !DOCTYPE declaration in the chapter.
This means you have to make a little driver file if you want to
process the chapter separately. Or you can use the rootid parameter of
the stylesheets.
(Continue reading)

Permalink | Reply | 2 comments |
headers
John R. Daily | 1 Sep 2002 17:37

Re: docbook vs latex

My employer, Progeny Linux Systems, faced this issue a couple of
years ago, and settled on DocBook.  We knew LaTeX, didn't know
DocBook, but we've been very happy with our decision.

> - latex is by far more comprehensive and better documented (of course, it's 
> been around much longer)

I've found that the web-based documentation for DocBook is
superior to that for LaTeX.  Despite years of use, I can't do
much in LaTeX without a book or two around, because I've never
found a web site that covers LaTeX to my satisfaction, whereas
DocBook is comprehensively covered by the online version of "The
Definitive Guide".

> - docbook is simpler and therefore easier to use

Easier to write, not necessarily easier to use.

* Setting up a build system for translating DocBook to other
  output formats requires either quite a bit of money for
  commercial software, or quite a bit of time for open source
  solutions.  Perhaps the time factor is true for commercial
  software as true.

* The firm structure of XML should make it easier to comprehend
  than the rather erratic syntax of LaTeX ("fragile" commands?).

> - docbook-xsl is a very flexible mechanism to generate and customize 
> html-output whereas latex2html doesn't seem to be maintained very well
(Continue reading)

Permalink | Reply | 16 comments |
headers
Robert Krüger | 1 Sep 2002 17:42
Picon
Favicon

Re: Re: docbook vs latex

On Sunday 01 September 2002 16:39, Norman Walsh wrote:
> / Robert Krüger <krueger <at> signal7.de> was heard to say:
> | - latex is by far more comprehensive and better documented (of course,
> | it's been around much longer)
>
> Perhaps. Have you read http://docbook.org/tdg/en/html/?

yes but for many problems e.g. for referencing figures (or sections etc.) by 
their number I did't find an answer and the browsed through the element 
reference which is somewhat hard to digest. of course this is very subjective 
and I compared it to my first latex steps where a simple introductory 
tutorial answered all those questions by example.  I just think it would help 
to have a small but complete docbook document with a few sections cross 
references,  bibliography and table of contents some programlistings and 
hyperlinks etc. (i.e. the common stuff 90% of the people need, when they 
write a paper using docbook) where this is explained by example but it is 
very possible it exists and I just missed that.  

>
> | - docbook is simpler and therefore easier to use
> | - docbook-xsl is a very flexible mechanism to generate and customize
> | html-output whereas latex2html doesn't seem to be maintained very well
> | - docbook has some strange concepts (e.g. xrefs to a section resolving to
> | the "Sexction x.y" instead of just the number, making it unflexible for
> | no real benefit)
>
> Just as there's no single LaTeX document class that would satisfy all
> users, there's no single set of stylesheet parameters that would
> satisfy all users. You can certainly make the section references
> resolve to just "x.y" if you wish. I'd argue that it's not
(Continue reading)

Permalink | Reply | 3 comments |
headers
Robert Krüger | 1 Sep 2002 17:42
Picon
Favicon

Re: newbie: partitioning docbook documents

>
> That's easy, just drop them in a separate file and point to them.
>
> <programlisting><textobject>
> <textdata fileref="pathtoprogramlisting"/>
> </textobject>
> </programlisting>

that doesn't seem to be implemented by docbook-xsl. I get a 

 file:///usr/local/docbook/xsl/html/docbook.xsl; Line 75; Column -1; No 
template matches textdata.

but maybe I need to update. I'll check that.

>
> | do I have to declare external entities for that? I have played around
> | with that but ran into problems (CDATA section was not parsed when in a
> | separate file). could anyone give me a working example for the two things
> | I describe above.
>
> Not parsed? I'm not sure what you mean by that.

sorry, my fault, that's hard to understand.  I got a parser error but I'll 
check that again as it's most likely a problem with the parser and not 
particular to docbook. I must make sure I didn't screw up before I bother you 
with that again. 

>
>                                         Be seeing you,
(Continue reading)

Permalink | Reply | 1 comment |
headers
Robert Krüger | 1 Sep 2002 17:59
Picon
Favicon

Re: docbook vs latex

>
> Easier to write, not necessarily easier to use.
>
> * Setting up a build system for translating DocBook to other
>   output formats requires either quite a bit of money for
>   commercial software, or quite a bit of time for open source
>   solutions.  Perhaps the time factor is true for commercial
>   software as true.

I got the impression from browsing mailing list archives. I haven't dared 
trying anything but using the ant style task with docbook-xsl because the 
chain of tools to use and the mails in the mailinglist were a little 
terrifying but we will probably try that in the not so distant future to make 
a decision. 

>
> * The firm structure of XML should make it easier to comprehend
>   than the rather erratic syntax of LaTeX ("fragile" commands?).

agree 100%

>
> > - docbook-xsl is a very flexible mechanism to generate and customize
> > html-output whereas latex2html doesn't seem to be maintained very well
>
> XSL is indeed great.  Bewarned, however, that printed output is
> problematic.

yes, currently I'm happy with the things I can do as far as the HTML output is 
concerned as I'm familiar with xslt. but now I'm faced with the printing
(Continue reading)

Permalink | Reply | 0 comments |

Gmane