How to Generate PDF from Docbook 5.0

How to generate pdf from docbook 5.0

I see three options (available in Debian/Ubuntu) to generate pdf from docbook:

• jade, which provides the docbook2pdf command the asker used. jade is ancient and works with SGML, which predates XML and does not support Unicode; it also lacks support for docbook 5.

• the docbook-xsl stylesheets which go through XSL-FO. docbook-xsl is for docbook 4.5, docbook-xsl-ns is for docbook5. Use fop to go from XSL-FO to PDF. Pipeline: docbook5 —(xsl)—> xml.fo —(fop)—> pdf . Commands involved: xsltproc, fop.

• dblatex, which is primarily targeting docbook4.5 but has been updated for some of docbook5.

xmlto can drive the last two, although it currently defaults to docbook-xsl and not docbook-xsl-ns.

---

A quick Docbook5 user guide

Prerequisites

sudo aptitude install docbook5 docbook-xsl-ns xsltproc fop xmlto libxml2-utils xmlstarlet

Validation

xmlstarlet val --err --xsd /usr/share/xml/docbook/schema/xsd/5.0/docbook.xsd book.xml

PDF output

xsltproc /usr/share/xml/docbook/stylesheet/docbook-xsl-ns/fo/docbook.xsl book.xml > book.fo
fop -fo book.fo -pdf book.pdf

Generate PDF from docbook XML when building Java project using Gradle

Ok, so finally I found the solution. In order to generate a PDF, you have to provide the following files :

• The docbook file (.XML)
• An XSL stylesheet file (.XSL)
• The docbook.gradle file that you can grab from here: https://github.com/SpringSource/spring-build-gradle/blob/master/docbook.gradle
• The build.gradle file

You have to add after to build.gradle the line

apply from: "docbook.gradle"

after

apply plugin: "java"

Then, append to the end of build.gradle this:

docbookPdf {
    sourceFileName = "docbook.xml"
    stylesheet = file("doc/docbook-style.xsl")
    sourceDirectory = file( "doc" )
    docsDir = new File(project.getBuildDir(), "docs");
}

Here, we've put the docbook.xml and docbook-style.xsl in rootDirectory/doc, and we put the generated PDF in rootDirectory/docs (/pdf).

Here is an example of a docbook stylesheet that you can use: http://cl.ly/2n1p3o0r1L3Z1d2U4345

To generate the PDF, from the terminal, go to the directory where the file build.gradle is and execute

gradle docbookPdf

if you named the task 'docbookPdf'.

That's it. It should work on any platform.

Converting Docbook 5.0 (with partial includes) to PDF

There is no way to "provide the docbookxi.rng to the toolchain" that would help in this case. There isn't even a standard way to associate an XML document with a RELAX NG schema. The xmlns="http://docbook.org/ns/docbook" namespace declaration identifies the document as DocBook 5 (together with the version attribute), but it does not say anything about the location of the schema.

A line like this one,

<xi:include href="./TestDocument.included.xml" xpointer="Section2"/>

means: "include the portion of TestDocument.included.xml that is identified by the element that has an attribute of type ID with a value of Section2".

In DocBook 5, xml:id is used for unique identifiers. This attribute is recognized as being of type ID, and there is no need for a schema to determine its "ID-ness" (see http://www.w3.org/TR/xml-id/). So if you have anyid attributes in your DocBook 5 documents, change them to xml:id.

Howewer, you should also make sure that the XML parser supports xml:id. Xerces seems to be lacking here, so it might still not work for you (see https://issues.apache.org/jira/browse/XERCESJ-1113).

If there are problems, you could try to use the DocBook 5 DTD (yes, there is a DTD even though the normative schema is written in RELAX NG). That DTD declares xml:id to be of type ID.

Issue with DocBook to PDF using dblatex under Windows 7

After a lot of testing I found the issue is with the version of dblatex installed, or more specifically the version of dbtexmf that is installed with it. Installing version 0.3 of dblatex (instead of the latest, currently 0.3.4) solved the issue.

Hope that helps someone who has the same issue.

Cheers,

Will

Is it possible to include a docbook article into a book ?

The problem in your code snippet is that you include (XInclude) article within chapter - not within book itself. And this is disallowed by DocBook schema (article can't be within chapter)

I.e.:

• book < article (or set < article) are allowed;
• BUT this (as in your sample): book < chapter <article is NOT

You just didn't see the full picture because of xinclude statement.

So the workaround is (compare these two snippets):

Yours:

<book version="5.1" ...>
...
<title>xyz</title>

<chapter>
   <title>my xsd previously rendered by oxygen</title>
   <xi:include href="generated_schemata/my_xsd.xml"/>
</chapter>
</book>

The correct one:

<book version="5.1"...>
...
<title>xyz</title>

<xi:include href="generated_schemata/my_xsd.xml"/>

</book>

NOTE: you have different schema validation on book (5.1) and article (5.0)! Be aware about it!

Numbering of figures in DocBook

There is no parameter to switch on the wanted behaviour, but it can be done by customizing a template in common/labels.xsl (the number part of a title is called a "label" in DocBook-XSL).

You will need to create a customization layer and add the following to it:

<xsl:template match="db:figure" mode="label.markup">
  <xsl:choose>
    <xsl:when test="@label">
      <xsl:value-of select="@label"/>
    </xsl:when>
    <xsl:otherwise>
     <!-- Use simple sequential numbering within a book -->
     <xsl:number format="1" from="db:book" level="any"/> 
    </xsl:otherwise>
  </xsl:choose>
</xsl:template>

Validating Docbook 5.0, link/linkend

Maybe it’s a bug in the version of xmlstarlet you have installed? It works for me on Debian:

$ xmlstarlet val --err --xsd /usr/share/xml/docbook/schema/xsd/5.0/docbook.xsd -
<?xml version='1.0' encoding='utf-8'?>
<article xmlns='http://docbook.org/ns/docbook'
         xmlns:xlink='http://www.w3.org/1999/xlink' version='5.0'>
<section xml:id='H_0'>
<title>This is a title</title>
<para>
Blah <link linkend='H_0'>This is a link</link>blah blah blah.</para>
</section>
</article>
- - valid
    ^^^^^

Here’s my xmlstarlet version info:

$ xmlstarlet --version
1.6.1
compiled against libxml2 2.9.4, linked with 20904
compiled against libxslt 1.1.29, linked with 10129

---

Incidentally, though, the DocBook document in the question isn’t actually valid—because a DocBook article element must have either a title or info child:

$ cat > test.xml
<?xml version='1.0' encoding='utf-8'?>
<article xmlns='http://docbook.org/ns/docbook'
         xmlns:xlink='http://www.w3.org/1999/xlink' version='5.0'>
<section xml:id='H_0'>
<title>This is a title</title>
<para>
Blah <link linkend='H_0'>This is a link</link>blah blah blah.</para>
</section>
</article>

$ java -jar /usr/share/java/jing.jar \
    /usr/share/xml/docbook/schema/rng/5.0/docbook.rng test.xml
test.xml:3:23: error: element "section" not allowed yet; expected element "info",
"subtitle", "title" or "titleabbrev"

See http://tdg.docbook.org/tdg/5.0/article.html:

article — An article.

Synopsis

Sequence of:

• One of:

  • Sequence of:

    • Interleave of:

      • title
      • titleabbrev?
      • subtitle?

    • info? (db.titleforbidden.info)

  • info (db.titlereq.info)

The lack of a ? question mark after title and info there, combined with the One of means that one or the other of title or info is required.

I’m surprised the XSD schema doesn’t catch that. But I guess maybe it’s an indication that to make sure your DocBook documents actually are valid, you probably want to consider validating against the RelaxNG schema (/usr/share/xml/docbook/schema/rng/5.0/docbook.rng file) instead.

---

Related Topics