Shared documentation system
shaunm at gnome.org
Sun Jan 4 00:11:03 EET 2004
I hope you've all had a nice holiday. Let's get this discussion fired
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
And, of course, we need something like Identifier, what KDE currently
uses X-DOC-Identifier for. I rather like the identifier scheme that I
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
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
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
More information about the xdg