RFC: local-config-independant hyperlinks between docs
Here's the problem: Some packages in the distribution have a doc
which features references to other package that *may* be installed,
but on which they don't depend.
This is often solved by making these hyperlinks point to a non-local
URL, where this document can be found.
This has the advantage of keeping these links valid, but has the
following disavantages, which I think should be addressed:
* a Debian machine may not have net access, thus making these links
useless for many people.
* it doesn't allow to browse local documentation when it is available.
Here's a solution I thought of. It surely needs some improvements,
and only the basic idea is there - it only handles HTML - it does not
address httpd-less machines, unless the browser can run a cgi script
by itself.
* A cgi script like the one attached is installed as
/usr/lib/cgi-bin/find-doc
* The package maintainer patches the docs to replace all relevant
links by links of the form
"/cgi-bin/find-doc/<package>/some/doc?http://machine.there/here/is/some/doc";
* Then the find-doc script arranges to redirect the browser to the
local doc if any, or else displays a message about the missing
package, and offers a link to the non-local doc, maybe a form to
ask root to install the relevant package, etc.
What do others think about this idea ?
--
Yann Dirson <ydirson@a2points.com> | Stop making M$-Bill richer & richer,
alt-email: <dirson@univ-mlv.fr> | support Debian GNU/Linux:
debian-email: <dirson@debian.org> | more powerful, more stable !
http://www.a2points.com/homepage/3475232 | Check <http://www.debian.org/>
#!/bin/sh
# CGI script handling links between possibly-cooperative program's docs.
# to be called as:
# http://localhost/cgi-bin/find-doc/tkman/tkman-help.html?http://http.cs.berkeley.edu/~phelps/
# Notes:
# * it only handles accurately docs installed under /usr/doc/<package>/
# * it requires the <package> to be the name of the doc-package (if
# doc/foo-doc is a symlink to doc/foo, specify foo-doc, or the message
# will be wrong)
# PATH_INFO: the local file if present, with leading /usr/doc stripped
# QUERY_STRING:
# * the remote URL
# parse arguments
URL=$(echo ${QUERY_STRING} | cut -d+ -f1)
PACKAGE=$(echo ${PATH_INFO} | cut -d/ -f2)
# if the local doc
if [ -r "/usr/doc/${PATH_INFO}" ]
then
# just do as-if the local doc was referenced
echo "Location: http://${HTTP_HOST}/doc${PATH_INFO}";
echo ""
else
# produce a warning that the package is not there,
# and offer a non-local alternative
echo "Content-type: text/html"
echo
echo "<HTML><HEAD><TITLE>Document not installed</TITLE>"
echo "<BODY><h1 align=center>Document not installed</h1>"
echo "<P align=center>This doc is part of"
echo "<BR>the \`<strong>${PACKAGE}</strong>' Debian package,"
echo "<BR>which is not installed on host \"${HTTP_HOST}\""
if [ "${QUERY_STRING}" ]
then
echo "<P align=center>You can find the same information at:"
echo "<BR><A href=\"${URL}\">${URL}</A>"
else
echo "<P align=center>I can't tell you where else to find it."
fi
echo "</HTML>"
fi
Reply to: