reorg of ALL docs

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

So, what this discussion has pointed out to me is that, as usual, I am
wrong ;-)

I still think that, for the short term, the right thing to do is to commit
the by-type core.html index and remove the alpha one.  However, in the
long term, the modules docs (including core.html) should be a reference
only.  For a reference, an alpha index seems the best way to go.

What gets us from the short term to the long term?  Well, I think that
there needs to a separate doc for each overall topic that provides a
unifying discussion of all the directives of that "type".  For example,
there should be

- Process Creation
- Authentication & Access Restrictions
- Configuration Files
- Environment Variables
- HTTP response headers
- Logging
etc.

Each document provides a discussion of the topic, and provides LINKS
to all the directives (in various modules) that apply to that topic.
The Apache docs already have a little bit of this: The Virtual Hosts docs
and the Content Negotiation docs are examples.  Of course, it is a huge
amount of work to do all this, and it won't get done all at once, but I
think it is the way to go.

All this other work that I have been doing is basically just serving to
cover up for the lack of real task-oriented docs.  It is better than
nothing, but it is really not the correct way to go.  I am grafting a
task-oriented structure onto what should be the reference part of the
docs.

So, two questions:
- Do others agree with my diagnosis?
- Does anyone want to volunteer to take on one or more of these
"unifying" documents?  I don't think they need to be long and complicated.
Rather, they just need to mention all the directives that apply with a
general description of what they do, and provide some examples where
appropriate.

-- 
Joshua Slive
slive@finance.commerce.ubc.ca
http://finance.commerce.ubc.ca/~slive/
Phone: (604) 822-1871