3 # Process a list of Python and/or XML files containing SCons documentation.
5 # This script creates formatted lists of the Builders, Tools or
6 # construction variables documented in the specified XML files.
8 # Dependening on the options, the lists are output in either
9 # DocBook-formatted generated XML files containing the summary text
10 # and/or .mod files contining the ENTITY definitions for each item,
11 # or in man-page-formatted output.
23 base_sys_path = [os.getcwd() + '/build/test-tar-gz/lib/scons'] + sys.path
26 Usage: scons-proc.py [--man|--xml]
27 [-b file(s)] [-t file(s)] [-v file(s)] [infile ...]
29 -b file(s) dump builder information to the specified file(s)
30 -t file(s) dump tool information to the specified file(s)
31 -v file(s) dump variable information to the specified file(s)
32 --man print info in man page format, each -[btv] argument
34 --xml (default) print info in SML format, each -[btv] argument
35 is a pair of comma-separated .gen,.mod file names
38 opts, args = getopt.getopt(sys.argv[1:],
41 'man', 'xml', 'tools=', 'variables='])
49 if o in ['-b', '--builders']:
51 elif o in ['-h', '--help']:
52 sys.stdout.write(helpstr)
54 elif o in ['--man', '--xml']:
56 elif o in ['-t', '--tools']:
58 elif o in ['-v', '--variables']:
61 h = SConsDoc.SConsDocHandler()
62 saxparser = xml.sax.make_parser()
63 saxparser.setContentHandler(h)
64 saxparser.setErrorHandler(h)
76 _, ext = os.path.splitext(f)
78 dir, _ = os.path.split(f)
80 sys.path = [dir] + base_sys_path
81 module = SConsDoc.importfile(f)
82 h.set_file_info(f, len(xml_preamble.split('\n')))
84 content = module.__scons_doc__
85 except AttributeError:
88 del module.__scons_doc__
90 h.set_file_info(f, len(xml_preamble.split('\n')))
91 content = open(f).read()
93 content = content.replace('&', '&')
94 input = xml_preamble + content + xml_postamble
96 saxparser.parse(StringIO.StringIO(input))
98 sys.stderr.write("error in %s\n" % f)
103 THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT.
107 Regular_Entities_Header = """\
115 Link_Entities_Header = """\
118 Entities that are links to the %s entries in the appendix.
124 def __init__(self, entries, **kw):
125 values = entries.values()
128 for k, v in kw.items():
130 def fopen(self, name):
133 return open(name, 'w')
135 class SCons_XML_to_XML(SCons_XML):
136 def write(self, files):
137 gen, mod = string.split(files, ',')
140 def write_gen(self, filename):
143 f = self.fopen(filename)
144 for v in self.values:
145 f.write('\n<varlistentry id="%s%s">\n' %
146 (self.prefix, self.idfunc(v.name)))
147 for term in self.termfunc(v.name):
148 f.write('<term><%s>%s</%s></term>\n' %
149 (self.tag, term, self.tag))
150 f.write('<listitem>\n')
151 for chunk in v.summary.body:
154 s = map(lambda x: '&cv-link-%s;' % x, v.sets)
156 f.write('Sets: ' + ', '.join(s) + '.\n')
159 u = map(lambda x: '&cv-link-%s;' % x, v.uses)
161 f.write('Uses: ' + ', '.join(u) + '.\n')
163 f.write('</listitem>\n')
164 f.write('</varlistentry>\n')
165 def write_mod(self, filename):
168 f = self.fopen(filename)
171 f.write(Regular_Entities_Header % self.description)
173 for v in self.values:
174 f.write('<!ENTITY %s%s "<%s>%s</%s>">\n' %
175 (self.prefix, self.idfunc(v.name),
176 self.tag, self.entityfunc(v.name), self.tag))
180 f.write(Link_Entities_Header % self.description)
182 for v in self.values:
183 f.write('<!ENTITY %slink-%s \'<link linkend="%s%s"><%s>%s</%s></link>\'>\n' %
184 (self.prefix, self.idfunc(v.name),
185 self.prefix, self.idfunc(v.name),
186 self.tag, self.entityfunc(v.name), self.tag))
190 class SCons_XML_to_man(SCons_XML):
193 def initial_chunks(self, name):
195 def write(self, filename):
198 f = self.fopen(filename)
200 for v in self.values:
201 chunks.extend(self.mansep())
202 for n in self.initial_chunks(v.name):
203 chunks.append('.IP %s\n' % n)
204 chunks.extend(map(str, v.summary.body))
206 body = ''.join(chunks)
207 body = string.replace(body, '<programlisting>', '.ES')
208 body = string.replace(body, '</programlisting>', '.EE')
209 body = string.replace(body, '\n</para>\n<para>\n', '\n\n')
210 body = string.replace(body, '<para>\n', '')
211 body = string.replace(body, '<para>', '\n')
212 body = string.replace(body, '</para>\n', '')
213 body = re.sub('\.EE\n\n+(?!\.IP)', '.EE\n.IP\n', body)
214 body = re.sub('&(scons|SConstruct|SConscript|jar);', r'\\fB\1\\fP', body)
215 body = string.replace(body, '&Dir;', r'\fBDir\fP')
216 body = string.replace(body, '⌖', r'\fItarget\fP')
217 body = string.replace(body, '&source;', r'\fIsource\fP')
218 body = re.sub('&b(-link)?-([^;]*);', r'\\fB\2\\fP()', body)
219 body = re.sub('&cv(-link)?-([^;]*);', r'$\2', body)
220 body = re.sub(r'<(command|envar|filename|literal|option)>([^<]*)</\1>',
222 body = re.sub(r'<(classname|emphasis|varname)>([^<]*)</\1>',
224 body = re.compile(r'^\\f([BI])(.*)\\fP\s*$', re.M).sub(r'.\1 \2', body)
225 body = re.compile(r'^\\f([BI])(.*)\\fP(\S+)', re.M).sub(r'.\1R \2 \3', body)
226 body = string.replace(body, '<', '<')
227 body = string.replace(body, '>', '>')
228 body = re.sub(r'\\([^f])', r'\\\\\1', body)
229 body = re.compile("^'\\\\\\\\", re.M).sub("'\\\\", body)
230 body = re.compile(r'^\.([BI]R?) -', re.M).sub(r'.\1 \-', body)
231 body = re.compile(r'^\.([BI]R?) (\S+)\\\\(\S+)', re.M).sub(r'.\1 "\2\\\\\\\\\2"', body)
232 body = re.compile(r'\\f([BI])-', re.M).sub(r'\\f\1\-', body)
235 if output_type == '--man':
236 processor_class = SCons_XML_to_man
237 elif output_type == '--xml':
238 processor_class = SCons_XML_to_XML
240 sys.stderr.write("Unknown output type '%s'\n" % output_type)
244 g = processor_class(h.builders,
245 description = 'builder',
248 idfunc = lambda x: x,
249 termfunc = lambda x: [x+'()', 'env.'+x+'()'],
250 entityfunc = lambda x: x)
252 g.mansep = lambda: ['\n', "'\\" + '"'*69 + '\n']
253 g.initial_chunks = lambda n: [n+'()', 'env.'+n+'()']
255 g.write(buildersfiles)
258 g = processor_class(h.tools,
259 description = 'tool',
262 idfunc = lambda x: string.replace(x, '+', 'X'),
263 termfunc = lambda x: [x],
264 entityfunc = lambda x: x)
269 g = processor_class(h.cvars,
270 description = 'construction variable',
273 idfunc = lambda x: x,
274 termfunc = lambda x: [x],
275 entityfunc = lambda x: '$'+x)
277 g.write(variablesfiles)
281 # indent-tabs-mode:nil
283 # vim: set expandtab tabstop=4 shiftwidth=4: