apache1.1b1 documentation bug fix and suggestion

[John Heidemann <jo...@ISI.EDU>]

I have two comments about apache documentation.

First, the Configuration.tmpl says:
	# Optional modules for *full* NCSA compatibility --- we think these log
	# files are a bad idea, but reasonable people seem to disagree:
	
	# Module agent_log_module    mod_log_agent.o
	# Module referer_log_module  mod_log_referer.o

It's very confusing for a user to be told that something is bad
without being given an alternative.

My guess is that in Apache it's better to this information with
mod_log_config.  The attached patch (against apache1.1b1) makes this
suggestion:

--- Configuration.tmpl- Mon Apr 29 18:11:35 1996
+++ Configuration.tmpl  Mon Apr 29 18:12:54 1996
@@ -190,6 +190,11 @@
 # Module agent_log_module    mod_log_agent.o
 # Module referer_log_module  mod_log_referer.o
 
+# (A better approach in apache is to enable mod_log_config
+# and add a directive like
+#      LogFormat "%h %l %u %t \"%r\" %s %b (%{Referer}i)"
+# to your httpd.conf.)
+
 # Finally, outright experiments --- mod_dld defines commands which
 # allows other modules to be loaded in at runtime, and mod_cookies
 # uses Netscape cookies to automatically construct and log accurate

If my guess about the better approach was wrong, please enlighten
me... and update the Configuration.tmpl.  If there's no consensus
about the one better approach, you can change "A better" to "Another"
in the above patch.


Second, Apache's got good documentation.  It's too bad it's not kept
with the source code.  A "doc" subdirectory would make the
documentation easier and faster to get at, available when off-line,
and available for editing (I considered patching
<http://www.apache.org/docs/mod_log_referer.html> wrt my first
comment, but I don't have source :-( ).

Has anyone considered distributing the documentation HTML, Postscript,
and source with the Apache source code distribution?


   -John Heidemann
    ISI

Re: apache1.1b1 documentation bug fix and suggestion

[ra...@madhaus.utcs.utoronto.ca]

> John> Has anyone considered distributing the documentation HTML,
> John> Postscript, and source with the Apache source code distribution?
> 
> I think this is a good idea.  We are planning to include the docs in
> our distribution.

On that note, a local luser here bugged me about the format of the .htaccess
files for Apache.  Inherently obvious I would think, but I gave him the
RTFM treatment and pointed him at the www.apache.org documentation.  He came
back complaining that all he could find was a long list of configuration
directives without any examples of where or how they should be used.  I
checked and had to agree and ended up pointing him at the NCSA docs at hoohoo
where they do have some idiot-level stuff.

Hopefully this is the kind of thing Laura is going to catch?

-Rasmus

Re: apache1.1b1 documentation bug fix and suggestion

[Tom Tromey <tr...@cygnus.com>]

John> Has anyone considered distributing the documentation HTML,
John> Postscript, and source with the Apache source code distribution?

I think this is a good idea.  We are planning to include the docs in
our distribution.

Tom

Re: apache1.1b1 documentation bug fix and suggestion

[Brian Behlendorf <br...@organic.com>]

On Mon, 29 Apr 1996, John Heidemann wrote:
> Second, Apache's got good documentation.  It's too bad it's not kept
> with the source code.  A "doc" subdirectory would make the
> documentation easier and faster to get at, available when off-line,
> and available for editing (I considered patching
> <http://www.apache.org/docs/mod_log_referer.html> wrt my first
> comment, but I don't have source :-( ).
> 
> Has anyone considered distributing the documentation HTML, Postscript,
> and source with the Apache source code distribution?

The postscript docs are available as a tar file - the HTML docs probably 
could be as well, in fact they are, as 
ftp://ftp.apache.org/apache/docs.tar, but that's undocumented. :)  
We discussed this a while back and I believe the conclusion we came to 
was that it would just make the distribution a whole lot larger....

	Brian

--=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=--
brian@organic.com  |  We're hiring!  http://www.organic.com/Home/Info/Jobs/