Blame SOURCES/docbook-simple.README.redhat

4d4011
docbook-simple - basic distribution howto
4d4011
-----------------------------------------
4d4011
4d4011
The Simplified DocBook XML DTD is a small subset of the DocBook XML
4d4011
DTD having only ~100 elements. The full version has ~380 elements.
4d4011
4d4011
Online documentation of the content models for this dtd is here:
4d4011
 http://www.oasis-open.org/docbook/xml/simple/
4d4011
4d4011
This DTD only supports simple documents, e.g. 'article' or 'refentry',
4d4011
rather than the more complex documents like 'book' or 'set' which is
4d4011
supported by the full docbook DTD.
4d4011
4d4011
Simplified DocBook documents can be viewed in a browser (w/o requiring
4d4011
XSLT processing) and can be styled with a CSS stylesheet, which can be
4d4011
specified in the document itself with an XML Processing Instruction
4d4011
(PI) of the form:
4d4011
4d4011
4d4011
4d4011
The default stylesheet generates quite plain output and should likely
4d4011
be customized. Section III below gives an example of how to reference
4d4011
the CSS stylesheet in your source document.
4d4011
4d4011
4d4011
I. How To Write An Article That Uses The Simplified Docbook DTD:
4d4011
================================================================
4d4011
4d4011
Use the following prolog in your XML file to use the Simplified
4d4011
DocBook Document Type in your document:
4d4011
4d4011
4d4011
4d4011
     PUBLIC "-//OASIS//DTD Simplified DocBook XML V1.1//EN"
4d4011
     "http://www.oasis-open.org/docbook/xml/simple/1.1/sdocbook.dtd">
4d4011
<article>
4d4011
...
4d4011
</article>
4d4011
4d4011
4d4011
II. How To Write A Manual Page That Uses The Simplified DocBook DTD:
4d4011
====================================================================
4d4011
4d4011
The sdocbookref.dtd provides a simplified subset of DocBook to support
4d4011
writing manual pages.
4d4011
4d4011
Use the following prolog in your XML file to use the Simplified
4d4011
DocBook Document Type in your document:
4d4011
4d4011
4d4011
4d4011
     PUBLIC "-//OASIS//DTD Simplified DocBook RefEntry XML V1.1//EN"
4d4011
     "http://www.oasis-open.org/docbook/xml/simple/1.1/sdocbookref.dtd">
4d4011
<refentry>
4d4011
...
4d4011
</refentry>
4d4011
4d4011
4d4011
III. How To Associate A CSS Stylesheet To Your Simplified Docbook Document:
4d4011
===========================================================================
4d4011
4d4011
Simply place the xml-stylesheet PI in the prolog of the doc as follows:
4d4011
4d4011
4d4011
4d4011
4d4011
     PUBLIC "-//OASIS//DTD Simplified DocBook XML V1.1//EN"
4d4011
     "http://www.oasis-open.org/docbook/xml/simple/1.1/sdocbook.dtd">
4d4011
<article>
4d4011
...
4d4011
</article>
4d4011
4d4011
You may place the stylesheet wherever you please, as long as the path
4d4011
to the stylesheet in the PI is correct with respect to the HTML output
4d4011
files.
4d4011
4d4011
4d4011
IV. Generating HTML From Your XML Source Document:
4d4011
==================================================
4d4011
4d4011
Before processing your document, you might wish to take a look at some
4d4011
of the HTML stylesheet parameters you can set to customize the output
4d4011
HTML. These parameters are all explained in the reference
4d4011
documentation included with the docbook-style-xsl package. In
4d4011
addition, you may wish to take a peek at the
4d4011
/usr/share/sgml/docbook/xsl-stylesheets/html/param.xsl file, which
4d4011
lists the defaults for the HTML parameters.
4d4011
4d4011
For example, to generate a bunch of linked HTML pages (aka chunked)
4d4011
from your XML source document while setting the parameter
4d4011
'toc.section.depth' to a value of '2', you can issue an xsltproc
4d4011
command like the following:1
4d4011
4d4011
xsltproc --stringparam toc.section.depth 2 \
4d4011
	 /usr/share/sgml/docbook/xsl-stylesheets/html/chunk.xsl \
4d4011
	 sourcefile.xml
4d4011
4d4011
*Note: I do not cover the conversion to print output in this README,
4d4011
        as the print toolchains are slightly more complicated.
4d4011
4d4011
4d4011
Feel free to offer comments, suggestions, or complaints.
4d4011
4d4011
     Mark
4d4011
4d4011
4d4011
 -- Mark Johnson <mjohnson@redhat.com>, Tue Sep  7 15:51:51 EDT 2004
4d4011
 --changes for 1.1 by Ondrej Vasik <ovasik@redhat.com>, Thu May 24 2007