httpd-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Alexei Kosut <ako...@nueva.pvt.k12.ca.us>
Subject Re: More docs fun....
Date Mon, 18 Nov 1996 20:47:52 GMT
On 18 Nov 1996, Paul Richards wrote:

> Ok, I've committed my merged docs into the htdocs area. There were
> nominally four votes for this but 2 of them were conditional on us
> agreeing to distribute the docs. The new docs is about 100K so I see
> no reason not to. In any case, I can and will remove all these
> redundant docs when we have a final decision. For now, please take a
> look at the model I've adopted in htdocs. The basic idea is that there
> is a *single* set of docs that covers all the servers. I've added
> compatibility notes to new directives and modules etc that say things
> like "This module is only available in Apache 1.1 and later".

I'm not altogether sure this will always work. And certainly people
picking up a copy of 1.2 don't need the 1.0/1.1 docs. Well, actually,
they might... I suppose as long as it's clear what's going on, and the
docs don't turn into garbage, it's okay.

> The whole issue of tagging/branching etc is now irrelevant, the docs
> evolve as a single entity along with the server source. Putting the
> docs onto the web site is simply a question of 
> 
> cd /docs
> cvs export docs
> 
> which we can do periodically when we feel there's been some changes
> made that should "go live".

Can we make a script somewhere that takes care of updating the docs
automatically, so people don't screw this up? Also, mighn't it me a
better idea to simply check out the docs module (is that still right?)
into the DocumentRoot of the server, so we can just run cvs update on
it? (we'd probably want to tell the HTTP and FTP servers to ignore
directories named CVS - that should make it completely safe, as far as
I know).

One problem I do see with this, though: if the same set of docs always
applies, this means that we need to manually fix changes in old
versions for non-released versions. That sentance didn't make any
sense, so I'll use an example: 1.2b1 is not yet released, so we can't
update the actual web pages with 1.2 docs until it is. So if we, for
example, want to change the 1.1 docs, we can't do it straight from the
CVS tree. We'd have to do it manually. This will be a big problem
especially after the 1.2 release, as people give us bug reports about
the docs, but if we already start working on the 2.0 docs (although we
probably won't immediately *grin*), we can't simply use CVS to update
the docs. At least, I think that's the case. It'd be nice if I were
wrong.

> I have some notes from my merging activities:
> 
> 1) AuthDB directives are listed but they don't actually point anywhere
>    other than to the AuthDBM file. I haven't fixed this yet.

I seem to recall making a mod_auth_db.html file for the 1.1 docs. Did
it disappear somehow?

> 2) IdentityCheck was in the 1.0 docs, it's still in the current docs
>    but has gone missing from the directive listing.

Hmm. Wasn't that one of those things that was added into 1.1? Or maybe
not.

> 3) The old 1.0 FAQ wasn't merged since the current FAW is an updated
>    document although some of the old entries might still be of
>    interest.

Yeah. Someone needs to work on that. Rob, you're probably in the best
position to know what the FAQs are, from the bug reports.

> 4) The 1.0 and current mod_userdir docs have a subtle difference that
>    I haven't fixed because I don't have time at the moment to go look
>    at the source and see if the difference is significant or whether it's
>    just a documentation improvement.

The 1.1 UserDir directive supports a number of additional
syntaxes. We can use the 1.1 docs, and say that everything except the

UserDir public_html

form is only available in 1.1 or later.

> 5) I haven't updated the mod_mime documentation, there are major
>    changes between 1.0 and 1.1 in that area and I haven't got time
>    right now to document this area properly.

If I get a chance, I'll look into this.

Okay, so is this actually what's going on? If it is, and we can agree
on this, I'll work on the docs and try to make them correct and
reflecting 1.2. If not, can we please figure something out, and soon?

There's still a docs directory in the apache module. Shouldn't it be
removed, if we're using htdocs/manual now? Shouldn't the apache-docs
module be removed too? I don't like having too many copies of the same
things lying around, because (as Brian points out), it gets
confusing. I want one set of docs in the CVS tree, not three.

Otherwise, it looks good.

P.S. some of the docs are wrong - Alias and ScriptAlias have always
been there, for example, not just "Apache 1.1 and later".

-- 
________________________________________________________________________
Alexei Kosut <akosut@nueva.pvt.k12.ca.us>      The Apache HTTP Server
URL: http://www.nueva.pvt.k12.ca.us/~akosut/   http://www.apache.org/


Mime
View raw message