list at joreybump.com
Sun Mar 26 13:45:18 EST 2006
Jim Gallacher wrote: > Jorey Bump wrote: > >> My recommendation to Publisher beginners is to avoid using modules >> named index.py and index() functions until they thoroughly understand >> how mod_python works. Index traversal is a special case in 3.x, and >> it's nearly impossible to understand coming from a different >> background. The documentation can also be misleading (note that this >> is for mod_python 3.x, not 2.x!): >> >> http://www.modpython.org/live/current/doc-html/hand-pub-alg-trav.html > > In what way is it misleading? Suggestions to make it clearer are welcome. The examples are correct, but I think they'd be easier for newbies to understand if they were presented using the module extension to better distinguish index.py from index(): http://www.somehost/index.py/index will return "We are in index()" http://www.somehost/index.py/ will return "We are in index()" http://www.somehost/index will return "We are in index()" http://www.somehost/index.py/hello will return "We are in hello()" http://www.somehost/hello will return "We are in hello()" http://www.somehost/spam will return "404 Not Found" Also, since index traversal is a special case, there should be an example demonstrating the behaviour of calling a module that contains no index(): http://host/eggs.py will return "404 Not Found" if it has no index() Furthermore, index traversal is only partially available when using AddHandler, and this should be noted: http://www.somehost/index.py/ will return "We are in index()" http://www.somehost/index will return "404 Not Found" This should be good enough. It doesn't address using index.py in DirectoryIndex, the implications of Multiviews, or the additional permutations possible when adding trailing slashes, but the first two are external issues and last one might be too much information. I think this is very important because the user's first encounter with Publisher might occur here, where AddHandler is used: http://www.modpython.org/live/current/doc-html/tut-pub.html On that page, the user is offered a link to the Publisher section, where SetHandler is used. I think you'll agree that at this point a new user will have no idea of the differences between AddHandler and SetHandler, and will be frustrated trying to implement the examples under AddHandler, since *none* of them will work. In fact, this is such an important topic, AddHandler vs. SetHandler should have a dedicated chapter very early in the manual, and it should be mentioned again in the Publisher traversal section, with a link. Both have their advantages, so a preference for neither should be assumed.