Main   Changelog   Spec   Patches   Sources   Download   Gear   Bugs e FR  Repocop 

docbook-simple - basic distribution howto
-----------------------------------------

The Simplified DocBook XML DTD is a small subset of the DocBook XML
DTD having only ~100 elements. The full version has ~380 elements.

Online documentation of the content models for this dtd is here:
 http://www.oasis-open.org/docbook/xml/simple/

This DTD only supports simple documents, e.g. 'article' or 'refentry',
rather than the more complex documents like 'book' or 'set' which is
supported by the full docbook DTD.

Simplified DocBook documents can be viewed in a browser (w/o requiring
XSLT processing) and can be styled with a CSS stylesheet, which can be
specified in the document itself with an XML Processing Instruction
(PI) of the form:

<?xml-stylesheet type="text/css" href="path-to-sdocbook.css"?>

The default stylesheet generates quite plain output and should likely
be customized. Section III below gives an example of how to reference
the CSS stylesheet in your source document.


I. How To Write An Article That Uses The Simplified Docbook DTD:
================================================================

Use the following prolog in your XML file to use the Simplified
DocBook Document Type in your document:

<?xml version="1.0"?>
<!DOCTYPE article
     PUBLIC "-//OASIS//DTD Simplified DocBook XML V1.1//EN"
     "http://www.oasis-open.org/docbook/xml/simple/1.1/sdocbook.dtd">
<article>
...
</article>


II. How To Write A Manual Page That Uses The Simplified DocBook DTD:
====================================================================

The sdocbookref.dtd provides a simplified subset of DocBook to support
writing manual pages.

Use the following prolog in your XML file to use the Simplified
DocBook Document Type in your document:

<?xml version="1.0"?>
<!DOCTYPE refentry
     PUBLIC "-//OASIS//DTD Simplified DocBook RefEntry XML V1.1//EN"
     "http://www.oasis-open.org/docbook/xml/simple/1.1/sdocbookref.dtd">
<refentry>
...
</refentry>


III. How To Associate A CSS Stylesheet To Your Simplified Docbook Document:
===========================================================================

Simply place the xml-stylesheet PI in the prolog of the doc as follows:

<?xml version="1.0"?>
<?xml-stylesheet type="text/css" href="path--to-sdocbook.css"?>
<!DOCTYPE article
     PUBLIC "-//OASIS//DTD Simplified DocBook XML V1.1//EN"
     "http://www.oasis-open.org/docbook/xml/simple/1.1/sdocbook.dtd">
<article>
...
</article>

You may place the stylesheet wherever you please, as long as the path
to the stylesheet in the PI is correct with respect to the HTML output
files.


IV. Generating HTML From Your XML Source Document:
==================================================

Before processing your document, you might wish to take a look at some
of the HTML stylesheet parameters you can set to customize the output
HTML. These parameters are all explained in the reference
documentation included with the docbook-style-xsl package. In
addition, you may wish to take a peek at the
/usr/share/sgml/docbook/xsl-stylesheets/html/param.xsl file, which
lists the defaults for the HTML parameters.

For example, to generate a bunch of linked HTML pages (aka chunked)
from your XML source document while setting the parameter
'toc.section.depth' to a value of '2', you can issue an xsltproc
command like the following:1

xsltproc --stringparam toc.section.depth 2 \
	 /usr/share/sgml/docbook/xsl-stylesheets/html/chunk.xsl \
	 sourcefile.xml

*Note: I do not cover the conversion to print output in this README,
        as the print toolchains are slightly more complicated.


Feel free to offer comments, suggestions, or complaints.

     Mark


 -- Mark Johnson <mjohnson@redhat.com>, Tue Sep  7 15:51:51 EDT 2004
 --changes for 1.1 by Ondrej Vasik <ovasik@redhat.com>, Thu May 24 2007