httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject Re: Re: --- About Documentation --- (long ;-)
Date Fri, 04 Oct 2002 12:16:09 GMT

Hi Ken,

> he has a point.  in all the fancy cleanup work, did we miss something
> in terms of relative links?
>> Why canĀ“t i download all this documentation so i can read off-line
>> it goes directly against the open source filosofy and enoing to save
> the source code and alter the path to the .css file after saving this
> to an directory!!!

I would tend to consider this to be
a) some browser bug and/or
b) some usability/expectation problem.

I used Mozilla and M$IE 5.0 to display the page in question,
let both of them use "Save as ..." to store this page to my
hard disk, and inspected the source code. Both browsers do
actually rewrite the HTML source of the stored page - they
1. create a directory of the name of the file (without its
   extension) in the same directory where the file is stored,
2. store all related files (CSS, JS, GIF, ...) into this
   directory and
3. modify the corresponding links in the HTML source.
The downloaded file is perfectly usable offline - I don't
experience any problem with relative links there. So if this
user cannot do what I did, he may use some strange browser.

On the other hand, having to visit each and every page to get
a usable offline version of the Apache module doesn't seem to
be the way how to do it, although some user may not be aware
of better alternatives.
This is what I named "usability problem" above.

If I wanted to have some Apache manual offline, I would have
at least these options:
a) Install Apache and use the manual shipped with it (which
   indeed requires an Apache to be running, because of the
   language negotiation features - it doesn't work to access
   these files via the "file:" protocol)
b) Get some offline reader and let it traverse the whole site - not a good way, as it
   would take some time (and cause a lot of traffic on the
   server), but would serve me a version that is truly usable
None of these seems to be explicitly explained on any Apache
page - they tend to be common sense for an experienced WWW,
while some novice user might wenn experience the problems
described in this mail.

All of the suggestions below refer to a HTML version of the
manual. They may be usable for an XML version as well, but
I am not sure about that.

What I _don't_ (yet) have as an option is
c) click on some link that allows me to separately download
   a HTML only (no negotiation!) version of the Apache manual
   as some compressed archive file specific for _my_ language.
I think this would be much closer to the expectation of this

The links to the negotiated variants would work offline if
there only were files without language specific extensions,
and preferredly those for the language I am used to read.
So the trick seems be to
a) generate a language specific version of the manual (for
   each language in question) and
b) offer this version for download.
The server's language negotiation mechanism would then apply
to the download request only.

This might require
1. computing the set of all languages that have at least one
   language specific file within the Apache documentation (by
   traversing the complete document tree of the manual)
2. have some program request the list of all available documents
   a) via HTTP, sending one of these languages in the "Accept-
      Language:" header, if any server-sided intelligence is
      being used within at least one page (see end of mail) or
   b) by simply reading the file's content
   and store the result into some file with no language speci-
   fic extension,
3. have some loop over all languages from 1. to do 2., storing
   the result into some directory tree specific to the language
   being used in the "Accept-Language:" header of the results
   (and thus heavily duplicating these files in cases where no
   language specific version is available).
   In the case of 2.b) a simple file copy would suffice.
4. convert each of the resulting document trees into a com-
   pressed archive named "apache_manual.gz.<language>",
5. offer a link "download this manual" on the start page of
   the online version of the Apache online manual,
6. let this link point to
   thus make the Apache negotiation feature provide the language
   specific version for this user.
   (I intentionally made this URL absolute, so that the link
    would still work inside some downloaded version of the
    manual, and you can thus update your manual if you want to.
    A more sophisticated method would use not a direct link to
    the archive file, but a link to some CGI script that will
    receive the last modification date of the already downloaded
    version and would then response something semantically
    equivalent to a HTTP-304, to prevent unnecessary downloads
    of the same documentation archive ... this would then re-
    quire the link inside this start page to be generated while
    creating the archives, as to provide the modification date
    as query string.)

This way, the set of all required language-specific and negotia-
tion independent download archives could be computed by some not
too complicated server-side intelligence.
This tool would have to be run each time the online version of
the manual has been changed. (Of course, you could use some cron
job to periodically check the last modification date of all the
online files, compare them with the last modification dates of
the compressed archives, and update the archives if required -
this would free the online documentation update person from
another manual operation that could be forgotten.)

As for the implementation, this seems like a task for some
Makefile ... no individual software required, unless 2.a) would
require HTTP access (unlikely at the current state of the manual,
but one day you might want to have "live examples" for features
like SSI, negotiation, authentication etc. in the manual, which
would then make the whole idea described in this mail unusable).

The only thing that would be necessary is some tool to generate
the set of languages available, which might be some simple di-
rectory traversing script; this would then create the (additio-
nally required) language directories and generate/update the
Makefiles inside each of these. The cron job would just run
a) this Makefile generator and then
b) a "make" over the tree of the generated language specific files.

Regards, Michael

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message