httpd-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Paul Richards <p.richa...@elsevier.co.uk>
Subject Re: More docs fun....
Date Tue, 19 Nov 1996 09:55:41 GMT
Alexei Kosut <akosut@nueva.pvt.k12.ca.us> writes:

> 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.

Well, after my first attempt at using branches I realised that the
differences between the 1.0 docs and the current docs were minimal, a
handful of new directives and modules and that the vast majority of
changes were actually fixes and enhancements to docs that applied to
all versions. We just had lots of copies of the same files lying
around, the only differences being in URL paths and minor changes.

In any case, we run lots of different versions of the server here
(don't fix what ain't broken principle applies) so having a reference
manual that explains what changed at what version level is useful. I
also think it reflects what people expect from software documentation,
if you pick up an OS manual then this is generally how it deals with
version differences. It makes it easy to find out things like, the
context of Redirect was enhanced in 1.1 without having to search
through several almost identical copies of the documentation.
Maintenance becomes much simpler since you just change the
documentation once and not for every version. It's very handy to see
the history of a particular feature documented, this just doesn't
happen if you have separate manuals for each release that just cover
the functionality for that release.

> 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).

A script would certainly be written to do this. I though about using a
checked out copy and it is my personal preference actually but I
wasn't sure people would be entirely happy with that so I used export
to show how it can be done without any CVS stuff left around.

> 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.

We can use CVS for the docs in the same way as we do for the src
now. At release time we branch the docs tree and the 1.2 branch is
what goes onto the web server. You put fixes and things onto that
branch and the script will install that branch onto the server. You
can work on the next version of the docs on the head. We don't have to
wait until the next src release to do a docs release so if you want to
revamp the docs to at any time then you can.

It would be preferable to have a docs release at the same time as a
src release so that it can all be tagged and tarred together but that
is not a requirement. A separate docs release can be done at any time.

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

I couldn't find it. I think all that's really required is to add the
extra DB directives to the DBM file anyway, makes sense to keep this
information close together.

> > 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.

It's in the 1.0 docs.

> > 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.

Fine.

> > 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.

Great, if I can hand off the actual documentation issues to people who
understand those areas of the code better then I can just look after
the cvs maintenance/release side of it.

> 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?

+1 from me (gee I hate voting :-)

> 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.

When we have an ultimate decision on this I will cast the docs
location in stone and permanently remove the old areas from the
repository. It will be as if they never existed.

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

Hmm, ok, then I guess they weren't documented in 1.0, my merging
activities basically involved doing diffs and adding comments for
things that weren't present in the 1.0 docs. I only checked
the sources for the first few queries I had after that I just
trusted the docs.

A docs cleanup will still be required but that wasn't my aim, I just
wanted to present what I felt was a better mechanism for handling
them. I'm not entirely sure that my format and wording is spot on for
covering version differences but that's easily changed if we decide
this is the structure we want.

(I though compatibility was a bad idea after a while since we might
want to use that for differences with other servers rather than
between versions. Maybe "Availability" would have been a better
choice, or even just "History" as you get at the bottom of manpages).

-- 
  Paul Richards. Originative Solutions Ltd.  (Netcraft Ltd. contractor)
  Elsevier Science TIS online journal project.
  Email: p.richards@elsevier.co.uk
  Phone: 0370 462071 (Mobile), +44 (0)1865 843155

Mime
View raw message