From 6885c3fd4f501aff9d5cde7b0bb3aedaf5b63e10 Mon Sep 17 00:00:00 2001 From: Dirk Baechle Date: Sat, 4 May 2013 00:41:56 +0200 Subject: - cleaned up 'bin' directory - several smaller fixes - added first version of the Overview document for the doc toolchain --- bin/SConsExamples.py | 114 ++--- bin/docs-check-unique-examples.py | 17 - bin/docs-create-example-outputs.py | 19 + bin/docs-update-generated.py | 7 +- bin/docs-validate.py | 4 - bin/scons-doc.py | 555 --------------------- bin/scons-proc.py | 30 +- .../xmlmind/addon/config/scons/common.incl | 4 +- doc/generated/builders.gen | 430 +++++++--------- doc/images/overview.graphml | 418 ++++++++++++++++ doc/overview.rst | 174 +++++++ doc/user/pdf.xsl | 13 +- 12 files changed, 870 insertions(+), 915 deletions(-) delete mode 100644 bin/docs-check-unique-examples.py create mode 100644 bin/docs-create-example-outputs.py delete mode 100644 bin/scons-doc.py create mode 100644 doc/images/overview.graphml create mode 100644 doc/overview.rst diff --git a/bin/SConsExamples.py b/bin/SConsExamples.py index cba248b..9823a05 100644 --- a/bin/SConsExamples.py +++ b/bin/SConsExamples.py @@ -1,7 +1,7 @@ -#!/usr/bin/env python -# +# !/usr/bin/env python +# # Copyright (c) 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 @@ -9,10 +9,10 @@ # 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 @@ -21,18 +21,18 @@ # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -# -# +# +# # This script looks for some XML tags that describe SCons example # configurations and commands to execute in those configurations, and # uses TestCmd.py to execute the commands and insert the output from # those commands into the XML that we output. This way, we can run a # script and update all of our example documentation output without # a lot of laborious by-hand checking. -# +# # An "SCons example" looks like this, and essentially describes a set of # input files (program source files as well as SConscript files): -# +# # # # env = Environment() @@ -42,7 +42,7 @@ # int main() { printf("foo.c\n"); } # # -# +# # The contents within the tag will get written # into a temporary directory whenever example output needs to be # generated. By default, the contents are not inserted into text @@ -50,41 +50,41 @@ # in which case they will get inserted within a tag. # This makes it easy to define the example at the appropriate # point in the text where you intend to show the SConstruct file. -# +# # Note that you should usually give the a "name" # attribute so that you can refer to the example configuration later to # run SCons and generate output. -# +# # If you just want to show a file's contents without worry about running # SCons, there's a shorter tag: -# +# # # env = Environment() # env.Program('foo') # -# +# # This is essentially equivalent to , # but it's more straightforward. -# +# # SCons output is generated from the following sort of tag: -# +# # # scons -Q foo # scons -Q foo # -# +# # You tell it which example to use with the "example" attribute, and then # give it a list of tags to execute. You can also # supply an "os" tag, which specifies the type of operating system this # example is intended to show; if you omit this, default value is "posix". -# +# # The generated XML will show the command line (with the appropriate # command-line prompt for the operating system), execute the command in # a temporary directory with the example files, capture the standard # output from SCons, and insert it into the text as appropriate. # Error output gets passed through to your error output so you # can see if there are any problems executing the command. -# +# import os import re @@ -94,10 +94,10 @@ import time import SConsDoc from SConsDoc import tf as stf -# +# # The available types for ExampleFile entries -# -FT_FILE = 0 # a physical file (=) +# +FT_FILE = 0 # a physical file (=) FT_FILEREF = 1 # a reference (=) class ExampleFile: @@ -155,7 +155,7 @@ def readExampleInfos(fpath, examples): t.parseXmlFile(fpath) # Parse scons_examples - for e in stf.findAll(t.root, "scons_example", SConsDoc.dbxid, + for e in stf.findAll(t.root, "scons_example", SConsDoc.dbxid, t.xpath_context, t.nsmap): n = '' if stf.hasAttribute(e, 'name'): @@ -166,7 +166,7 @@ def readExampleInfos(fpath, examples): examples[n] = i # Parse file and directory entries - for f in stf.findAll(e, "file", SConsDoc.dbxid, + for f in stf.findAll(e, "file", SConsDoc.dbxid, t.xpath_context, t.nsmap): fi = ExampleFile() if stf.hasAttribute(f, 'name'): @@ -175,7 +175,7 @@ def readExampleInfos(fpath, examples): fi.chmod = stf.getAttribute(f, 'chmod') fi.content = stf.getText(f) examples[n].files.append(fi) - for d in stf.findAll(e, "directory", SConsDoc.dbxid, + for d in stf.findAll(e, "directory", SConsDoc.dbxid, t.xpath_context, t.nsmap): di = ExampleFolder() if stf.hasAttribute(d, 'name'): @@ -186,7 +186,7 @@ def readExampleInfos(fpath, examples): # Parse scons_example_files - for f in stf.findAll(t.root, "scons_example_file", SConsDoc.dbxid, + for f in stf.findAll(t.root, "scons_example_file", SConsDoc.dbxid, t.xpath_context, t.nsmap): if stf.hasAttribute(f, 'example'): e = stf.getAttribute(f, 'example') @@ -202,7 +202,7 @@ def readExampleInfos(fpath, examples): # Parse scons_output - for o in stf.findAll(t.root, "scons_output", SConsDoc.dbxid, + for o in stf.findAll(t.root, "scons_output", SConsDoc.dbxid, t.xpath_context, t.nsmap): if stf.hasAttribute(o, 'example'): n = stf.getAttribute(o, 'example') @@ -219,7 +219,7 @@ def readExampleInfos(fpath, examples): if stf.hasAttribute(o, 'suffix'): eout.suffix = stf.getAttribute(o, 'suffix') - for c in stf.findAll(o, "scons_output_command", SConsDoc.dbxid, + for c in stf.findAll(o, "scons_output_command", SConsDoc.dbxid, t.xpath_context, t.nsmap): oc = ExampleCommand() if stf.hasAttribute(c, 'edit'): @@ -252,7 +252,7 @@ def readAllExampleInfos(dpath): return examples -generated_examples = os.path.join('doc','generated','examples') +generated_examples = os.path.join('doc', 'generated', 'examples') def ensureExampleOutputsExist(dpath): """ Scan for XML files in the given directory and @@ -268,8 +268,8 @@ def ensureExampleOutputsExist(dpath): for key, value in examples.iteritems(): # Process all scons_output tags for o in value.outputs: - cpath = os.path.join(generated_examples, - key+'_'+o.suffix+'.xml') + cpath = os.path.join(generated_examples, + key + '_' + o.suffix + '.xml') if not os.path.isfile(cpath): # Start new XML file s = stf.newXmlTree("screen") @@ -282,8 +282,8 @@ def ensureExampleOutputsExist(dpath): if r.isFileRef(): # Get file's content content = value.getFileContents(r.name) - fpath = os.path.join(generated_examples, - key+'_'+r.name.replace("/","_")) + fpath = os.path.join(generated_examples, + key + '_' + r.name.replace("/", "_")) # Write file f = open(fpath, 'w') f.write("%s\n" % content) @@ -305,8 +305,8 @@ def createAllExampleOutputs(dpath): idx = 0 for key, value in examples.iteritems(): # Process all scons_output tags - print "%.2f%s (%d/%d) %s" % (float(idx+1)*100.0/float(total), - perc, idx+1, total, key) + print "%.2f%s (%d/%d) %s" % (float(idx + 1) * 100.0 / float(total), + perc, idx + 1, total, key) create_scons_output(value) # Process all scons_example_file tags @@ -314,8 +314,8 @@ def createAllExampleOutputs(dpath): if r.isFileRef(): # Get file's content content = value.getFileContents(r.name) - fpath = os.path.join(generated_examples, - key+'_'+r.name.replace("/","_")) + fpath = os.path.join(generated_examples, + key + '_' + r.name.replace("/", "_")) # Write file f = open(fpath, 'w') f.write("%s\n" % content) @@ -334,7 +334,7 @@ def collectSConsExampleNames(fpath): t.parseXmlFile(fpath) # Parse it - for e in stf.findAll(t.root, "scons_example", SConsDoc.dbxid, + for e in stf.findAll(t.root, "scons_example", SConsDoc.dbxid, t.xpath_context, t.nsmap): n = '' if stf.hasAttribute(e, 'name'): @@ -347,7 +347,7 @@ def collectSConsExampleNames(fpath): print "Error: Example in file '%s' is missing a name!" % fpath failed_suffixes = True - for o in stf.findAll(t.root, "scons_output", SConsDoc.dbxid, + for o in stf.findAll(t.root, "scons_output", SConsDoc.dbxid, t.xpath_context, t.nsmap): n = '' if stf.hasAttribute(o, 'example'): @@ -399,15 +399,15 @@ def exampleNamesAreUnique(dpath): return unique -################################################################ -# +# ############################################################### +# # In the second half of this module (starting here) # we define the variables and functions that are required # to actually run the examples, collect their output and # write it into the files in doc/generated/examples... # which then get included by our UserGuide. -# -################################################################ +# +# ############################################################### sys.path.append(os.path.join(os.getcwd(), 'QMTest')) sys.path.append(os.path.join(os.getcwd(), 'build', 'QMTest')) @@ -430,7 +430,7 @@ Prompt = { } # The magick SCons hackery that makes this work. -# +# # So that our examples can still use the default SConstruct file, we # actually feed the following into SCons via stdin and then have it # SConscript() the SConstruct file. This stdin wrapper creates a set @@ -438,7 +438,7 @@ Prompt = { # Surrogates print output like the real tools and behave like them # without actually having to be on the right platform or have the right # tool installed. -# +# # The upshot: The wrapper transparently changes the world out from # under the top-level SConstruct file in an example just so we can get # the command output. @@ -676,16 +676,16 @@ def command_scons(args, c, test, dict): except KeyError: delete_keys.append(key) os.environ[key] = val - test.run(interpreter = sys.executable, - program = scons_py, + test.run(interpreter=sys.executable, + program=scons_py, # We use ToolSurrogates to capture win32 output by "building" # examples using a fake win32 tool chain. Suppress the # warnings that come from the new revamped VS support so # we can build doc on (Linux) systems that don't have # Visual C installed. - arguments = '--warn=no-visual-c-missing -f - ' + ' '.join(args), - chdir = test.workpath('WORK'), - stdin = Stdin % dict) + arguments='--warn=no-visual-c-missing -f - ' + ' '.join(args), + chdir=test.workpath('WORK'), + stdin=Stdin % dict) os.environ.update(save_vals) for key in delete_keys: del(os.environ[key]) @@ -697,8 +697,8 @@ def command_scons(args, c, test, dict): if lines: while lines[-1] == '': lines = lines[:-1] - #err = test.stderr() - #if err: + # err = test.stderr() + # if err: # sys.stderr.write(err) return lines @@ -783,10 +783,10 @@ def create_scons_output(e): for f in e.files: if f.isFileRef(): continue - # + # # Left-align file's contents, starting on the first # non-empty line - # + # data = f.content.split('\n') i = 0 # Skip empty lines @@ -883,10 +883,10 @@ def create_scons_output(e): sroot.text = content # Construct filename - fpath = os.path.join(generated_examples, - e.name+'_'+o.suffix+'.xml') + fpath = os.path.join(generated_examples, + e.name + '_' + o.suffix + '.xml') # Expand Element tree - s = stf.decorateWithCommentHeader(stf.convertElementTree(sroot)[0]) + s = stf.decorateWithHeader(stf.convertElementTree(sroot)[0]) # Write it to file stf.writeTree(s, fpath) diff --git a/bin/docs-check-unique-examples.py b/bin/docs-check-unique-examples.py deleted file mode 100644 index d9e5cf6..0000000 --- a/bin/docs-check-unique-examples.py +++ /dev/null @@ -1,17 +0,0 @@ -#!/usr/bin/env python -# -# Searches through the whole doc/user tree and verifies -# that the names of the single examples are unique over -# all *.xml files. -# Additionally, the suffix entries have to be unique -# within each scons_command_output. -# - -import os -import SConsExamples - -if __name__ == "__main__": - if SConsExamples.exampleNamesAreUnique(os.path.join('doc','user')): - print "OK" - else: - print "Not all example names and suffixes are unique! Please correct the errors listed above and try again." diff --git a/bin/docs-create-example-outputs.py b/bin/docs-create-example-outputs.py new file mode 100644 index 0000000..30dc0ee --- /dev/null +++ b/bin/docs-create-example-outputs.py @@ -0,0 +1,19 @@ +#!/usr/bin/env python +# +# Searches through the whole doc/user tree and creates +# all output files for the single examples. +# + +import os +import sys +import SConsExamples + +if __name__ == "__main__": + print "Checking whether all example names are unique..." + if SConsExamples.exampleNamesAreUnique(os.path.join('doc','user')): + print "OK" + else: + print "Not all example names and suffixes are unique! Please correct the errors listed above and try again." + sys.exit(0) + + SConsExamples.createAllExampleOutputs(os.path.join('doc','user')) diff --git a/bin/docs-update-generated.py b/bin/docs-update-generated.py index e689903..66b22c0 100644 --- a/bin/docs-update-generated.py +++ b/bin/docs-update-generated.py @@ -11,7 +11,7 @@ import os import SConsDoc # Directory where all generated files are stored -gen_folder = 'doc/generated' +gen_folder = os.path.join('doc','generated') def argpair(key): """ Return the argument pair *.gen,*.mod for the given key. """ @@ -41,8 +41,9 @@ def generate_all(): print "Couldn't create destination folder %s! Exiting..." % gen_folder return # Call scons-proc.py - os.system('python bin/scons-proc.py -b %s -f %s -t %s -v %s %s' % - (argpair('builders'), argpair('functions'), + os.system('python %s -b %s -f %s -t %s -v %s %s' % + (os.path.join('bin','scons-proc.py'), + argpair('builders'), argpair('functions'), argpair('tools'), argpair('variables'), ' '.join(flist))) diff --git a/bin/docs-validate.py b/bin/docs-validate.py index fc90ee7..1ed0da0 100644 --- a/bin/docs-validate.py +++ b/bin/docs-validate.py @@ -2,10 +2,6 @@ # # Searches through the whole source tree and validates all # documentation files against our own XSD in docs/xsd. -# Additionally, it rewrites all files such that the XML gets -# pretty-printed in a consistent way. This is done to ensure that -# merging and diffing doesn't get too hard when people start to -# use different XML editors... # import os diff --git a/bin/scons-doc.py b/bin/scons-doc.py deleted file mode 100644 index 95da5f3..0000000 --- a/bin/scons-doc.py +++ /dev/null @@ -1,555 +0,0 @@ -#!/usr/bin/env python -# -# Copyright (c) 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. - -# -# -# This script looks for some XML tags that describe SCons example -# configurations and commands to execute in those configurations, and -# uses TestCmd.py to execute the commands and insert the output from -# those commands into the XML that we output. This way, we can run a -# script and update all of our example documentation output without -# a lot of laborious by-hand checking. -# -# An "SCons example" looks like this, and essentially describes a set of -# input files (program source files as well as SConscript files): -# -# -# -# env = Environment() -# env.Program('foo') -# -# -# int main() { printf("foo.c\n"); } -# -# -# -# The contents within the tag will get written -# into a temporary directory whenever example output needs to be -# generated. By default, the contents are not inserted into text -# directly, unless you set the "printme" attribute on one or more files, -# in which case they will get inserted within a tag. -# This makes it easy to define the example at the appropriate -# point in the text where you intend to show the SConstruct file. -# -# Note that you should usually give the a "name" -# attribute so that you can refer to the example configuration later to -# run SCons and generate output. -# -# If you just want to show a file's contents without worry about running -# SCons, there's a shorter tag: -# -# -# env = Environment() -# env.Program('foo') -# -# -# This is essentially equivalent to , -# but it's more straightforward. -# -# SCons output is generated from the following sort of tag: -# -# -# scons -Q foo -# scons -Q foo -# -# -# You tell it which example to use with the "example" attribute, and then -# give it a list of tags to execute. You can also -# supply an "os" tag, which specifies the type of operating system this -# example is intended to show; if you omit this, default value is "posix". -# -# The generated XML will show the command line (with the appropriate -# command-line prompt for the operating system), execute the command in -# a temporary directory with the example files, capture the standard -# output from SCons, and insert it into the text as appropriate. -# Error output gets passed through to your error output so you -# can see if there are any problems executing the command. -# - -import os -import re -import sys -import time - -sys.path.append(os.path.join(os.getcwd(), 'QMTest')) -sys.path.append(os.path.join(os.getcwd(), 'build', 'QMTest')) - -scons_py = os.path.join('bootstrap', 'src', 'script', 'scons.py') -if not os.path.exists(scons_py): - scons_py = os.path.join('src', 'script', 'scons.py') - -scons_lib_dir = os.path.join(os.getcwd(), 'bootstrap', 'src', 'engine') -if not os.path.exists(scons_lib_dir): - scons_lib_dir = os.path.join(os.getcwd(), 'src', 'engine') - -os.environ['SCONS_LIB_DIR'] = scons_lib_dir - -import TestCmd - - -Prompt = { - 'posix' : '% ', - 'win32' : 'C:\\>' -} - -# The magick SCons hackery that makes this work. -# -# So that our examples can still use the default SConstruct file, we -# actually feed the following into SCons via stdin and then have it -# SConscript() the SConstruct file. This stdin wrapper creates a set -# of ToolSurrogates for the tools for the appropriate platform. These -# Surrogates print output like the real tools and behave like them -# without actually having to be on the right platform or have the right -# tool installed. -# -# The upshot: The wrapper transparently changes the world out from -# under the top-level SConstruct file in an example just so we can get -# the command output. - -Stdin = """\ -import os -import re -import SCons.Action -import SCons.Defaults -import SCons.Node.FS - -platform = '%(osname)s' - -Sep = { - 'posix' : '/', - 'win32' : '\\\\', -}[platform] - - -# Slip our own __str__() method into the EntryProxy class used to expand -# $TARGET{S} and $SOURCE{S} to translate the path-name separators from -# what's appropriate for the system we're running on to what's appropriate -# for the example system. -orig = SCons.Node.FS.EntryProxy -class MyEntryProxy(orig): - def __str__(self): - return str(self._subject).replace(os.sep, Sep) -SCons.Node.FS.EntryProxy = MyEntryProxy - -# Slip our own RDirs() method into the Node.FS.File class so that the -# expansions of $_{CPPINC,F77INC,LIBDIR}FLAGS will have the path-name -# separators translated from what's appropriate for the system we're -# running on to what's appropriate for the example system. -orig_RDirs = SCons.Node.FS.File.RDirs -def my_RDirs(self, pathlist, orig_RDirs=orig_RDirs): - return [str(x).replace(os.sep, Sep) for x in orig_RDirs(self, pathlist)] -SCons.Node.FS.File.RDirs = my_RDirs - -class Curry(object): - def __init__(self, fun, *args, **kwargs): - self.fun = fun - self.pending = args[:] - self.kwargs = kwargs.copy() - - def __call__(self, *args, **kwargs): - if kwargs and self.kwargs: - kw = self.kwargs.copy() - kw.update(kwargs) - else: - kw = kwargs or self.kwargs - - return self.fun(*self.pending + args, **kw) - -def Str(target, source, env, cmd=""): - result = [] - for cmd in env.subst_list(cmd, target=target, source=source): - result.append(' '.join(map(str, cmd))) - return '\\n'.join(result) - -class ToolSurrogate(object): - def __init__(self, tool, variable, func, varlist): - self.tool = tool - if not isinstance(variable, list): - variable = [variable] - self.variable = variable - self.func = func - self.varlist = varlist - def __call__(self, env): - t = Tool(self.tool) - t.generate(env) - for v in self.variable: - orig = env[v] - try: - strfunction = orig.strfunction - except AttributeError: - strfunction = Curry(Str, cmd=orig) - # Don't call Action() through its global function name, because - # that leads to infinite recursion in trying to initialize the - # Default Environment. - env[v] = SCons.Action.Action(self.func, - strfunction=strfunction, - varlist=self.varlist) - def __repr__(self): - # This is for the benefit of printing the 'TOOLS' - # variable through env.Dump(). - return repr(self.tool) - -def Null(target, source, env): - pass - -def Cat(target, source, env): - target = str(target[0]) - f = open(target, "wb") - for src in map(str, source): - f.write(open(src, "rb").read()) - f.close() - -def CCCom(target, source, env): - target = str(target[0]) - fp = open(target, "wb") - def process(source_file, fp=fp): - for line in open(source_file, "rb").readlines(): - m = re.match(r'#include\s[<"]([^<"]+)[>"]', line) - if m: - include = m.group(1) - for d in [str(env.Dir('$CPPPATH')), '.']: - f = os.path.join(d, include) - if os.path.exists(f): - process(f) - break - elif line[:11] != "STRIP CCCOM": - fp.write(line) - for src in map(str, source): - process(src) - fp.write('debug = ' + ARGUMENTS.get('debug', '0') + '\\n') - fp.close() - -public_class_re = re.compile('^public class (\S+)', re.MULTILINE) - -def JavaCCom(target, source, env): - # This is a fake Java compiler that just looks for - # public class FooBar - # lines in the source file(s) and spits those out - # to .class files named after the class. - tlist = list(map(str, target)) - not_copied = {} - for t in tlist: - not_copied[t] = 1 - for src in map(str, source): - contents = open(src, "rb").read() - classes = public_class_re.findall(contents) - for c in classes: - for t in [x for x in tlist if x.find(c) != -1]: - open(t, "wb").write(contents) - del not_copied[t] - for t in not_copied.keys(): - open(t, "wb").write("\\n") - -def JavaHCom(target, source, env): - tlist = map(str, target) - slist = map(str, source) - for t, s in zip(tlist, slist): - open(t, "wb").write(open(s, "rb").read()) - -def JarCom(target, source, env): - target = str(target[0]) - class_files = [] - for src in map(str, source): - for dirpath, dirnames, filenames in os.walk(src): - class_files.extend([ os.path.join(dirpath, f) - for f in filenames if f.endswith('.class') ]) - f = open(target, "wb") - for cf in class_files: - f.write(open(cf, "rb").read()) - f.close() - -# XXX Adding COLOR, COLORS and PACKAGE to the 'cc' varlist(s) by hand -# here is bogus. It's for the benefit of doc/user/command-line.in, which -# uses examples that want to rebuild based on changes to these variables. -# It would be better to figure out a way to do it based on the content of -# the generated command-line, or else find a way to let the example markup -# language in doc/user/command-line.in tell this script what variables to -# add, but that's more difficult than I want to figure out how to do right -# now, so let's just use the simple brute force approach for the moment. - -ToolList = { - 'posix' : [('cc', ['CCCOM', 'SHCCCOM'], CCCom, ['CCFLAGS', 'CPPDEFINES', 'COLOR', 'COLORS', 'PACKAGE']), - ('link', ['LINKCOM', 'SHLINKCOM'], Cat, []), - ('ar', ['ARCOM', 'RANLIBCOM'], Cat, []), - ('tar', 'TARCOM', Null, []), - ('zip', 'ZIPCOM', Null, []), - ('BitKeeper', 'BITKEEPERCOM', Cat, []), - ('CVS', 'CVSCOM', Cat, []), - ('RCS', 'RCS_COCOM', Cat, []), - ('SCCS', 'SCCSCOM', Cat, []), - ('javac', 'JAVACCOM', JavaCCom, []), - ('javah', 'JAVAHCOM', JavaHCom, []), - ('jar', 'JARCOM', JarCom, []), - ('rmic', 'RMICCOM', Cat, []), - ], - 'win32' : [('msvc', ['CCCOM', 'SHCCCOM', 'RCCOM'], CCCom, ['CCFLAGS', 'CPPDEFINES', 'COLOR', 'COLORS', 'PACKAGE']), - ('mslink', ['LINKCOM', 'SHLINKCOM'], Cat, []), - ('mslib', 'ARCOM', Cat, []), - ('tar', 'TARCOM', Null, []), - ('zip', 'ZIPCOM', Null, []), - ('BitKeeper', 'BITKEEPERCOM', Cat, []), - ('CVS', 'CVSCOM', Cat, []), - ('RCS', 'RCS_COCOM', Cat, []), - ('SCCS', 'SCCSCOM', Cat, []), - ('javac', 'JAVACCOM', JavaCCom, []), - ('javah', 'JAVAHCOM', JavaHCom, []), - ('jar', 'JARCOM', JarCom, []), - ('rmic', 'RMICCOM', Cat, []), - ], -} - -toollist = ToolList[platform] -filter_tools = '%(tools)s'.split() -if filter_tools: - toollist = [x for x in toollist if x[0] in filter_tools] - -toollist = [ToolSurrogate(*t) for t in toollist] - -toollist.append('install') - -def surrogate_spawn(sh, escape, cmd, args, env): - pass - -def surrogate_pspawn(sh, escape, cmd, args, env, stdout, stderr): - pass - -SCons.Defaults.ConstructionEnvironment.update({ - 'PLATFORM' : platform, - 'TOOLS' : toollist, - 'SPAWN' : surrogate_spawn, - 'PSPAWN' : surrogate_pspawn, -}) - -SConscript('SConstruct') -""" - -# "Commands" that we will execute in our examples. -def command_scons(args, c, test, dict): - save_vals = {} - delete_keys = [] - try: - ce = c.environment - except AttributeError: - pass - else: - for arg in c.environment.split(): - key, val = arg.split('=') - try: - save_vals[key] = os.environ[key] - except KeyError: - delete_keys.append(key) - os.environ[key] = val - test.run(interpreter = sys.executable, - program = scons_py, - # We use ToolSurrogates to capture win32 output by "building" - # examples using a fake win32 tool chain. Suppress the - # warnings that come from the new revamped VS support so - # we can build doc on (Linux) systems that don't have - # Visual C installed. - arguments = '--warn=no-visual-c-missing -f - ' + ' '.join(args), - chdir = test.workpath('WORK'), - stdin = Stdin % dict) - os.environ.update(save_vals) - for key in delete_keys: - del(os.environ[key]) - out = test.stdout() - out = out.replace(test.workpath('ROOT'), '') - out = out.replace(test.workpath('WORK/SConstruct'), - '/home/my/project/SConstruct') - lines = out.split('\n') - if lines: - while lines[-1] == '': - lines = lines[:-1] - #err = test.stderr() - #if err: - # sys.stderr.write(err) - return lines - -def command_touch(args, c, test, dict): - if args[0] == '-t': - t = int(time.mktime(time.strptime(args[1], '%Y%m%d%H%M'))) - times = (t, t) - args = args[2:] - else: - time.sleep(1) - times = None - for file in args: - if not os.path.isabs(file): - file = os.path.join(test.workpath('WORK'), file) - if not os.path.exists(file): - open(file, 'wb') - os.utime(file, times) - return [] - -def command_edit(args, c, test, dict): - try: - add_string = c.edit[:] - except AttributeError: - add_string = 'void edit(void) { ; }\n' - if add_string[-1] != '\n': - add_string = add_string + '\n' - for file in args: - if not os.path.isabs(file): - file = os.path.join(test.workpath('WORK'), file) - contents = open(file, 'rb').read() - open(file, 'wb').write(contents + add_string) - return [] - -def command_ls(args, c, test, dict): - def ls(a): - return [' '.join(sorted([x for x in os.listdir(a) if x[0] != '.']))] - if args: - l = [] - for a in args: - l.extend(ls(test.workpath('WORK', a))) - return l - else: - return ls(test.workpath('WORK')) - -def command_sleep(args, c, test, dict): - time.sleep(int(args[0])) - -CommandDict = { - 'scons' : command_scons, - 'touch' : command_touch, - 'edit' : command_edit, - 'ls' : command_ls, - 'sleep' : command_sleep, -} - -def ExecuteCommand(args, c, t, dict): - try: - func = CommandDict[args[0]] - except KeyError: - func = lambda args, c, t, dict: [] - return func(args[1:], c, t, dict) - - -def for_display(contents): - contents = contents.replace('__ROOT__', '') - contents = contents.replace('<', '<') - contents = contents.replace('>', '>') - return contents - - -def create_scons_output(e): - # The real raison d'etre for this script, this is where we - # actually execute SCons to fetch the output. - - # Loop over all outputs for the example - for o in e.outputs: - # Create new test directory - t = TestCmd.TestCmd(workdir='', combine=1) - if o.preserve: - t.preserve() - t.subdir('ROOT', 'WORK') - t.rootpath = t.workpath('ROOT').replace('\\', '\\\\') - - for d in e.dirs: - dir = t.workpath('WORK', d.name) - if not os.path.exists(dir): - os.makedirs(dir) - - for f in e.files: - if f.isFileRef(): - continue - # - # Left-align file's contents, starting on the first - # non-empty line - # - data = f.content.split('\n') - i = 0 - # Skip empty lines - while data[i] == '': - i = i + 1 - lines = data[i:] - i = 0 - # Scan first line for the number of spaces - # that this block is indented - while lines[0][i] == ' ': - i = i + 1 - # Left-align block - lines = [l[i:] for l in lines] - path = f.name.replace('__ROOT__', t.rootpath) - if not os.path.isabs(path): - path = t.workpath('WORK', path) - dir, name = os.path.split(path) - if dir and not os.path.exists(dir): - os.makedirs(dir) - content = '\n'.join(lines) - content = content.replace('__ROOT__', t.rootpath) - path = t.workpath('WORK', path) - t.write(path, content) - if hasattr(f, 'chmod'): - os.chmod(path, int(f.chmod, 0)) - - # Regular expressions for making the doc output consistent, - # regardless of reported addresses or Python version. - - # Massage addresses in object repr strings to a constant. - address_re = re.compile(r' at 0x[0-9a-fA-F]*\>') - - # Massage file names in stack traces (sometimes reported as absolute - # paths) to a consistent relative path. - engine_re = re.compile(r' File ".*/src/engine/SCons/') - - # Python 2.5 changed the stack trace when the module is read - # from standard input from read "... line 7, in ?" to - # "... line 7, in ". - file_re = re.compile(r'^( *File ".*", line \d+, in) \?$', re.M) - - # Python 2.6 made UserList a new-style class, which changes the - # AttributeError message generated by our NodeList subclass. - nodelist_re = re.compile(r'(AttributeError:) NodeList instance (has no attribute \S+)') - - for c in o.commandlist: - # Open new output file - fpath = os.path.join(SConsExamples.generated_examples, - e.name+'_'+c.suffix+'.out','w') - outfp = open(fpath) - outfp.write(Prompt[o.os]) - d = c.cmd.replace('__ROOT__', '') - outfp.write('' + d + '\n') - - cmd_work = c.cmd.replace('__ROOT__', t.workpath('ROOT')) - args = cmd_work.split() - lines = ExecuteCommand(args, c, t, {'osname':o.os, 'tools':o.tools}) - content = None - if c.output: - content = c.output - elif lines: - content = '\n'.join(lines) - if content: - content = address_re.sub(r' at 0x700000>', content) - content = engine_re.sub(r' File "bootstrap/src/engine/SCons/', content) - content = file_re.sub(r'\1 ', content) - content = nodelist_re.sub(r"\1 'NodeList' object \2", content) - content = for_display(content) - outfp.write(content + '\n') - outfp.close() - -# Local Variables: -# tab-width:4 -# indent-tabs-mode:nil -# End: -# vim: set expandtab tabstop=4 shiftwidth=4: diff --git a/bin/scons-proc.py b/bin/scons-proc.py index 36176f1..5be1f00 100644 --- a/bin/scons-proc.py +++ b/bin/scons-proc.py @@ -134,7 +134,8 @@ class SCons_XML(object): ve = stf.newNode("varlistentry") stf.setAttribute(ve, 'id', '%s%s' % (v.prefix, v.idfunc())) - stf.appendNode(ve, v.xml_term()) + for t in v.xml_terms(): + stf.appendNode(ve, t) vl = stf.newNode("listitem") added = False if v.summary is not None: @@ -237,29 +238,26 @@ class SConsThing(Proxy): def idfunc(self): return self.name - def xml_term(self): + def xml_terms(self): e = stf.newNode("term") stf.setText(e, self.name) - return e + return [e] class Builder(SConsThing): description = 'builder' prefix = 'b-' tag = 'function' - def xml_term(self): - t = stf.newNode("term") - s = stf.newNode("synopsis") + def xml_terms(self): + ta = stf.newNode("term") b = stf.newNode(self.tag) stf.setText(b, self.name+'()') - stf.appendNode(s, b) - stf.appendNode(t, s) - s = stf.newNode("synopsis") + stf.appendNode(ta, b) + tb = stf.newNode("term") b = stf.newNode(self.tag) stf.setText(b, 'env.'+self.name+'()') - stf.appendNode(s, b) - stf.appendNode(t, s) - return t + stf.appendNode(tb, b) + return [ta, tb] def entityfunc(self): return self.name @@ -345,18 +343,14 @@ h = parse_docs(args, False) write_output_files(h, buildersfiles, functionsfiles, toolsfiles, variablesfiles, SCons_XML.write_mod) -# Step 2: Patching the include paths for entity definitions in XML files -print "Patching include paths..." -os.system('python bin/docs-correct-mod-paths.py') - -# Step 3: Validating all input files +# Step 2: Validating all input files print "Validating files against SCons XSD..." if SConsDoc.validate_all_xml(['src']): print "OK" else: print "Validation failed! Please correct the errors above and try again." -# Step 4: Creating actual documentation snippets, using the +# Step 3: Creating actual documentation snippets, using the # fully resolved and updated entities from the *.mod files. print "Updating documentation for builders, tools and functions..." h = parse_docs(args, True) diff --git a/doc/editor_configs/xmlmind/addon/config/scons/common.incl b/doc/editor_configs/xmlmind/addon/config/scons/common.incl index eafa0a4..d03f74c 100644 --- a/doc/editor_configs/xmlmind/addon/config/scons/common.incl +++ b/doc/editor_configs/xmlmind/addon/config/scons/common.incl @@ -11,7 +11,9 @@ + literallayout programlisting screen synopsis + sconstruct scons_example_file example_commands + scons_output_command file directory" /> diff --git a/doc/generated/builders.gen b/doc/generated/builders.gen index 2b033e4..0e3073e 100644 --- a/doc/generated/builders.gen +++ b/doc/generated/builders.gen @@ -15,12 +15,10 @@ - - CFile() - - - env.CFile() - + CFile() + + + env.CFile() @@ -43,12 +41,10 @@ env.CFile(target = 'bar', source = 'bar.y') - - Command() - - - env.Command() - + Command() + + + env.Command() @@ -63,12 +59,10 @@ for the calling syntax and details. - - CXXFile() - - - env.CXXFile() - + CXXFile() + + + env.CXXFile() @@ -92,12 +86,10 @@ env.CXXFile(target = 'bar', source = 'bar.yy') - - DVI() - - - env.DVI() - + DVI() + + + env.DVI() @@ -153,12 +145,10 @@ env.DVI(target = 'ccc.dvi', source = 'ccc.latex') - - Install() - - - env.Install() - + Install() + + + env.Install() @@ -178,12 +168,10 @@ env.Install('/usr/local/bin', source = ['foo', 'bar']) - - InstallAs() - - - env.InstallAs() - + InstallAs() + + + env.InstallAs() @@ -201,12 +189,10 @@ arguments list different numbers of files or directories. - - InstallVersionedLib() - - - env.InstallVersionedLib() - + InstallVersionedLib() + + + env.InstallVersionedLib() @@ -226,12 +212,10 @@ env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'], - - Jar() - - - env.Jar() - + Jar() + + + env.Jar() @@ -277,12 +261,10 @@ env.Jar(target = 'bar.jar', - - Java() - - - env.Java() - + Java() + + + env.Java() @@ -357,12 +339,10 @@ env['ENV']['LANG'] = 'en_GB.UTF-8' - - JavaH() - - - env.JavaH() - + JavaH() + + + env.JavaH() @@ -415,12 +395,10 @@ env.JavaH(target = 'export', - - Library() - - - env.Library() - + Library() + + + env.Library() @@ -432,12 +410,10 @@ builder method. - - LoadableModule() - - - env.LoadableModule() - + LoadableModule() + + + env.LoadableModule() @@ -451,12 +427,10 @@ this creates a loadable module bundle. - - M4() - - - env.M4() - + M4() + + + env.M4() @@ -476,12 +450,10 @@ env.M4(target = 'foo.c', source = 'foo.c.m4') - - Moc() - - - env.Moc() - + Moc() + + + env.Moc() @@ -499,12 +471,10 @@ env.Moc('foo.cpp') # generates foo.moc - - MOFiles() - - - env.MOFiles() - + MOFiles() + + + env.MOFiles() @@ -556,12 +526,10 @@ Compile files for languages defined in LINGUAS file - - MSVSProject() - - - env.MSVSProject() - + MSVSProject() + + + env.MSVSProject() @@ -739,12 +707,10 @@ env.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'], - - MSVSSolution() - - - env.MSVSSolution() - + MSVSSolution() + + + env.MSVSSolution() @@ -813,12 +779,10 @@ env.MSVSSolution(target = 'Bar' + env['MSVSSOLUTIONSUFFIX'], - - Object() - - - env.Object() - + Object() + + + env.Object() @@ -830,12 +794,10 @@ builder method. - - Package() - - - env.Package() - + Package() + + + env.Package() @@ -905,12 +867,10 @@ env.Package( NAME = 'foo', - - PCH() - - - env.PCH() - + PCH() + + + env.PCH() @@ -932,12 +892,10 @@ env['PCH'] = env.PCH('StdAfx.cpp')[0] - - PDF() - - - env.PDF() - + PDF() + + + env.PDF() @@ -963,12 +921,10 @@ env.PDF(target = 'bbb', source = 'bbb.dvi') - - POInit() - - - env.POInit() - + POInit() + + + env.POInit() @@ -1071,12 +1027,10 @@ which has same efect as: - - PostScript() - - - env.PostScript() - + PostScript() + + + env.PostScript() @@ -1102,12 +1056,10 @@ env.PostScript(target = 'bbb', source = 'bbb.dvi') - - POTUpdate() - - - env.POTUpdate() - + POTUpdate() + + + env.POTUpdate() @@ -1274,12 +1226,10 @@ then the messages.pot will contain - - POUpdate() - - - env.POUpdate() - + POUpdate() + + + env.POUpdate() @@ -1393,12 +1343,10 @@ pre-configured via environment. - - Program() - - - env.Program() - + Program() + + + env.Program() @@ -1429,12 +1377,10 @@ env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f']) - - RES() - - - env.RES() - + RES() + + + env.RES() @@ -1457,12 +1403,10 @@ env.RES('resource.rc') - - RMIC() - - - env.RMIC() - + RMIC() + + + env.RMIC() @@ -1506,12 +1450,10 @@ env.RMIC(target = 'outdir3', - - RPCGenClient() - - - env.RPCGenClient() - + RPCGenClient() + + + env.RPCGenClient() @@ -1531,12 +1473,10 @@ env.RPCGenClient('src/rpcif.x') - - RPCGenHeader() - - - env.RPCGenHeader() - + RPCGenHeader() + + + env.RPCGenHeader() @@ -1556,12 +1496,10 @@ env.RPCGenHeader('src/rpcif.x') - - RPCGenService() - - - env.RPCGenService() - + RPCGenService() + + + env.RPCGenService() @@ -1581,12 +1519,10 @@ env.RPCGenClient('src/rpcif.x') - - RPCGenXDR() - - - env.RPCGenXDR() - + RPCGenXDR() + + + env.RPCGenXDR() @@ -1606,12 +1542,10 @@ env.RPCGenClient('src/rpcif.x') - - SharedLibrary() - - - env.SharedLibrary() - + SharedLibrary() + + + env.SharedLibrary() @@ -1716,12 +1650,10 @@ when it is done linking it. - - SharedObject() - - - env.SharedObject() - + SharedObject() + + + env.SharedObject() @@ -1770,12 +1702,10 @@ below, for more information. - - StaticLibrary() - - - env.StaticLibrary() - + StaticLibrary() + + + env.StaticLibrary() @@ -1816,12 +1746,10 @@ will raise an error if there is any mismatch. - - StaticObject() - - - env.StaticObject() - + StaticObject() + + + env.StaticObject() @@ -1890,12 +1818,10 @@ below, for more information. - - Substfile() - - - env.Substfile() - + Substfile() + + + env.Substfile() @@ -1985,12 +1911,10 @@ subst.Substfile('pgm2.c', [Value('#include "@foo@.h"'), - - Tar() - - - env.Tar() - + Tar() + + + env.Tar() @@ -2033,12 +1957,10 @@ env.Tar('foo') - - Textfile() - - - env.Textfile() - + Textfile() + + + env.Textfile() @@ -2106,12 +2028,10 @@ blob.txt - - Translate() - - - env.Translate() - + Translate() + + + env.Translate() @@ -2246,12 +2166,10 @@ running scons '.'. - - TypeLibrary() - - - env.TypeLibrary() - + TypeLibrary() + + + env.TypeLibrary() @@ -2280,12 +2198,10 @@ files. - - Uic() - - - env.Uic() - + Uic() + + + env.Uic() @@ -2311,12 +2227,10 @@ env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'), - - Zip() - - - env.Zip() - + Zip() + + + env.Zip() diff --git a/doc/images/overview.graphml b/doc/images/overview.graphml new file mode 100644 index 0000000..74f80d7 --- /dev/null +++ b/doc/images/overview.graphml @@ -0,0 +1,418 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + User's view + + + + + + + + + + Folder 1 + + + + + + + + + + + + + + + + XML files (src/user/man/...) + + + + + + + + + + + + + + + + + XML validation + + + + + + + + + + + + + + + + + Writer + + + + + + + + + + + + + + + + + + + + + + Creating entity lists + + + + + + + + + + + + + + + + + + Check that example +names are unique + + + + + + + + + + + + + + + + + Create example outputs + + + + + + + + + + + + + + + + + Resolve XIncludes for text +and examples + + + + + + + + + + + + + + + + + Create HTML, PDF, Man + + + + + + + + + + + + + + + + + Install in proper place +for packaging + + + + + + + + + + + + + + + + + Create API doc +(Epydoc) + + + + + + + + + + + + + + + + + get validated + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + switching to Docbook + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + edits/creates + + + + + + + + <?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 15.0.2, SVG Export Plug-In . SVG Version: 6.00 Build 0) --> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> +<svg version="1.1" id="Ebene_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px" + width="57px" height="65px" viewBox="0 0 57 65" enable-background="new 0 0 57 65" xml:space="preserve"> +<g> + + <linearGradient id="SVGID_1_" gradientUnits="userSpaceOnUse" x1="26.5396" y1="-732.5005" x2="27.7805" y2="-762.2984" gradientTransform="matrix(1 0 0 -1 0.1201 -708.5371)"> + <stop offset="0.2711" style="stop-color:#FFAB4F"/> + <stop offset="1" style="stop-color:#FFD28F"/> + </linearGradient> + <path fill="url(#SVGID_1_)" stroke="#ED9135" stroke-miterlimit="10" d="M49.529,51.225c-4.396-4.396-10.951-5.884-12.063-6.109 + V37.8H19.278c0,0,0.038,6.903,0,6.868c0,0-6.874,0.997-12.308,6.432C1.378,56.691,0.5,62.77,0.5,62.77 + c0,1.938,1.575,3.492,3.523,3.492h48.51c1.947,0,3.521-1.558,3.521-3.492C56.055,62.768,54.211,55.906,49.529,51.225z"/> + + <radialGradient id="face_x5F_white_1_" cx="27.7827" cy="-734.2632" r="23.424" fx="23.2131" fy="-736.753" gradientTransform="matrix(1 0 0 -1 0.1201 -708.5371)" gradientUnits="userSpaceOnUse"> + <stop offset="0" style="stop-color:#FFD28F"/> + <stop offset="1" style="stop-color:#FFAB4F"/> + </radialGradient> + <path id="face_x5F_white_3_" fill="url(#face_x5F_white_1_)" stroke="#ED9135" stroke-miterlimit="10" d="M43.676,23.357 + c0.086,10.2-6.738,18.52-15.246,18.586c-8.503,0.068-15.467-8.146-15.553-18.344C12.794,13.4,19.618,5.079,28.123,5.012 + C36.627,4.945,43.59,13.158,43.676,23.357z"/> + + <linearGradient id="face_highlight_1_" gradientUnits="userSpaceOnUse" x1="2941.4297" y1="5677.457" x2="2965.0596" y2="5770.9087" gradientTransform="matrix(0.275 0 0 0.2733 -783.3976 -1543.4047)"> + <stop offset="0" style="stop-color:#FFFFFF;stop-opacity:0.42"/> + <stop offset="1" style="stop-color:#FFFFFF;stop-opacity:0.2067"/> + </linearGradient> + <path id="face_highlight_3_" fill="url(#face_highlight_1_)" d="M27.958,6.333c-6.035,0.047-10.747,4.493-12.787,10.386 + c-0.664,1.919-0.294,4.043,0.98,5.629c2.73,3.398,5.729,6.283,9.461,8.088c3.137,1.518,7.535,2.385,11.893,1.247 + c2.274-0.592,3.988-2.459,4.375-4.766c0.183-1.094,0.293-2.289,0.283-3.553C42.083,13.952,36.271,6.268,27.958,6.333z"/> + <path fill="#CC9869" stroke="#99724F" stroke-linecap="round" stroke-linejoin="round" d="M32.215,9.938 + c0,0,5.688,2.75,7.688,8.125c2.104,5.652,4.123,8.232,4.188,8c1.875-6.794,1.063-21.438-10.17-21.587 + c-20.455-7.663-25.58,11.962-23.893,19.65c1.078,4.911,2.234,6.686,3.938,8.08C13.966,32.205,15.028,17.563,32.215,9.938z"/> + + <radialGradient id="collar_x5F_body_2_" cx="15.1587" cy="-765.7056" r="32.4004" gradientTransform="matrix(1 0 0 -1 0.1201 -708.5371)" gradientUnits="userSpaceOnUse"> + <stop offset="0" style="stop-color:#B0E8FF"/> + <stop offset="1" style="stop-color:#74AEEE"/> + </radialGradient> + <path id="collar_x5F_body_1_" fill="url(#collar_x5F_body_2_)" stroke="#5491CF" d="M0.5,62.768c0,1.938,1.575,3.494,3.523,3.494 + h48.51c1.947,0,3.521-1.559,3.521-3.494c0,0-1.844-6.861-6.525-11.543c-4.815-4.813-11.244-6.146-11.244-6.146 + c-1.771,1.655-5.61,2.802-10.063,2.802c-4.453,0-8.292-1.146-10.063-2.802c0,0-5.755,0.586-11.189,6.021 + C1.378,56.689,0.5,62.768,0.5,62.768z"/> + + <radialGradient id="collar_x5F_r_2_" cx="31.5" cy="-755.832" r="9.2834" gradientTransform="matrix(1 0 0 -1 0.1201 -708.5371)" gradientUnits="userSpaceOnUse"> + <stop offset="0" style="stop-color:#80CCFF"/> + <stop offset="1" style="stop-color:#74AEEE"/> + </radialGradient> + <path id="collar_x5F_r_1_" fill="url(#collar_x5F_r_2_)" stroke="#5491CF" d="M38.159,41.381c0,0-0.574,2.369-3.013,4.441 + c-2.108,1.795-5.783,2.072-5.783,2.072l3.974,6.217c0,0,2.957-1.637,5.009-3.848c1.922-2.072,1.37-5.479,1.37-5.479L38.159,41.381z + "/> + + <radialGradient id="collar_x5F_l_2_" cx="19.1377" cy="-755.873" r="9.2837" gradientTransform="matrix(1 0 0 -1 0.1201 -708.5371)" gradientUnits="userSpaceOnUse"> + <stop offset="0" style="stop-color:#80CCFF"/> + <stop offset="1" style="stop-color:#74AEEE"/> + </radialGradient> + <path id="collar_x5F_l_1_" fill="url(#collar_x5F_l_2_)" stroke="#5491CF" d="M18.63,41.422c0,0,0.576,2.369,3.012,4.441 + c2.109,1.793,5.785,2.072,5.785,2.072l-3.974,6.217c0,0-2.957-1.637-5.007-3.85c-1.922-2.072-1.37-5.48-1.37-5.48L18.63,41.422z"/> + + <radialGradient id="Knob2_2_" cx="27.8872" cy="7.9414" r="0.9669" gradientTransform="matrix(1 0 0 -1 0.04 64.1543)" gradientUnits="userSpaceOnUse"> + <stop offset="0" style="stop-color:#80CCFF"/> + <stop offset="1" style="stop-color:#74AEEE"/> + </radialGradient> + <circle id="Knob2_1_" fill="url(#Knob2_2_)" stroke="#5491CF" cx="28.258" cy="56.254" r="0.584"/> + + <radialGradient id="Knob1_2_" cx="27.9253" cy="1.6973" r="0.9669" gradientTransform="matrix(1 0 0 -1 0.04 64.1543)" gradientUnits="userSpaceOnUse"> + <stop offset="0" style="stop-color:#80CCFF"/> + <stop offset="1" style="stop-color:#74AEEE"/> + </radialGradient> + <circle id="Knob1_1_" fill="url(#Knob1_2_)" stroke="#5491CF" cx="28.296" cy="62.499" r="0.584"/> +</g> +</svg> + + + + diff --git a/doc/overview.rst b/doc/overview.rst new file mode 100644 index 0000000..612fbba --- /dev/null +++ b/doc/overview.rst @@ -0,0 +1,174 @@ +============================= +SCons Documentation Toolchain +============================= + + +Introduction +============ + +This text tries to give an overview of the current SCons documentation toolchain. +The interested user should be able to better understand where and how the text he writes +is processed. +It is also a reference for core developers and the release team. + +.. image:: images/overview.png + +The diagram above roughly shows the steps that we currently need for creating all the MAN pages, User manuals and +reference documents. You may think: "Geeez, that looks so complicated. Why can't they +simply convert XML files to PDF with Docbook, or use reST?" Please be patient, and +continue reading. Things will get a little clearer soon. + +Our toolchain doesn't only produce HTML and PDF files that are nice to look at, it also performs a lot +of processing under the covers. We try to have our documentation as consistent as possible to the +current behaviour of the source code, but this requires some extra steps. + +So let's start right at the top... + +Writer's view +============= + +The toolchain is set up, such that the User has a very restricted view on this whole "document +processing thingy". All he should be concerned about is to edit existing text or write new sections +and paragraphs. +Sometimes even a completely new chapter has to be added, in general he can fire up his XML editor of choice +and type away. + +If he is a really nice user, he cares about validating his XML files against our special +"SCons Docbook DTD/XSD". Either during typing, supported by his XML editor, or by executing a special +script + +:: + + python bin/docs-validate.py + + +from the top source folder afterwards. Preferably both. + +Everything's looking okay, all validation passed? Good, then he simply commits his new work, and +creates a pull request on Bitbucket. That's it! + +Additionally, he can create the single documents on his side if he wants to get a feel for how the +final result looks (and who doesn't?). Each of the document folders (``design``, ``developer``, ``man``, +``python10``, ``reference``, and ``user``) contains an ``SConstruct`` file along with the actual +XML files. You can call + +:: + + python ../../src/script/scons.py + +from within the directory, and have the MAN pages or HTML created...even PDF, if you have a +renderer installed (``fop``, ``xep`` or ``jw``). + +Validation +========== + +Just a few more words about the validation step. +We are using our own DTD/XSD as a kind of hook, which only exists to link our own +SCons documentation tags into the normal Docbook XSD. For the output, we always +have an intermediary step (see diagram above), where we rewrite tags like ``cvar`` +into a block of Docbook formatting elements representing it. + +The toolchain, and all the Python scripts supporting it, are based on the prerequisite that +all documents are valid against the SCons Docbook XSD. This step guarantees that we can +accept the pull request of a user/writer with all his changes, and can create the documentation +for a new release of SCons without any problems at a later time. + + +Entities +======== + +We are using entities for special keywords like ``SCons`` that should appear with the same +formatting throughout the text. These are kept in a single file ``doc/scons.mod`` which gets +included by the documents. + +Additionally, for each Tool, Builder, Cvar and Function, a bunch of linkends in the form of +entities get defined. They can be used in the MAN page and the User manual. + +When you add an XML file in the ``src/engine/Tools`` folder, e.g. for a tool named ``foobar``, +you can use the two entities + +*t-foobar* + which prints the name of the Tool, and + +*t-link-foobar* + which is a link to the description of the Tool in the Appendix + +of the User guide's text. + +By calling the script + +:: + + python bin/docs-update-generated.py + +you can recreate the lists of entities (``*.mod``) in the ``generated`` folder, if required. +At the same time, this will generate the ``*.gen`` files, which list the full +description of all the Builders, Tools, Functions and CVars for the MAN page +and the guide's appendix. + +For more information about how to properly describe these elements, refer to +the start of the Python script ``bin/SConsDoc.py``. It explains the available +tags and the exact syntax in detail. + + +Examples +======== + +In the User Guide, we support automatically created examples. This means that the output of the specified +source files and SConstructs, is generated by running them with the current SCons version. +We do this to ensure that the output displayed in the manual, is identical to what you get when you run +the example on the command-line. + +A short description about how these examples have to be defined, can be found at the start of the file +``bin/SConsExamples.py``. Call + +:: + + python bin/docs-create-example-outputs.py + +from the top level source folder, to run all examples through SCons. + +Before this script starts to generate any output, it checks whether the names of all defined examples are +unique. Another important prerequisite is, that for every example all the single ``scons_output`` blocks need to have +a ``suffix`` attribute defined. These suffixes also have to be unique, within each example. + +All example output files (``*.xml``) get written to the folder ``doc/generated/examples``, together with all files defined +via the ``scons_example_file`` tag. They are put under version control, too. Like this, it is easier to compare +whether the output got broken for a new version of SCons. + +Note, that these output files are not actually needed for editing the documents. When loading the User manual into an XML +editor, you will always see the example's definition. Only when you create some output, the files from +``doc/generated/examples`` get XIncluded and all special ``scons*`` tags are transformed into Docbook elements. + + +Directories +=========== + +Documents are in the folders ``design``, ``developer``, ``man``, +``python10``, ``reference``, and ``user``. + +*editor_configs* + Prepared configuration sets for the validating WYSIWYG XML editors + XmlMind and Serna. You'll probably want to try the latter, because + the XXE config requires you to have a full version (costing a few + hundred bucks) and is therefore untested. For installing the Serna + config, simply copy the ``scons`` folder into the ``plugins`` + directory of your installation. Likewise, the XXE files from the + ``xmlmind`` folder have to be copied into ``~/.xxe4/`` under Linux. + +*generated* + Entity lists and outputs of the UserGuide examples. They get generated + by the update scripts ``bin/docs-update-generated.py`` + and ``bin/docs-create-example-outputs.py``. + +*images* + Images for the ``overview.rst`` document. + +*xsd* + The SCons Docbook schema (XSD), based on the Docbook v4.5 DTD/XSD. + +*xslt* + XSLT transformation scripts for converting the special SCons + tags like ``scons_output`` to valid Docbook during document + processing. + diff --git a/doc/user/pdf.xsl b/doc/user/pdf.xsl index cda0644..652975f 100644 --- a/doc/user/pdf.xsl +++ b/doc/user/pdf.xsl @@ -36,6 +36,8 @@ 0pt + + /appendix toc,title article/appendix nop @@ -54,8 +56,15 @@ reference toc,title set toc,title - - + + bold + + + + + + + -- cgit v0.12