Re: Comments on Help System Spec and Spoon

[Don Scorgie <DonScorgie Blueyonder co uk>]

Hey,

Thanks for the comments.  I'll do my best to respond.

On Wed, 2006-11-29 at 17:21 +0100, karderio wrote:
> Hi :o)
> 
> I read the Help System Spec and checked out Spoon last night - I must
> say this all seems most excellent ! Can't wait : great ideas, and if the
> implementation finally resembles all that is suggested on the wiki, you
> may just have built the world's best software help system !
> 
> One idea - when it says "Documents should have a simple and consistent
> way of referencing other pieces of documentation, independent of the
> desktop environment." could this not be independent of the presence of
> said document on the system also - say provide a web address in case the
> doc is missing for example ? Thus, in a doc we can reference other
> documentation, regardless of it's presence or not, or conversely, we can
> reference a doc on the web, but use the local copy if one exists. I'm
> not sure how this could be implemented, perhaps you would need a web
> service that could be called with a docs id, if a doc is missing.

Spoon (and the help spec) provides a simple and transparent way of
referencing documentation, regardless of whether the file is local or
not.  If the "DocPath" element is a URI (i.e. beginning http:, file:,
smb: or anything else), it is taken as-is.  If the DocPath is a file
location (i.e. anything else), it is promoted to file://<path>.  There
are no fallback methods as this could (and probably would) be viewed as
overkill.

> 
> What type of documentation is covered by the doc system ? Maybe a
> specific domain should be given in the introduction. Can the doc system
> be used to document domestic appliances, or is if for software only ? Is
> it for GUI software only, or can it be for the command line also ?

The meta data system shouldn't concern itself with what format the help
files take.  It should probably be whittled down slightly to remove the
possibility of using domestic applicances, however, if hoover want
vacuum cleaner manuals to be available through yelp, I see no reason to
exclude them ;)  Spoon should allow any program (command-line based or
GUI) to access it's info.  It doesn't depend on any external libraries.

> 
> Could the build system have an option to provide a manpage if a project
> is missing one ? It could be a simple explanation of where to find the
> actual documentation for example, or even the complete documentation
> itself. Some distributions insist on a manpage for inclusion, and some
> people are used to typing "man [command]". Also this would ease
> accessing the documentation from the command line. Perhaps this
> documentation system could supersede man pages and info pages, by
> providing a nice terminal based interface. If this interface supported
> both "mallard", info and man, it could replace the man and info
> commands, and add a new command "help". I realise this is out of the
> specs scope, I'm just getting carried away with the possibilities of
> this thing !

:)  Generation of man pages is well outside the scope of the project.
However, creating a man / info / other command line viewer should be
possible (but not planned).  The Spoon API is pretty limited right now
(to ~ 1 useful call) however, the next task is to extend that somewhat
(including a for_each_doc_type type function that would be passed a mime
type and perform a specified function for each doc found with that mime
type).  Right now, man and info pages aren't included in Spoon
initialisation, though the may be added at some point (which would make
Spoon pretty cool in that regard and remove a huge chunk of yelp code).

> 
> I'm worried that the fact that meta data being stored in a specific
> place could pose permission problems. What if we don't have permission
> to put our scroll in that directory ? Currently, AFAICS, if I install a
> GNOME app, I must install it's help in a specific directory for the app
> to be able to display it. Perhaps I'm missing something, but it seems
> that if you do not have root privileges, an app *can't display it's
> help*. I have a piece of software where I recommend to users to install
> it in their ~/.local directory, but have to explain to them how to place
> symlinks so the docs will work... I hope I'm wrong about all this ;)

Spoon uses XDG_DATA_DIRS and XDG_DATA_HOME to find scrolls.  Scrolls in
XDG_DATA_HOME (Typically $HOME/.local/share/help) will take precedence
over other scrolls.  This is one of the (many) things I disliked about
scrollkeeper and one of the things I wanted to fix in Spoon.

This means, you don't need root permission to install help files.
Either adjust $XDG_DATA_DIRS to include the installed directory, or use
$XDG_DATA_HOME.

> 
> When invoking the help browser, the spec says "Both methods are
> asynchronous and are not expected to return anything." I would argue
> that these methods should at least return weather the help has been
> properly displayed or not, in order that we may show an error message to
> the user if the help wasn't found or some other problem. I think this is
> important, even in the best of current systems a file can get deleted or
> become corrupt. There was a blog entry dicussing a similar theme
> recently on planet GNOME [1], I rather agree with the author. Comment
> [2] contains a practical example of actual code, for which not having a
> return value would cause problems, if you like.

There are 2 routes here:
a) The calls are synchronous and return a value (True / False).  In this
case, it is up to the application to show the warning dialog.
b) As described in the spec (asynchronous, no return).  In this case,
the browser is launched and if finding the doc fails, the help browser
displays the warning.

I chose (b) as 1) It reduced the number of strings that need to be
translated (instead of 2 strings per app which are basically the same,
only 2 strings in yelp need be translated) and 2) It is more consistent
(i.e. all the error messages will be the same, no matter what program
launched the help browser).

> 
> Apart from that, I find everything just fabulous ! One phantasmagorical
> idea that came to mind while writing this would be some sort of
> Document-O-Sphere - a central place one could come to when looking for
> documentation, as if one were consulting the Wikipedia, with a universal
> unique way of identifying documentation. This would of course concern
> other things than software documentation. It would permit things like
> just printing the document identifier on say, your new computer
> keyboard : you would go to the Document-O-Sphere with this identifier
> end get the docs, which are shown in your default documentation browser,
> saving on paper/disks and guaranteeing up-to date documentation. Such a
> thing could be based on a centralised, distributed or peer to peer
> model. I'd be happy to throw ideas in a pile if anybody thinks the
> concept is worth exploring.

Okay, that's probably a little further down the road.  Maybe get our
various (GNOME) projects (ProjectMallard, lib.g.o, Pulse,
CodenameGraphite, FoieGras and Spoon) up and running properly first and
then maybe we can consider World Domination [1].

Thanks
Don

[1] Although, I have been planning Project World Domination for some
time.  Its a 7 stage plan.  I think I'm onto stage 3 atm.  Stage 4 is
the really tricky part, which randomly involves sheep.  Until stage 3 is
complete, there's no use in contemplating Stage 4.