> I arrived to the cache key documentation from the Google-found > "Generator Configuration Articles" [1], particularly its cache key > section, and a few pages lower, the section about the library key. > > It says the following: > > "The contribution source tree will then be downloaded from the > repository, the generator will adjust to the local path, and the > contribution is then used just like a local library. A consideration > that comes into play here is where the files are placed locally. The > default location is a subdirectory from your cache path named downloads. > You can modify this through the downloads attribute of the cache key in > your config." > > Then I clicked over to the reference and read the cache key's > description (with its three supported subkeys). > > So I guess it might be useful to somehow hint in the documentation about > how "cache" is not a root key.
This is exactly in the document that I linked (generator_config.html). What comes into play is that the information is *organized*, in an introductory overview, a reference part, and an "assorted bits and pieces" part, and the systematical way to consume this information would be to consult the parts in that order. The problem is that when Google throws you straight into the last part, things are of course confusing, as they somewhat assume (and build upon) the knowledge obtained in the earlier parts. And I honestly don't know how to amend this. It's certainly no help to repeat every piece of information everywhere where it might matter (and would be a maintenance nightmare), or link everything from everywhere (to produce a net of "spaghetti links"), or throwing gratuitous warnings at the reader saying "make sure you have read and understood [blah]". The only thing that would help in my view would be conveying the systematic of things. > Which is I think the reverse of what > "peer keys" currently define. That expression wasn't exactly clear > until Tristan told me how to use the cache key. The term "peer key" is explained at the top of the reference page, saying "Special note boxes starting with 'peer-keys' indicate interactions of the current key with other configuration keys that should be present in the job for the current key to function properly". What is *not* apparent on this level of information (raw config keys and their interactions) is that peer keys are already provided by the built-in jobs if you chose to tweak one of those (like "source"), in contrast to building up an entire job from scratch. > Yep, this part was clear from the first time I read "cache"'s reference. > I think altering $CACHE and cache/downloads is enough. This makes sure > anything depending on $CACHE will be affected consistently (particularly > cache/compile itself), and will move downloads out from there as a > special case, 1) to be web-accessible (this was one of my issues, can't > reach stuff outside the document root with a web browser), and 2) so I > have it nearby and don't have to travel across my file system to fetch > the files (and have the option to version control them together with my > own code). So that means it is working now for you? T. ------------------------------------------------------------------------------ RSA(R) Conference 2012 Save $700 by Nov 18 Register now http://p.sf.net/sfu/rsa-sfdev2dev1 _______________________________________________ qooxdoo-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/qooxdoo-devel
