| 1 |
<?xml version="1.0" encoding="UTF-8"?> |
| 2 |
<!-- |
| 3 |
SPDX-License-Identifier: MIT |
| 4 |
|
| 5 |
Copyright The SCons Foundation |
| 6 |
--> |
| 7 |
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
| 8 |
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> |
| 9 |
<article> |
| 10 |
<title>The SCons Docbook tool</title> |
| 11 |
<articleinfo> |
| 12 |
<author> |
| 13 |
<surname>Dirk Baechle</surname> |
| 14 |
</author> |
| 15 |
<pubdate>2010-12-30</pubdate> |
| 16 |
</articleinfo> |
| 17 |
<section id="basics"><title>Basics</title> |
| 18 |
<para>This tool tries to make working with Docbook in SCons a little easier. |
| 19 |
It provides several toolchains for creating different output formats, |
| 20 |
like HTML or PDF. Contained in the package is |
| 21 |
a distribution of the Docbook XSL stylesheets as of version 1.76.1. |
| 22 |
As long as you don't specify your own stylesheets for customization (see <link linkend="stylesheet">Selecting stylesheet</link>), |
| 23 |
these official versions are picked as default...which should reduce |
| 24 |
the inevitable setup hassles for you. |
| 25 |
</para> |
| 26 |
<para>Implicit dependencies to images and XIncludes are detected automatically |
| 27 |
if you meet the HTML requirements (see <link linkend="requirements">Requirements</link>). The additional |
| 28 |
stylesheet <literal>utils/xmldepend.xsl</literal> by Paul DuBois is used for this purpose. |
| 29 |
</para> |
| 30 |
<para>Note, that there is no support for XML catalog resolving offered! This tool calls |
| 31 |
the XSLT processors and PDF renderers with the stylesheets you specified, that's it. |
| 32 |
The rest lies in your hands and you still have to know what you're doing when |
| 33 |
resolving names via a catalog. |
| 34 |
</para> |
| 35 |
<section id="install"><title>Install</title> |
| 36 |
<para>Installing it, requires you to copy (or, even better: checkout) the contents of the |
| 37 |
package's <literal>docbook</literal> folder to |
| 38 |
</para> |
| 39 |
<orderedlist><listitem><para><quote><literal>/path_to_your_project/site_scons/site_tools/docbook</literal></quote>, if you need the Docbook Tool in one project only, or |
| 40 |
</para> |
| 41 |
</listitem> |
| 42 |
<listitem><para><quote><literal>~/.scons/site_scons/site_tools/docbook</literal></quote>, for a system-wide installation under your current login. |
| 43 |
</para> |
| 44 |
</listitem> |
| 45 |
</orderedlist> |
| 46 |
<para>For more infos about this, please refer to |
| 47 |
</para> |
| 48 |
<itemizedlist><listitem><para>the SCons User's Guide, chap. 19.7 "Where to put your custom Builders and Tools" and |
| 49 |
</para> |
| 50 |
</listitem> |
| 51 |
<listitem><para>the SCons Tools Wiki page at <ulink url="https://github.com/SCons/scons/wiki/ToolsIndex">http://github.com/SCons/scons/wiki/ToolsIndex</ulink>. |
| 52 |
</para> |
| 53 |
</listitem> |
| 54 |
</itemizedlist> |
| 55 |
</section> |
| 56 |
<section id="activation"><title>How to activate</title> |
| 57 |
<para>For activating the tool "docbook", you have to add its name to the Environment constructor, |
| 58 |
like this |
| 59 |
</para> |
| 60 |
<screen>env = Environment(tools=['docbook']) |
| 61 |
</screen> |
| 62 |
<para>On its startup, the Docbook tool tries to find a required <literal>xsltproc</literal> processor, and |
| 63 |
a PDF renderer, e.g. <literal>fop</literal>. So make sure that these are added to your system's environment |
| 64 |
<literal>PATH</literal> and can be called directly, without specifying their full path. |
| 65 |
</para> |
| 66 |
</section> |
| 67 |
<section id="requirements"><title>Requirements</title> |
| 68 |
<para>For the most basic processing of Docbook to HTML, you need to have installed |
| 69 |
</para> |
| 70 |
<itemizedlist><listitem><para>the Python <literal>lxml</literal> binding to <literal>libxml2</literal>, or |
| 71 |
</para> |
| 72 |
</listitem> |
| 73 |
<listitem><para>the direct Python bindings for <literal>libxml2/libxslt</literal>, or |
| 74 |
</para> |
| 75 |
</listitem> |
| 76 |
<listitem><para>a standalone XSLT processor, currently detected are <literal>xsltproc</literal>, <literal>saxon</literal>, <literal>saxon-xslt</literal> |
| 77 |
and <literal>xalan</literal>. |
| 78 |
</para> |
| 79 |
</listitem> |
| 80 |
</itemizedlist> |
| 81 |
<para>Rendering to PDF requires you to have one of the applications <literal>fop</literal>, <literal>xep</literal> or <literal>jw</literal> |
| 82 |
installed. |
| 83 |
</para> |
| 84 |
</section> |
| 85 |
</section> |
| 86 |
<section id="process"><title>Processing documents</title> |
| 87 |
<para>Creating a HTML or PDF document is very simple and straightforward. Say |
| 88 |
</para> |
| 89 |
<screen>env = Environment(tools=['docbook']) |
| 90 |
env.DocbookHtml('manual.html', 'manual.xml') |
| 91 |
env.DocbookPdf('manual.pdf', 'manual.xml') |
| 92 |
</screen> |
| 93 |
<para>to get both outputs from your XML source <literal>manual.xml</literal>. As a shortcut, you can |
| 94 |
give the stem of the filenames alone, like this: |
| 95 |
</para> |
| 96 |
<screen>env = Environment(tools=['docbook']) |
| 97 |
env.DocbookHtml('manual') |
| 98 |
env.DocbookPdf('manual') |
| 99 |
</screen> |
| 100 |
<para>and get the same result. Target and source lists are also supported: |
| 101 |
</para> |
| 102 |
<screen>env = Environment(tools=['docbook']) |
| 103 |
env.DocbookHtml(['manual.html','reference.html'], ['manual.xml','reference.xml']) |
| 104 |
</screen> |
| 105 |
<para>or even |
| 106 |
</para> |
| 107 |
<screen>env = Environment(tools=['docbook']) |
| 108 |
env.DocbookHtml(['manual','reference']) |
| 109 |
</screen> |
| 110 |
<important><para>Whenever you leave out the list of sources, you may not specify a file extension! The |
| 111 |
Tool uses the given names as file stems, and adds the suffixes for target and source files |
| 112 |
accordingly. |
| 113 |
</para> |
| 114 |
</important> |
| 115 |
<para>The rules given above are valid for the Builders <literal>DocbookHtml</literal>, <literal>DocbookPdf</literal>, |
| 116 |
<literal>DocbookSlidePdf</literal> and <literal>DocbookXInclude</literal>. For the <literal>DocbookMan</literal> transformation you |
| 117 |
can specify a target name, but the actual output names are automatically set from |
| 118 |
the <literal>refname</literal> entries in your XML source. |
| 119 |
</para> |
| 120 |
<para>Please refer to <link linkend="chunked">the section Chunked output</link> for more infos about the other Builders. |
| 121 |
</para> |
| 122 |
</section> |
| 123 |
<section id="stylesheet"><title>Selecting your own stylesheet</title> |
| 124 |
<para>If you want to use a specific XSL file, you can set the additional <literal>xsl</literal> parameter to your |
| 125 |
Builder call as follows: |
| 126 |
</para> |
| 127 |
<screen>env.DocbookHtml('other.html', 'manual.xml', xsl='html.xsl') |
| 128 |
</screen> |
| 129 |
<para>Since this may get tedious if you always use the same local naming for your customized XSL files, |
| 130 |
e.g. <literal>html.xsl</literal> for HTML and <literal>pdf.xsl</literal> for PDF output, a set of variables for setting the |
| 131 |
default XSL name is provided. These are: |
| 132 |
</para> |
| 133 |
<screen>DOCBOOK_DEFAULT_XSL_HTML |
| 134 |
DOCBOOK_DEFAULT_XSL_HTMLCHUNKED |
| 135 |
DOCBOOK_DEFAULT_XSL_HTMLHELP |
| 136 |
DOCBOOK_DEFAULT_XSL_PDF |
| 137 |
DOCBOOK_DEFAULT_XSL_MAN |
| 138 |
DOCBOOK_DEFAULT_XSL_SLIDESPDF |
| 139 |
DOCBOOK_DEFAULT_XSL_SLIDESHTML |
| 140 |
</screen> |
| 141 |
<para>and you can set them when constructing your environment: |
| 142 |
</para> |
| 143 |
<screen>env = Environment(tools=['docbook'], |
| 144 |
DOCBOOK_DEFAULT_XSL_HTML='html.xsl', |
| 145 |
DOCBOOK_DEFAULT_XSL_PDF='pdf.xsl') |
| 146 |
env.DocbookHtml('manual') # now uses html.xsl |
| 147 |
</screen> |
| 148 |
</section> |
| 149 |
<section id="chunked"><title>Chunked output</title> |
| 150 |
<para>The Builders <literal>DocbookHtmlChunked</literal>, <literal>DocbookHtmlhelp</literal> and <literal>DocbookSlidesHtml</literal> |
| 151 |
are special, in that: |
| 152 |
</para> |
| 153 |
<orderedlist><listitem><para>they create a large set of files, where the exact names and their number depend |
| 154 |
on the content of the source file, and |
| 155 |
</para> |
| 156 |
</listitem> |
| 157 |
<listitem><para>the main target is always named <literal>index.html</literal>, i.e. the output name for the |
| 158 |
XSL transformation is not picked up by the stylesheets. |
| 159 |
</para> |
| 160 |
</listitem> |
| 161 |
</orderedlist> |
| 162 |
<para>As a result, there is simply no use in specifying a target HTML name. |
| 163 |
So the basic syntax for these builders is: |
| 164 |
</para> |
| 165 |
<screen>env = Environment(tools=['docbook']) |
| 166 |
env.DocbookHtmlhelp('manual') |
| 167 |
</screen> |
| 168 |
<para>Only if you use the <literal>root.filename</literal> (<literal>titlefoil.html</literal> for slides) parameter in |
| 169 |
your own stylesheets you have to give the new target name. This ensures that the |
| 170 |
dependencies get correct, especially for the cleanup via <quote><literal>scons -c</literal></quote>: |
| 171 |
</para> |
| 172 |
<screen>env = Environment(tools=['docbook']) |
| 173 |
env.DocbookHtmlhelp('mymanual.html','manual', xsl='htmlhelp.xsl') |
| 174 |
</screen> |
| 175 |
<para>Some basic support for the <literal>base.dir</literal> is added (this has not been properly tested |
| 176 |
with variant dirs, yet!). You can add the <literal>base_dir</literal> keyword to your Builder |
| 177 |
call, and the given prefix gets prepended to all the created filenames: |
| 178 |
</para> |
| 179 |
<screen>env = Environment(tools=['docbook']) |
| 180 |
env.DocbookHtmlhelp('manual', xsl='htmlhelp.xsl', base_dir='output/') |
| 181 |
</screen> |
| 182 |
<para>Make sure that you don't forget the trailing slash for the base folder, else |
| 183 |
your files get renamed only! |
| 184 |
</para> |
| 185 |
</section> |
| 186 |
<section id="builders"><title>All builders</title> |
| 187 |
<para>A simple list of all builders currently available: |
| 188 |
</para> |
| 189 |
<variablelist><varlistentry><term>DocbookHtml |
| 190 |
</term> |
| 191 |
<listitem><para>Single HTML file. |
| 192 |
</para> |
| 193 |
</listitem> |
| 194 |
</varlistentry> |
| 195 |
<varlistentry><term>DocbookHtmlChunked |
| 196 |
</term> |
| 197 |
<listitem><para>Chunked HTML files, with support for the <literal>base.dir</literal> parameter. The <literal>chunkfast.xsl</literal> |
| 198 |
file (requires "EXSLT") is used as the default stylesheet. |
| 199 |
</para> |
| 200 |
</listitem> |
| 201 |
</varlistentry> |
| 202 |
<varlistentry><term>DocbookHtmlhelp |
| 203 |
</term> |
| 204 |
<listitem><para>Htmlhelp files, with support for <literal>base.dir</literal>. |
| 205 |
</para> |
| 206 |
</listitem> |
| 207 |
</varlistentry> |
| 208 |
<varlistentry><term>DocbookPdf |
| 209 |
</term> |
| 210 |
<listitem><para>PDF output. |
| 211 |
</para> |
| 212 |
</listitem> |
| 213 |
</varlistentry> |
| 214 |
<varlistentry><term>DocbookMan |
| 215 |
</term> |
| 216 |
<listitem><para>Man pages. |
| 217 |
</para> |
| 218 |
</listitem> |
| 219 |
</varlistentry> |
| 220 |
<varlistentry><term>DocbookSlidesPdf |
| 221 |
</term> |
| 222 |
<listitem><para>Slides in PDF format. |
| 223 |
</para> |
| 224 |
</listitem> |
| 225 |
</varlistentry> |
| 226 |
<varlistentry><term>DocbookSlidesHtml |
| 227 |
</term> |
| 228 |
<listitem><para>Slides in HTML format, with support for <literal>base.dir</literal>. |
| 229 |
</para> |
| 230 |
</listitem> |
| 231 |
</varlistentry> |
| 232 |
<varlistentry><term>DocbookXInclude |
| 233 |
</term> |
| 234 |
<listitem><para>Can be used to resolve XIncludes in a preprocessing step. |
| 235 |
</para> |
| 236 |
</listitem> |
| 237 |
</varlistentry> |
| 238 |
</variablelist> |
| 239 |
</section> |
| 240 |
<section id="more"><title>Need more?</title> |
| 241 |
<para>This work is still in a very basic state and hasn't been tested well |
| 242 |
with things like variant dirs, yet. Unicode problems and poor performance |
| 243 |
with large input files may occur. There will definitely arise the need for |
| 244 |
adding features, or a variable. Let us know if you can think of a nice |
| 245 |
improvement or have worked on a bugfix/patch with success. Enter your issues at the |
| 246 |
Launchpad bug tracker for the Docbook Tool, or write to the User General Discussion |
| 247 |
list of SCons at <literal>[email protected]</literal>. |
| 248 |
</para> |
| 249 |
</section> |
| 250 |
|
| 251 |
</article> |