[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Web Standards version 2.3

Dear Developers,

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


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
 Version 2.3
 Bruce Perens 6-November-1996

 1. Rationale
 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
 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 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.
 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. 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.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
 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
 this directory.
|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

Reply to: