Shared documentation system
Cornelius Schumacher
schumacher at kde.org
Thu Dec 11 18:15:43 EET 2003
On Monday 08 December 2003 08:44, Shaun McCance wrote:
> On Sun, 2003-12-07 at 22:51, Cornelius Schumacher wrote:
> > On Monday 08 December 2003 01:10, Shaun McCance wrote:
>
> [snip]
>
> > > In the case of mixing applications from different desktops, the
> > > proble misn't devastating. Most users will get the help for an
> > > application by selecting it from the Help menu. In KMail, that will
> > > open up the KDE Help Center. In Evolution, that will open up Yelp.
> > >
> > > This presents a problem for third-party software, though. When ISVs
> > > develop documentation for their applications, what do they do? If
> > > they have to jump through hoops to make it work with different
> > > desktops, then they probably just won't bother. They'll put it in
> > > HTML and open a webbrowser.
> >
> > Yes, you are completely right. The desktop file approach of KHelpCenter
> > already makes it quite easy to add 3rd party documentation. SUSE for
> > example uses this mechanism to integrate the documentation of the
> > complete distribution into the help center. It also provides an
> > apache-based help browser for these docs using the same meta files as
> > the KHelpCenter.
>
> Oh certainly. It's not that nobody can use these systems. It's not all
> that difficult to stick something in ScrollKeeper either. But for one
> reason or another, people don't use them as much as they could. Right
> now I'm using Fedora Core 1. Fedora has a ton of documentation, but
> none if it is in ScrollKeeper.
Using Scrollkeeper is quite complex for developers, especially for packaging.
I suppose if the same effect can be achieved with a simple hand-written file
which doesn't add any new dependencies to the package adding meta information
for documentation would have a chance of wider acceptance.
> So if there's a common system, it's just that much easier for people to
> get their documentation to show up. And hopefully it would also mean we
> have more people behind the system, and thus more people to smack others
> when they don't register their documents with the help system.
Agreed, I'm very much in favor of a common system.
> I think it's very beneficial to have all documentation work the same
> way, and to have stuff like the applications categorization and the
> documentation categorization work as similarly as possible.
Yes, but at least for backwards compatibility it would be nice, if the more
complex application categorization mechanism wouldn't be mandatory for the
docs from the beginning on. This would also make life for help browser
developers easier.
> And even I find myself sometimes wondering something like "Where the
> hell is the documentation for Foo located in the categorization?" If
> the structure mimicked the applications menu, then documents would be
> easier to find. Obviously, the categorization has to have more than
> just the applications, because there is documentation that doesn't
> belong to any application.
But it would definitely be nice if at least for the documentation which
belongs to the apps contained in the menu the doc would reflect that. For
KHelpCenter this is already the case, by the way ;-)
> All right, I don't really like having the categorization strictly follow
> the heirarchy of files in the filesystem. I think the Menu spec took a
> huge step forward on that, and we should follow.
In principle yes, but as said before, for backwards compatibility and for
easier implementation of help browsers I would like to keep that optional for
the beginning and allow for specifying doc hierarchy by file system
hierarchy.
> As for using .desktop files for the metadata, I have a few reservations,
> but I'm not entirely opposed. One problem I have is that the syntax
> isn't, to my knowledge, well-defined. At least I don't know of a real
> specification on them.
Well, there is the specification at
http://www.freedesktop.org/Standards/desktop-entry-spec. If this isn't
sufficient we should fix that.
> With XML, I have a clearly-defined syntax, and I have a fully conformant
> parser available to me. In fact, one of the main reasons I concocted my
> own XML format, rather than using actual RDF/XML, is that if I were to
> use RDF/XML, I would feel compelled to support it fully, not some half
> ass subset. And I don't have an RDF library readily available.
We have parsers for the desktop files as well. In KDE there is a class
KDesktopFile. I assume there is someting similar in GNOME, isn't it?
> This problem clearly isn't insurmountable, as we do use the .desktop
> format all over the place already. I've just had my share of experience
> with documentation systems which weren't clearly defined in some manner,
> and people took advantage of things that "happened to work". This can
> become a real pain in the ass.
Yes, so we should try to address this problem in whatever specification we
will come up with.
> Another problem I have with .desktop files is that it's not clear to me
> how to do any nesting. What I outlined allowed a single metadata file
> to reference many different "copies" of the same document. This sort of
> information can be immensely useful. It may not be immediately relevant
> to a simple help viewer, but the worst mistake you can make when making
> this sort of thing is that the only thing using your system will be the
> help viewer.
For what cases would you need the concept of copies? For translations of
documents this is handled by KHelpCenter by having the same desktop file with
multiple extensions.
> So I have other motives here. Every now and then, when I get a bit
> tired of putting bugs into Yelp, I take a little time off hacking to
> make empty promises to people. And one of the things I promise is an
> automatic documentation for the web building tool. And I mean fully
> automatic. The *model* presented by the format works very well this.
I don't quite follow you here. What documentation for which web building tool
do you mean?
> > If there is interest I could post a more detailed description of the
> > meta information KHelpCenter uses right now. It's similar to what you
> > suggested to put into the XML files.
>
> That would be good. Since you're actually using these sorts of files
> already, you'd have a better idea of what can be done with them. The
> .desktop files are easier to hand-edit, and developers will be more
> familiar with them, so there is definately an advantage to using them.
> If I can be convinced that they won't cripple the ability to store
> meaningful information, I won't really have any objections.
I have attached the current documentation of the meta data KHelpCenter
currently uses.
--
Cornelius Schumacher <schumacher at kde.org>
-------------- next part --------------
KHelpCenter documentation meta data structure
=============================================
KHelpCenter uses meta data files which describe the documentation available in
the system. Each document is represented by a meta data file and shown as an
entry in the KHelpCenter navigation tree view. The meta data contains
information about title and short description of the document, the location of
the document and some more information like how to search the document and
translations of title and description. Document hierarchy is represented as
hierarchy of the meta data files. Directories are also described by a meta data
file which contains the same information as a document meta data file.
Format of the meta data files
-----------------------------
The meta files adhere to the Desktop Entry Standard
(http://www.freedesktop.org/Standards/desktop-entry-spec). Documentation
specific extensions are covered by an own namespace using the prefix "X-DOC-".
The following table describes all keys which are currently used by
KHelpCenter:
Key Value Description
Name string Title of document
Name[xx] string Translated title for language xx
Comment string Short description of document
Comment[xx] string Translated short description for
Language xx
Icon string Name of icon for document
DocPath URI Location of document. In addition to the
standard URI schemes like http: and file:
all schemes which are supported through
kioslaves can be used. In particular the
followind non-standard URI schemes are
supported:
help: KDE manual identified by app name
ghelp: GNOME manual identified by app name
man: man page
info: info page
cgi: output of CGI script
DocPath[xx] URI Language specific location for
language xx
Lang langcode Language of document
X-DOC-Identifier string Unique identifier for document, if this
entry is not present the base name of the
file is used as identifier
X-DOC-Indexer command Command used for creating a search index
for the document.
The following symbols are replaced by the
corresponding values:
%f - Filename
X-DOC-IndexTestFile filename Name of file whose existence indicates
the existence of a usable search index
X-DOC-Search command Command used for searching, the output
of the command should be HTML which is
shown in KHelpCenter.
The following symbols in the command are
replaced by the corresponding values:
%k - Words to be searched for
%n - Maximum number of results
%m - Method for combining search words,
can be 'and' or 'or'
%l - Language of documents to be searched
%s - Scope of search. This is a list of
identifiers as given by the
X-DOC-Identifier entry or the bas
name of the desktop file if not
present.
X-DOC-SearchMethod string If this entry is 'htdig' htdig is used to
index and search the document. The
Indexer, IndexTestFile and Search entries
aren't required in this case.
X-DOC-SearchEnabledDefault bool If set to 'true' the document is searched
by default, if set to 'false' it is not.
This setting is overrideen by user
selected search scopes.
X-DOC-Weight int A number indicating the position of the
document within the list of siblings. A
greater weight indicates that the document
is 'heavier', thus shown below 'lighter'
documents. The default weigth is 0.
X-KDE-KHelpcenter string If this entry is set to one of the
following values a set of documents
generated by other means than desktop file
meta info is inserted at the place
specified by the desktop file:
'apps' manuals of applications
from the start menu
'scrollkeeper' scrollkeeper docs
'applets' panel applet docs
'kinfocenter' kinfocenter docs
'kcontrol' kcontrol module docs
'konqueror' konqueror plugin docs
'kioslave' kioslave docs
'info' info pages
Meta File Location
------------------
A list of directories given by the config entry "MetaInfoDirs" in the "Genral"
group of the help center configuration file "khelpcenterrc" (at
$KDEDIRS/share/config) is scanned for desktop files. They are merged to a common
hierarchy. If the "MetaInfoDirs" entry is empty the directory at
$KDEDIRS/share/apps/khelpcenter/plugins is used.
Document Hierarchy
------------------
The hierarchy of the documents shown in the help center is reflected by the
hierachy of the desktop files in the filesystem. Directories can have an
associated desktop file with the name ".directory". It can contain all the
keys described above.
Language handling
-----------------
In addition to translation of meta information like title and short description
of documents which is contained in the meta file, translations of whole
documents are handled. Each translation of a document has an own desktop file.
The language of the document is indicated by adding the language code as
additional suffix to the the filename of the desktop file. The language suffix
is added before the ".desktop" suffix (Example: 'apache.de.desktop' would be the
file name for the german translation of the apache documentation).
KHelpCenter shows only the documents whose language is contained in the list of
used languages configured for the desktop in the control center. A document
corresponding to a desktop file without language suffix is always shown.
More information about the xdg
mailing list