About DocBook

DocBook is an XML formalism for describing (technical) complex documents intended for publication.

This description is independent of the publication medium : web page (HTML), printed matter (PDF), epub or other.

Once a publication medium is chosen, the XML-DocBook document will be transformed into the corresponding XML format via an XSLT stylesheet.

A set of standard stylesheets is available from a SourceForge project called DocBook XSL.

Download (zipped directory).

Inside of the docbook-xsl-ns-1.78.1 directory, there is a subdirectory for each publication medium, and in each of these subdiretories the master stylesheet is docbook.xsl.

Example : docbook-xsl-ns-1.78.1/xhtml/docbook.xsl.

Explanations by DocBook main designer : The Design of the DocBook XSL Stylesheets.

It is up to the user to customize the stylesheet that fits the publishing medium of his choice in order to suit his specific needs.

Reference documentation.

Users' guide.

The main tool for customizing a DocBook-XSL stylesheet (call it stls.xsl) is

Example for PDF output (doc2fo.xsl)

<?xml version='1.0'?> 
<!DOCTYPE stylesheet [
    <!ENTITY dbdir "/path-to-reach.../docbook-xsl-ns-1.78.1">
]>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"  
                version="1.0"
                xmlns:d="http://docbook.org/ns/docbook"
                xmlns:fo="http://www.w3.org/1999/XSL/Format">

  <xsl:import href= "&dbdir;/fo/docbook.xsl"/> 

  <xsl:output method="xml" indent="yes"/>
  
<!-- setting paper size -->
  <xsl:param name="paper.type" select="'A4'"/>

<!-- titles with the same typeface as the text (default is 'sans-serif') -->
  <xsl:param name="title.font.family" select="'serif'"/>
  
<!-- ensuring a page break before first-level sections -->
  <xsl:attribute-set name="section.level1.properties">
  	<xsl:attribute name="break-before">page</xsl:attribute>
  </xsl:attribute-set>
  
<!-- special rule for quotations -->
  <xsl:template match="d:quote">
  	<fo:block font-family="sans-serif">
  		<xsl:apply-imports />
  	</fo:block>
  </xsl:template>

</xsl:stylesheet>
    		

The DocBook-to-XHTML stylesheet translates almost verbatim DocBook tag names into HTML-CSS class names.

Example : DocBook source, XHTML rendering

<simplelist>
   	<member>
   		<quote>DocBook does not provide the equivalent of HTML’s br tag, 
   		  	so there’s no way to interject a line break into normal running text.
   		</quote>
   		See <computeroutput>literallayout</computeroutput>.
   	</member>
   	<member>DocBook adds many more <emphasis>block</emphasis> and <emphasis>inline</emphasis> elements.</member>
   	<member>DocBook provides two different <emphasis>root</emphasis> elements : 
   		<computeroutput>book</computeroutput> and <computeroutput>article</computeroutput>.
   	</member>
</simplelist>
   		  			
------------------------------------------

<table border="0" summary="Simple list" class="simplelist">
    <tr>
        <td>
   		  	<span class="quote">“<span class="quote">DocBook does not provide the equivalent of HTML’s br tag, 
   		  		so there’s no way to interject a line break into normal running text.
   		  	</span>”</span>
   		  	See <code class="computeroutput">literallayout</code>.
   		</td>
	</tr>
    <tr>
        <td>DocBook adds many more <span class="emphasis"><em>block</em></span> and <span class="emphasis"><em>inline</em></span> elements.</td>
    </tr>
    <tr>
        <td>DocBook provides two different <span class="emphasis"><em>root</em></span> elements : 
   		  	<code class="computeroutput">book</code> and <code class="computeroutput">article</code>.
   		</td>
    </tr>
</table>
    		

This opens the possibiity to attach specific styles to DocBook tags via a CSS.

Attachment of a CSS is obtained by setting the html.stylesheet parameter to the URL of the CSS :

<xsl:param name="html.stylesheet" select="'myCSS.css'"/>.

Very simple example :

body {
    margin-left:50px;
    font-family:sans-serif;
}
.quote {
    font-family:serif;
}
			

Use of CSS applies only to XHTML, not to PDF output.

Use of CSS applies only to style, not to inserting elements such as horizontal bar <hr />.

So that overriding of imported rules remains the major tool for the DocBook designer !

Example for HTML output (doc2xhtml.xsl)

<?xml version='1.0'?> 
<!DOCTYPE stylesheet [
    <!ENTITY dbdir "/Users/jfp/Sites/EPITA/International/Site2014b/DocBook/docbook-xsl-ns-1.78.1">
]>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"  
                version="1.0"
                xmlns:d="http://docbook.org/ns/docbook"
                xmlns="http://www.w3.org/1999/xhtml">

  <xsl:import href="&dbdir;/xhtml/docbook.xsl"/>

  <xsl:output method="xml" indent="yes"/>
  
  <!-- setting the CSS -->
  <xsl:param name="html.stylesheet" select="'myCSS.css'"/>
  
  <!-- inserting a bar before each sect1 -->
  <xsl:template match="d:sect1"> <!-- override -->
  	<br />
  	<hr />
  	<xsl:apply-imports />
  </xsl:template>

</xsl:stylesheet>