add more layout packager details

[solvingj]

I was reading the documentation and trying to understand the layouts() feature in order to write the blog post. One thing I noticed is that it feels difficult to comprehend all the implications of all the values one can set in layouts (at least for me).

I think this makes sense and is a natural consequence of the tradeoffs we're chosing to make. Previously, self.copy() had the nice property that the src= and dest= and pattern= were all basically declared exactly where they were used. However, now that we've realized we need to use that information in other places, and compose that information in different ways, we needed to raise the level of abstraction. The unfortunate loss is that it will now be difficult to look at a recipe and determine what patterns will be copied from what directories. You have to do the composition in your head, which looks like it's going to be exceptionally difficult because it's a matrix of root paths, sub-paths and patterns, and then doubled due to cpp.source and cpp.build.

This PR is actually just an initial pass at helping people connect the dots. I think we need to spend quite a bit more effort making it "make sense".

[solvingj]

For those reviewing this PR, I want to re-iterate that you consider the following:

I think one of the goals of the layout() method is to unify/simplify the relationship between a new "local flow", and the source()/build()/package() methods. However, with this first release, we've focused on adding the necessary power and flexibility which makes it more complex to understand and use. I think that's a totally reasonable challenge to have in a first release of an ambitious and powerful feature.

The suggestion here is simply to look for simple/creative ways to reduce that complexity for the next release if possible.

I think the first and most obvious thing people are likely to do with layouts() is try to replace an existing package() method with layout() + package() + LayoutPackager(), and THEN try the local flow with the new recipe. So, perhaps think about users who are trying to achieve "functional equivalence" between self.copy and LayoutPackager.

Also, think about what to do for ultra-common case of package methods which just call cmake.install(). To be honest, unfortunately, these recipes seem like a challenge to the new feature.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}