CGI tutorial

[Rich Bowen <rb...@rcbowen.com>]

Just what we need. Yet another CGI tutorial. But I thought it might be
useful to have an introductory CGI tutorial in the Apache docs, and,
hey, I've already written it.

For your rewiew and comments, here 'tis. Please be ruthless, as before,
and we'll try to get it into the docs in the next week or so.

Rich
-- 
Author: Apache Server Unleashed - www.apacheunleashed.com
Director of Web Application Development - http://www.cre8tivegroup.com/

Re: CGI tutorial

[Rich Bowen <rb...@rcbowen.com>]

Joshua Slive wrote:
<Some great comments ...>

Thanks for your useful input. I've implemented it all except #5 and #7:

> 5. A mention of suexec, perhaps under the "File permissions" section would
> be appropriate.  This is especially important because Redhat ships with
> suexec enabled, but with permissions that cause scripts to fail in user
> directories.  They need to look in the suexec log file for more details.
> 
> 7. It might be good to divide the "It still doesn't work" section into
> three sub-sections based on what they will see in the browser:
> "Forbidden", the source code of the cgi script, and "Internal Server
> Error".  The first two can be very short ("Your permissions are wrong,
> check the error log for more details", and "You have not properly
> configured for cgi execution, see the above section".)  The third one
> is almost always "Premature end of script headers", which you
> discuss further.

5 because, frankly, I've never used suexec, and although I suppose I
could read the docs and figure out the right thing to say to a beginner,
I thought that someone else might be more up to the job.

7 because I'm not sure I'm following what you think needs to be done.

I'll go ahead and commit it as I have it here, and folks can hack on it
as needed.

Rich
-- 
Author: Apache Server Unleashed - www.apacheunleashed.com
Director of Web Application Development - http://www.cre8tivegroup.com/

Re: CGI tutorial

[Joshua Slive <sl...@finance.commerce.ubc.ca>]

On Sat, 11 Nov 2000, Rich Bowen wrote:

> Just what we need. Yet another CGI tutorial. But I thought it might be
> useful to have an introductory CGI tutorial in the Apache docs, and,
> hey, I've already written it.
> 
> For your rewiew and comments, here 'tis. Please be ruthless, as before,
> and we'll try to get it into the docs in the next week or so.
> 

Very nice!

Here's some suggestions:

(As always, I am perfectly willing to make these changes myself after
you commit if you approve of them but don't want to make them yourself.)

1. It would be very good to reference the CGI specification (or simply
reference the FAQ that references it).

2. I think that you should really say a few words about how the server
communicates with CGI scripts: ie environment variables, and (for POST
requests) standard input.  A link to the env.html doc might be good.

3. In your "outside scriptalias" section, you are missing the AddHandler
cgi-script stuff.

4. I would probably reverse the order of "explictly using Options..." and
".htaccess files".

5. A mention of suexec, perhaps under the "File permissions" section would
be appropriate.  This is especially important because Redhat ships with
suexec enabled, but with permissions that cause scripts to fail in user
directories.  They need to look in the suexec log file for more details.

6. You probably want to change "This week's column" to "This document"
or something similar.

7. It might be good to divide the "It still doesn't work" section into
three sub-sections based on what they will see in the browser:
"Forbidden", the source code of the cgi script, and "Internal Server
Error".  The first two can be very short ("Your permissions are wrong,
check the error log for more details", and "You have not properly
configured for cgi execution, see the above section".)  The third one
is almost always "Premature end of script headers", which you 
discuss further.

8. Under "Syntax errors", you probably want to mention something about the
most common problem: Wrong path to the interpreter (perl) specified 
on the first line of the script.

9. You probably should be encouraging people to check the error log rather
than discouraging them ("cryptic error logs" ;-).

Great work!

Joshua.