perl-modperl-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stas Bekman <>
Subject Re: mod_perl Documentation..
Date Tue, 02 Feb 1999 08:11:07 GMT
> > Hello, Philippe
> > 
> > Your suggestion would be good for the benefit of the mod_perl community
> > only if I decide to convert the current guide into the one you suggest or
> > the one I wrote (faq_manager). It's absolutely inacceptible if you are
> > going to create another copy of the guide, which will be "a bit" different
> > from the original version. Already today there is a lot of confusion of
> > what documentation should be taken for granted, since there are modules'
> > pods, faqs and the guide (and the book). I have tried to convince the
> > separate faq maintainers to merge into one guide, but they disagreed.
> > 
> > So I would suggest the following: If you have suggestions to make the
> > guide more navigatable, go ahead. But please don't make another copy of
> > it. I don't have a problem with Copyright, but it will create a lot of
> > confusion.
> > 
> > Hope we understand each other.
> > 
> > Have a great day!
> Hi Stas, sorry I took some time to reply, but I am a student and exams are
> keeping me busy :-)
> I understand 100% what you are saying and I that's why I decided to write
> to you in the first place.
> As told me Doug, I know I could provide some form of help regarding the
> mod_perl documentation.  I have the time and the interest.  
> So if there is anything I could help you with, just tell me about.  i.e.
> If you consider moving the guide to the FAQ-O-Matic format, I could do the
> actual conversion then you could deal with the updating of it's actual
> content.
> I just think there isn't enough documentation avaliable.  I thought about
> the FAQ-O-Matic format because I saw one application of it that could be
> great:
> Offering a space on it for each Module Documentation, so that the authors
> of the modules would have a centralized place to put the documentation for
> their modules.  It would them  be a lot easier for users to get answers.
> Making sure those answers are easily avaliable to anyone else.
> Anyway, that's what I thought about.
> Anything else I can help out with is welcome.


As I said I've found having the docs written in pod and then translated to
html as a great convenience. Writing and maintaining the html at first
place, is a hell even with faq-o-matic like tools, since you have to
format the text by yourself, and when you want to update it it's much
harder because of the HTML tags scattered around and distracting from the
real content.

I would prefer to post the pods for the guide for anybody who wants to
add/modify them. (I'll put them into CVS...).

Very soon now I'll release a prototype of the new modperl site, whose main
feature is automatical doc creation and linking from pods and txts, with
easier navigation of automatically extended/expanded menu. Just give me a
few more days (subscribe to modperl-cvs to stay updated, I wouldn't post
to the modperl list before it's finished).

Ofcourse any help and ideas are welcome. Doug what do you think, how do we
solve this "controversy"? I just wanted to avoid having another copy of
docs which is similar but different, so the reader will be not confused. 
I'm not sure what's better many docs scattered around or no docs at all. 

If we are already on this point, my opinion is that we should eliminate
all the separate faqs and integrate them in to one manual, taking into
account that the guide already includes most of the contents from the
faqs. We should make it possible for the original authors to be able to
continue to maintain the parts they have kindly wrote in first place.

Your input is welcome.

Stas Bekman  
Perl,CGI,Apache,Linux,Web,Java,PC at  &  ==  ||
single o-> + single o-+ = singlesheaven

View raw message