[Scons-users] Feedback request: an AsciiDoc tool

[Marc Joliet]

Am Wed, 28 Nov 2012 14:44:24 +0100
schrieb Dirk Bächle <tshortik at gmx.de>:


> Hi Marc,


Hi Dirk,


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


Thanks a lot for looking at this! I pushed the changes just now, if you want to
look at them.


> 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.


I must be confused then, because "grep -i emitter __init__.py" doesn't return
anything. Or do you mean in general?


> 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.


Exactly. Or the *.epub.d directory, for that matter.


> 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.


I agree, and I wanted to do it like that, too, but:
a) I could not for the life of me figure out what I was doing wrong. I hope you
   or somebody else with the expertise will be able to look into this.
b) Having all of that handled in one place in the pseudo-builder instead of
   having part of it in an emitter looks cleaner, IMHO.


> 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.


OK, so skeys is only evaluated once for each source node, and not for every
additional node returned by the 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)


Like I said, I handled this with a scan_check function, I was just wondering
why skeys didn't work as I had expected (or hoped). Although I see that your
suggestion is more "correct", so I'll switch using to that :) .


> 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.


This is one of those things that confuses me. You say I need to (and the man
page does, too), but SCons seems to do the right thing ("scons --tree=prune" is
correct). In fact, using File() forces me to prepend the path of the node
manually. Does it just accidentally work?

I made the change, it's just confusing when something is not supposed to work
and then in spite of that it seems to work, after all.


> 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.


Yes, good point. I ended up getting the variables from kwargs and passing them
to the helper functions manually.


> 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.


Thanks, I'll definitely look into that.


> Best regards,

> 

> Dirk


Best regards,
-- 
Marc Joliet
--
"People who think they know everything really annoy those of us who know we
don't" - Bjarne Stroustrup
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 198 bytes
Desc: not available
Url : <http://four.pairlist.net/pipermail/scons-users/attachments/20121129/b901922b/attachment-0001.pgp>