On Saturday 25 November 2006 17:39, Don Scorgie wrote: > > I've put up a new version (0.2) for viewing / download at: > (html) > http://www.gnome.org/~dscorgie/help-spec-0-2.html > > (docbook xml) > http://www.gnome.org/~dscorgie/help-spec-0.2.xml
This already looks quite good. It seems we are finally getting somewhere :-). So despite being late I still wanted to make some comments. > * Removed .directory files Arranging documentation meta files in a directory hierarchy is a simple way to structure documentation. For this to work we need the .directory files, so that the directories can be given user-visible titles which can be shown in the help browser. There are other ways to specify hierarchies like the menu spec, but they are much more complex, so I think it would be good to leave the .directory files in the help spec as an easy way to allow a structured view to the documentation. The help browser still can ignore this information, if it uses a more advanced way for creating a hierarchical display or only offers a flat view on the documentation. > * Added new chunks about how to invoke the help browser (+ examples) > (Preferably through dbus, with alternative) I like the idea of providing a D-Bus API. This seems to be a good way to specify a standard way of calling the help system without the overhead of going through a command line tool. One question, though: Is D-Bus able to start the help browser on demand when a call is made to the API or is it needed that the help browser is already running (providing it is the help browser implementing the API)? What about adding a call "open_browser", which would open the help browser without showing a specific document, but with a generic start page? The open_browser call could also get a DocIdentifier as optional argument, so that it could open the browser and show the corresponding document. For some help browsers this might be identical to open_document, but for browsers which e.g. show a navigation panel it might make a difference (e.g. open_document only showing the document but not the navigation panel and open_browser showing both). What's the use case for the close_document call? Wouldn't it be up to the user to close the help window? Maybe it's a lack of my phantasy but I can't imagine a situation where an application wanted to close a help window programmatically. > * Remove the help: URI section. It causes confusion and is inextensible > (installing a package in /opt with the docpath defined as help:<file> > would point to the wrong place) One purpose of the help: URIs is to specify a standard location for documentation files. While it should be possible to install documentation to other locations it still would be nice to have a standard location, so that the location where files are installed is not completely arbitrary. To make a separate spec for this purpose would probably be overkill, so I think it would be nice to keep this in the help system spec. Isn't the extensibility aspect taken care of by using $XDG_DATA_DIRS? When installing a package to a non-standard location, several paths have to be adjusted anyway, so that binaries, man pages etc. can be found, so in the example if the corresponding directory under /opt is included in the XDG_DATA_DIRS variable the help URI would still work. The help: URIs also address the problem of translated documentation. With the help URIs it's sufficient to provide one meta file with one DocPath for all translated versions of a manual. Without the help: URIs you need to put the exact path into the metafile which means that you either have to supply a meta file per translation or to put DocPaths for all languages in the meta file. Both means adding a lot of at least partly redundant information. This has several problems, e.g. the increased danger of having inconsistent data or slow parsing of the meta data. Finally the help: URI scheme provides a solution for addressing a specific part of a document by using appropriate anchors. This is needed for example when a dialog has a help button and pressing on the button has to show up the section of the manual which is describing the dialog. So, all in all, I think we still need the help: URIs in the spec. Some other comments: I think it's preferable to use the suffix ".desktop" for the meta files instead of ".document". The meta files are valid .desktop files and adhere to the desktop entry specification, so it seems to be logical to use the suffix which is specified there. The help system meta files are more an extended version of the desktop files than a new file type. Another reason to use the .desktop suffix is that normal desktop files which for example are used for creating the start menu could additionally also contain the information for the help system, so the meta information for application manuals for the help system could be extracted from the same files without the need to duplicate any data. As the DocHeritage entry is only used for backwards compatibility it might be better to leave it out from the specification. It still could be used e.g. as X-Scrollkeeper-DocHeritage by help browsers which previously used Scrollkeeper. In the section about language-specific documentation there is the use of an environment variable $LANGUAGE mentioned. How exactly is this meant to work? Wouldn't it be better to leave that out of the specification and leave it to the help system implementation to determine what languages the user wants to see? I suppose this setting would end up in a configuration dialog of the help browser anyway. So using environment variables might be a bit cumbersome. -- Cornelius Schumacher <[EMAIL PROTECTED]> _______________________________________________ xdg mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/xdg
