Shared documentation system

[Shaun McCance]

I hope you've all had a nice holiday.  Let's get this discussion fired
back up.

At this point, I've basically agreed on desktop files as the metadata
format.  KDE already uses this format, and I don't see any objections
from any other parties.

Given the problems with managing multiple copies in a single metadata
file, we should probably have a single metadata file for each copy of
documentation installed (translation, formatting, version, etc.)  This,
however, has a disadvantage in not having a single file that references
some piece of documentation.

I had originally hoped that opening the documentation for an application
could just involve opening the metadata file.  This would allow a user's
preferred help browser setting to be set with the same system used for
any other preferred applications.  I think we may still be able to work
something to that effect in.  And if not, it's not a huge loss.

So first we need to standardize on keys.  The desktop entry spec has a
Type key.  I think this should be used and set to "Documentation".  We
can probably all agree on the keys Name, Comment, Icon, DocPath, and
Lang.  I think we should have a ContentType key, which would give the
MIME type of the referenced documentation.

I've said a few times that I'd like to work with something like the menu
spec, so of course I'd like Categories, OnlyShowIn, and NotShowIn, as in

http://freedesktop.org/Standards/menu-spec/0.8/ar01s03.html

And, of course, we need something like Identifier, what KDE currently
uses X-DOC-Identifier for.  I rather like the identifier scheme that I
outlined earlier:

https://listman.redhat.com/archives/xdg-list/2003-December/msg00160.html

As a recap, identifiers would use a slash-separated string as a simple
namespacing mechanism.  Every identifier is under one of a couple of
standard top-level namespaces.  Additional namespaces can be introduced
below that.

Applications would put their documentation under apps/ and then use
their application name, such as apps/kmail or apps/evolution.  If an
application has more than one piece of documentation, it can use its
application name as an additional namespace, such as

apps/glade-2/faq
apps/glade-2/turbo-start
apps/glade-2/user-guide

GNOME desktop documentation would be under gnome/ and KDE desktop
documentation would be under kde/.  Or perhaps there should be an
additional desktop/ top-level namespace, and then we could have
desktop/gnome/, desktop/kde/, desktop/xfce/, etc.  That would really
make it easier to handle more desktops.  Other possible top-level
namespaces are libs/, system/, and vendor/.

There could also be man/, info/, kde/, and scrollkeeper/ top-level
namespaces.  No document installed with this system would use those. 
Rather, if a help browser pulls in stuff from another system, it can
automatically assign an ID.  This way every document can be referenced
the same way, regardless of where it came from.

I would like a Replaces key in the metadata that gives a list of IDs of
documents that this document replaces.


All right, this list isn't exhaustive.  I want to get some foundation
first, and then we can build.  In particular, I want to hear people's
thoughts on the proposed identification system.  I think it's simple and
effective.  It also makes it pretty simple to map existing help systems
into this one.

If we can get some agreement on the basics, I can start to write up a
specification for this.  It'll need a place to live on the web, of
course.

--
Shaun