Version &version; 12 October 2006 Don Scorgie

DonScorgie@Blueyonder.co.uk

Roman Joost

romanofski@gimp.org

Christopher Lahey James

clahey@ximian.com

Shaun McCance

shaunm@gnome.org

Cornelius Schumacher

schumacher@kde.org

Providing help to the user is one of the most important functions of a user-friendly desktop system. This document specifies how desktop help systems can find, navigate, show and search documentation. This includes application manuals, context-sensitive help and documentation not associated with a specific application. Documentation can be provided in in numerous formats, for example Docbook, HTML, PDF and can also be provided over the net. The goal of this standard is to provide the base for a unified cross-desktop documentation system. Notes are used throughout to indicate something I'm not sure of, something that needs input from others or random mumblings from myself. They should be removed once the issue has been resolved. (Don Scorgie) This help system standard aims at providing help browser developers and application authors as well as documentation creators the means to integrate and consistently handle all documentation present on a system. It doesn't mean to specify any implementation details or to impose any policies about what type of help browser to use or how exactly the documentation is organized or formatted. These are the specific goals of the help system specification: Users should be able to choose the help browser of their choice. The help system should impose as little policy as possible on the help browser, and should expose as little policy as possible to documenters. It should be simple to place a document in the help system. The help system shouldn't require anything to be run to register or unregister a document. That just begs for problems. The help system should not assume anything about the viewing program. The viewer may not be a graphical program like Yelp or the KDE Help Center. It may be a print system, a console program, or some sort of documentation server. Documents should be able to supply meaningful metadata, which help viewers may be able to use. The metadata format for documents should be easily extended in a well-defined way. Applications should have a simple and consistent way of accessing their documentation, independent of the desktop environment. Documents should have a simple and consistent way of referencing other pieces of documentation, independent of the desktop environment. The help system should be capable of pulling information from other existing help systems. This way we can have legacy compatibility with KDE's and GNOME's current systems. Also, this can provide a consistent means for help viewers to integrate man and info, if they choose to. Put this before goals? Help System The framework for finding, navigating, showing and searching help. This usually includes a help browser, support for applications showing manuals and context help. Help Browser An application for browsing all help content which is available on the system. This usually includes showing a, possibly hierarchical list, of available documentation, facilitates to search all documentation and a view of the selected documentation. Document A self-contained piece of documentation. This can for example be an application manual, a single help page, a complete book or a website. Section A document may be made up of separate sections. These may be defined within the document or externally. For more details on this, please see the Additional Sections section of this document. The help system accesses the documentation by making use of meta data which accompanies the documentation. This meta data is provided at a standard location as files whose content is based on the desktop entry specification. The meta data contains information about the title of the document, where to find it, what type of format it is and to which categories it belongs. Based on this information help browsers can provide navigation, search and display of all documents known to the help system. The help system specification also introduces a common URI scheme to reference help. It uses the protocol "help:" and is based on unique identifiers of the documents described in the meta data. It is processed by the help system to access documentation, taking into account language settings and possibly other preferences of the user. This way applications can provide online help or context-specific help in a unified way. For making the help system aware of a certain piece of documentation it's enough to create the meta data file and put it at the appropriate location. This makes it easy for documentation creators to integrate their documentation into the help system and also provides a simple way to integrate third party documentation. More advanced features of help browsers like hierarchical displays of documents and their content or searching documentation can implemented in a generic way using the meta data information provided by the help system. The help system specification doesn't impose any policies or restrictions how help browsers should implement these kind of functionality. In order to provide the help system with the information where to find individual pieces of documentation and some more meta information, each document or Mallard section is accompanied with a file containing the meta data using the desktop entry specification (aka a "desktop file"). The desktop files contain some extended attributes specific to the help system. Individual documents or Mallard sections come with individual desktop files in order to make packaging easier and not requiring any post-installation processing. This section describes, how the meta data files are found by the help system, what specific entries they contain and how language-specifics are handled. The help system should read desktop files containing meta data from $XDG_DATA_DIRS/help/ using the XDG Base Directory Specification. This means files are looked up in a directory in the home directory of the user and one or more system-wide directories. If a file with the same name is found at multiple locations, the first one has to be used and the others are ignored. Subdirectories of $XDG_DATA_DIRS/help/ have to be scanned recursively to get all desktop files. As per the Base Directory Specification, if $XDG_DATA_DIRS is empty, a default search path of /usr/local/share/:/usr/share/ should be used. The filename of the desktop file consists of a basename and the ".desktop" suffix. The basename is the unique identifier for the document the desktop file is associated with, unless it is overwritten by a "DocIdentifier" entry in the file itself. Filenames have to be unique across the system in any case. As a special case for each subdirectory in $XDG_DATA_DIRS/help a desktop file with the name ".directory" can exist which describes the subdirectory. Subdirectories can be used as categories by the help system. Is a ".desktop" suffix wise? (Confusion with other .desktop entries). Maybe a ".help" suffix? Is ".directory" requires? We already scan subdirectories. Do we encourage people to place metadata files in subdirectories? (I'd prefer all entries to be in basedir. Otherwise each app will create its own subdirectory with 1 file in it etc.). Obviously I'm not clear on exactly what a .directory fil buys us. someone care to explain? From further reading it appears .directory files are used to create new categories for help browsers. Instead, I propose we stick to only the XDG menu spec categories. Otherwise, trouble ensues. The help system specification uses a couple of standard fields. They are described in the desktop entry specification. All entries below belong to the group header "Document". The "Required?" field states whether the key is required or option. If it is optional, sane defaults must be provided by the help system (identified in footnotes). Key Description Value Type Required? Name Title of document. localestring Yes Comment Short description of document. localestring NoDefaults to empty Icon Name of icon for document. string NoDefaults to empty In addition to the standard fields the metadata files uses a couple of extension to the desktop entry standard within this group which contain the meta data required by the help system. The keys of all help system specific entries in this group are prefixed with "Doc". Key Description Value Type Required? DocPath Location of document. In addition to the standard URI schemes like http: and file: the help system can support non-standard URI schemes to access specific kinds of documentation which aren't accessible by a standard URI. In particular the following non-standard URI schemes can be supported: help: KDE manual identified by app name, ghelp: GNOME manual identified by app name, man: man page, info: info page URI (locale-dependent) Yes DocType Mime type of document. string Yes Categories Categories the document belongs to. For possible values see the menu entry specification. Help browsers can base a hierarchical view on the categories. semi-colon separated strings Yes DocWeight 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 weight is 0. Negative values are legal. When assigning weights to documents it should be made sure that enough room is left to make it possible to put other documents before or after the documents. int NoDefaults to 0 DocIdentifier Unique identifier for document. Entries should be an R-DNS style, for example "org.gnome.user-guide" or "org.kde.konqueror". If this isn't present, it defaults to "org.other.<basename>" string YesMarking as required. See note at foot of table. DocSearchEnabledDefault If set to 'true' the document is searched by default, if set to 'false' it is not. This setting is overridden by user selected search scopes. bool NoDefaults to 'true' DocLang Language of document. The default language is English ("en"). language code NoDefaults to "en" DocHeritage The scrollkeeper seriesid, used for backwards compatibility. Sigh. If the document is new or does not have a current scrollkeeper seriesid, this field is not required. Should be of the R-DNS form "org.scrollkeeper.<seriesid>". string NoDefaults to empty DocIdentifier is marked as required. It does have a backup though - defaulting to "org.other.<basename>". Strongly encouraged at the least (from a GNOME perspective). All desktop file fields can be language-specific (e.g. "Name[fr]"). This is especially useful for the title and comment fields to provide translations of the meta data. It can also be used for the DocPath field, to reference translated versions of documents. An alternative to language-specific DocPath fields is to provide a separate desktop file for each translated version of the document. Which alternative is the best one is often determined by packaging requirements. Language-specific desktop files are read from $XDG_DATA_DIRS/help/LC, where LC is a two-letter ISO language code (TODO: reference language code specification). The files in language-specific directories are read according to the same rules as non-language-specific files. If there are multiple versions of the same document in different languages, there can be multiple desktop files with the same name. It is up to the help system to decide which file is to be used based on the preferences of the user. The help system can have a user-defined prioritized list of languages which is used to determine which is the best version of the document to show to the user. In addition to "full" documents described previously, a new document type is currently under development in GNOME, here it is refered to as "Mallard". In this, documents are seen as containers with each section having its own group header. These sections may either be specified within the document desktop file, or in their own desktop file. These section files are stored in the $XDG_DATA_DIRS/help (sub-)directories and have filenames consisting of a basename and the ".section" suffix. As before, the first entry found is used and subsequent entries are ignored. In the special case where a ".section" file defines a section already found in a document file and both files are in the same directory , the new section overloads the previously defined section. shaunm: It this correct? I get the feeling this would be the preferred way of doing this. The entries within sections belong to the "Section" group header and are described below. All entries are prefixed by "Section". Key Description Value Type Required? SectionName The title of the section localestring Yes SectionIdentifier The ID of the section for referencing within the document string Yes SectionDocument The parent document to which the section belong. This is in the form of the parent documents "DocIdentifier" in the R-DNS style described above. For subsections (or lower), the R-DNS must include the parent section path. E.g. "org.gnome.user-guide.CDBurning" would describe a section from the GNOME user guide that is a child of the "CDBurning" section. string Yes SectionPath The path to the file containing the section. This can be either relative to the parent document's path (if no full path is given) or an absolute file path URI Yes SectionChildren Any child sections the Section has. Each child must have a defined ".section" file or section within an already used desktop file. Child sections may be defined within the current file. If the child section entry cannot be found, it is discarded. semi-colon separated strings NoDefaults to empty The help standard doesn't imply any policy where the files containing the actual documentation are located. The only requirement is that the DocPath from the meta data files points to the right location. If the DocPath is a full URI, it is taken as it is. Absolute paths are promoted to "file:" URIs. To provide a standard location for documentation the help system specification defines a "help:" URI which is used to locate documents at standard locations. It is described in the help: URI section The help system has to be able to identify and reference help documents. This is needed for applications to provide manuals or context-sensitive help or to cross-link documents. It is also needed for locating documentation from within the desktop meta data files. Each document is uniquely identified by an identifier. The identifier is defined within the metadata file as the DocIdentifier entry. The identifier has to be unique on the system. If there are multiple language versions of a document all of them are identified by the same identifier. In the previous section, the DocIdentifier is described as required. I'm beginning to see that it may not be and building from filename might be a good idea. Though, this proves problematic with Mallard docs. The unique identifier is used within the help system to determine if duplication has occurred. If two metadata files have the same identifier, the later one is discarded. In the special case of two metadata files in the same directory sharing an identifier, the behavior is undefined (the first found by the help system will be used). To reference a document or a specific location inside a document the "help:" URI is used. It has two parts, the identifier and an optional anchor part (e.g. "help:gimp" or "help:konqueror#settings"). Help URIs can be used in the DocPath in a meta data desktop file to locate the actual document for a given identifier. For a given identifier provided by a help URI, the document is looked up by searching for the directory $XDG_DATA_DIRS/help/$lang/$identifier/, where $lang is a two-letter ISO language code. The help browser determines which language code to use based on the preferences of the user. The classic $lang/$identifier / $identifier/$lang debate occurs here. Anyone want to comment...? The first document instance found in the search path is taken. Other directories are ignored. Documents in the home directory of the user take precedence over system-wide directories as specified by the XDG Directory Base Standard. In the directory the help system looks for the file "index.html". If this doesn't exist it looks for "index.docbook". If this doesn't exist, it looks for "$identifier.xml". The found file is shown as the document corresponding to the help URI. If the help URI includes an anchor part, it refers to a specific location in the document. If the document is HTML, the # refers to a standard HTML lookup. If it's Docbook, the # refers to the blockid and the help browser needs to display that blockid. For other documentation type, this anchor refers to the "section" of the document (as defined by the document type) and must be honoured. If the help browser displays the docbook file as multiple pages, it must display the page containing the given blockid and should scroll to the given block. If no files are found for a given help URI, the help system must look up the meta data file associated with the identifier and look up the help based on its DocPath entry. If the desktop file isn't found or the DocPath contains a help: URI with the same identifier as the one being looked up, the browser should treat this as a "document not found" error condition. Searching is left to the help browser. It should use the meta information provided by the desktop files. Search results should contain help URIs to reference the documents or the parts of documents where the search terms were found. The DocSearchType entry in the desktop file should be used to determine which algorithm is used to perform the search. If a document is searched by default or only on explicit request by the user is controlled by the DocSearchEnabledDefault entry in the meta data desktop file. Currently, GNOME help searching relies on either Beagle or its own XML search, neither of which respect DocSearchEnabledDefault or equivalent. The basic search goal in both cases is "If it's there, search it". The XML search could be adapted, but what about the Beagle case? Does KDE use a desktop search framework? How would that fit in? Most help browsers provide a hierarchical view on all documentation present on the system. The meta data gives some information how to do this by providing categories via the Categories entry in the desktop file. For possible category values see the menu entry specification A help browser can make use of a menu description files specified by the Menu Specification to describe the hierarchy of the shown documentation. This section (at least, the second paragraph) is dangerously close to enforcing policy on the Help Browser. Is this entire section necessary? It's up to Help Browsers what to do with the information provided - how to display it etc. I'd be in favor of removing this section entirely. Application usually contain a menu entry for invoking the help browser. They should pass the help URI to the desktop-specific help system. If a desktop environment provides a help browser it has to provide a program "xdg_help" in the binary search path which starts the help browser. The program has to take a help: URI as argument and must show the corresponding document or part of document when invoked. Add a little saying that the "xdg_help" should actually be a symlink to the true help browser? Or is that implied? This appendix gives examples of metadata desktop files for use within the help system. A basic docbook desktop file with German translation (with apologies for the translation). # Beanstalk manual description [Document] Name=The Beanstalk Manual Name[de]=Das Bohnenstange-Handbuch Comment=Jack likes beanstalks. With this manual, you too can grow you're own beanstalk. Who knows, you may even find a golden egg or two! Comment[de]=Jack mag Bohnenstangen. Mit diesem Handbuch kannst du dich wachsen auch sollst Bohnenstange besitzen. Wer weiß, kannst du ein goldenes Ei oder zwei sogar finden! DocPath=file://usr/share/help/C/beanstalk/beanstalk.xml DocPath[de]=file://usr/share/help/de/beanstalk/beanstalk.xml DocType=application/docbook+xml Categories=GNOME;Building;Construction DocIdentifier=org.gnome.beanstalk # Displaces a document previously registered with scrollkeeper DocHeritage=org.scrollkeeper.2a958241-f90e-4aca-a201-cc5d21b7b6ce Another manual (with different keys), installed as a pdf. No translations. [Document] # Glermo's proprietary app. Installed as a pdf to stop thieving. # Comments are lines that begin with a '#' symbol. Name=Glermo's Magic Beanstalk Recipes Comment=Tired of the semi-finished Beanstalk from Jack? With Gelrmo, you don't need to worry, we're already finished! #TODO: Does the icon need to be path based or named icons only? (Or both?) Icon=glermo-beanstalk # Installed in a standard location described previously DocPath=help:glermo DocType=application/pdf # We want to be first on the list, dag nabbit DocWeight=-50 Categories=Construction DocIdentifier=org.other.glermo # We don't want to be searched. Glermo doesn't like being searched at # airports. Glermo's slightly strange like that. DocSearchEnabledDefault=false In this section, one Mallard "document" is described - "GNOME User Guide", comprising of 2 sections - "Desktop Tools" and "CD Burning". The "CD Burning" section also has one child - "DVD Burning". I'll forgo you the agony of my translations. # First the document. This would be user-guide.desktop or user-guide.help [Document] Name=GNOME User Guide Comment=Learn how to use you're GNOME desktop # DocPath actually describes the path containing the document # components (in the first instance) DocPath=file://usr/share/gnome/help/user-guide/C # Made up mime type. Do we need to define a mime type for Mallard docs? DocType=application/mallard+xml Categories=GNOME # We really want to be listed first. For real reasons this time, # not just vanity DocWeight=-5 DocIdentifier=org.gnome.user-guide # Define one section [Section] SectionName=Desktop Tools # Don't give a path. This will autogamically find the file as # /usr/share/gnome/help/user-guide/C/desktop-tools.xml # From above SectionPath=desktop-tools.xml SectionIdentifier=desktoptools # Don't need to define section document as we're defined in the parent # docs metadata file # Now we define the second section [Section] SectionName=CD Burning SectionPath=cdburning.xml SectionIdentifier=cdburning In the same directory, someone else has defined a new section file, defining a new "CD Burning" section. This new section contains a new subsection - "DVD Burning". This new version will overwrite the section defined above. # The new CD Burning section. This would be the file cdburning.section [Section] SectionName=Burning Media SectionIdentifier=cdburning SectionDocument=org.gnome.user-guide # Sections defined outside the main document metadata file # almost certianly want to define the location with an absolute path SectionPath=file://tmp/testing/cdburning.xml SectionChildren=dvdburning # Define the dvd burning section here as well SectionName=Burning a DVD SectionIdentifier=dvdburning # Not strictly necessary as we already know the parent (above), but it won't # hurt to define it anyway SectionPath=file://tmp/testing/dvdburning.xml # Parent is the CD Burning section. Add that to the Document ID as below SectionDocument=org.gnome.user-guide.cdburning In order to cut down on duplicate effort, and to aid interoperability, it is proposed that KDE and GNOME work together to create a common library for metadata access. This library would scan all metadata files, build an internal list of available documents and provide access to this information through an API suitable for needsAPI discussion would need to take place. Nothing has been decided on the shape of the API yet.. A (simplified) workflow for constructing the internal list of available documents would be: Get the $XDG_DATA_DIRS environment variable. If empty, default to static list of directories For each directory found above: Find all .section files. Read and parse them. Any duplication can be discarded. Any sections without a current owner create a new document (to be filled). Find all .desktop / .help files. Read and parse them. Any duplication can be discarded. Repeat for each subdirectory within current directory. For each available document, ensure complete information is available - title, docpath, identifier. Any incomplete entries are discarded (with a printed warning?). The above is currently incomplete as .directory entries are ignored. Are these needed? How would they be used properly? This section is pretty empty. Are people interested in creating the library? What needs to be included? Or, should the functionality be within the help browser? Personally, I think a library is the way to go. We're all doing the same thing with the files, why not split the functionality out into a common library and cut down on duplication? It also encourages easier development for other help browsers. In order to fulfill on of the aims of this spec, backward compatibility with current metadata systems must be provided. Here, the upgrade path for this is discussed. I have no experience with KDE metadata system. I don't believe it uses scrollkeeper. Can someone comment / add necessary info here? Currently, metadata access is provided through "scrollkeeper". The metadata format is XML and requires registration at install time. In order to transition invisibly (to the user) to the proposed system, two utilities must be provided: Migration Script Responsible for translating existing "omf" files across to the new desktop file format described in this spec. This would ideally be done during the installation step of the compatibility program. Registration Script This would replace the current "scrollkeeper-update" script, which searches through the /usr/share/omf directory looking for new omf files and adding them to the scrollkeeper database. Instead, this script would scan through, find new files and translate them to .desktop files. There is a prototype of the "migration" script available as part of the "Spoon" package.