Shared documentation system

[Shaun McCance]

On Tue, 2004-01-06 at 05:37, Murphy wrote:
> Hey'
> 
> On 05 Jan 2004 18:32:24 -0600 Shaun McCance wrote:
> 
> > Oh, absolutely.  This is essential.  Once we have a simple means of
> > addressing documentation hammered out, we can easily add a key to the
> > applications' desktop files to give a listing of keys of all relevant
> > documentation.
> 
> I'm a bit worried (perhaps mistakenly) about the desktop entry files
> getting too large and slowing down menu parsing, etc.  Would it be better
> in that case, to simply have a key that points from the .desktop to a
> single .document file and then the .document can grow at it's own pace?

Yeah.  The application's desktop file would just provide a list of keys
of relevant documentation desktop files.  We wouldn't want to duplicate
any metadata in there.  So here is gnome-terminal's desktop file, sans
translations.

[Desktop Entry]
Encoding=UTF-8
Name=Terminal
Comment=Command line
Exec=gnome-terminal
Icon=gnome-terminal.png
Type=Application
X-GNOME-DocPath=gnome-terminal/index.html
X-GNOME-Bugzilla-Bugzilla=GNOME
X-GNOME-Bugzilla-Product=gnome-terminal
X-GNOME-Bugzilla-Component=general
Categories=GNOME;Application;System;Utility;TerminalEmulator;
StartupNotify=True

I'm proposing another key be added to this, say Documents.  We would
remove the X-GNOME-DocPath key, and add,

Documents=apps/gnome-terminal;

That's all we add to the application's desktop file.  That's sufficient
information to get the documentation's desktop file, which can give us
all the metadata we need.  The reason it's a list is that many apps have
more than one piece of documentation.  Glade, for instance, has three. 
So Glade's desktop file could have

Documents=apps/glade/faq;apps/glade/turbo-start;apps/glade/user-guide

Then we would have desktop files for each document installed.  So using
gnome-terminal again, we would have a desktop file like

[Desktop Entry]
Encoding=UTF-8
Identifier=apps/gnome-terminal
Name=Terminal User Guide
Comment=User guide for the GNOME terminal emulator
Icon=gnome-terminal.png
Type=Documentation
DocPath=/usr/share/gnome/help/gnome-terminal/C/gnome-terminal.xml
ContentType=text/x-docbook
X-GNOME-Bugzilla-Bugzilla=GNOME
X-GNOME-Bugzilla-Product=gnome-terminal
X-GNOME-Bugzilla-Component=docs
Categories=GNOME;Application;System;Utility;TerminalEmulator;
Replaces=scrollkeeper/d7834910-40e7-11d6-87e4-aa5f78e530ae;

The X-GNOME-* keys are GNOME extensions, obviously.  Type is set to
Documentation.  DocPath gives a full path to the documentation file. 
ContentType gives the MIME type of the documentation (and I just made
the text/x-docbook MIME type up).

Replaces gives a list of IDs of documents that this document replaces. 
In this case, scrollkeeper/ is one of the automatic namespaces.  That
is, no documents would install themselves in this system under that
namespace.  Rather, help browsers that import ScrollKeeper information
map each document from ScrollKeeper into this system.  Part of that
mapping involves giving the document an identifier in this system's
identification scheme.  ScrollKeeper identifies documents with the
seriesid attribute, which has values like that ugly random string you
see above.  What I've done with Replaces is said, "If you grab stuff
from ScrollKeeper, you should throw out this ScrollKeeper document,
because this document replaces it."

--
Shaun