[zc.buildout] "Adding and removing options" section unclear
Hi All, This section of the docs at http://pypi.python.org/pypi/zc.buildout/1.0.6 doesn't seem to make much sense. extension1.cfg and extension2.cfg are set up but no examples use them as far as I can see. The demo also uses extending of configurations as well as buildout extensions before these have been introduced as concepts. I'm *guessing* that:
write(sample_buildout, 'base.cfg', ... """ ... [buildout] ... parts = part2 ... ... [part2] ... recipe = ... option = b1 b2 b3 b4 ... """)
write(sample_buildout, 'extension1.cfg', ... """ ... [buildout] ... extends = base.cfg ... ... [part2] ... option -= b1 b2 ... """)
..will result in 'option' being 'b3 b4' when extension1.cfg is used, but there's no explanation of how this works. Are option values always split on spaces or is there another set of rules for this? Where is this documented? cheers, Chris -- Simplistix - Content Management, Zope & Python Consulting - http://www.simplistix.co.uk
On Jul 15, 2008, at 3:09 PM, Chris Withers wrote:
Hi All,
This section of the docs at http://pypi.python.org/pypi/zc.buildout/1.0.6 doesn't seem to make much sense.
extension1.cfg and extension2.cfg are set up but no examples use them as far as I can see.
The demo also uses extending of configurations as well as buildout extensions before these have been introduced as concepts.
Could you be more specific? What section of the documentation are you in? Jim -- Jim Fulton Zope Corporation
Jim Fulton wrote:
Could you be more specific? What section of the documentation are you in?
I can try, but I was about as specific as I could be first time round... http://pypi.python.org/pypi/zc.buildout/1.0.6 The sections titled "adding and removing options". cheers, Chris -- Simplistix - Content Management, Zope & Python Consulting - http://www.simplistix.co.uk
On Tue, Jul 15, 2008 at 08:28:35PM +0100, Chris Withers wrote:
Jim Fulton wrote:
Could you be more specific? What section of the documentation are you in?
I can try, but I was about as specific as I could be first time round...
Never assume people read the Subject line. Marius Gedminas -- The memory management on the PowerPC can be used to frighten small children. -- Linus Torvalds
On Jul 15, 2008, at 3:09 PM, Chris Withers wrote:
Hi All,
This section of the docs at http://pypi.python.org/pypi/zc.buildout/1.0.6 doesn't seem to make much sense.
You are referring to: http://pypi.python.org/pypi/zc.buildout/1.0.6#adding-and-removing-options
extension1.cfg and extension2.cfg are set up but no examples use them as far as I can see.
The last example extends extensions2.cfg, which extends extensions1.cfg.
The demo also uses extending of configurations as well as buildout extensions before these have been introduced as concepts.
Yup. That's annoying. This section should be moved until after extending has been described and should use an extension. Probably just invoking the buildout with -vv should be enough. I'm hoping the person who wrote this section is paying attention so I don't have to fix this myself. :)
I'm *guessing* that:
write(sample_buildout, 'base.cfg', ... """ ... [buildout] ... parts = part2 ... ... [part2] ... recipe = ... option = b1 b2 b3 b4 ... """)
write(sample_buildout, 'extension1.cfg', ... """ ... [buildout] ... extends = base.cfg ... ... [part2] ... option -= b1 b2 ... """)
..will result in 'option' being 'b3 b4'
Right.
when extension1.cfg is used, but there's no explanation of how this works. Are option values always split on spaces
Yes
or is there another set of rules for this?
No.
Where is this documented?
That section tries to explain it. The parsing rule should have been stated. The example should be made simpler. The extension business complicates it excessively. Jim -- Jim Fulton Zope Corporation
Jim Fulton wrote:
You are referring to: http://pypi.python.org/pypi/zc.buildout/1.0.6#adding-and-removing-options
Yup.
extension1.cfg and extension2.cfg are set up but no examples use them as far as I can see.
The last example extends extensions2.cfg, which extends extensions1.cfg.
Oh, right, 4th time of reading I see that... :-S
The demo also uses extending of configurations as well as buildout extensions before these have been introduced as concepts.
Yup. That's annoying. This section should be moved until after extending has been described and should use an extension.
I'm guessing you mean "shouldn't use an extension"? Extensions look like something I don't ever want to have to use ;-)
when extension1.cfg is used, but there's no explanation of how this works. Are option values always split on spaces
Yes
Okay, I don't know if there's a "this is how sections, names and values" work section but if there isn't, there should be, and if there is, I missed it and I don't remember reading anything about how and where values are split ;-) (ie: does a recipe get the values pre-split or does it need to split itself and therefore is it just convention that prevents a recipe from splitting on other characters too?)
Where is this documented?
That section tries to explain it. The parsing rule should have been stated. The example should be made simpler. The extension business complicates it excessively.
Yup. Maybe just a simple bit on "this is how sections, names and values work" would do it? cheers, Chris -- Simplistix - Content Management, Zope & Python Consulting - http://www.simplistix.co.uk
On Jul 15, 2008, at 3:47 PM, Chris Withers wrote: ...
The demo also uses extending of configurations as well as buildout extensions before these have been introduced as concepts. Yup. That's annoying. This section should be moved until after extending has been described and should use an extension.
I'm guessing you mean "shouldn't use an extension"? Extensions look like something I don't ever want to have to use ;-)
Right. They are a rather advanced feature. We use them to support sftp urls.
when extension1.cfg is used, but there's no explanation of how this works. Are option values always split on spaces Yes
Okay, I don't know if there's a "this is how sections, names and values" work section but if there isn't, there should be, and if there is, I missed it
http://pypi.python.org/pypi/zc.buildout/1.0.6#configuration-file-syntax
and I don't remember reading anything about how and where values are split ;-)
Parsing of option values is specific to individual recipes, so it isn't part of the general syntax. Having said that, many many options are treated as white-space delimited sequences of values. The += and - = syntax is only useful for options that have this form. The documentation should have said more about this.
(ie: does a recipe get the values pre-split
no
or does it need to split itself
yes
and therefore is it just convention that prevents a recipe from splitting on other characters too?)
Yes. In fact, if values can have spaces in them, then a option may be split on new lines. For example the eggs option in many recipes, which should really be named "requirements", is split on new lines because the individual values can have spaces in them. Jim -- Jim Fulton Zope Corporation
Jim Fulton wrote:
Okay, I don't know if there's a "this is how sections, names and values" work section but if there isn't, there should be, and if there is, I missed it
http://pypi.python.org/pypi/zc.buildout/1.0.6#configuration-file-syntax
Okay, but that doesn't mention splitting on spaces ;-) It's also below stuff dealing with writing recipe clases, etc, which seems weird as understanding the format of the .cfg file seems pretty integral to using buildout from the get-go :-S
and I don't remember reading anything about how and where values are split ;-)
Parsing of option values is specific to individual recipes, so it isn't part of the general syntax. Having said that, many many options are treated as white-space delimited sequences of values. The += and -= syntax is only useful for options that have this form. The documentation should have said more about this.
...and I'm still left baffled. so: - the parsing of the value is soley up to the recipe - but += -= are "buildout" things that can be applied to all values, no matter their recipe - and many many options, but not all, are treated as whitespace delimited sequences of values um... :'( (I don't know the emoticon for an exploding head)
and therefore is it just convention that prevents a recipe from splitting on other characters too?)
Yes. In fact, if values can have spaces in them, then a option may be split on new lines. For example the eggs option in many recipes, which should really be named "requirements", is split on new lines because the individual values can have spaces in them.
So what happens if I use += or -= with the eggs option? (and I've wanted to do just this in the past, but didn't even know I could...) cheers, Chris -- Simplistix - Content Management, Zope & Python Consulting - http://www.simplistix.co.uk
On Jul 15, 2008, at 4:03 PM, Chris Withers wrote: ...
and therefore is it just convention that prevents a recipe from splitting on other characters too?) Yes. In fact, if values can have spaces in them, then a option may be split on new lines. For example the eggs option in many recipes, which should really be named "requirements", is split on new lines because the individual values can have spaces in them.
So what happens if I use += or -= with the eggs option? (and I've wanted to do just this in the past, but didn't even know I could...)
You'll get garbage. Jim -- Jim Fulton Zope Corporation
Jim Fulton wrote:
So what happens if I use += or -= with the eggs option? (and I've wanted to do just this in the past, but didn't even know I could...)
You'll get garbage.
Always nice knowing a tool is point the gun firmly at your feet for you ;-) Shame, being able ot do += -= and have the recipe interpret what that meant would be cool... Chris -- Simplistix - Content Management, Zope & Python Consulting - http://www.simplistix.co.uk
participants (3)
-
Chris Withers -
Jim Fulton -
Marius Gedminas