- added EPUB Builder to the DocBook Tool, based on the work of Andrew Featherstone

3 files changed, 452 insertions, 0 deletions

diff --git a/test/Docbook/basic/epub/epub.py b/test/Docbook/basic/epub/epub.py
new file mode 100644
index 00000000..c819dd78
--- /dev/null
+++ b/test/Docbook/basic/epub/epub.py
@@ -0,0 +1,62 @@
+#!/usr/bin/env python
+#
+# 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.
+#
+
+"""
+Test the EPUB builder.
+"""
+
+import TestSCons
+
+test = TestSCons.TestSCons()
+
+try:
+    import libxml2
+except:
+    try:
+        import lxml
+    except:
+        test.skip_test('Cannot find installed Python binding for libxml2 or lxml, skipping test.\n')
+
+test.dir_fixture('image')
+
+# Normal invocation
+test.run()
+test.must_exist(test.workpath('manual.epub'))
+test.must_exist(test.workpath('OEBPS','toc.ncx'))
+test.must_exist(test.workpath('OEBPS','content.opf'))
+test.must_exist(test.workpath('META-INF','container.xml'))
+
+# Cleanup
+test.run(arguments='-c')
+test.must_not_exist(test.workpath('manual.epub'))
+test.must_not_exist(test.workpath('OEBPS'))
+test.must_not_exist(test.workpath('META-INF'))
+
+test.pass_test()
+
+# Local Variables:
+# tab-width:4
+# indent-tabs-mode:nil
+# End:
+# vim: set expandtab tabstop=4 shiftwidth=4:
diff --git a/test/Docbook/basic/epub/image/SConstruct b/test/Docbook/basic/epub/image/SConstruct
new file mode 100644
index 00000000..16a06996
--- /dev/null
+++ b/test/Docbook/basic/epub/image/SConstruct
@@ -0,0 +1,2 @@
+env = Environment(tools=['docbook'])
+env.DocbookEpub('manual')
diff --git a/test/Docbook/basic/epub/image/manual.xml b/test/Docbook/basic/epub/image/manual.xml
new file mode 100644
index 00000000..ca12e0ed
--- /dev/null
+++ b/test/Docbook/basic/epub/image/manual.xml
@@ -0,0 +1,388 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+  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.
+
+-->
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+<article>
+  <title>The SCons qt4 tool</title>
+
+  <articleinfo>
+    <author>
+      <surname>Dirk Baechle</surname>
+    </author>
+
+    <pubdate>2010-12-06</pubdate>
+  </articleinfo>
+
+  <section id="basics">
+    <title>Basics</title>
+
+    <para>This tool can be used to compile Qt projects, designed for versions
+    4.x.y and higher. It is not usable for Qt3 and older versions, since some
+    of the helper tools (<literal>moc</literal>, <literal>uic</literal>)
+    behave different.</para>
+
+    <section id="install">
+      <title>Install</title>
+
+      <para>Installing it, requires you to copy (or, even better: checkout)
+      the contents of the package's <literal>qt4</literal> folder to</para>
+
+      <orderedlist>
+        <listitem>
+          <para><quote><literal>/path_to_your_project/site_scons/site_tools/qt4</literal></quote>,
+          if you need the Qt4 Tool in one project only, or</para>
+        </listitem>
+
+        <listitem>
+          <para><quote><literal>~/.scons/site_scons/site_tools/qt4</literal></quote>,
+          for a system-wide installation under your current login.</para>
+        </listitem>
+      </orderedlist>
+
+      <para>For more infos about this, please refer to</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>the SCons User's Guide, chap. 17.7 "Where to put your custom
+          Builders and Tools" and</para>
+        </listitem>
+
+        <listitem>
+          <para>the SCons Tools Wiki page at <ulink
+          url="http://scons.org/wiki/ToolsIndex">http://scons.org/wiki/ToolsIndex</ulink>.</para>
+        </listitem>
+      </itemizedlist>
+    </section>
+
+    <section id="activation">
+      <title>How to activate</title>
+
+      <para>For activating the tool "qt4", you have to add its name to the
+      Environment constructor, like this</para>
+
+      <screen>env = Environment(tools=['default','qt4'])
+</screen>
+
+      <para>On its startup, the Qt4 tool tries to read the variable
+      <literal>QT4DIR</literal> from the current Environment and
+      <literal>os.environ</literal>. If it is not set, the value of
+      <literal>QTDIR</literal> (in Environment/<literal>os.environ</literal>)
+      is used as a fallback.</para>
+
+      <para>So, you either have to explicitly give the path of your Qt4
+      installation to the Environment with</para>
+
+      <screen>env['QT4DIR'] = '/usr/local/Trolltech/Qt-4.2.3'
+</screen>
+
+      <para>or set the <literal>QT4DIR</literal> as environment variable in
+      your shell.</para>
+    </section>
+
+    <section id="requirements">
+      <title>Requirements</title>
+
+      <para>Under Linux, "qt4" uses the system tool
+      <literal>pkg-config</literal> for automatically setting the required
+      compile and link flags of the single Qt4 modules (like QtCore,
+      QtGui,...). This means that</para>
+
+      <orderedlist>
+        <listitem>
+          <para>you should have <literal>pkg-config</literal> installed,
+          and</para>
+        </listitem>
+
+        <listitem>
+          <para>you additionally have to set
+          <literal>PKG_CONFIG_PATH</literal> in your shell environment, such
+          that it points to $<literal>QT4DIR/lib/pkgconfig</literal> (or
+          $<literal>QT4DIR/lib</literal> for some older versions).</para>
+        </listitem>
+      </orderedlist>
+
+      <para>Based on these two environment variables
+      (<literal>QT4DIR</literal> and <literal>PKG_CONFIG_PATH</literal>), the
+      "qt4" tool initializes all <literal>QT4_*</literal> construction
+      variables listed in the Reference manual. This happens when the tool is
+      "detected" during Environment construction. As a consequence, the setup
+      of the tool gets a two-stage process, if you want to override the values
+      provided by your current shell settings:</para>
+
+      <screen># Stage 1: create plain environment
+qtEnv = Environment()
+# Set new vars
+qtEnv['QT4DIR'] = '/usr/local/Trolltech/Qt-4.2.3
+qtEnv['ENV']['PKG_CONFIG_PATH'] = '/usr/local/Trolltech/Qt-4.2.3/lib/pkgconfig'
+# Stage 2: add qt4 tool
+qtEnv.Tool('qt4')
+</screen>
+    </section>
+  </section>
+
+  <section id="boilerplate">
+    <title>Suggested boilerplate</title>
+
+    <para>Based on the requirements above, we suggest a simple ready-to-go
+    setup as follows:</para>
+
+    <para>SConstruct</para>
+
+    <screen># Detect Qt version
+qtdir = detectLatestQtDir()
+
+# Create base environment
+baseEnv = Environment()
+#...further customization of base env
+
+# Clone Qt environment
+qtEnv = baseEnv.Clone()
+# Set QT4DIR and PKG_CONFIG_PATH
+qtEnv['ENV']['PKG_CONFIG_PATH'] = os.path.join(qtdir, 'lib/pkgconfig')
+qtEnv['QT4DIR'] = qtdir
+# Add qt4 tool
+qtEnv.Tool('qt4')
+#...further customization of qt env
+
+# Export environments
+Export('baseEnv qtEnv')
+
+# Your other stuff...
+# ...including the call to your SConscripts
+</screen>
+
+    <para>In a SConscript</para>
+
+    <screen># Get the Qt4 environment
+Import('qtEnv')
+# Clone it
+env = qtEnv.clone()
+# Patch it
+env.Append(CCFLAGS=['-m32']) # or whatever
+# Use it
+env.StaticLibrary('foo', Glob('*.cpp'))
+</screen>
+
+    <para>The detection of the Qt directory could be as simple as directly
+    assigning a fixed path</para>
+
+    <screen>def detectLatestQtDir():
+    return "/usr/local/qt4.3.2"
+</screen>
+
+    <para>or a little more sophisticated</para>
+
+    <screen># Tries to detect the path to the installation of Qt with
+# the highest version number
+def detectLatestQtDir():
+    if sys.platform.startswith("linux"):
+        # Simple check: inspect only '/usr/local/Trolltech'
+        paths = glob.glob('/usr/local/Trolltech/*')
+        if len(paths):
+            paths.sort()
+            return paths[-1]
+        else:
+            return ""
+    else:
+        # Simple check: inspect only 'C:\Qt'
+        paths = glob.glob('C:\\Qt\\*')
+        if len(paths):
+            paths.sort()
+            return paths[-1]
+        else:
+            return os.environ.get("QTDIR","")
+</screen>
+  </section>
+
+  <section id="firstproject">
+    <title>A first project</title>
+
+    <para>The following SConscript is for a simple project with some cxx
+    files, using the QtCore, QtGui and QtNetwork modules:</para>
+
+    <screen>Import('qtEnv')
+env = qtEnv.Clone()
+env.EnableQt4Modules([
+                      'QtGui',
+                      'QtCore',
+                      'QtNetwork'
+                     ])
+# Add your CCFLAGS and CPPPATHs to env here...
+
+env.Program('foo', Glob('*.cpp')) 
+</screen>
+  </section>
+
+  <section id="mocup">
+    <title>MOC it up</title>
+
+    <para>For the basic support of automocing, nothing needs to be done by the
+    user. The tool usually detects the <literal>Q_OBJECT</literal> macro and
+    calls the <quote><literal>moc</literal></quote> executable
+    accordingly.</para>
+
+    <para>If you don't want this, you can switch off the automocing by
+    a</para>
+
+    <screen>env['QT4_AUTOSCAN'] = 0
+</screen>
+
+    <para>in your SConscript file. Then, you have to moc your files
+    explicitly, using the Moc4 builder.</para>
+
+    <para>You can also switch to an extended automoc strategy with</para>
+
+    <screen>env['QT4_AUTOSCAN_STRATEGY'] = 1
+</screen>
+
+    <para>Please read the description of the
+    <literal>QT4_AUTOSCAN_STRATEGY</literal> variable in the Reference manual
+    for details.</para>
+
+    <para>For debugging purposes, you can set the variable
+    <literal>QT4_DEBUG</literal> with</para>
+
+    <screen>env['QT4_DEBUG'] = 1
+</screen>
+
+    <para>which outputs a lot of messages during automocing.</para>
+  </section>
+
+  <section id="forms">
+    <title>Forms (.ui)</title>
+
+    <para>The header files with setup code for your GUI classes, are not
+    compiled automatically from your <literal>.ui</literal> files. You always
+    have to call the Uic4 builder explicitly like</para>
+
+    <screen>env.Uic4(Glob('*.ui'))
+env.Program('foo', Glob('*.cpp'))
+</screen>
+  </section>
+
+  <section id="resources">
+    <title>Resource files (.qrc)</title>
+
+    <para>Resource files are not built automatically, you always have to add
+    the names of the <literal>.qrc</literal> files to the source list for your
+    program or library:</para>
+
+    <screen>env.Program('foo', Glob('*.cpp')+Glob('*.qrc'))
+</screen>
+
+    <para>For each of the Resource input files, its prefix defines the name of
+    the resulting resource. An appropriate
+    <quote><literal>-name</literal></quote> option is added to the call of the
+    <literal>rcc</literal> executable by default.</para>
+
+    <para>You can also call the Qrc4 builder explicitly as</para>
+
+    <screen>qrccc = env.Qrc4('foo') # ['foo.qrc'] -&gt; ['qrc_foo.cc']
+</screen>
+
+    <para>or (overriding the default suffix)</para>
+
+    <screen>qrccc = env.Qrc4('myprefix_foo.cxx','foo.qrc') # -&gt; ['qrc_myprefix_foo.cxx']
+</screen>
+
+    <para>and then add the resulting cxx file to the sources of your
+    Program/Library:</para>
+
+    <screen>env.Program('foo', Glob('*.cpp') + qrccc)
+</screen>
+  </section>
+
+  <section id="translation">
+    <title>Translation files</title>
+
+    <para>The update of the <literal>.ts</literal> files and the conversion to
+    binary <literal>.qm</literal> files is not done automatically. You have to
+    call the corresponding builders on your own.</para>
+
+    <para>Example for updating a translation file:</para>
+
+    <screen>env.Ts4('foo.ts','.') # -&gt; ['foo.ts']
+</screen>
+
+    <para>By default, the <literal>.ts</literal> files are treated as
+    <emphasis>precious</emphasis> targets. This means that they are not
+    removed prior to a rebuild, but simply get updated. Additionally, they do
+    not get cleaned on a <quote><literal>scons -c</literal></quote>. If you
+    want to delete the translation files on the
+    <quote><literal>-c</literal></quote> SCons command, you can set the
+    variable <quote><literal>QT4_CLEAN_TS</literal></quote> like this</para>
+
+    <screen>env['QT4_CLEAN_TS']=1
+</screen>
+
+    <para>Example for releasing a translation file, i.e. compiling it to a
+    <literal>.qm</literal> binary file:</para>
+
+    <screen>env.Qm4('foo') # ['foo.ts'] -&gt; ['foo.qm']
+</screen>
+
+    <para>or (overriding the output prefix)</para>
+
+    <screen>env.Qm4('myprefix','foo') # ['foo.ts'] -&gt; ['myprefix.qm']
+</screen>
+
+    <para>As an extension both, the Ts4() and Qm4 builder, support the
+    definition of multiple targets. So, calling</para>
+
+    <screen>env.Ts4(['app_en','app_de'], Glob('*.cpp'))
+</screen>
+
+    <para>and</para>
+
+    <screen>env.Qm4(['app','copy'], Glob('*.ts'))
+</screen>
+
+    <para>should work fine.</para>
+
+    <para>Finally, two short notes about the support of directories for the
+    Ts4() builder. You can pass an arbitrary mix of cxx files and subdirs to
+    it, as in</para>
+
+    <screen>env.Ts4('app_en',['sub1','appwindow.cpp','main.cpp']))
+</screen>
+
+    <para>where <literal>sub1</literal> is a folder that gets scanned
+    recursively for cxx files by <literal>lupdate</literal>. But like this,
+    you lose all dependency information for the subdir, i.e. if a file inside
+    the folder changes, the .ts file is not updated automatically! In this
+    case you should tell SCons to always update the target:</para>
+
+    <screen>ts = env.Ts4('app_en',['sub1','appwindow.cpp','main.cpp'])
+env.AlwaysBuild(ts)
+</screen>
+
+    <para>Last note: specifying the current folder
+    <quote><literal>.</literal></quote> as input to Ts4() and storing the
+    resulting .ts file in the same directory, leads to a dependency cycle! You
+    then have to store the .ts and .qm files outside of the current folder, or
+    use <literal>Glob('*.cpp'))</literal> instead.</para>
+  </section>
+</article>