Debian Codegraph @

SCons/Tool/docbook/docs/manual.xml

raw
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>