Date: Mon, 18 Sep 2000 21:28:00 +0100 From: Mark Ovens <marko@freebsd.org> To: doc@freebsd.org, ports@freebsd.org Subject: An opportunity for FreeBSD Message-ID: <20000918212800.L567@parish>
next in thread | raw e-mail | index | archive | help
Some time ago Andrew Boothman produced a couple of perl scripts to
collate all the documentation for ports/packages installed on a
machine and produce an HTML index file of it. It was suggested that
this could be extended to become part of the ports/packages mechanism
so that the index was automatically updated whenever a port/package
was installed or uninstalled. This got a rather cool reception from
the ports people (after all, no-one gets excited about having even
more work to do :)).
I recently picked up this project, partly because I think it's a good
idea, and partly because it provides a good vehicle for me to use to
learn perl(1).
Nik Clayton told me about a similar project that was starting up:
"There's another angle I think that's worth investigating. At the
O'Reilly docs summit a couple of months back, representatives from
the GNOME, KDE, and Linux documentation projects were all looking
at the similar problem of getting apps to register their
documentation, and also to try and provide an interface over and
above simple HTML."
I fired off an e-mail to a couple of contacts Nik gave me, one of the
replies I got is included at the end of this mail. As you can see the
project is only just getting started and as yet no code has been
produced. Currently the webpage mentioned in the e-mail has been taken
down as they discovered that the name "Dewey" (from the Dewey-decimel
system used for cataloguing by libraries) was trade-marked. The
project is looking for a new name.
I believe that it would be a Good Thing (TM) for FreeBSD to join this
project for several reasons:
1. We really should have a mechanism for indexing the docs
installed by the ports/packages.
2. By adopting Dewey (or whatever it becomes known as) rather
than developing our own system we will reduce the work involved
in implementation and maintenance.
3. It will help raise the visibility of FreeBSD in a predominately
Linux environment.
If we get involved now, at the outset, we will have a say in the
design and development of the system (i.e. prevent it becoming overly
Linux-specific) and get FreeBSD-specifics in the base source code. As
you might expect, this is going to be GPL'd (down Brett, down boy ;))
but I doubt that we will change that, however it would become an Open
Source project, rather than a Linux project (that FreeBSD may possibly
adopt in the future).
As to the additional work that this will make for port maintainers if
Dewey is adopted will be considerably less than using our own system.
For larger ports whose projects support Dewey, e.g. KDE, GNOME, etc.,
there should be no work at all as the meta-data will be in the source
tar-balls and for ports without the meta-data included we should be
able to automate its generation (although some hand tweaking may be
necessary).
Furthermore, this extra work is likely to be a one-off occurrence
since document files are rarely added/removed/renamed, only the
content is changed.
The only other areas where work will be needed is for bsd.port.mk(?)
to be modified to call Dewey as part of the install target (I expect
that Dewey will be able to determine if the port has any docs to
register). pkg_add(1) will also need modifying to do the same thing
when installing packages and pkg_delete(1) to call Dewey to
de-register the docs when a port/package is uninstalled.
I have subscribed to the mailing list (which is rather quiet at the
moment, but should liven up once code is available) and would like to
be able to announce that FreeBSD is "officially" supporting the
project (which means a committment to adopting Dewey for the
ports/packages when it reaches production quality). I am willing to
act as co-ordinator for this and will attempt to do most of the work.
I also intend to lobby the {Net,Open}BSD docs people to support Dewey.
If all three projects get involved it will, IMHO, give *BSD a big
presence (and influence) in a Linux project.
Please honour the Reply-To: so we just get one thread, in -doc.
----- begin included message from Dan Mueth <d-mueth@uchicago.edu> ----
We are trying to solve this problem with Dewey
(http://dewey.sourceforge.net/). Here's the basic idea:
Each document is accompanied by a 16-element OMF metadata description
describing the document (title, author, language, subject, description,
license, ...). Generally, this can be an external XML file or else built
directly into DocBook/XML files. After both the doc and metadata file are
installed, a command is sent to dewey which tells it to register the
document. Dewey keeps track of where the document and its metadata are
stored, as well as doing a few nice things like registering it in a
subject-sorted Contents List and yanking out the TOC(table of
contents) for DocBook docs. This info is stored in XML files. Then, the
help browser can ask Dewey for paths to particular information, like the
Contents List or the TOC for a particular doc, or to do simple searches on
document metadata (eg. "all documents with 'GIMP' in the subject or
title"). Note that this system also allows one to store metadata for
documents which are not local to the particular machines. Further, in
future versions, Dewey will be able to exchange information with servers
on the Net which function as giant electronic card catalogs, storing and
searching the metadata but not necessarily the documents
themselves.
If you are interested, join the mailing list from the URL above. A couple
of us are also on IRC a lot at #dewey on irc.openprojects.net. We don't
have much code yet, but we've made some progress on figuring out how we'll
do the 0.1 version and should have more code very soon. We are hoping to
have a basic functional system within a few weeks.
Dan
------ end included message -------
--
4.4 - The number of the Beastie
________________________________________________________________
51.44°N FreeBSD - The Power To Serve http://www.freebsd.org
2.057°W My Webpage http://ukug.uk.freebsd.org/~mark
mailto:marko@freebsd.org http://www.radan.com
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20000918212800.L567>