Hi, I'll preface all the comments by stating that the spec was originally written by others. My meagre contribution amounted to adding the "Additional Sections" (section 5.4), the examples and "Joint System Proposal", the many notes scattered throughout and correcting any glaring spelling mistakes. This has the advantage of shifting the blame away from me :) It will also explain why my comments are what they are.
On Tue, 2006-10-31 at 21:31 +0100, Frans Englich wrote: > On Tuesday 31 October 2006 16:51, Don Scorgie wrote: > > As you know, this is interesting and needed work. :) > > OSDL has also been looking into improving documentation interoperability. > Perhaps these two projects should be merged so we can solve two problems in > one blow. Here's some background(see comments for IRC log, and links): > > http://englich.wordpress.com/2006/10/17/open-source-documentation-framework/ > > > A little while ago, Cornelius Schumacher sent me an old draft of a spec > > for a joint help system between GNOME and KDE. Since then, I've been > > looking through, adapting it slightly and adding various bits needed by > > GNOME [1]. > > > > I feel its in something approaching a decent state (well, enough for > > people to look over and comment on), so I'm not attaching it to this > > email. Instead, you can get it from [2]. It's in docbook format, so > > you can view it in you're favourite help browser at you're leisure. > > Attached is a XHTML rendering for those not into Docbook(extract with > bunzip2). > > > You will notice a lot of Note boxes within the file. In these cases, > > they're where I wasn't sure about something, wanted to add some thoughts > > (but didn't seem to fit properly) or I got bored and wrote garbage ;) > > > > Hopefully, this won't disappear into the ether and instead something > > will come of it. Any feedback and comments much appreciated. > > I did one quick read-through and here's my quick comments(will send separate > mails). > > According to my opinion the spec is in general vague and have editorial > issues(about one on average in each paragraph), as typical for Free Desktop > specifications. But that's quite expected considering it's early in the > development process. So, it will need a rewrite when that time comes. Yep, early draft. > > > A significant size of the spec is spent on a mapping/URI-resolver > system(which > I don't fully get yet). My initial reaction is that it would be a gigantic > improvement to use OASIS XML Catalogs here: > > 1. Installed catalogs would be registered with the help system > 2. The help system computes an URI that identifies the topic of interest > 3. The help system resolves this URI through the catalogs for a URI to > dereference for a physical resource for user consumption. > > It would re-use a powerful, generic, implemented, well-spec'd mechanism that > provides all one needs for mapping URIs. My personal opinion is that user-facing XML sucks. The files are intended to be edited by doc writers. Doc writers already deal with docbook / XML. We shouldn't lumping more on them (especially when the XML flavour is different). Just my personal opinion. In addition, the other freedesktop specs use the keyfile format (.desktop files for example). We should remain consistent. > It's not defined why DocSearchEnabledDefault should be used, so it's > unusable > as is. That is, can the user use that key without taking a particular > implementation into account? Doesn't look like so from my reading. > > My gut feeling is that it should be left out. Either that, or > define "searching". Something I wouldn't like to do ;-) > > Here the problems with that Desktop files didn't re-use XML shines > through: > with XML it would be possible to specify custom keys in an > interoperable way. > For example, search hints for a specific implementation could be > supplied. Yep. I was pretty blurry on what exactly this did. Again, my personal opinion is that any searching should search anything it can (and allow the user to reduce the search criteria as desired). I think the DocSearchEnabledDefault should be left out. We do have hints for how search should be done - the mime type (DocType). It's up to the help app to determine if it can search that doc type. > The specification use URI schemes(it doesn't define what they mean or > should > be treated, so in either case it needs to be rewritten) that aren't > valid, > which in my opinion is a no go. > > For example, the "help" scheme is not registered, and there's nothing > that > prevents me from writing a spec after I've finished this mail that > defines "help" in another way. For a discussion of this problem, > see(especially the comments are useful): > > http://englich.wordpress.com/2006/10/13/kdes-uris/ > > I see here an opportunity to break KDE's trend of using proprietary > schemes. I > think this is especially important in this case since it is the > intention of > the help system to be interoperable. > > I think fixing this is easy. Since it's not required that the URIs > must be > exposed to users, they can read in anyway. Currently, we (GNOME) use ghelp: for our URI [1](which is used to find the document within our current metadata framework). The "help:" uri is intended to provide a default location for help files within the metadata file. This is one of the areas I considered removing. The gratuitous use of custom URI's is bad (IMO). I came up with several other objections (about installing the help file in a non-standard location. In which case, any metadata with help: uri is going to break), but in the end, decided to leave it in for now. Another point I'd be glad to remove. Thanks Don [1] E.g calling 'yelp ghelp:zenity' from the command line will search scrollkeeper for the document who's filename is 'zenity.xml' _______________________________________________ xdg mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/xdg
