2 # SConscript file for building SCons documentation.
4 # THIS IS NOT READY YET. DO NOT TRY TO BUILD SCons WITH ITSELF YET.
8 # Copyright (c) 2001 Steven Knight
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:
18 # The above copyright notice and this permission notice shall be included
19 # in all copies or substantial portions of the Software.
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.
34 Import('env', 'whereis')
39 doc_tar_gz = os.path.join('#build',
41 'scons-doc-%s.tar.gz' % env.Dictionary('VERSION'))
44 # We'll only try to build text files (for some documents)
45 # if lynx is available to do the dump.
47 fig2dev = whereis('fig2dev')
48 groff = whereis('groff')
49 lynx = whereis('lynx')
50 man2html = whereis('man2html')
56 entity_re = re.compile(r'<!entity\s+(?:%\s+)?(?:\S+)\s+SYSTEM\s+"([^"]*)">/', re.I)
57 format_re = re.compile(r'<(?:graphic|imagedata)\s+fileref="([^"]*)"(?:\s+format="([^"]*)")?')
60 # Find internal dependencies in .sgml files:
62 # <!entity bground SYSTEM "bground.sgml">
63 # <graphic fileref="file.jpg">
64 # <imagedata fileref="file.jpg">
66 # This only finds one per line, and assumes that anything
67 # defined as a SYSTEM entity is, in fact, a file included
68 # somewhere in the document.
70 def scansgml(contents, argument = None):
73 matches = entity_re.findall(contents)
77 matches = format_re.findall(contents)
80 if format and file[-len(format):] != format:
82 if argument and not os.path.isabs(file):
83 file = os.path.join(argument, file)
90 # Always create a version.sgml file containing the version information
91 # for this run. Ignore it for dependency purposes so we don't
92 # rebuild all the docs every time just because the date changes.
94 date, ver, rev = env.Dictionary('DATE', 'VERSION', 'REVISION')
95 verfile = str(File("version.sgml"))
100 open(verfile, "w").write("""<!--
101 THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT.
103 <!ENTITY builddate "%s">
104 <!ENTITY buildversion "%s">
105 <!ENTITY buildrevision "%s">
106 """ % (date, ver, rev))
109 # Each document will live in its own subdirectory. List them here
110 # as hash keys, with a hash of the info to control its build.
114 'htmlindex' : 'book1.html',
118 'scan' : Scanner(name = 'design',
120 argument = 'design'),
123 'htmlindex' : 't1.html',
128 'graphics' : [ 'arch', 'builder', 'job-task', 'node', 'scanner', 'sig' ],
129 'scan' : Scanner(name = 'python10',
131 argument = 'python10'),
134 'htmlindex' : 'book1.html',
139 'scan' : Scanner(name = 'user',
146 # We have to tell Cons to QuickScan the top-level SGML files which
147 # get included by the document SGML files in the subdirectories.
154 s = Scanner(name = 'sgml', function = scansgml)
156 for sgml in included_sgml:
157 File(sgml).scanner_set(s)
160 # For each document, build the document itself in HTML, Postscript,
163 for doc in docs.keys():
164 main = os.path.join(doc, 'main.sgml')
167 htmldir = os.path.join('HTML', 'scons-%s' % doc)
168 htmlindex = os.path.join(htmldir, docs[doc]['htmlindex'])
169 html = os.path.join('HTML', 'scons-%s.html' % doc)
170 ps = os.path.join('PS', 'scons-%s.ps' % doc)
171 pdf = os.path.join('PDF', 'scons-%s.pdf' % doc)
172 text = os.path.join('TEXT', 'scons-%s.txt' % doc)
174 s = docs[doc].get('scan')
176 File(os.path.join('build', 'doc', main)).scanner_set(s)
178 if docs[doc].get('html'):
179 env.Command(htmlindex, main, [
180 "rm -f ${TARGET.dir}/*.html",
181 "jw -b html -o ${TARGET.dir} $SOURCES",
182 "mv -v ${TARGET.dir}/index.html $TARGET || true",
185 env.Command(html, main, "jw -u -b html $SOURCES > $TARGET")
187 tar_deps.extend([html, htmlindex])
188 tar_list = string.join([tar_list, html, htmldir], " ")
191 for g in docs[doc].get('graphics', []):
192 fig = os.path.join(doc, '%s.fig' % g)
193 jpg = os.path.join(htmldir, '%s.jpg' % g)
194 env.Command(jpg, fig,
195 "%s -L jpeg -q 100 $SOURCES $TARGET" % fig2dev)
198 if docs[doc].get('ps'):
199 env.Command(ps, main, [
200 "rm -f ${TARGET.dir}/%s" % out,
201 "jw -b ps -o ${TARGET.dir} $SOURCES",
202 "mv ${TARGET.dir}/main.ps $TARGET",
203 "rm -f ${TARGET.dir}/%s" % out,
206 tar_list = tar_list + " " + ps
208 for g in docs[doc].get('graphics', []):
209 fig = os.path.join(doc, '%s.fig' % g)
210 eps = os.path.join('PS', '%s.eps' % g)
211 env.Command(eps, fig, "%s -L eps $SOURCES $TARGET" % fig2dev)
214 if docs[doc].get('pdf'):
215 env.Command(pdf, main, [
216 "rm -f ${TARGET.dir}/%s" % out,
217 "jw -b pdf -o ${TARGET.dir} $SOURCES",
218 "mv ${TARGET.dir}/main.pdf $TARGET",
219 "rm -f ${TARGET.dir}/out",
222 tar_list = tar_list + " " + pdf
224 if docs[doc].get('text') and lynx:
225 env.Command(text, html, "lynx -dump ${SOURCE.abspath} > $TARGET")
226 tar_deps.append(text)
227 tar_list = tar_list + " " + text
230 # Man page(s), in good ol' troff format.
232 scons_1 = os.path.join('man', 'scons.1')
235 ps = os.path.join('PS', 'scons-man.ps')
236 text = os.path.join('TEXT', 'scons-man.txt')
238 env.Command(ps, scons_1, "groff -man -Tps $SOURCES > $TARGET")
240 env.Command(text, scons_1, "groff -man -Tascii $SOURCES > $TARGET")
242 tar_deps.extend([ps, text])
243 tar_list = string.join([tar_list, ps, text], " ")
246 html = os.path.join('HTML' , 'scons-man.html')
248 env.Command(html, scons_1, "man2html $SOURCES > $TARGET")
250 tar_deps.append(html)
251 tar_list = tar_list + " " + html
254 # Now actually create the tar file of the documentation,
255 # for easy distribution to the web site.
257 env.Command(doc_tar_gz, tar_deps,
258 "tar zchv -f $TARGET -C build/doc %s" % tar_list)