[mod_python] Re: Mod_python Digest, Vol 42, Issue 4

Steve Holden wrote:
> Graham Dumpleton wrote:
>> 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.
>>
> Why not just start using an exisitng Wiki like the one at python.org, 
> then migrate when the ASF wiki is ready?

Because we now have our own, as of Sept 12! We've not made an official 
announcement on this list yet, as I wanted to have a discussion on what 
should go in the wiki vs. the official documentation vs. the website 
before we starting piling in. There is a problem potential licensing 
problem if we use the wiki for the official documentation and then in 
turn want to distribute those docs with the mod_python source.

>> 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.
>>
> Yup. It might make more sense to distinguish it as an add-on (or at 
> least flag the differences clearly for novices).
> 
>> 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.
>>
> Which, IMHO, is even more obscurantist than the mod_python 
> documentation. It seems to assume you've already read much of the source 
> code and are familiar with C ... in which case why would you be using 
> mod_python in the first place :-) ?

Graham can speak for himself of course, but I don't think he meant the C 
API. You need to understand the various phases of Apache request 
processing to really use the full potential of mod_python. This 
understanding is independent of the Apache C API, but will be new 
territory for someone coming from something like of php (as an example). 
In this respect our documentation could be *much* better. I think people 
can get really excited about the possibilities once they realize the 
power that mod_python offers. It's more than just a nice way to run some 
python scripts.

Jim