SCons/Tool/docbook/docbook.xml

   1 <?xml version="1.0"?>
   2 <!--
   3 SPDX-License-Identifier: MIT
   4 SPDX-FileCopyrightText: Copyright The SCons Foundation (https://scons.org)
   5 SPDX-FileType: DOCUMENTATION
   6
   7 This file is processed by the bin/SConsDoc.py module
   8 -->
   9
  10 <!DOCTYPE sconsdoc [
  11 <!ENTITY % scons SYSTEM '../../../doc/scons.mod'>
  12 %scons;
  13 <!ENTITY % builders-mod SYSTEM '../../../doc/generated/builders.mod'>
  14 %builders-mod;
  15 <!ENTITY % functions-mod SYSTEM '../../../doc/generated/functions.mod'>
  16 %functions-mod;
  17 <!ENTITY % tools-mod SYSTEM '../../../doc/generated/tools.mod'>
  18 %tools-mod;
  19 <!ENTITY % variables-mod SYSTEM '../../../doc/generated/variables.mod'>
  20 %variables-mod;
  21 ]>
  22
  23 <sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
  24           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  25           xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
  26
  27 <tool name="docbook">
  28 <summary>
  29 <para>This tool tries to make working with Docbook in &SCons; a little easier.
  30 It provides several toolchains for creating different output formats,
  31 like HTML or PDF. Contained in the package is
  32 a distribution of the Docbook XSL stylesheets as of version 1.76.1.
  33 As long as you don't specify your own stylesheets for customization,
  34 these official versions are picked as default...which should reduce
  35 the inevitable setup hassles for you.
  36 </para>
  37 <para>Implicit dependencies to images and XIncludes are detected automatically
  38 if you meet the HTML requirements. The additional
  39 stylesheet <filename>utils/xmldepend.xsl</filename> by Paul DuBois is used for this purpose.
  40 </para>
  41 <para>Note, that there is no support for XML catalog resolving offered! This tool calls
  42 the XSLT processors and PDF renderers with the stylesheets you specified, that's it.
  43 The rest lies in your hands and you still have to know what you're doing when
  44 resolving names via a catalog.
  45 </para>
  46 <para>For activating the tool "docbook", you have to add its name to the Environment constructor,
  47 like this
  48 </para>
  49 <screen>env = Environment(tools=['docbook'])
  50 </screen>
  51 <para>On its startup, the &t-docbook; tool tries to find a required <literal>xsltproc</literal> processor, and
  52 a PDF renderer, e.g. <application>fop</application>. So make sure that these are added to your system's environment
  53 <envar>PATH</envar> and can be called directly without specifying their full path.
  54 </para>
  55 <para>For the most basic processing of Docbook to HTML, you need to have installed
  56 </para>
  57 <itemizedlist><listitem><para>the Python <systemitem>lxml</systemitem>
  58 binding to <systemitem>libxml2</systemitem>, or</para>
  59 </listitem>
  60 <listitem><para>a standalone XSLT processor, currently detected are <application>xsltproc</application>, <application>saxon</application>, <application>saxon-xslt</application>
  61 and <application>xalan</application>.
  62 </para>
  63 </listitem>
  64 </itemizedlist>
  65 <para>Rendering to PDF requires you to have one of the applications
  66 <application>fop</application> or <application>xep</application> installed.
  67 </para>
  68
  69 <para>Creating a HTML or PDF document is very simple and straightforward. Say
  70 </para>
  71 <screen>env = Environment(tools=['docbook'])
  72 env.DocbookHtml('manual.html', 'manual.xml')
  73 env.DocbookPdf('manual.pdf', 'manual.xml')
  74 </screen>
  75 <para>to get both outputs from your XML source <filename>manual.xml</filename>. As a shortcut, you can
  76 give the stem of the filenames alone, like this:
  77 </para>
  78 <screen>env = Environment(tools=['docbook'])
  79 env.DocbookHtml('manual')
  80 env.DocbookPdf('manual')
  81 </screen>
  82 <para>and get the same result. Target and source lists are also supported:
  83 </para>
  84 <screen>env = Environment(tools=['docbook'])
  85 env.DocbookHtml(['manual.html','reference.html'], ['manual.xml','reference.xml'])
  86 </screen>
  87 <para>or even
  88 </para>
  89 <screen>env = Environment(tools=['docbook'])
  90 env.DocbookHtml(['manual','reference'])
  91 </screen>
  92 <important><para>Whenever you leave out the list of sources, you may not specify a file extension! The
  93 Tool uses the given names as file stems, and adds the suffixes for target and source files
  94 accordingly.
  95 </para>
  96 </important>
  97 <para>The rules given above are valid for the Builders &b-link-DocbookHtml;,
  98 &b-link-DocbookPdf;, &b-link-DocbookEpub;, &b-link-DocbookSlidesPdf; and &b-link-DocbookXInclude;. For the
  99 &b-link-DocbookMan; transformation you
 100 can specify a target name, but the actual output names are automatically
 101 set from the <literal>refname</literal> entries in your XML source.
 102 </para>
 103
 104 <para>The Builders &b-link-DocbookHtmlChunked;, &b-link-DocbookHtmlhelp; and
 105 &b-link-DocbookSlidesHtml; are special, in that:
 106 </para>
 107 <orderedlist><listitem><para>they create a large set of files, where the exact names and their number depend
 108 on the content of the source file, and
 109 </para>
 110 </listitem>
 111 <listitem><para>the main target is always named <filename>index.html</filename>, i.e. the output name for the
 112 XSL transformation is not picked up by the stylesheets.
 113 </para>
 114 </listitem>
 115 </orderedlist>
 116 <para>As a result, there is simply no use in specifying a target HTML name.
 117 So the basic syntax for these builders is always:
 118 </para>
 119 <screen>env = Environment(tools=['docbook'])
 120 env.DocbookHtmlhelp('manual')
 121 </screen>
 122
 123 <para>If you want to use a specific XSL file, you can set the
 124 additional <parameter>xsl</parameter> 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. <filename>html.xsl</filename> for HTML and <filename>pdf.xsl</filename> for PDF output, a set of
 131 variables for setting the 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_EPUB
 138 DOCBOOK_DEFAULT_XSL_MAN
 139 DOCBOOK_DEFAULT_XSL_SLIDESPDF
 140 DOCBOOK_DEFAULT_XSL_SLIDESHTML
 141 </screen>
 142 <para>and you can set them when constructing your environment:
 143 </para>
 144 <screen>
 145 env = Environment(
 146     tools=['docbook'],
 147     DOCBOOK_DEFAULT_XSL_HTML='html.xsl',
 148     DOCBOOK_DEFAULT_XSL_PDF='pdf.xsl',
 149 )
 150 env.DocbookHtml('manual')  # now uses html.xsl
 151 </screen>
 152 </summary>
 153 <sets>
 154 <item>DOCBOOK_DEFAULT_XSL_HTML</item>
 155 <item>DOCBOOK_DEFAULT_XSL_HTMLCHUNKED</item>
 156 <item>DOCBOOK_DEFAULT_XSL_HTMLHELP</item>
 157 <item>DOCBOOK_DEFAULT_XSL_PDF</item>
 158 <item>DOCBOOK_DEFAULT_XSL_EPUB</item>
 159 <item>DOCBOOK_DEFAULT_XSL_MAN</item>
 160 <item>DOCBOOK_DEFAULT_XSL_SLIDESPDF</item>
 161 <item>DOCBOOK_DEFAULT_XSL_SLIDESHTML</item>
 162 <item>DOCBOOK_XSLTPROC</item>
 163 <item>DOCBOOK_XMLLINT</item>
 164 <item>DOCBOOK_FOP</item>
 165 <item>DOCBOOK_XSLTPROCFLAGS</item>
 166 <item>DOCBOOK_XMLLINTFLAGS</item>
 167 <item>DOCBOOK_FOPFLAGS</item>
 168 <item>DOCBOOK_XSLTPROCPARAMS</item>
 169 <item>DOCBOOK_XSLTPROCCOM</item>
 170 <item>DOCBOOK_XMLLINTCOM</item>
 171 <item>DOCBOOK_FOPCOM</item>
 172 </sets>
 173 <uses>
 174 <item>DOCBOOK_XSLTPROCCOMSTR</item>
 175 <item>DOCBOOK_XMLLINTCOMSTR</item>
 176 <item>DOCBOOK_FOPCOMSTR</item>
 177 </uses>
 178 </tool>
 179
 180
 181 <cvar name="DOCBOOK_DEFAULT_XSL_HTML">
 182 <summary>
 183 <para>
 184 The default XSLT file for the &b-link-DocbookHtml; builder within the
 185 current environment, if no other XSLT gets specified via keyword.
 186 </para>
 187 </summary>
 188 </cvar>
 189
 190
 191 <cvar name="DOCBOOK_DEFAULT_XSL_HTMLCHUNKED">
 192 <summary>
 193 <para>
 194 The default XSLT file for the &b-link-DocbookHtmlChunked; builder within the
 195 current environment, if no other XSLT gets specified via keyword.
 196 </para>
 197 </summary>
 198 </cvar>
 199
 200 <cvar name="DOCBOOK_DEFAULT_XSL_HTMLHELP">
 201 <summary>
 202 <para>
 203 The default XSLT file for the &b-link-DocbookHtmlhelp; builder within the
 204 current environment, if no other XSLT gets specified via keyword.
 205 </para>
 206 </summary>
 207 </cvar>
 208
 209 <cvar name="DOCBOOK_DEFAULT_XSL_PDF">
 210 <summary>
 211 <para>
 212 The default XSLT file for the &b-link-DocbookPdf; builder within the
 213 current environment, if no other XSLT gets specified via keyword.
 214 </para>
 215 </summary>
 216 </cvar>
 217
 218 <cvar name="DOCBOOK_DEFAULT_XSL_EPUB">
 219 <summary>
 220 <para>
 221 The default XSLT file for the &b-link-DocbookEpub; builder within the
 222 current environment, if no other XSLT gets specified via keyword.
 223 </para>
 224 </summary>
 225 </cvar>
 226
 227 <cvar name="DOCBOOK_DEFAULT_XSL_MAN">
 228 <summary>
 229 <para>
 230 The default XSLT file for the &b-link-DocbookMan; builder within the
 231 current environment, if no other XSLT gets specified via keyword.
 232 </para>
 233 </summary>
 234 </cvar>
 235
 236 <cvar name="DOCBOOK_DEFAULT_XSL_SLIDESPDF">
 237 <summary>
 238 <para>
 239 The default XSLT file for the &b-link-DocbookSlidesPdf; builder within the
 240 current environment, if no other XSLT gets specified via keyword.
 241 </para>
 242 </summary>
 243 </cvar>
 244
 245 <cvar name="DOCBOOK_DEFAULT_XSL_SLIDESHTML">
 246 <summary>
 247 <para>
 248 The default XSLT file for the &b-link-DocbookSlidesHtml; builder within the
 249 current environment, if no other XSLT gets specified via keyword.
 250 </para>
 251 </summary>
 252 </cvar>
 253
 254 <cvar name="DOCBOOK_XSLTPROC">
 255 <summary>
 256 <para>
 257 The path to the external executable <literal>xsltproc</literal>
 258 (or <literal>saxon</literal>, <literal>xalan</literal>), if one of them
 259 is installed.
 260 Note, that this is only used as last fallback for XSL transformations, if
 261 no lxml Python binding can be imported in the current system.
 262 </para>
 263 </summary>
 264 </cvar>
 265
 266 <cvar name="DOCBOOK_XMLLINT">
 267 <summary>
 268 <para>
 269 The path to the external executable <literal>xmllint</literal>, if it's installed.
 270 Note, that this is only used as last fallback for resolving
 271 XIncludes, if no lxml Python binding can be imported
 272 in the current system.
 273 </para>
 274 </summary>
 275 </cvar>
 276
 277 <cvar name="DOCBOOK_FOP">
 278 <summary>
 279 <para>
 280 The path to the PDF renderer <literal>fop</literal> or <literal>xep</literal>,
 281 if one of them is installed (<literal>fop</literal> gets checked first).
 282 </para>
 283 </summary>
 284 </cvar>
 285
 286 <cvar name="DOCBOOK_XSLTPROCFLAGS">
 287 <summary>
 288 <para>
 289 Additonal command-line flags for the external executable
 290 <literal>xsltproc</literal> (or <literal>saxon</literal>,
 291 <literal>xalan</literal>).
 292 </para>
 293 </summary>
 294 </cvar>
 295
 296 <cvar name="DOCBOOK_XMLLINTFLAGS">
 297 <summary>
 298 <para>
 299 Additonal command-line flags for the external executable
 300 <literal>xmllint</literal>.
 301 </para>
 302 </summary>
 303 </cvar>
 304
 305 <cvar name="DOCBOOK_FOPFLAGS">
 306 <summary>
 307 <para>
 308 Additonal command-line flags for the
 309 PDF renderer <literal>fop</literal> or <literal>xep</literal>.
 310 </para>
 311 </summary>
 312 </cvar>
 313
 314 <cvar name="DOCBOOK_XSLTPROCPARAMS">
 315 <summary>
 316 <para>
 317 Additonal parameters that are not intended for the XSLT processor executable, but
 318 the XSL processing itself. By default, they get appended at the end of the command line
 319 for <literal>saxon</literal> and <literal>saxon-xslt</literal>, respectively.
 320 </para>
 321 </summary>
 322 </cvar>
 323
 324 <cvar name="DOCBOOK_XSLTPROCCOM">
 325 <summary>
 326 <para>
 327 The full command-line for the external executable
 328 <literal>xsltproc</literal> (or <literal>saxon</literal>,
 329 <literal>xalan</literal>).
 330 </para>
 331 </summary>
 332 </cvar>
 333
 334 <cvar name="DOCBOOK_XMLLINTCOM">
 335 <summary>
 336 <para>
 337 The full command-line for the external executable
 338 <literal>xmllint</literal>.
 339 </para>
 340 </summary>
 341 </cvar>
 342
 343 <cvar name="DOCBOOK_FOPCOM">
 344 <summary>
 345 <para>
 346 The full command-line for the
 347 PDF renderer <literal>fop</literal> or <literal>xep</literal>.
 348 </para>
 349 </summary>
 350 </cvar>
 351
 352 <cvar name="DOCBOOK_XSLTPROCCOMSTR">
 353 <summary>
 354 <para>
 355 The string displayed when <literal>xsltproc</literal> is used to transform
 356 an XML file via a given XSLT stylesheet.
 357 </para>
 358 </summary>
 359 </cvar>
 360
 361 <cvar name="DOCBOOK_XMLLINTCOMSTR">
 362 <summary>
 363 <para>
 364 The string displayed when <literal>xmllint</literal> is used to resolve
 365 XIncludes for a given XML file.
 366 </para>
 367 </summary>
 368 </cvar>
 369
 370 <cvar name="DOCBOOK_FOPCOMSTR">
 371 <summary>
 372 <para>
 373 The string displayed when a renderer like <literal>fop</literal> or
 374 <literal>xep</literal> is used to create PDF output from an XML file.
 375 </para>
 376 </summary>
 377 </cvar>
 378
 379 <builder name="DocbookHtml">
 380 <summary>
 381 <para>
 382 A pseudo-Builder, providing a Docbook toolchain for HTML output.
 383 </para>
 384 <example_commands>env = Environment(tools=['docbook'])
 385 env.DocbookHtml('manual.html', 'manual.xml')
 386 </example_commands>
 387 <para>
 388 or simply
 389 </para>
 390 <example_commands>env = Environment(tools=['docbook'])
 391 env.DocbookHtml('manual')
 392 </example_commands>
 393 </summary>
 394 </builder>
 395
 396 <builder name="DocbookHtmlChunked">
 397 <summary>
 398 <para>
 399 A pseudo-Builder providing a Docbook toolchain for chunked HTML output.
 400 It supports the <parameter>base.dir</parameter> parameter. The
 401 <filename>chunkfast.xsl</filename> file (requires &quot;EXSLT&quot;) is used as the
 402 default stylesheet. Basic syntax:
 403 </para>
 404
 405 <example_commands>env = Environment(tools=['docbook'])
 406 env.DocbookHtmlChunked('manual')
 407 </example_commands>
 408 <para>
 409 where <filename>manual.xml</filename> is the input file.
 410 </para>
 411 <para>If you use the <parameter>root.filename</parameter>
 412 parameter in your own stylesheets you have to specify the new target name.
 413 This ensures that the dependencies get correct, especially for the cleanup via <quote><literal>scons -c</literal></quote>:
 414 </para>
 415 <screen>env = Environment(tools=['docbook'])
 416 env.DocbookHtmlChunked('mymanual.html', 'manual', xsl='htmlchunk.xsl')
 417 </screen>
 418 <para>Some basic support for the <parameter>base.dir</parameter> parameter
 419 is provided.  You can add the <parameter>base_dir</parameter> keyword to
 420 your Builder call, and the given prefix gets prepended to all the
 421 created filenames:
 422 </para>
 423 <screen>env = Environment(tools=['docbook'])
 424 env.DocbookHtmlChunked('manual', xsl='htmlchunk.xsl', base_dir='output/')
 425 </screen>
 426 <para>Make sure that you don't forget the trailing slash for the base folder, else
 427 your files get renamed only!
 428 </para>
 429 </summary>
 430 </builder>
 431
 432 <builder name="DocbookHtmlhelp">
 433 <summary>
 434 <para>
 435 A pseudo-Builder, providing a Docbook toolchain for HTMLHELP output.
 436 Its basic syntax is:
 437 </para>
 438
 439 <example_commands>env = Environment(tools=['docbook'])
 440 env.DocbookHtmlhelp('manual')
 441 </example_commands>
 442 <para>
 443 where <filename>manual.xml</filename> is the input file.
 444 </para>
 445
 446 <para>If you use the <parameter>root.filename</parameter>
 447 parameter in your own stylesheets you have to specify the new target name.
 448 This ensures that the dependencies get correct, especially for the cleanup via <quote><userinput>scons -c</userinput></quote>:
 449 </para>
 450 <screen>env = Environment(tools=['docbook'])
 451 env.DocbookHtmlhelp('mymanual.html', 'manual', xsl='htmlhelp.xsl')
 452 </screen>
 453 <para>Some basic support for the <parameter>base.dir</parameter> parameter
 454 is provided. You can add the <parameter>base_dir</parameter> keyword to
 455 your Builder call, and the given prefix gets prepended to all the
 456 created filenames:
 457 </para>
 458 <screen>env = Environment(tools=['docbook'])
 459 env.DocbookHtmlhelp('manual', xsl='htmlhelp.xsl', base_dir='output/')
 460 </screen>
 461 <para>Make sure that you don't forget the trailing slash for the base folder, else
 462 your files get renamed only!
 463 </para>
 464
 465 </summary>
 466 </builder>
 467
 468 <builder name="DocbookPdf">
 469 <summary>
 470 <para>
 471 A pseudo-Builder, providing a Docbook toolchain for PDF output.
 472 </para>
 473
 474 <example_commands>env = Environment(tools=['docbook'])
 475 env.DocbookPdf('manual.pdf', 'manual.xml')
 476 </example_commands>
 477
 478 <para>
 479 or simply
 480 </para>
 481
 482 <example_commands>env = Environment(tools=['docbook'])
 483 env.DocbookPdf('manual')
 484 </example_commands>
 485
 486 </summary>
 487 </builder>
 488
 489 <builder name="DocbookEpub">
 490 <summary>
 491 <para>
 492 A pseudo-Builder, providing a Docbook toolchain for EPUB output.
 493 </para>
 494
 495 <example_commands>env = Environment(tools=['docbook'])
 496 env.DocbookEpub('manual.epub', 'manual.xml')
 497 </example_commands>
 498
 499 <para>
 500 or simply
 501 </para>
 502
 503 <example_commands>env = Environment(tools=['docbook'])
 504 env.DocbookEpub('manual')
 505 </example_commands>
 506
 507 </summary>
 508 </builder>
 509
 510 <builder name="DocbookMan">
 511 <summary>
 512 <para>
 513 A pseudo-Builder, providing a Docbook toolchain for Man page output.
 514 Its basic syntax is:
 515 </para>
 516
 517 <example_commands>env = Environment(tools=['docbook'])
 518 env.DocbookMan('manual')
 519 </example_commands>
 520 <para>
 521 where <filename>manual.xml</filename> is the input file. Note, that
 522 you can specify a target name, but the actual output names are automatically
 523 set from the <literal>refname</literal> entries in your XML source.
 524 </para>
 525 </summary>
 526 </builder>
 527
 528 <builder name="DocbookSlidesPdf">
 529 <summary>
 530 <para>
 531 A pseudo-Builder, providing a Docbook toolchain for PDF slides output.
 532 </para>
 533
 534 <example_commands>env = Environment(tools=['docbook'])
 535 env.DocbookSlidesPdf('manual.pdf', 'manual.xml')
 536 </example_commands>
 537
 538 <para>
 539 or simply
 540 </para>
 541
 542 <example_commands>env = Environment(tools=['docbook'])
 543 env.DocbookSlidesPdf('manual')
 544 </example_commands>
 545 </summary>
 546 </builder>
 547
 548 <builder name="DocbookSlidesHtml">
 549 <summary>
 550 <para>
 551 A pseudo-Builder, providing a Docbook toolchain for HTML slides output.
 552 </para>
 553
 554 <example_commands>env = Environment(tools=['docbook'])
 555 env.DocbookSlidesHtml('manual')
 556 </example_commands>
 557
 558 <para>If you use the <parameter>titlefoil.html</parameter> parameter in
 559 your own stylesheets you have to give the new target name. This ensures
 560 that the dependencies get correct, especially for the cleanup via
 561 <quote><userinput>scons -c</userinput></quote>:
 562 </para>
 563 <screen>env = Environment(tools=['docbook'])
 564 env.DocbookSlidesHtml('mymanual.html','manual', xsl='slideshtml.xsl')
 565 </screen>
 566
 567 <para>Some basic support for the <parameter>base.dir</parameter> parameter
 568 is provided. You
 569 can add the <parameter>base_dir</parameter> keyword to your Builder
 570 call, and the given prefix gets prepended to all the created filenames:
 571 </para>
 572 <screen>env = Environment(tools=['docbook'])
 573 env.DocbookSlidesHtml('manual', xsl='slideshtml.xsl', base_dir='output/')
 574 </screen>
 575 <para>Make sure that you don't forget the trailing slash for the base folder, else
 576 your files get renamed only!
 577 </para>
 578
 579 </summary>
 580 </builder>
 581
 582 <builder name="DocbookXInclude">
 583 <summary>
 584 <para>
 585 A pseudo-Builder, for resolving XIncludes in a separate processing step.
 586 </para>
 587
 588 <example_commands>env = Environment(tools=['docbook'])
 589 env.DocbookXInclude('manual_xincluded.xml', 'manual.xml')
 590 </example_commands>
 591 </summary>
 592 </builder>
 593
 594 <builder name="DocbookXslt">
 595 <summary>
 596 <para>
 597 A pseudo-Builder, applying a given XSL transformation to the input file.
 598 </para>
 599
 600 <example_commands>env = Environment(tools=['docbook'])
 601 env.DocbookXslt('manual_transformed.xml', 'manual.xml', xsl='transform.xslt')
 602 </example_commands>
 603
 604 <para>Note, that this builder requires the <parameter>xsl</parameter> parameter
 605 to be set.
 606 </para>
 607 </summary>
 608 </builder>
 609
 610 </sconsdoc>