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:

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:

     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:

     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:

     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