On Tue, Nov 23, 2010 at 8:00 PM, Chris McDonough <chr...@plope.com> wrote: > On Tue, 2010-11-23 at 19:35 -0800, Mike Orr wrote: >> I wonder if it would be clearer to to put the URL Dispatch chapter >> before Context Finding and Traversal in the manual. URL Dispatch seems >> to be simpler, and it doesn't require learning about the root object, >> context object, and context finding only to learn you won't be using >> them. It seems like URL Dispatch can be presented in a way that people >> will see immediately if they're not using it, without having to pore >> through the abstract concepts of "context finding" and "view lookup". >> Then if they want to use traversal or learn about these objects, they >> can learn about them afterward, otherwise they can skip those two >> chapters. > > I sympathize with this, and I think we can probably organize it better. > Casey Duncan is currently working on editing the book as a for-pay sort > of thing. I'm hoping he'll come up with some concrete suggestions as to > how to reorganize things, but maybe I can put a bug in his ear along the > lines of your suggestion. > > FTR, it would be more technically accurate to say that users *will* be > using a root object, a context object, and context finding when he uses > URL dispatch, but he can mostly ignore their existence. URL dispatch > literally is a context finding mechanism. This is why the docs are > organized as they are now. > > OTOH, users do indeed need to know about view lookup even if they only > use URL dispatch. A matched route doesn't always imply the lookup of > one single canonical view. For example, if a route matches, it might go > to one view if the request method is POST, another if the request method > is GET.
OK, I think we can handle this in a short paragraph at the beginning of the URL Dispatch chapter. Just quickly explain in passing what these are and that the'll be covered more in depth in the following chapters. Currently the "Context Finding and View Lookup" chapter and the "Traversal" chapter are the most confusing parts of the manual to Pylons users; they make the framework seem foreign and hard to grasp. You have to make your way through nine dense paragraphs and a section on which mechanism to use, and then if you start reading the traversal chapter anyway it gets hard to follow with all these new concepts. I think traversal fans can skim over the URL dispatch chapter easier than people coming from a Routes background can skim over the two other chapters. -- Mike Orr <sluggos...@gmail.com> -- You received this message because you are subscribed to the Google Groups "pylons-devel" group. To post to this group, send email to pylons-de...@googlegroups.com. To unsubscribe from this group, send email to pylons-devel+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/pylons-devel?hl=en.
