You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@httpd.apache.org by Paul Richards <p....@elsevier.co.uk> on 1996/11/18 20:59:28 UTC
More docs fun....
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".
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".
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.
2) IdentityCheck was in the 1.0 docs, it's still in the current docs
but has gone missing from the directive listing.
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.
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.
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.
--
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
Re: More docs fun....
Posted by Paul Richards <p....@elsevier.co.uk>.
Alexei Kosut <ak...@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
Re: More docs fun....
Posted by Alexei Kosut <ak...@nueva.pvt.k12.ca.us>.
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 <ak...@nueva.pvt.k12.ca.us> The Apache HTTP Server
URL: http://www.nueva.pvt.k12.ca.us/~akosut/ http://www.apache.org/
Re: More docs fun....
Posted by Brian Behlendorf <br...@organic.com>.
On 20 Nov 1996, Tom Tromey wrote:
> Paul> I've considered writing an install target, anyone agree?
> Paul> Desirable for 1.2 or not?
>
> I've never understood why Apache wants to be built in its final
> install directory. It seems really weird.
>
> Our version has an install target. We also distribute an
> "install-apache" script that sets up a default server configuration.
> It does what was suggested here -- it sets up the Apache manual as the
> default content. It also creates a short "apache" script that can be
> used to stop/start the server (eg "apache start" or "apache stop").
>
> I can send the install-apache script to anybody who is interested.
> Parts of it are probably particular to our environment, but it might
> still be useful.
I guess the big question for me is, where is the docroot? Under /usr/local/etc
still? I haven't had my docroots there for years, they've either been a user
home directory (~www) or on its own disk partition (/www, etc). I suppose that
can be a question during an interactive install, or part of the Configuration
file. If that's the case, "make install" should probably install the docs
*only* if this is a brand new install.
Brian
--=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=--
brian@organic.com www.apache.org hyperreal.com http://www.organic.com/JOBS
Re: More docs fun....
Posted by Tom Tromey <tr...@creche.cygnus.com>.
Paul> I've considered writing an install target, anyone agree?
Paul> Desirable for 1.2 or not?
I've never understood why Apache wants to be built in its final
install directory. It seems really weird.
Our version has an install target. We also distribute an
"install-apache" script that sets up a default server configuration.
It does what was suggested here -- it sets up the Apache manual as the
default content. It also creates a short "apache" script that can be
used to stop/start the server (eg "apache start" or "apache stop").
I can send the install-apache script to anybody who is interested.
Parts of it are probably particular to our environment, but it might
still be useful.
Tom
--
tromey@cygnus.com Member, League for Programming Freedom
Re: More docs fun....
Posted by Paul Richards <p....@elsevier.co.uk>.
Alexei Kosut <ak...@nueva.pvt.k12.ca.us> writes:
> Sounds good. As for image references... well, we'd actually have to
> include the images now, wouldn't we. That's another couple-dozen
> kilobytes, for those of us keeping track...
Umm, yeah. I think having the manuals appear as an intro when the
server starts up would be a nice feature myself. This doesn't actually
work of course because the server doesn't seem to start up knowing
where the htdocs directory is even though there was a sample index
file in there before.
I've considered writing an install target, anyone agree? Desirable for
1.2 or not?
> One thing I'm concerned about is that we have hundreds of thousands of
> people using Apache 1.1.[01], which says to see
> http://www.apache.org/docs/1.1/ for information on that release. We
> need to either symlink or Alias or Redirect that directory to
> somewhere else, like http://www.apache.org/docs/, or to
> new_features_1_1.html or somewhere.
I'd prefer something to patch over this in the server rather than
anything that'll go into cvs and be distributed as part of Apache.
> And there's a question of what is a "module" file, and what is a
> "general info" file. Where does keepalive.html go, for example?
This is why we need a docs cleanup :-)
--
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
Re: More docs fun....
Posted by Brian Behlendorf <br...@organic.com>.
On Tue, 19 Nov 1996, Alexei Kosut wrote:
> On Tue, 19 Nov 1996, Brian Behlendorf wrote:
>
> > In fact, there's a slew of enhancements I'd like to make, but they sort of have
> > to be done in a batch, so I'd like to ask to be a bottleneck for an evening so
> > I can do the following:
> >
> > Put per-module docs in a mod/ subdirectory
> > Put general-informational files in an info/ subdirectory
> > Fix headers and footers to include things properly
> > Fix image references
> >
> > I can do this tomorrow night, it should only take a few hours. After that we
> > can go crazy with writing sections and fixing typos and such. What do folks
> > think?
>
> Sounds good. As for image references... well, we'd actually have to
> include the images now, wouldn't we. That's another couple-dozen
> kilobytes, for those of us keeping track...
>
> One thing I'm concerned about is that we have hundreds of thousands of
> people using Apache 1.1.[01], which says to see
> http://www.apache.org/docs/1.1/ for information on that release. We
> need to either symlink or Alias or Redirect that directory to
> somewhere else, like http://www.apache.org/docs/, or to
> new_features_1_1.html or somewhere.
I'll set up appropriate redirects/rewrites.
> And there's a question of what is a "module" file, and what is a
> "general info" file. Where does keepalive.html go, for example?
Ah, by "general info" I mean, not directive documentation but stuff like
"perf.html" and "security_tips.html". I'd leave keepalive.html in the main
directory, I think.
Brian
--=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=--
brian@organic.com www.apache.org hyperreal.com http://www.organic.com/JOBS
Re: More docs fun....
Posted by Alexei Kosut <ak...@nueva.pvt.k12.ca.us>.
On Tue, 19 Nov 1996, Brian Behlendorf wrote:
> In fact, there's a slew of enhancements I'd like to make, but they sort of have
> to be done in a batch, so I'd like to ask to be a bottleneck for an evening so
> I can do the following:
>
> Put per-module docs in a mod/ subdirectory
> Put general-informational files in an info/ subdirectory
> Fix headers and footers to include things properly
> Fix image references
>
> I can do this tomorrow night, it should only take a few hours. After that we
> can go crazy with writing sections and fixing typos and such. What do folks
> think?
Sounds good. As for image references... well, we'd actually have to
include the images now, wouldn't we. That's another couple-dozen
kilobytes, for those of us keeping track...
One thing I'm concerned about is that we have hundreds of thousands of
people using Apache 1.1.[01], which says to see
http://www.apache.org/docs/1.1/ for information on that release. We
need to either symlink or Alias or Redirect that directory to
somewhere else, like http://www.apache.org/docs/, or to
new_features_1_1.html or somewhere.
And there's a question of what is a "module" file, and what is a
"general info" file. Where does keepalive.html go, for example?
--
________________________________________________________________________
Alexei Kosut <ak...@nueva.pvt.k12.ca.us> The Apache HTTP Server
URL: http://www.nueva.pvt.k12.ca.us/~akosut/ http://www.apache.org/
Re: More docs fun....
Posted by Brian Behlendorf <br...@organic.com>.
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".
Okay, cool, I think we're moving in the right direction. I think this is a
better model than the 1.0/, 1.1/, 1.2/ etc subdirs, as URL's can be made more
permanent. Some production work should be done to make this mini-docs site
more attractive - I can start by moving images into here in a way which will
will be portable to the web site as well.
In fact, there's a slew of enhancements I'd like to make, but they sort of have
to be done in a batch, so I'd like to ask to be a bottleneck for an evening so
I can do the following:
Put per-module docs in a mod/ subdirectory
Put general-informational files in an info/ subdirectory
Fix headers and footers to include things properly
Fix image references
I can do this tomorrow night, it should only take a few hours. After that we
can go crazy with writing sections and fixing typos and such. What do folks
think?
Brian
--=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=--
brian@organic.com www.apache.org hyperreal.com http://www.organic.com/JOBS