Re: Debian WWW standards version 2.0
From: Ian Jackson <ian@chiark.greenend.org.uk>
> 1. Preformatted HTML files ought to be accessible and accessed by
> default _without_ going through a webserver. This is faster (in some
> cases _much_ faster) and more secure.
There is more support for this in 2.1, but not full support.
This would be much more of a win if so much stuff like man and info
pages was not runtime-converted. This is not to say that I think
runtime-conversion is a bad idea. It is rather difficult to support
"file:" access unless you use relative links _everywhere_, with relative
links through a symlink to go from /var/debian-www to /usr/doc and back.
That was rejected as being difficult to explain and not necessary because
of the relative unimportance of the goal of providing "file:" access
everywhere.
> 2. CGI manual conversions and so forth should _by default_ be
> restricted to access from localhost.
I don't see why, given that the user has control over this. I think
95% of servers running under Debian will only serve documentation.
Many users will put a Debian system on their net and then may use
Netscape from some other platform to read its documentation (I do that
a lot from my SGI now).
> There should be a single point where these scripts can be en- and
> disabled.
There is. Remove cgi-bin/debian. Under some servers cgi-bin/debian is
a script, not a symlink (this is the case under WN and could be so for
most other servers) and you can add security features to it if you wish.
> 3. The files that you're putting in /usr/lib/debian-www/documents
> actually belong in /usr/doc; there is no distinction between what goes
> in /usr/lib/debian-www/documents and what in /usr/doc. Conclusion:
> /usr/lib/debian-www/documents should be abolished.
Yes, this avoids having two places for documentation. I will state
that packages should install their HTML pages under
/usr/doc/<package-name>/ and the only thing they should install in
/usr/lib/debian-www/ is CGI scripts, which go in
/usr/lib/debian-www/cgi-bin .
> 4. We need a standard way of getting things onto a master index, a la
> install-info.
Lars has done a good job at this with "dwww" so far. I am deliberately
leaving this out of the standard until he comes to us with needs that
can't be filled without the cooperation of the installing package.
> 5. The pathnameword `ROM' has gained currency here on this list but
> will I think otherwise be ill-understood in this context. I suggest
> we don't use it.
I can make /usr/doc be exported as http://localhost/debian/doc .
However, the cgi-bin is another story, as there are explicitly ROM and
variable areas for CGI scripts.
> 6. Adding general stuff in /usr/doc shouldn't require calling an
> update script (but of course we need to be able to add index entries).
The problem is that update-debian-www is intended to appease WWW servers
like WN that need to write an index file of their own in every directory
they serve.
I think only things that install HTML pages should call update-debian-www.
"dwww" can call the script when it runs to add other kinds of files,
although this will fail (hopefully silently) if /usr/doc really is
read-only when "dwww" runs. update-debian-www must be called before
/usr/doc is made read-only, for example while a plug-and-play CD image is
created.
I can add to the spec that the update-debian-www script
take a list of directory names to be scanned, so
that we can limit its execution time.
> 7. Webservers should not conflict. Ergo, update-debian-www (which
> should have the word `cgi' somewhere in its name) needs to be a .d in
> /etc, called using run-parts, rather than an actual program.
OK, that sounds like a good way to handle it, IF you can make run-parts
pass arguments to the scripts it runs. I don't understand why
it should have "CGI" in its name - its major role is to appease WWW
servers like WN that want to put index files in directories that they
serve.
> you quote the absolute pathname `/usr/bin/update-debian-www'.
> Absolute pathnames are evil, and should not be used.)
OK, given that we will use run-parts.
> 8. Everything in your document should use `localhost' instead of
> `hostname'. However, actual files should try to avoid specifying
> hostnames.
This was addressed in version 2.1
> 9. You don't say what documentation-providing packages should do.
> Make sure you specify both `sides' of the interface.
Currently, all they should do is install HTML pages in their
/usr/doc/<package> directory. Would you like to specify that they
install /usr/doc/<package>/index.html if they install web pages?
Thanks
Bruce
--
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: