From 140d836e9cd54fb67b969fd82ef7ed19ba574d40 Mon Sep 17 00:00:00 2001 From: Luca Falavigna Date: Sat, 26 Apr 2014 15:11:58 +0200 Subject: Imported Upstream version 2.3.1 --- src/engine/SCons/Tool/docbook/docs/SConstruct | 34 ++++ src/engine/SCons/Tool/docbook/docs/html.xsl | 55 ++++++ src/engine/SCons/Tool/docbook/docs/manual.xml | 270 ++++++++++++++++++++++++++ src/engine/SCons/Tool/docbook/docs/pdf.xsl | 62 ++++++ 4 files changed, 421 insertions(+) create mode 100644 src/engine/SCons/Tool/docbook/docs/SConstruct create mode 100644 src/engine/SCons/Tool/docbook/docs/html.xsl create mode 100644 src/engine/SCons/Tool/docbook/docs/manual.xml create mode 100644 src/engine/SCons/Tool/docbook/docs/pdf.xsl (limited to 'src/engine/SCons/Tool/docbook/docs') diff --git a/src/engine/SCons/Tool/docbook/docs/SConstruct b/src/engine/SCons/Tool/docbook/docs/SConstruct new file mode 100644 index 0000000..4c048d5 --- /dev/null +++ b/src/engine/SCons/Tool/docbook/docs/SConstruct @@ -0,0 +1,34 @@ +# +# Copyright (c) 2001-2010 The SCons Foundation +# +# Permission is hereby granted, free of charge, to any person obtaining +# a copy of this software and associated documentation files (the +# "Software"), to deal in the Software without restriction, including +# without limitation the rights to use, copy, modify, merge, publish, +# distribute, sublicense, and/or sell copies of the Software, and to +# permit persons to whom the Software is furnished to do so, subject to +# the following conditions: +# +# The above copyright notice and this permission notice shall be included +# in all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY +# KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE +# WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE +# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION +# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + + +import os + +env = Environment(ENV = os.environ, + tools = ['docbook']) + +env.DocbookPdf('manual', xsl='pdf.xsl') +#env.DocbookPdf('reference', xsl='pdf.xsl') + +env.DocbookHtml('manual', xsl='html.xsl') +#env.DocbookHtml('reference', xsl='html.xsl') + diff --git a/src/engine/SCons/Tool/docbook/docs/html.xsl b/src/engine/SCons/Tool/docbook/docs/html.xsl new file mode 100644 index 0000000..f53e1b3 --- /dev/null +++ b/src/engine/SCons/Tool/docbook/docs/html.xsl @@ -0,0 +1,55 @@ + + + + + + + + + + +/appendix toc,title +article/appendix nop +/article toc,title +book toc,title,figure,table,example,equation +/chapter toc,title +part toc,title +/preface toc,title +reference toc,title +/sect1 toc +/sect2 toc +/sect3 toc +/sect4 toc +/sect5 toc +/section toc +set toc,title + + + + diff --git a/src/engine/SCons/Tool/docbook/docs/manual.xml b/src/engine/SCons/Tool/docbook/docs/manual.xml new file mode 100644 index 0000000..e232c6a --- /dev/null +++ b/src/engine/SCons/Tool/docbook/docs/manual.xml @@ -0,0 +1,270 @@ + + + +
+ The SCons Docbook tool + + + Dirk Baechle + + 2010-12-30 + +
Basics +This tool tries to make working with Docbook in SCons a little easier. +It provides several toolchains for creating different output formats, +like HTML or PDF. Contained in the package is +a distribution of the Docbook XSL stylesheets as of version 1.76.1. +As long as you don't specify your own stylesheets for customization (see Selecting stylesheet), +these official versions are picked as default...which should reduce +the inevitable setup hassles for you. + +Implicit dependencies to images and XIncludes are detected automatically +if you meet the HTML requirements (see Requirements). The additional +stylesheet utils/xmldepend.xsl by Paul DuBois is used for this purpose. + +Note, that there is no support for XML catalog resolving offered! This tool calls +the XSLT processors and PDF renderers with the stylesheets you specified, that's it. +The rest lies in your hands and you still have to know what you're doing when +resolving names via a catalog. + +
Install +Installing it, requires you to copy (or, even better: checkout) the contents of the +package's docbook folder to + +/path_to_your_project/site_scons/site_tools/docbook, if you need the Docbook Tool in one project only, or + + +~/.scons/site_scons/site_tools/docbook, for a system-wide installation under your current login. + + + +For more infos about this, please refer to + +the SCons User's Guide, chap. 19.7 "Where to put your custom Builders and Tools" and + + +the SCons Tools Wiki page at http://scons.org/wiki/ToolsIndex. + + + +
+
How to activate +For activating the tool "docbook", you have to add its name to the Environment constructor, +like this + +env = Environment(tools=['docbook']) + +On its startup, the Docbook tool tries to find a required xsltproc processor, and +a PDF renderer, e.g. fop. So make sure that these are added to your system's environment +PATH and can be called directly, without specifying their full path. + +
+
Requirements +For the most basic processing of Docbook to HTML, you need to have installed + +the Python lxml binding to libxml2, or + + +the direct Python bindings for libxml2/libxslt, or + + +a standalone XSLT processor, currently detected are xsltproc, saxon, saxon-xslt +and xalan. + + + +Rendering to PDF requires you to have one of the applications fop, xep or jw +installed. + +
+
+
Processing documents +Creating a HTML or PDF document is very simple and straightforward. Say + +env = Environment(tools=['docbook']) +env.DocbookHtml('manual.html', 'manual.xml') +env.DocbookPdf('manual.pdf', 'manual.xml') + +to get both outputs from your XML source manual.xml. As a shortcut, you can +give the stem of the filenames alone, like this: + +env = Environment(tools=['docbook']) +env.DocbookHtml('manual') +env.DocbookPdf('manual') + +and get the same result. Target and source lists are also supported: + +env = Environment(tools=['docbook']) +env.DocbookHtml(['manual.html','reference.html'], ['manual.xml','reference.xml']) + +or even + +env = Environment(tools=['docbook']) +env.DocbookHtml(['manual','reference']) + +Whenever you leave out the list of sources, you may not specify a file extension! The +Tool uses the given names as file stems, and adds the suffixes for target and source files +accordingly. + + +The rules given above are valid for the Builders DocbookHtml, DocbookPdf, +DocbookSlidePdf and DocbookXInclude. For the DocbookMan transformation you +can specify a target name, but the actual output names are automatically set from +the refname entries in your XML source. + +Please refer to the section Chunked output for more infos about the other Builders. + +
+
Selecting your own stylesheet +If you want to use a specific XSL file, you can set the additional xsl parameter to your +Builder call as follows: + +env.DocbookHtml('other.html', 'manual.xml', xsl='html.xsl') + +Since this may get tedious if you always use the same local naming for your customized XSL files, +e.g. html.xsl for HTML and pdf.xsl for PDF output, a set of variables for setting the +default XSL name is provided. These are: + +DOCBOOK_DEFAULT_XSL_HTML +DOCBOOK_DEFAULT_XSL_HTMLCHUNKED +DOCBOOK_DEFAULT_XSL_HTMLHELP +DOCBOOK_DEFAULT_XSL_PDF +DOCBOOK_DEFAULT_XSL_MAN +DOCBOOK_DEFAULT_XSL_SLIDESPDF +DOCBOOK_DEFAULT_XSL_SLIDESHTML + +and you can set them when constructing your environment: + +env = Environment(tools=['docbook'], + DOCBOOK_DEFAULT_XSL_HTML='html.xsl', + DOCBOOK_DEFAULT_XSL_PDF='pdf.xsl') +env.DocbookHtml('manual') # now uses html.xsl + +
+
Chunked output +The Builders DocbookHtmlChunked, DocbookHtmlhelp and DocbookSlidesHtml +are special, in that: + +they create a large set of files, where the exact names and their number depend +on the content of the source file, and + + +the main target is always named index.html, i.e. the output name for the +XSL transformation is not picked up by the stylesheets. + + + +As a result, there is simply no use in specifying a target HTML name. +So the basic syntax for these builders is: + +env = Environment(tools=['docbook']) +env.DocbookHtmlhelp('manual') + +Only if you use the root.filename (titlefoil.html for slides) parameter in +your own stylesheets you have to give the new target name. This ensures that the +dependencies get correct, especially for the cleanup via scons -c: + +env = Environment(tools=['docbook']) +env.DocbookHtmlhelp('mymanual.html','manual', xsl='htmlhelp.xsl') + +Some basic support for the base.dir is added (this has not been properly tested +with variant dirs, yet!). You can add the base_dir keyword to your Builder +call, and the given prefix gets prepended to all the created filenames: + +env = Environment(tools=['docbook']) +env.DocbookHtmlhelp('manual', xsl='htmlhelp.xsl', base_dir='output/') + +Make sure that you don't forget the trailing slash for the base folder, else +your files get renamed only! + +
+
All builders +A simple list of all builders currently available: + +DocbookHtml + +Single HTML file. + + + +DocbookHtmlChunked + +Chunked HTML files, with support for the base.dir parameter. The chunkfast.xsl +file (requires "EXSLT") is used as the default stylesheet. + + + +DocbookHtmlhelp + +Htmlhelp files, with support for base.dir. + + + +DocbookPdf + +PDF output. + + + +DocbookMan + +Man pages. + + + +DocbookSlidesPdf + +Slides in PDF format. + + + +DocbookSlidesHtml + +Slides in HTML format, with support for base.dir. + + + +DocbookXInclude + +Can be used to resolve XIncludes in a preprocessing step. + + + + +
+
Need more? +This work is still in a very basic state and hasn't been tested well +with things like variant dirs, yet. Unicode problems and poor performance +with large input files may occur. There will definitely arise the need for +adding features, or a variable. Let us know if you can think of a nice +improvement or have worked on a bugfix/patch with success. Enter your issues at the +Launchpad bug tracker for the Docbook Tool, or write to the User General Discussion +list of SCons at users@scons.tigris.org. + +
+ +
diff --git a/src/engine/SCons/Tool/docbook/docs/pdf.xsl b/src/engine/SCons/Tool/docbook/docs/pdf.xsl new file mode 100644 index 0000000..25b4433 --- /dev/null +++ b/src/engine/SCons/Tool/docbook/docs/pdf.xsl @@ -0,0 +1,62 @@ + + + + + + + + + + +0pt + + +/appendix toc,title +article/appendix nop +/article toc,title +book toc,title,figure,table,example,equation +/chapter toc,title +part toc,title +/preface toc,title +reference toc,title +/sect1 toc +/sect2 toc +/sect3 toc +/sect4 toc +/sect5 toc +/section toc +set toc,title + + + + + + + + -- cgit v1.2.3