Merged in dirkbaechle/scons (pull request #121)

Fixes for doc toolchain

20 files changed, 312 insertions, 176 deletions

diff --git a/doc/SConscript b/doc/SConscript
index c731dabbc..d5cd01c98 100644
--- a/doc/SConscript
+++ b/doc/SConscript
@@ -42,6 +42,7 @@ fop = whereis('fop')
 xep = whereis('xep')
 epydoc_cli = whereis('epydoc')
 gs = whereis('gs')
+lynx = whereis('lynx')
 
 #
 #
@@ -96,6 +97,9 @@ if not fop and not xep:
 if skip_doc:
     print "doc: ...skipping building User Guide."
 else:
+    if not lynx:
+        print "doc: Warning, lynx is not installed...created release packages won't be complete!"
+    
     #
     # Always create a version.xml file containing the version information
     # for this run.  Ignore it for dependency purposes so we don't
@@ -104,7 +108,65 @@ else:
     date, ver, rev = env.Dictionary('DATE', 'VERSION', 'REVISION')
     version_xml = File(os.path.join(build, "version.xml"))
     writeVersionXml(str(version_xml), date, ver, rev)
-    
+
+    import shutil
+    import SCons.Builder
+    import SCons.Util
+    #
+    # Builder for copying files to an Install dir, based
+    # on their extension (better: glob matching pattern)...
+    #    
+    def _glob_install_action(target, source, env):
+        if not SCons.Util.is_List(target):
+            target = [target]
+        if not SCons.Util.is_List(source):
+            source = [source]
+        for t, s in zip(target, source):
+            shutil.copy(str(s), str(t))
+    def _glob_install_emitter(target, source, env):
+        if not SCons.Util.is_List(target):
+            target = [target]
+        if not SCons.Util.is_List(source):
+            source = [source]
+            
+        res = []
+        res_src = []
+        tdir = env.Dir(target[0])
+        for g in glob.glob(str(source[0])):
+            head, tail = os.path.split(g)
+            res.append(os.path.join(str(tdir), tail))
+            res_src.append(g)
+        return res, res_src
+    _glob_install_builder = SCons.Builder.Builder(action=_glob_install_action,
+                                                  emitter=_glob_install_emitter)
+    env['BUILDERS']['GlobInstall'] = _glob_install_builder
+
+    #
+    # Builder for copying ChunkedHTML files to an Install dir...
+    #    
+    def _chunked_install_action(target, source, env):
+        if not SCons.Util.is_List(target):
+            target = [target]
+        if not SCons.Util.is_List(source):
+            source = [source]
+        tdir, tail = os.path.split(str(target[0]))
+        spattern = os.path.join(os.path.split(str(source[0]))[0], '*.html')
+        for g in glob.glob(spattern):
+            shutil.copy(g, tdir)
+            
+    def _chunked_install_emitter(target, source, env):
+        if not SCons.Util.is_List(target):
+            target = [target]
+        if not SCons.Util.is_List(source):
+            source = [source]
+            
+        tdir = env.Dir(target[0])
+        head, tail = os.path.split(str(source[0]))
+        return os.path.join(str(tdir), tail), source
+    _chunked_install_builder = SCons.Builder.Builder(action=_chunked_install_action,
+                                                     emitter=_chunked_install_emitter)
+    env['BUILDERS']['ChunkedInstall'] = _chunked_install_builder
+
     if not env.GetOption('clean'):
         #
         # Ensure that all XML files are valid against our XSD, and
@@ -124,69 +186,64 @@ else:
             print "Not all example names and suffixes are unique! Please correct the errors listed above and try again."
             sys.exit(0)
     
-        #
-        # Copy generated files (.gen/.mod/.xml) to the build folder
-        #
-        env.Execute(Mkdir(os.path.join(build, 'generated')))
-        env.Execute(Mkdir(os.path.join(build, 'generated', 'examples')))
-        for g in glob.glob(os.path.join('generated', '*.gen')):
-            env.Execute(Copy(os.path.join(build, 'generated'), g))
-        for g in glob.glob(os.path.join('generated', '*.mod')):
-            env.Execute(Copy(os.path.join(build, 'generated'), g))
-        for g in glob.glob(os.path.join('generated', 'examples', '*')):
-            env.Execute(Copy(os.path.join(build, 'generated', 'examples'), g))
-
-        #
-        # Copy XSLT files (.xslt) to the build folder
-        #
-        env.Execute(Mkdir(os.path.join(build, 'xslt')))
-        for g in glob.glob(os.path.join('xslt','*.*')):
-            env.Execute(Copy(os.path.join(build, 'xslt'), g))
+    # List of prerequisite files in the build/doc folder
+    buildsuite = []
+    
+    def copy_dbfiles(env, toolpath, paths, fpattern, use_builddir=True):
+        """ Helper function, copies a bunch of files matching
+            the given fpattern to a target directory.
+        """
+        global buildsuite
+        if not SCons.Util.is_List(toolpath):
+            toolpath = [toolpath]
+        if not SCons.Util.is_List(paths):
+            paths = [paths]
+        if not SCons.Util.is_List(fpattern):
+            fpattern = [fpattern]
+
+        if use_builddir:
+            target_dir = env.Dir(os.path.join(build_dir, *(toolpath+paths)))
+            buildsuite.extend(env.GlobInstall(target_dir,
+                                              os.path.join('..', *(toolpath+paths+fpattern))))
+        else:
+            target_dir = env.Dir(os.path.join(*(toolpath+paths)))
+            buildsuite.extend(env.GlobInstall(target_dir,
+                                              os.path.join(*(paths + fpattern))))
+    
+    #
+    # Copy generated files (.gen/.mod/.xml) to the build folder
+    #
+    copy_dbfiles(env, build, 'generated', '*.gen', False)
+    copy_dbfiles(env, build, 'generated', '*.mod', False)
+    copy_dbfiles(env, build, ['generated','examples'], '*', False)
 
-        #
-        # Copy Docbook stylesheets and Tool to the build folder
-        #
-        dbtoolpath = ['src', 'engine', 'SCons', 'Tool', 'docbook']
-        env.Execute(Mkdir(os.path.join(build_dir, *dbtoolpath)))
-        env.Execute(Mkdir(os.path.join(build_dir, *(dbtoolpath + ['utils']))))
-        env.Execute(Copy(os.path.join(build_dir, *dbtoolpath),
-                         os.path.join('..', *(dbtoolpath + ['__init__.py']))))
-        env.Execute(Copy(os.path.join(build_dir, *(dbtoolpath + ['utils'])),
-                         os.path.join('..', *(dbtoolpath + ['utils', 'xmldepend.xsl']))))
-        dbpath = dbtoolpath + ['docbook-xsl-1.76.1']
-        env.Execute(Mkdir(os.path.join(build_dir, *(dbpath + ['common']))))
-        env.Execute(Mkdir(os.path.join(build_dir, *(dbpath + ['lib']))))
-        env.Execute(Mkdir(os.path.join(build_dir, *(dbpath + ['html']))))
-        env.Execute(Mkdir(os.path.join(build_dir, *(dbpath + ['fo']))))
-        env.Execute(Mkdir(os.path.join(build_dir, *(dbpath + ['manpages']))))
-        env.Execute(Mkdir(os.path.join(build_dir, *(dbpath + ['epub']))))
-        env.Execute(Mkdir(os.path.join(build_dir, *(dbpath + ['xhtml-1_1']))))
-        env.Execute(Copy(os.path.join(build_dir, *dbpath),
-                         os.path.join('..', *(dbpath + ['VERSION']))))
-        for g in glob.glob(os.path.join('..', *(dbpath + ['common', '*.*']))):
-            env.Execute(Copy(os.path.join(build_dir, *(dbpath + ['common'])), g))
-        for g in glob.glob(os.path.join('..', *(dbpath + ['lib', '*.*']))):
-            env.Execute(Copy(os.path.join(build_dir, *(dbpath + ['lib'])), g))
-        for g in glob.glob(os.path.join('..', *(dbpath + ['html', '*.*']))):
-            env.Execute(Copy(os.path.join(build_dir, *(dbpath + ['html'])), g))
-        for g in glob.glob(os.path.join('..', *(dbpath + ['fo', '*.*']))):
-            env.Execute(Copy(os.path.join(build_dir, *(dbpath + ['fo'])), g))
-        for g in glob.glob(os.path.join('..', *(dbpath + ['manpages', '*.*']))):
-            env.Execute(Copy(os.path.join(build_dir, *(dbpath + ['manpages'])), g))
-        for g in glob.glob(os.path.join('..', *(dbpath + ['epub', '*.xsl']))):
-            env.Execute(Copy(os.path.join(build_dir, *(dbpath + ['epub'])), g))
-        for g in glob.glob(os.path.join('..', *(dbpath + ['xhtml-1_1', '*.*']))):
-            env.Execute(Copy(os.path.join(build_dir, *(dbpath + ['xhtml-1_1'])), g))
+    #
+    # Copy XSLT files (.xslt) to the build folder
+    #
+    copy_dbfiles(env, build, 'xslt', '*.*', False)
 
-        #
-        # Copy additional Tools (gs, zip)
-        #
-        toolpath = ['src', 'engine', 'SCons', 'Tool']
-        env.Execute(Copy(os.path.join(build_dir, *toolpath),
-                         os.path.join('..', *(toolpath + ['gs.py']))))
-        env.Execute(Copy(os.path.join(build_dir, *toolpath),
-                         os.path.join('..', *(toolpath + ['zip.py']))))
+    #
+    # Copy DocBook stylesheets and Tool to the build folder
+    #
+    dbtoolpath = ['src', 'engine', 'SCons', 'Tool', 'docbook']
+    copy_dbfiles(env, dbtoolpath, [], '__init__.py')
+    copy_dbfiles(env, dbtoolpath, 'utils', 'xmldepend.xsl')
+    dbpath = dbtoolpath + ['docbook-xsl-1.76.1']
+    copy_dbfiles(env, dbpath, [], 'VERSION')
+    copy_dbfiles(env, dbpath, ['common'], '*.*')
+    copy_dbfiles(env, dbpath, ['lib'], '*.*')
+    copy_dbfiles(env, dbpath, ['html'], '*.*')
+    copy_dbfiles(env, dbpath, ['fo'], '*.*')
+    copy_dbfiles(env, dbpath, ['manpages'], '*.*')
+    copy_dbfiles(env, dbpath, ['epub'], '*.xsl')
+    copy_dbfiles(env, dbpath, ['xhtml-1_1'], '*.*')
 
+    #
+    # Copy additional Tools (gs, zip)
+    #
+    toolpath = ['src', 'engine', 'SCons', 'Tool']
+    copy_dbfiles(env, toolpath, [], 'gs.py')
+    copy_dbfiles(env, toolpath, [], 'zip.py')
 
     #
     # Each document will live in its own subdirectory.  List them here
@@ -195,13 +252,14 @@ else:
     # of the outputs get installed to the build folder and added to
     # the different source and binary packages in the end.
     #
-    docs = {'design' : ['chtml','pdf'],
-            #'python10' : ['chtml','html','pdf'],
-            'reference' : ['chtml','html','pdf'],
-            #'developer' : ['chtml','html','pdf'],
-            'user' : ['chtml','html','pdf','epub'],
-            'man' : ['man','epub']
+    docs = {'design' : ['chunked','pdf'],
+            #'python10' : ['chunked','html','pdf'],
+            'reference' : ['chunked','html','pdf'],
+            #'developer' : ['chunked','html','pdf'],
+            'user' : ['chunked','html','pdf','epub','text'],
+            'man' : ['man','epub','text']
            }
+           
     # The names of the target files for the MAN pages
     man_page_list = ['scons.1','scons-time.1','sconsign.1']
     
@@ -216,15 +274,13 @@ else:
             continue
         base, ext = os.path.splitext(s)
         if ext in ['.fig', '.jpg']:
-            env.Execute(Copy(build, s))
+            buildsuite.extend(env.Command(os.path.join(build, s), 
+                                          s, 
+                                          Copy("$TARGET", "$SOURCE")))
         else:
-            revaction([env.File(os.path.join(build, s))], 
+            revaction([env.File(os.path.join(build, s))],
                       [env.File(s)], env)
 
-    #
-    # For each document, build the document itself in HTML,
-    # and PDF formats.
-    #
     for doc in docs:
         
         #
@@ -232,8 +288,10 @@ else:
         # build directory, while branding them with the
         # SCons copyright and the current revision number...
         #
-        env.Execute(Mkdir(os.path.join(build, doc)))
-        env.Execute(Mkdir(os.path.join(build, doc, 'titlepage')))
+        if not os.path.exists(os.path.join(build, doc)):
+            env.Execute(Mkdir(os.path.join(build, doc)))
+        if not os.path.exists(os.path.join(build, doc, 'titlepage')):
+            env.Execute(Mkdir(os.path.join(build, doc, 'titlepage')))
         manifest = File(os.path.join(doc, 'MANIFEST')).rstr()
         src_files = bootstrap.parseManifestLines(doc, open(manifest).readlines())
         for s in src_files:
@@ -242,22 +300,56 @@ else:
             doc_s = os.path.join(doc, s)
             build_s = os.path.join(build, doc, s)
             base, ext = os.path.splitext(doc_s)
+            head, tail = os.path.split(s)
+            if head:
+                target_dir = os.path.join(build, doc, head)
+            else:
+                target_dir = os.path.join(build, doc)
             if ext in ['.fig', '.jpg', '.svg']:
-                env.Execute(Copy(build_s, doc_s))
+                buildsuite.extend(env.Command(build_s, doc_s, 
+                                              Copy("$TARGET", "$SOURCE")))
             else:
                 revaction([env.File(build_s)], 
                           [env.File(doc_s)], env)
 
+
+    #
+    # For each document, build the document itself in HTML,
+    # and PDF formats.
+    #
+    docnodes = {}
+    for doc in docs:
+
         #
-        # Call SCons in each local doc folder directly, such that
-        # we can Glob for the created *.html files afterwards to
-        # get the dependencies for the install targets right.
+        # Call SCons in each local doc folder
         #
         cleanopt = ''
         if env.GetOption('clean'):
             cleanopt = ' -c'
-        cmd = env.subst("cd %s && $PYTHON ${SCONS_PY.abspath}" % os.path.join(build, doc))+cleanopt
-        os.system(cmd)
+        scdir = os.path.join(build, doc)
+        sctargets = []
+        if 'html' in docs[doc]:
+            sctargets.append(env.File(os.path.join(scdir, 'index.html')))
+        if 'chunked' in docs[doc]:
+            sctargets.append(env.File(os.path.join(scdir, 'scons-%s' % doc, 'index.html')))
+        if 'pdf' in docs[doc]:
+            sctargets.append(env.File(os.path.join(scdir, 'scons-%s.pdf' % doc)))
+        if 'epub' in docs[doc]:
+            sctargets.append(env.File(os.path.join(scdir, 'scons-%s.epub' % doc)))
+            
+        if 'man' in docs[doc]:
+            for m in man_page_list:
+                sctargets.append(os.path.join(scdir, m))
+                man, _1 = os.path.splitext(m)
+            
+                sctargets.append(os.path.join(scdir, 'scons-%s.pdf' % man))
+                sctargets.append(os.path.join(scdir, 'scons-%s.html' % man))
+        
+        docnodes[doc] = env.Command(sctargets, buildsuite, 
+                                    "cd %s && $PYTHON ${SCONS_PY.abspath}%s" % (scdir, cleanopt))
+        
+    install_css = False
+    for doc in docs:
 
         # Collect the output files for this subfolder
         htmldir = os.path.join(build, 'HTML', 'scons-%s' % doc)
@@ -265,22 +357,30 @@ else:
         html = os.path.join(build, 'HTML', 'scons-%s.html' % doc)
         pdf = os.path.join(build, 'PDF', 'scons-%s.pdf' % doc)
         epub = os.path.join(build, 'EPUB', 'scons-%s.epub' % doc)
-        if 'chtml' in docs[doc]:
-            env.Install(htmldir, Glob(os.path.join(build, doc,'scons-%s' % doc, '*.html')))
-            tar_deps.extend([htmlindex])
+        text = os.path.join(build, 'TEXT', 'scons-%s.txt' % doc)
+        if 'chunked' in docs[doc]:
+            installed_chtml = env.ChunkedInstall(env.Dir(htmldir), 
+                                                 os.path.join(build, doc,'scons-%s' % doc, 'index.html'))
+            installed_chtml_css = env.Install(env.Dir(htmldir),
+                                              os.path.join(build, doc, 'scons.css'))
+            env.Depends(installed_chtml, docnodes[doc])
+            env.Depends(installed_chtml_css, docnodes[doc])
+            
+            tar_deps.extend([htmlindex, installed_chtml_css])
             tar_list.extend([htmldir])
             Local(htmlindex)
             env.Ignore(htmlindex, version_xml)
 
         if 'html' in docs[doc]:
-            env.InstallAs(html, os.path.join(build, doc,'index.html'))
+            env.InstallAs(env.File(html), env.File(os.path.join(build, doc,'index.html')))
             tar_deps.extend([html])
             tar_list.extend([html])
             Local(html)
             env.Ignore(html, version_xml)
+            install_css = True
             
         if 'pdf' in docs[doc]:
-            env.InstallAs(pdf, os.path.join(build, doc,'scons-%s.pdf' % doc))
+            env.InstallAs(env.File(pdf), env.File(os.path.join(build, doc,'scons-%s.pdf' % doc)))
             Local(pdf)
             env.Ignore(pdf, version_xml)
 
@@ -288,13 +388,29 @@ else:
             tar_list.append(pdf)
 
         if 'epub' in docs[doc] and gs:
-            env.InstallAs(epub, os.path.join(build, doc,'scons-%s.epub' % doc))
+            env.InstallAs(env.File(epub), env.File(os.path.join(build, doc,'scons-%s.epub' % doc)))
             Local(epub)
             env.Ignore(epub, version_xml)
 
             tar_deps.append(epub)
             tar_list.append(epub)
             
+        if ('text' in docs[doc] and lynx and 
+            (('html' in docs[doc]) or (doc == 'man'))):
+            texthtml = os.path.join(build, doc,'index.html')
+            if doc == 'man':
+                # Special handling for single MAN file
+                texthtml = os.path.join(build, doc, 'scons-scons.html')
+            
+            env.Command(text, env.File(texthtml), "lynx -dump ${SOURCE.abspath} > $TARGET")
+            Local(text)
+
+            env.Ignore(text, version_xml)
+
+            tar_deps.append(text)
+            tar_list.append(text)
+            
+            
         if 'man' in docs[doc]:
             #
             # Man page(s)
@@ -305,13 +421,22 @@ else:
                 pdf = os.path.join(build, 'PDF', '%s-man.pdf' % man)
                 html = os.path.join(build, 'HTML' , '%s-man.html' % man)
             
-                env.InstallAs(pdf, os.path.join(build, 'man','scons-%s.pdf' % man))
-                env.InstallAs(html, os.path.join(build, 'man','scons-%s.html' % man))
+                env.InstallAs(env.File(pdf), env.File(os.path.join(build, 'man','scons-%s.pdf' % man)))
+                env.InstallAs(env.File(html), env.File(os.path.join(build, 'man','scons-%s.html' % man)))
             
                 tar_deps.extend([pdf, html])
                 tar_list.extend([pdf, html])
 
 
+    # Install CSS file, common to all single HTMLs
+    if install_css:
+        css_file = os.path.join(build, 'HTML', 'scons.css')
+        env.InstallAs(env.File(css_file), 
+                      env.File(os.path.join(build, 'user','scons.css')))
+        tar_deps.extend([css_file])
+        tar_list.extend([css_file])
+        Local(css_file)
+
 if not epydoc_cli:
     try:
         import epydoc
diff --git a/doc/design/chtml.xsl b/doc/design/chtml.xsl
index 457f56307..dde3c6f1c 100644
--- a/doc/design/chtml.xsl
+++ b/doc/design/chtml.xsl
@@ -33,6 +33,7 @@
 <xsl:param name="base.dir" select="'scons-design/'"/>

 <xsl:param name="l10n.gentext.default.language" select="'en'"/>

 <xsl:param name="section.autolabel" select="1"/>

+<xsl:param name="section.label.includes.component.label" select="1"/>

 <xsl:param name="html.stylesheet" select="'scons.css'"/>

 <xsl:param name="generate.toc">

 /appendix toc,title

diff --git a/doc/design/html.xsl b/doc/design/html.xsl
index 74ea5296d..9efc45850 100644
--- a/doc/design/html.xsl
+++ b/doc/design/html.xsl
@@ -32,6 +32,7 @@
 

 <xsl:param name="l10n.gentext.default.language" select="'en'"/>

 <xsl:param name="section.autolabel" select="1"/>

+<xsl:param name="section.label.includes.component.label" select="1"/>

 <xsl:param name="html.stylesheet" select="'scons.css'"/>

 <xsl:param name="generate.toc">

 /appendix toc,title

diff --git a/doc/design/pdf.xsl b/doc/design/pdf.xsl
index 652975f04..33100d29f 100644
--- a/doc/design/pdf.xsl
+++ b/doc/design/pdf.xsl
@@ -33,6 +33,7 @@
 	<xsl:include href="scons_title.xsl"/> 

 <xsl:param name="l10n.gentext.default.language" select="'en'"/>

 <xsl:param name="section.autolabel" select="1"></xsl:param>

+<xsl:param name="section.label.includes.component.label" select="1"/>

 <xsl:param name="paper.type" select="'letter'"></xsl:param>

 <xsl:param name="body.start.indent">0pt</xsl:param>

 <xsl:param name="shade.verbatim" select="1"></xsl:param>

diff --git a/doc/design/scons.css b/doc/design/scons.css
index 6941abba1..ff9b5a107 100644
--- a/doc/design/scons.css
+++ b/doc/design/scons.css
@@ -6,11 +6,11 @@ body {
 	}
 
 
-a {
+a:link {
 	color: #80572a;
 	}
 
-a:hover {
+a:link:hover {
 	color: #d72816;
 	text-decoration: none;
 	}
diff --git a/doc/man/html.xsl b/doc/man/html.xsl
index 864af882e..714412a6f 100644
--- a/doc/man/html.xsl
+++ b/doc/man/html.xsl
@@ -32,6 +32,7 @@
 

 <xsl:param name="l10n.gentext.default.language" select="'en'"/>

 <xsl:param name="section.autolabel" select="1"/>

+<xsl:param name="section.label.includes.component.label" select="1"/>

 <xsl:param name="html.stylesheet" select="'scons.css'"/>

 <xsl:param name="generate.toc">

 /appendix toc,title

diff --git a/doc/man/pdf.xsl b/doc/man/pdf.xsl
index f3141030b..c821dde1f 100644
--- a/doc/man/pdf.xsl
+++ b/doc/man/pdf.xsl
@@ -33,6 +33,7 @@
 	<xsl:include href="scons_title.xsl"/> 

 <xsl:param name="l10n.gentext.default.language" select="'en'"/>

 <xsl:param name="section.autolabel" select="1"></xsl:param>

+<xsl:param name="section.label.includes.component.label" select="1"/>

 <xsl:param name="paper.type" select="'letter'"></xsl:param>

 <xsl:param name="body.start.indent">0pt</xsl:param>

 <xsl:param name="shade.verbatim" select="1"></xsl:param>

diff --git a/doc/man/scons-time.xml b/doc/man/scons-time.xml
index d7b7c4208..a1ecadf75 100644
--- a/doc/man/scons-time.xml
+++ b/doc/man/scons-time.xml
@@ -1,39 +1,34 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!-- lifted from troff+man by doclifter -->
-<refentry id='sconstime1'
-          xmlns="http://www.scons.org/dbxsd/v1.0"
-          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-          xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
-<!--  __COPYRIGHT__ -->
+<!--
 
-<!--  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: -->
+  __COPYRIGHT__
 
-<!--  The above copyright notice and this permission notice shall be included -->
-<!--  in all copies or substantial portions of the Software. -->
+  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 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. -->
+  The above copyright notice and this permission notice shall be included
+  in all copies or substantial portions of the Software.
 
-<!--  __FILE__ __REVISION__ __DATE__ __DEVELOPER__ -->
+  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.
 
-<!--  ES \- Example Start \- indents and turns off line fill -->
-<!--  EE \- Example End \- ends indent and turns line fill back on -->
-<!-- '\"========================================================================== -->
-<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
-<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
-<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
-<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+-->
+
+<!-- lifted from troff+man by doclifter -->
+<refentry id='sconstime1'
+          xmlns="http://www.scons.org/dbxsd/v1.0"
+          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+          xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
 <refmeta>
 <refentrytitle>SCONS-TIME</refentrytitle>
 <manvolnum>1</manvolnum>
diff --git a/doc/man/scons.css b/doc/man/scons.css
index 6941abba1..ff9b5a107 100644
--- a/doc/man/scons.css
+++ b/doc/man/scons.css
@@ -6,11 +6,11 @@ body {
 	}
 
 
-a {
+a:link {
 	color: #80572a;
 	}
 
-a:hover {
+a:link:hover {
 	color: #d72816;
 	text-decoration: none;
 	}
diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index 60ecc6c31..d726796e6 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -1,4 +1,28 @@
 <?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+  __COPYRIGHT__
+
+  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 reference [
 <!ENTITY % version SYSTEM "../version.xml">
@@ -18,28 +42,6 @@
 <reference xmlns="http://www.scons.org/dbxsd/v1.0"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
-<!--  __COPYRIGHT__ -->
-
-<!--  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. -->
-
-<!--  __FILE__ __REVISION__ __DATE__ __DEVELOPER__ -->
 
   <referenceinfo>
     <title>SCons &buildversion;</title>
diff --git a/doc/man/sconsign.xml b/doc/man/sconsign.xml
index 47fff5606..ca99db6c2 100644
--- a/doc/man/sconsign.xml
+++ b/doc/man/sconsign.xml
@@ -1,36 +1,34 @@
 <?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+  __COPYRIGHT__
+
+  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.
+
+-->
+
 <!-- lifted from troff+man by doclifter -->
 <refentry id='sconsign1' 
           xmlns="http://www.scons.org/dbxsd/v1.0"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
-<!--  __COPYRIGHT__ -->
-
-<!--  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. -->
-
-<!--  __FILE__ __REVISION__ __DATE__ __DEVELOPER__ -->
-
-<!--  ES \- Example Start \- indents and turns off line fill -->
-<!-- ES listing suppressed (not used) -->
-<!--  EE \- Example End \- ends indent and turns line fill back on -->
-<!-- EE listing suppressed (not used) -->
 <refmeta>
 <refentrytitle>SCONSIGN</refentrytitle>
 <manvolnum>1</manvolnum>
diff --git a/doc/reference/chtml.xsl b/doc/reference/chtml.xsl
index 722aec162..d85874dc0 100644
--- a/doc/reference/chtml.xsl
+++ b/doc/reference/chtml.xsl
@@ -33,6 +33,7 @@
 <xsl:param name="base.dir" select="'scons-reference/'"/>

 <xsl:param name="l10n.gentext.default.language" select="'en'"/>

 <xsl:param name="section.autolabel" select="1"/>

+<xsl:param name="section.label.includes.component.label" select="1"/>

 <xsl:param name="html.stylesheet" select="'scons.css'"/>

 <xsl:param name="generate.toc">

 /appendix toc,title

diff --git a/doc/reference/html.xsl b/doc/reference/html.xsl
index 74ea5296d..9efc45850 100644
--- a/doc/reference/html.xsl
+++ b/doc/reference/html.xsl
@@ -32,6 +32,7 @@
 

 <xsl:param name="l10n.gentext.default.language" select="'en'"/>

 <xsl:param name="section.autolabel" select="1"/>

+<xsl:param name="section.label.includes.component.label" select="1"/>

 <xsl:param name="html.stylesheet" select="'scons.css'"/>

 <xsl:param name="generate.toc">

 /appendix toc,title

diff --git a/doc/reference/pdf.xsl b/doc/reference/pdf.xsl
index 652975f04..33100d29f 100644
--- a/doc/reference/pdf.xsl
+++ b/doc/reference/pdf.xsl
@@ -33,6 +33,7 @@
 	<xsl:include href="scons_title.xsl"/> 

 <xsl:param name="l10n.gentext.default.language" select="'en'"/>

 <xsl:param name="section.autolabel" select="1"></xsl:param>

+<xsl:param name="section.label.includes.component.label" select="1"/>

 <xsl:param name="paper.type" select="'letter'"></xsl:param>

 <xsl:param name="body.start.indent">0pt</xsl:param>

 <xsl:param name="shade.verbatim" select="1"></xsl:param>

diff --git a/doc/reference/scons.css b/doc/reference/scons.css
index 6941abba1..ff9b5a107 100644
--- a/doc/reference/scons.css
+++ b/doc/reference/scons.css
@@ -6,11 +6,11 @@ body {
 	}
 
 
-a {
+a:link {
 	color: #80572a;
 	}
 
-a:hover {
+a:link:hover {
 	color: #d72816;
 	text-decoration: none;
 	}
diff --git a/doc/user/chtml.xsl b/doc/user/chtml.xsl
index e292c88e1..e855c3103 100644
--- a/doc/user/chtml.xsl
+++ b/doc/user/chtml.xsl
@@ -33,6 +33,7 @@
 <xsl:param name="base.dir" select="'scons-user/'"/>

 <xsl:param name="l10n.gentext.default.language" select="'en'"/>

 <xsl:param name="section.autolabel" select="1"/>

+<xsl:param name="section.label.includes.component.label" select="1"/>

 <xsl:param name="html.stylesheet" select="'scons.css'"/>

 <xsl:param name="generate.toc">

 /appendix toc,title

diff --git a/doc/user/html.xsl b/doc/user/html.xsl
index c275c3d18..17dc189dc 100644
--- a/doc/user/html.xsl
+++ b/doc/user/html.xsl
@@ -32,6 +32,7 @@
 

 <xsl:param name="l10n.gentext.default.language" select="'en'"/>

 <xsl:param name="section.autolabel" select="1"/>

+<xsl:param name="section.label.includes.component.label" select="1"/>

 <xsl:param name="html.stylesheet" select="'scons.css'"/>

 <xsl:param name="generate.toc">

 /appendix toc,title

diff --git a/doc/user/pdf.xsl b/doc/user/pdf.xsl
index 9c545925f..2c0d086b3 100644
--- a/doc/user/pdf.xsl
+++ b/doc/user/pdf.xsl
@@ -33,6 +33,7 @@
 	<xsl:include href="scons_title.xsl"/> 

 <xsl:param name="l10n.gentext.default.language" select="'en'"/>

 <xsl:param name="section.autolabel" select="1"></xsl:param>

+<xsl:param name="section.label.includes.component.label" select="1"/>

 <xsl:param name="paper.type" select="'letter'"></xsl:param>

 <xsl:param name="body.start.indent">0pt</xsl:param>

 <xsl:param name="shade.verbatim" select="1"></xsl:param>

diff --git a/doc/user/scons.css b/doc/user/scons.css
index 6941abba1..ff9b5a107 100644
--- a/doc/user/scons.css
+++ b/doc/user/scons.css
@@ -6,11 +6,11 @@ body {
 	}
 
 
-a {
+a:link {
 	color: #80572a;
 	}
 
-a:hover {
+a:link:hover {
 	color: #d72816;
 	text-decoration: none;
 	}
diff --git a/src/engine/SCons/Tool/docbook/__init__.py b/src/engine/SCons/Tool/docbook/__init__.py
index 72ea17586..aacc26da0 100644
--- a/src/engine/SCons/Tool/docbook/__init__.py
+++ b/src/engine/SCons/Tool/docbook/__init__.py
@@ -429,6 +429,11 @@ def DocbookEpub(env, target, source=None, *args, **kw):
         mime_file.close()
         zf.write(mime_file.name, compress_type = zipfile.ZIP_STORED)
         for s in source:
+            if os.path.isfile(str(s)):
+                head, tail = os.path.split(str(s))
+                if not head:
+                    continue
+                s = head
             for dirpath, dirnames, filenames in os.walk(str(s)):
                 for fname in filenames:
                     path = os.path.join(dirpath, fname)