doc/SConscript

   1 #
   2 # SConscript file for building SCons documentation.
   3 #
   4 # THIS IS NOT READY YET.  DO NOT TRY TO BUILD SCons WITH ITSELF YET.
   5 #
   6
   7 #
   8 # Copyright (c) 2001, 2002 Steven Knight
   9 #
  10 # Permission is hereby granted, free of charge, to any person obtaining
  11 # a copy of this software and associated documentation files (the
  12 # "Software"), to deal in the Software without restriction, including
  13 # without limitation the rights to use, copy, modify, merge, publish,
  14 # distribute, sublicense, and/or sell copies of the Software, and to
  15 # permit persons to whom the Software is furnished to do so, subject to
  16 # the following conditions:
  17 #
  18 # The above copyright notice and this permission notice shall be included
  19 # in all copies or substantial portions of the Software.
  20 #
  21 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
  22 # KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  23 # WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  24 # NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  25 # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  26 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  27 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  28 #
  29
  30 import os.path
  31 import re
  32 import string
  33
  34 Import('env', 'whereis')
  35
  36 #
  37 #
  38 #
  39 doc_tar_gz = os.path.join('#build',
  40                           'dist',
  41                           'scons-doc-%s.tar.gz' % env.Dictionary('VERSION'))
  42
  43 #
  44 # We'll only try to build text files (for some documents)
  45 # if lynx is available to do the dump.
  46 #
  47 fig2dev = whereis('fig2dev')
  48 groff = whereis('groff')
  49 lynx = whereis('lynx')
  50 man2html = whereis('man2html')
  51 jade = whereis('jade')
  52 jadetex = whereis('jadetex')
  53 pdfjadetex = whereis('pdfjadetex')
  54 jw = whereis('jw')
  55 tidy = whereis('tidy')
  56
  57 tar_deps = []
  58 tar_list = ""
  59
  60 entity_re = re.compile(r'<!entity\s+(?:%\s+)?(?:\S+)\s+SYSTEM\s+"([^"]*)">', re.I)
  61 format_re = re.compile(r'<(?:graphic|imagedata)\s+fileref="([^"]*)"(?:\s+format="([^"]*)")?')
  62
  63 #
  64 # Find internal dependencies in .sgml files:
  65 #
  66 #   <!entity bground SYSTEM "bground.sgml">
  67 #   <graphic fileref="file.jpg">
  68 #   <imagedata fileref="file.jpg">
  69 #
  70 # This only finds one per line, and assumes that anything
  71 # defined as a SYSTEM entity is, in fact, a file included
  72 # somewhere in the document.
  73 #
  74 def scansgml(node, env, argument = None):
  75     includes = []
  76
  77     contents = node.get_contents()
  78
  79     includes.extend(entity_re.findall(contents))
  80
  81     matches = format_re.findall(contents)
  82     for m in matches:
  83         file, format = m
  84         if format and file[-len(format):] != format:
  85             file = file + format
  86         if argument and not os.path.isabs(file):
  87             file = os.path.join(argument, file)
  88         includes.append(file)
  89
  90     return includes
  91
  92 if jw:
  93     #
  94     # Always create a version.sgml file containing the version information
  95     # for this run.  Ignore it for dependency purposes so we don't
  96     # rebuild all the docs every time just because the date changes.
  97     #
  98     date, ver, rev = env.Dictionary('DATE', 'VERSION', 'REVISION')
  99     verfile = str(File("version.sgml"))
 100     try:
 101         os.unlink(verfile)
 102     except:
 103         pass
 104     open(verfile, "w").write("""<!--
 105 THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 106 -->
 107 <!ENTITY builddate "%s">
 108 <!ENTITY buildversion "%s">
 109 <!ENTITY buildrevision "%s">
 110 """ % (date, ver, rev))
 111
 112     #
 113     # Each document will live in its own subdirectory.  List them here
 114     # as hash keys, with a hash of the info to control its build.
 115     #
 116     docs = {
 117         'design' : {
 118                 'htmlindex' : 'book1.html',
 119                 'ps'        : 1,
 120                 'pdf'       : 1,
 121                 'text'      : 0,
 122                 'scan'      : Scanner(name = 'design',
 123                                       function = scansgml,
 124                                       argument = 'design'),
 125         },
 126         'python10' : {
 127                 'htmlindex' : 't1.html',
 128                 'html'      : 1,
 129                 'ps'        : 1,
 130                 'pdf'       : 0,
 131                 'text'      : 0,
 132                 'graphics'  : [ 'arch', 'builder', 'job-task', 'node', 'scanner', 'sig' ],
 133                 'scan'      : Scanner(name = 'python10',
 134                                       function = scansgml,
 135                                       argument = 'python10'),
 136         },
 137         'user' : {
 138                 'htmlindex' : 'book1.html',
 139                 'html'      : 0,
 140                 'ps'        : 0,
 141                 'pdf'       : 0,
 142                 'text'      : 0,
 143                 'scan'      : Scanner(name = 'user',
 144                                       function = scansgml,
 145                                       argument = 'user'),
 146         },
 147     }
 148
 149     #
 150     # We have to tell Cons to QuickScan the top-level SGML files which
 151     # get included by the document SGML files in the subdirectories.
 152     #
 153     included_sgml = [
 154         'scons.mod',
 155         'copyright.sgml',
 156     ]
 157
 158     s = Scanner(name = 'sgml', function = scansgml)
 159
 160     for sgml in included_sgml:
 161         File(sgml).scanner_set(s)
 162
 163     #
 164     # For each document, build the document itself in HTML, Postscript,
 165     # and PDF formats.
 166     #
 167     for doc in docs.keys():
 168         main = os.path.join(doc, 'main.sgml')
 169         out = 'main.out'
 170
 171         htmldir = os.path.join('HTML', 'scons-%s' % doc)
 172         htmlindex = os.path.join(htmldir, docs[doc]['htmlindex'])
 173         html = os.path.join('HTML', 'scons-%s.html' % doc)
 174         ps = os.path.join('PS', 'scons-%s.ps' % doc)
 175         pdf = os.path.join('PDF', 'scons-%s.pdf' % doc)
 176         text = os.path.join('TEXT', 'scons-%s.txt' % doc)
 177
 178         s = docs[doc].get('scan')
 179         if s:
 180             File(main).scanner_set(s)
 181
 182         if docs[doc].get('html') and jade:
 183             cmds = [
 184                 "rm -f ${TARGET.dir}/*.html",
 185                 "jw -b html -o ${TARGET.dir} $SOURCES",
 186                 "mv -v ${TARGET.dir}/index.html $TARGET || true",
 187             ]
 188             if tidy:
 189                 cmds.append("tidy -m -q $TARGET || true")
 190             env.Command(htmlindex, main, cmds)
 191
 192             cmds = [
 193                 "rm -f ${TARGET.dir}/main.html",
 194                 "jw -u -b html -o ${TARGET.dir} $SOURCES",
 195                 "mv -v ${TARGET.dir}/main.html $TARGET || true",
 196             ]
 197             if tidy:
 198                 cmds.append("tidy -m -q $TARGET || true")
 199             env.Command(html, main, cmds)
 200
 201             env.Ignore([html, htmlindex], "version.sgml")
 202
 203             tar_deps.extend([html, htmlindex])
 204             tar_list = string.join([tar_list, html, htmldir], " ")
 205
 206             if fig2dev:
 207                 for g in docs[doc].get('graphics', []):
 208                     fig = os.path.join(doc, '%s.fig' % g)
 209                     jpg = os.path.join(htmldir, '%s.jpg' % g)
 210                     env.Command(jpg, fig,
 211                                 "%s -L jpeg -q 100 $SOURCES $TARGET" % fig2dev)
 212                     env.Depends(ps, jpg)
 213
 214         if docs[doc].get('ps') and jadetex:
 215             env.Command(ps, main, [
 216                 "rm -f ${TARGET.dir}/%s" % out,
 217                 "jw -b ps -o ${TARGET.dir} $SOURCES",
 218                 "mv ${TARGET.dir}/main.ps $TARGET",
 219                 "rm -f ${TARGET.dir}/%s" % out,
 220             ])
 221
 222             env.Ignore(ps, "version.sgml")
 223
 224             tar_deps.append(ps)
 225             tar_list = tar_list + " " + ps
 226
 227             if fig2dev:
 228                 for g in docs[doc].get('graphics', []):
 229                     fig = os.path.join(doc, '%s.fig' % g)
 230                     eps = os.path.join('PS', '%s.eps' % g)
 231                     env.Command(eps, fig, "%s -L eps $SOURCES $TARGET" % fig2dev)
 232                     env.Depends(ps, eps)
 233
 234         if docs[doc].get('pdf') and pdfjadetex:
 235             env.Command(pdf, main, [
 236                 "rm -f ${TARGET.dir}/%s" % out,
 237                 "jw -b pdf -o ${TARGET.dir} $SOURCES",
 238                 "mv ${TARGET.dir}/main.pdf $TARGET",
 239                 "rm -f ${TARGET.dir}/out",
 240             ])
 241
 242             env.Ignore(pdf, "version.sgml")
 243
 244             tar_deps.append(pdf)
 245             tar_list = tar_list + " " + pdf
 246
 247         if docs[doc].get('text') and jade and lynx:
 248             env.Command(text, html, "lynx -dump ${SOURCE.abspath} > $TARGET")
 249
 250             env.Ignore(text, "version.sgml")
 251
 252             tar_deps.append(text)
 253             tar_list = tar_list + " " + text
 254
 255 #
 256 # Man page(s), in good ol' troff format.
 257 #
 258 scons_1 = os.path.join('man', 'scons.1')
 259
 260 if groff:
 261     ps = os.path.join('PS', 'scons-man.ps')
 262     text = os.path.join('TEXT', 'scons-man.txt')
 263
 264     env.Command(ps, scons_1, "groff -man -Tps $SOURCES > $TARGET")
 265
 266     env.Command(text, scons_1, "groff -man -Tascii $SOURCES > $TARGET")
 267
 268     tar_deps.extend([ps, text])
 269     tar_list = string.join([tar_list, ps, text], " ")
 270
 271 if man2html:
 272     html = os.path.join('HTML' , 'scons-man.html')
 273
 274     cmds = [ "man2html $SOURCES > $TARGET" ]
 275     if tidy:
 276         cmds.append("tidy -m -q $TARGET || true")
 277     env.Command(html, scons_1, cmds)
 278
 279     tar_deps.append(html)
 280     tar_list = tar_list + " " + html
 281
 282 #
 283 # Now actually create the tar file of the documentation,
 284 # for easy distribution to the web site.
 285 #
 286 if tar_deps:
 287     env.Command(doc_tar_gz, tar_deps,
 288                 "tar zc${TAR_HFLAG} -f $TARGET -C build/doc %s" % tar_list)