Debian WWW standards version 2.1
Here is version 2.1 of the WWW standards, with change bars. A "|"
character at the beginning of the line indicates a change from version 2.0 .
Changes are that update-debian-www has moved to /usr/sbin, and URL form and
hostname usage are now specified.
ATTENTION WWW PACKAGE MAINTAINERS: Relative URLs are specified.
Please check this out for compatibility with your WWW server.
I think we are actually converging on something that everyone can live
with now.
Thanks
Bruce
Debian WWW Organization
Version 2.1
Bruce Perens 4-November-1996
1. Rationale
1.1 Serving Debian Documentation
A primary purpose of the WWW server and browser on a Debian system is
to provide access to all available Debian documentation. This implies
several goals:
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 Debian documents must be robust.
If a WWW server is removed and a different one is then
installed, access to Debian 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, Debian users may wish to build large, publicly-accessible
WWW sites. Debian 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
Debian documentation.
There are a few goals necessary to support the Webmaster:
A. Debian can't take over the WWW site. This will only get in the
way of the Webmaster. Thus, Debian should restrict its activities
to its 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 installed by Debian.
|1.3 Nomenclature
| 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. No text, and deleting the two slashes before <hostname>,
| as in the form "http:/debian/foo.html".
| All three of these forms should be supported.
2.0 Implementation
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 Debian
package must not install data in the document root of the WWW server,
unless it is the package that installs the server itself.
Debian will maintain a directory /var/lib/debian-www/documents . Each
WWW server must export this directory as "http://<hostname>/debian/".
Data in this directory may be rewritten while the system is operating.
The WWW server may write its own housekeeping files under this
directory.
Debian will maintain a directory /var/lib/debian-www/cgi-bin . Each WWW
server must export this directory as "http://<hostname>/cgi-bin/debian/.
Data in this directory may be rewritten while the system is
operating. The WWW server may write its own housekeeping files under
this directory.
Debian will maintain a directory /usr/lib/debian-www/documents. 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
data that does not need to be re-written while the system is operating.
Each WWW server must export this directory as
"http://<hostname>/debian/ROM.documents . The WWW server must treat
this as ROM space, and must not write files under this directory. The
WWW server is allowed to use any contrivance to make this space
available. For example, it can provide access to the URL through a
"virtual path" CGI script, or it can create symbolic links from all of
the documents in the ROM space to a directory in read-write space.
Debian 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>/debian/ROM.usr.doc . The WWW server must treat this
as ROM space, and must not write files under this directory. The WWW
server is allowed to use any contrivance to make this space available.
For example, it can provide access to the URL through a "virtual path"
CGI script, or it can create symbolic links from all of the documents
in the ROM space to a directory in read-write space.
Debian packages may install files under the above directories and may
expect the WWW server to immediately make these files available. To
facilitate this the WWW server may create a script
|"/usr/sbin/update-debian-www". Packages that install files in the
above-mentioned directories will detect the existence of this script in
their postinst scripts, and will execute the script if it exists. The
script must scan the above mentioned areas for files, and must make
those files accessible.
Debian will maintain a directory /usr/lib/debian-www/cgi-bin. WWW
servers must not directly export this directory. However, symbolic
links may be created from /var/lib/debian-www/cgi-bin to
/usr/lib/debian-www/cgi-bin to make CGI scripts available for the
server to export. Packages may install these symbolic links
automatically. If a symbolic link is installed to make a new CGI script
available, the package that installs it must detect the presence of
|/usr/sbin/update-debian-www, and execute it if it exists.
|2.2 CGI Scripts
|
CGI scripts installed by Debian 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 URL Form
|
|HTML pages installed in the directory trees mentioned in this proposal
|should use relative URLs without host names to refer to other files in
|the same directory tree. Absolute URLs without host names should be used
|to refer to files in another directory tree. For example a URL to another
|file in the same directory tree can be of the form "http:../dwww/foo.html",
|and a URL to another file in a different directory tree can be of the form
|"http:/debian/ROM.documents/foo.html".
|
|
|2.4 Access to Documents Using the "file:" Protocol
|
|If all WWW servers now support this form, it may be possible to leave the
|protocol portion "http:" out of URLs. This would provide better support
|for access using the "file:" protocol. We should note however that the
|file protocol is not useful for CGI scripts, and that we intend to provide
|a large number of run-time translated documents via CGI scripts. Thus,
|the "file:" protocol may be of marginal usefulness.
--
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
Reply to: