|
Graham Dumpleton
grahamd at dscpl.com.au
Sat Sep 2 02:08:50 EDT 2006
All I can say is that we know the documentation is inadequate. We have been waiting for a long time for the ASF to setup a wiki page for mod_python so that we have a more flexible forum for putting up documentation that can better explain things. Ie., a place where documentation can be quickly added/changed as issues come up. At the moment the documentation is LaTeX based and a part of the source code. This doesn't lend itself to easy or quick updates as the main site is only updated when major releases occur. Anyway, for myself I have given up waiting for the wiki and am turning my existing mod_python articles into my own unofficial wiki so I can at least more quickly add new stuff. I have quite a long list of mini articles I want to write that I have been holding off doing due to the lack of an official wiki. Keep an eye out for more on this in the near future. In respect of mod_python vs mod_python.publisher, they are actually two totally different things. In some respects, mod_python.publisher and mod_python.psp should be released as totally separate products from the mod_python core. That they aren't often causes a lot of confusion as people, like yourself, see mod_python.publisher and mod_python as one in the same, when in fact mod_python.publisher is a higher level interface which is used in a totally different way. In respect of AddHandler, SetHandler, MultiViews etc, you need to realise that mod_python is an extension for Apache. Thus, such things like this aren't actually implemented by mod_python but are implemented by Apache. To use mod_python properly, you also need to understand Apache to some degree and that means also referring to the Apache documentation. Graham On 02/09/2006, at 3:51 PM, Blair P. Houghton wrote: > Graham Dumpleton <grahamd at dscpl.com.au> wrote: >> On 01/09/2006, at 12:01 PM, Blair P. Houghton wrote: >> It does, in as much as the example shows that is the case. It just >> does >> not spell it out in words as a requirement. Ie., it always uses >> "form.py/email". > > Documentation needs to explain what is going on. > >> Referencing just the script and no function name will work >> provided that >> the code file contains a function called index(). >> That you use a name "handler" suggests you are getting a bit muddled >> with the difference between basic mod_python handlers, where response >> handler is always called handler() and name of function doesn't >> need to be >> in the URL and mod_python.publisher where with the exception of >> index(), >> the function does have to be in the URL. > > I think that the fact that in one setup the default is handler() > and in another it is index(), and that this difference is not > made explicit early in the documentation, is the problem. > > Anyone who, like me, tries out the simpler mechanism and learns > that the default is handler(), won't be expecting it to change > when moving to the publisher mechanism. I wanted to use the > script that I had already been running, because changing more > than one thing at a time is a recipe for error. Of > course, what happened is that the documentation just expected > I'd throw away everything I'd done before and blindly type in > the publisher example script. Which is overly complicated for > its purpose, which of course is a recipe for error. So > of course I didn't do it that way. > >>> Note that the >>> '.py' suffix must be included also. >> Not necessarily. Whether this is the case will depend on how >> Apache is >> configured for MultiViews. Try the configuration: >> AddHandler mod_python .py >> PythonHandler mod_python.publisher >> PythonDebug On >> Options +MultiViews >> MultiviewsMatch Handlers >> AddType text/html;qs=1.0 .py >> AddType text/html;qs=0.9 .html >> AddType text/plain;qs=0.8 .txt >> On mod_python web site, do searches for "MultiViews >> MultiviewsMatch" and >> "MultiviewsMatch DirectoryIndex" for other discussions on this >> topic. Ones >> which include most are probably: >> http://www.modpython.org/pipermail/mod_python/2006-June/ >> 021435.html >> http://www.modpython.org/pipermail/mod_python/2006-March/ >> 020501.html > > This is interesting, but highly non-intuitive in the context of > "just trying to get the thing running so I can start to do some > productive work". > >>> I believe that the document from the live/current tree should be >>> moved to the document in the live/mod_python- >>> 3.2.10 tree ASAP so that people won't be caught by this any more. >> Those two trees are the same document, just different parts of >> the same document. > > Interesting. The "quick-start" page is a lot less "quick" than > the "introduction" one. And with that hairy example isn't even > close to quick. I think anything referring to a "quick start" > in the document should point right at the publisher introduction > page. Which should use the default index() function and point > out accessing it both explicitly and as a default in the URI. > Because nobody who's trying to get a "quick start" is going to > read anything called "Traversal" in the manual. > >> Both AddHandler and SetHandler approaches can work, but they are >> used for >> different reasons. > > Hmm. I didn't even notice that one was AddHandler and the other > was SetHandler. > > So here we have the documentation using two different ways to do > the same thing, without, again, pointing out why, in a place where > it would be of the most possible value to be explicit about it. > > --Blair > _______________________________________________ > Mod_python mailing list > Mod_python at modpython.org > http://mailman.modpython.org/mailman/listinfo/mod_python
|