HOWTO_Docbook

HOWTO Docbook

• Revision History
  • 16 September 2006 - rjf

Why Docbook?

Docbook allows you to edit a single source of information without typesetting. Docbook can output into various different file formats and typesettings that can include automatic table of contents generation and section numbering:

• Docbook was/is the major standard of all linux documentation stored on the Linux Documentation Project.
• website documentation (single html, multi-html pages)
  • Relatively straightforward and reliable success through xsltproc
• printed documentation (rtf, pdf)
  • confusion and unreliable success-rate through fop, jade, or other means

A Docbook File Example

 <?xml version="1.0"?>
 
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" 
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
 
 <!ENTITY info SYSTEM "info.txt">
 <!ENTITY report SYSTEM "report.txt">
 <!ENTITY glossary SYSTEM "glossary.txt">
 <!ENTITY bibliography SYSTEM "bibliography.txt">
 <!ENTITY appendixUserManual SYSTEM "appendixUserManual.txt">
 <!ENTITY appendixImplementationManual SYSTEM "appendixImplementationManual.txt">
 <!ENTITY appendixImplementationSource SYSTEM "appendixImplementationSource.txt">
 <!ENTITY appendixExperimentalResults SYSTEM "appendixExperimentalResults.txt">
 
 ]>
 
 <book>
 <bookinfo>
 &info;
 </bookinfo>
 
 &report;
 
 &glossary;
 &bibliography;
 
 &appendixUserManual;
 &appendixImplementationManual;
 &appendixImplementationSource;
 &appendixExperimentalResults;
 
 </book>

An Example Working Toolchain

 if xmllint --valid --noout main.xml
 then echo Docbook XML DTD validation succeeded.
 
 # Create HTML file
 xsltproc /usr/share/sgml/docbook/xsl-stylesheets-1.70.1/xhtml/docbook.xsl main.xml >main.html
 
 # Create PDF file
 fop -xsl /usr/share/sgml/docbook/xsl-stylesheets-1.70.1/fo/docbook.xsl \
     -xml main.xml \
     -pdf /home/rko/public_html/main.pdf
 
 else echo Validation failed.  No update possible.
 fi

Success or Failure on Gentoo

A lot of people have reported lots of problems using Docbook on Gentoo. I have docbook working fine on one Gentoo machine, but I cannot get another Gentoo machine to function properly. FOP uses Java, which could be part of the problem. I am posting this to encourage discussion of Gentoo users who try to use Docbook.

Reported Success

• Success with the above script --203.36.44.15 09:16, 12 September 2006 (UTC)

Reported Failures

• Failure with fop to create pdf documents. Numerous errors. --203.36.44.15 09:16, 12 September 2006 (UTC)
  • /usr/bin/fop book.fo -pdf book.pdf
    • Exception in thread "main" java.lang.NoClassDefFoundError?: org/apache/avalon/framework/logger/Logger at org.apache.fop.apps.Fop.main(Fop.java:60)
    • See: http://bugs.gentoo.org/show_bug.cgi?id=146960
  • [Error] autoidx.xsl:31:31: Element type "xsl:stylesheet" must be declared. (Tons of these errors, then fop dies.)