Re: Web Standards version 2.3
Bruce Perens wrote:
>
>|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 server can't, but dpkg can.
Ian's suggestion to put in each package a fragment of the index can be
considered.
The fragment could be the item of a list in which could be a simple
description of the package or another list with (relative) pointers to
the files and/or another index inside the package's hierarchy.
something like for package "foo":
(the base of the document will be "/auto/doc/" or "/usr/doc/" depending
on the protocol used to get the page, http or file)
<!--begin fragment in foo-->
<li><a href="foo">foo</a>
This is pachage foo.
<br>It can make you happy without bar.
<br>The documents in foo are:
<ul>
<li><a href="foo/README.txt">README</a>
An explanation in plain english.
<li><a href="foo/exaples/index.html">Some examples</a>
about the use and abuse of foo.
</ul>
<!--end fragment foo-->
The "file:" protocol needs explicit call to index.html; this works also
for the server, so I think its use should be mandated in the standard.
A very simple script (why a script? "cat" is enough) can rebuild the
index.html at the end of an installation stage in dselect, and ... when
dpkg is called by hand.
Maybe we can arrange something using the timestamp of the file and/or a
crontab activated by dpkg -i, that builds the index in background after
some seconds of dpkg inactivity and then deactivate itself.
I have done something like this in the package journal. A perl script,
j_mkindex, glues toghether (arount a header and a footer) the indexes
that each issue of a journal installs in /usr/doc/<xxx>, building the
global index.html on each installation/removal of one issue.
In this case the the work should be started by dpkg (--install,
--remove, --purge) and not in the postinst/postrm stages like in the
journal case.
We should issue a simple policy on how to write fragments and the script
could check if the tag used are compliant or not.
Ian Jackson wrote:
>
> 4. We need a standard way of getting things onto a master index, a la
> install-info. install-info is a pain because it attempts to modify a
> single file. Instead, have documents insert their index entries in
> some standard format as files in a directory, and rebuild the index
> using an update-html-index script. Since people need to be able to
> get at this index without installing a webserver, and programs need to
> be able to install while it's not there yet, this script needs to be
> in dpkg. That's OK because it can be little more than `cat'.
>
Fabrizio
--
+-------------------------------------------------------------+
| e-mail: fpolacco@megabaud.fi fpolacco@debian.org |
| http://megabaud.fi/~fpolacco/ Join the UKI Linux Project! |
| fingerprint 70 1A 72 2D 2B C8 A5 63 7A C2 CC E0 2A 54 AE DA |
| finger: fpolacco@megabaud.fi fpolacco@master.debian.org |
+-------------------------------------------------------------+
--
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: