Web Standards version 2.3
Here is version 2.3 of the Web Standard. This is now cast in concrete
for Debian 1.2 , and we can deploy it, or not, before the 1.2 release.
We should consider developing this more and then passing it on to FHS
or another wider group, and see what they come up with by 1.3 .
I have backed down from some of the more ambitious goals of standard
version 2.2 . Unfortunately, we will not be able to achieve _all_ of
the goals we wanted in 1.2, but we will at least be able to achieve some
1. The name "debian" has been replaced with "auto" in various places.
This is to connote that the pages are automaticaly-installed. It was
pointed out that embedding "debian" in paths and URLs makes this
standard too debian-specific :-) . However, we still needed a name
to distinguish automaticaly-installed documents from the root of the
web server, which should be entirely under local control or at least
under the control of the web server package.
2. update-debian-www has been deleted. It was to run too often and
require too much overhead. The requirement that servers make
information accessable immediately has thus been removed, so that
servers can run a cron job to perform the function that
update-debian-www previously performed. The only server that will
not make information immediately available because of this that I
know if is WN. We'll have to live with that or hack WN. WN also has
a problem in that it wants to write index files in /usr/doc, which
should really be a read-only area.
3. /usr/lib/debian-www/documents has been deleted. Ian Jackson correctly
pointed out that it is redundant with /usr/doc .
4. The URL for /usr/doc is now http://localhost/auto/doc .
5. Anchors are specified to be relative if at all possible, so that support
for the "file:" URL is possible.
6. The standard has been renamed.
This standard does _not_ address how packages should link themselves into
a global WWW index. I'd like to nail down what has already been written,
and let us have time to develop that for 1.3 .
Automaticaly-Installed WWW Organization
Bruce Perens 6-November-1996
1.1 Serving Documentation
|A primary purpose of the WWW server and browser on a system is to
|provide access to documentation about that system. This implies
A. WWW configuration must be automatic.
Since the user is reading documentation via WWW, we must
provide that user with a WWW configuration that works correctly
right away, without any configuration on the user's part.
| B. The WWW service of automaticaly-installed documents must be robust.
| If a WWW server is removed and a different one is then
installed, access to documentation must be maintained.
C. Automatic installation of documents must be supported.
Packages need a well-known fixed path that can be used to
install files, and a corresponding well-known URL to access
those files once they are installed.
1.2 Serving as a User-Specific WWW Site
|Obviously, users may wish to build large, publicly-accessible
|WWW sites. The automaticaly installed pages should not stand in the way
|of that. However, the Webmaster can be expected to understand their
document organization and to put a good deal of custom configuration into
their system. This is not the case for the user who simply uses the local
WWW server to read documentation.
There are a few goals necessary to support the Webmaster:
| A. Automatic documents can't take over the WWW site. This will only
| get in the way of the Webmaster. Thus, we should restrict
| our activities to our own well-known locations, and should
| _not_ install files in the root of the WWW server.
B. Webmasters all have their favorite server. Thus, we should support
as many servers as possible, and the documentation scheme
should work with all of them.
C. Security is important to the Webmaster. Thus, we should make it
as easy as possible to maintain the security of the system while
| it serves documents that have been automaticaly installed.
Where <hostname> appears in this document, it should be replaced by
one of the following:
1. The fully-qualified domain name of the host.
2. The host alias "localhost".
3. Only in an anchor: No text, and deleting the two slashes
before <hostname>, as in the form "http:/auto/foo.html".
In this case the protocol ("http:" or "file:") can also
be deleted, and the remaining path may be relative.
All three of these forms should be supported.
2.1 Well-Known Paths and URLs
The WWW server package maintainer may locate the document root of their
WWW server where they wish, except that the document root may not be
located in any of the directories mentioned in this proposal. A
package must not install data in the document root of the WWW server,
unless it is the package that installs the server itself.
|The system will maintain a directory /var/lib/auto-www/documents . Each
WWW server must export this directory as "http://<hostname>/auto/".
Data in this directory may be rewritten while the system is operating.
The WWW server may write its own housekeeping files under this
|The system will maintain a directory /var/lib/auto-www/cgi-bin . Each WWW
server must export this directory as "http://<hostname>/cgi-bin/auto/.
Data in this directory may be rewritten while the system is
operating. The WWW server may write its own housekeeping files under
|The system will maintain a directory /usr/doc . This directory is
restricted in that it may be on a read-only medium once packages have
been installed. This is an appropriate place to install program
documentation and examples that do not need to be re-written while the
system is operating. Each WWW server must export this directory as
|"http://<hostname>/auto/doc . The WWW server must treat this
|as read-only space, and must not write files under this directory.
|The system will maintain a directory /usr/lib/auto-www/cgi-bin. WWW
servers must not directly export this directory. However, symbolic
links may be created from /var/lib/auto-www/cgi-bin to
/usr/lib/auto-www/cgi-bin to make CGI scripts available for the
server to export. Packages may install these symbolic links
2.2 CGI Scripts
|CGI scripts installed by packages must conform to the current
CGI standard. If CGI scripts use server-specific features, they must
detect the presence or absence of those features, and should continue
to operate or at least fail gracefully with a message to the user if a
desired feature is not available.
2.3 Anchor Form
HTML pages installed in the directory trees mentioned in this proposal
|should use relative anchors without protocol or host name to refer to
|other HTML pages in the same directory tree. Absolute anchors should be
used to refer to files in another directory tree. For example an
anchor to another file in the same directory tree can be of the form
"../dwww/foo.html", and an anchor to another file in a different
directory tree can be of the form "http:/auto/doc/foo.html".
TO UNSUBSCRIBE FROM THIS MAILING LIST: e-mail the word "unsubscribe" to
debian-devel-REQUEST@lists.debian.org . Trouble? e-mail to Bruce@Pixar.com