Search:  
Gentoo Wiki

HOWTO_Docbook

Contents

HOWTO Docbook

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:

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

Reported Failures

Retrieved from "http://www.gentoo-wiki.info/HOWTO_Docbook"

Last modified: Fri, 05 Sep 2008 22:46:00 +0000 Hits: 1,097