[Scons-users] Feedback request: an AsciiDoc tool

[Dirk Bächle]

Hi Marc,

I had a quick look at your asciidoc Tool/Builder, following a few comments:



1.) Emitters vs. Clean

It's true that I use Clean() in the Docbook Builder, but only where I 
have to. Whenever the list of targets can be constructed from the 
sources and their dependencies, an Emitter should be used...and that's 
what I do.
This isn't possible for things like chunked HTML output, because the 
names of the output HTML files depend on the actual contents of the 
input files...so scanning this all would be too much.
Your Builder is working fine like it is now, so there is no real need to 
change it in this regard. But this is where I personally draw the line, 
and try to stick to the intended ways of dealing with dependencies in SCons.



2.) Scanners

If you define a scanner as "recursive", all dependencies that your 
scanner finds get re-evaluated in the next step. This means that for all 
nodes, SCons checks whether the file suffix is registered in the global 
scanner map, and then this scanner gets called recursively.
So if you return *.txt and *.img nodes from your scanner, and there is a 
'.img' scanner available in the Environment, it gets called on a '.img' 
dependency, even if you have only specified "skeys = ['.txt']" for your 
Scanner.
You can prevent this by defining the "recursive" parameter as function:

def _asciidoc_recursive_nodes(nodes):
   return [x for x in nodes if str(x).endswith('.txt')]
s = Scanner(..., recursive=_asciidoc_recursive_nodes)

Regard, that you always have to return actual node objects (File or Dir) 
from your scanner. You don't do this at the moment! Also check the MAN 
page at "Defining Your Own Scanner Object" for a working example.



3.) env.Clone

I noticed that you do a

   env = env.Clone(**kwargs)

at the start of your pseudo-Builders. This may be a convenient way to 
have additional vars at your fingertips, but don't forget that you are 
actually replacing the specified Environment with your own version.
The user might not expect this because that's not how other Builders work.
By passing the **kwargs through to your helper functions, you could 
easily get rid of this construct, in my opinion.



Finally, if you are still looking for documentation about the SConst 
testing framework, I'd like to recommend "QMTest/test-framework.rst" (in 
the repository) as a first read. Then, you might want to have a look at 
the Qt4 tests, for some real-life examples.

Best regards,

Dirk