"bugs" in documentation (mostly 1.1) (fwd)

[Rob Hartill <ro...@imdb.com>]

acked.


Message-Id: <UA...@garotte.va.pubnix.com>
To: apache-bugs@apache.org
Subject: "bugs" in documentation (mostly 1.1)
Date: Mon, 22 Apr 1996 20:18:30 -0400
From: "Josh M. Osborne" <st...@va.pubnix.com>

Whenever I release anything I bother to write documentation for I
sometimes get reports that "the documetation is bad/out of date",
but I seldom get anything as specific as the bug reports.  Here is
my attempt to give specific reports for your documentation "bugs".
(P.S. this is not ment to imply that your documentation is poor,
it is far better then I would expect for the $0 I pay for it, and
in fact, is better then some comercial programs come with...)

In http://www.apache.org/docs/1.1/mod_actions.html, the first
paragraph under the "Script" directave ends in "Method can be".
It looks like someone accientally managed to get that in there
while editing.

In http://www.apache.org/docs/1.1/keepalive.html the wording for
"KeepAliveTimeout" is a little unclear.  I susspect that it means
that the KeepAliveTimeout is used while waiting for requests, and
the normal Timeout is used while processing a request/sending a
reply.  The lanuage used is very clear about when the switch from
KeepAliveTimeout to Timeout is done.

I would suggest replacing the last sentence with something along
the lines of:

>From the time a request has been recieved until the reply has been
sent the regular  Timeout directive's value applies.  After a reply
has been sent and before recieveing a new request KeepAliveTimeout's
value is used.

The http://www.apache.org/docs/1.1/virtualhost.html URL doesn't
exist (http://www.apache.org/docs/1.1/ claims that's where the "New
non-IP Intensive VirtualHost Support" is documented).

In http://www.apache.org/docs/1.1/mod_auth_db.html mod_auth_db is
documented as "an alternative to DBM files for those systems which
support DB and not DBM", however the DB package ships with a DBM
emulation that seems to work just fine for most all programs (as
far as I know *all* programs that don't assume creating a DBM file
named foo will reall create a foo.dir and foo.pag, since DB will
create just one file (foo.db)).  "Most programs" definitly includes
Apache (at least your last release!).   Granted the DB interface
is cleaner, and can do more things, but the mod_auth_db module
doesn't seem to provide any extra features over the DBM auth.


The 1.0ish docs for the module API seemed a little vague on some
points, and didn't document things that look like they should have
been (the array stuff, the pool destruction stuff).  Unfortunitly
I was in too much of a hurry when I was writing my module (mod_semaphore
-- my employer has agreed to let me release it, but I havn't gotten
time to get a signature on paper) to write any extra docs, or even
remember exactly what needed help.  If someone is willing to correct
my spelling (I'm dislexic & spelling is very hard for me) I'll be
willing to write some of the missing stuff.  Not only will it make
Apache better, but if I misunderstood something it'll give me a
chance to fix a bug before it bites me...

----- End of forwarded message from Josh M. Osborne -----