I'm not sure how many people saw this post to desktop-devel-list, but I'm sure folks here will be interested. Greg
--- Begin Message ---
- From: Shaun McCance <shaunm wolfram com>
- To: desktop-devel-list gnome org
- Subject: Re: GNOME ABI review
- Date: 07 Aug 2003 11:27:45 -0500
On Wed, 2003-08-06 at 23:34, Havoc Pennington wrote: > 9. Online Help > > How do you install it and how do you display it? > Needs to be well-specified, well-documented, and kept working. This is something that I've been thinking about a lot over the last few weeks. ScrollKeeper is a nice start, but it suffers quite a bit from First System Syndrome. Here's my thoughts: Interoperability with KDE and other desktops is a MUST. Third-party application developers will want to stick their documentation somewhere and have it viewable regardless of your desktop environment. If they have to jump through hoops to make their documentation work, then they probably just won't do it. Consequently, this whole discussion should probably take place on freedesktop.org. Using OMF files is a Good Thing. Having to register them manually with the system is a bit questionable. It just begs for inconsistencies and difficult upgrade paths. It places more work on application developers and packagers. It makes it nearly impossible to provide alternative implementations of the help system. What are the reasons for registering? Well, first of all, ScrollKeeper generates a listing of all documentation on the system organized by category. I don't think it's necessary to generate a static category listing. Things like VFolers and the new Menu spec are figured out on the fly. More on this later. Also, ScrollKeeper generates a couple of utility files for the document, including a TOC and and index. However, it only knows how to make them for DocBook. So if a help browser supports some other format, and it wants to have a TOC, it has to implement it itself. Furthermore, the TOCs are problematic, because a help browser should have some degree of choice in how it presents documents to the user. I've had plenty of problems with changing certain behaviors in Yelp because I have to rely on these static TOC files. (And, in fact, there are actually a number of inconsistencies between Yelp's chunking and ScrollKeeper's TOCs that I just couldn't get around.) It turns out that TOCs are incredibly simple to construct. I've been working on some code that generates them with SAX, and it's pretty much instantaneous for incredibly large docs (like Gnumeric's). A more difficult issue is the index. If it's just a matter of getting and index for a single document, there's not much of an issue. An index can also be generated with SAX at parse-time very quickly. However, it would certainly be nice to have a master index of all docs installed on the system. I don't have a solution here just yet. Back to the category thing. ScrollKeeper adds the category attribute to the subject element of OMF. This is a heirarchy of pre-set categories. I'm not too fond of this. For one thing, the category names are made specific to KDE and GNOME. So I won't see the documentation for KDE programs in Yelp. But if I'm a GNOME user, but I use KMail, I would certainly like to see the KMail documentation in my help browser. A possible solution is to use the Menu spec. The category attribute could be changed to provide a space-separated list of categories as defined by the Menu spec. Then the menu files could construct the heirarchy for help files the same way they do for applications. This takes the actual heirarchy (an implementation detail, IMO) out of the OMF files. URLs are infinately problematic in our current system. First of all, the ghelp URL scheme is massive ad-hockery. If a URL scheme is needed at all, an intelligent one should be thought up and used by both KDE and GNOME. And it should be registered. But I don't think we need to do that. The OMF files can provide any number of alternative URLs for a particular document. Thus, documents should be able to be identified by a definitive URL (probably an http: URL), but then accessed by another URL (probably a file: URL). This would also help immensely in building documents for the web. A number of the GNOME docs have a ulink that points to ghelp:fdl. This works in Yelp, but fails miserably when HTML files are generated for the web. If a robust help system could be agreed upon by the different desktop environments, then GNOME could get rid of the X-GNOME-DocPath extension to .dekstop files, and KDE could get rid of the X-KDE-DocPath extension, and a single DocPath key could be defined that will actually work. A standard mechanism of providing rendering hints to the help browser would be nice. In my experience, it's pretty much impossible to do a documentation build system that produces perfect output without manual tweaking. For instance, Yelp's chunking rules are rather sub-optimal for quite a few documents. A set of standard PIs would probably do the trick quite nicely. Hints, of course, should just be just that. A help browser should be able to display a document reasonably well without the hints, and a document shouldn't rely on the help browser understanding its hints. Along similar lines, it would certainly be nice to provide generic XML support. DocBook is a nice format, but we shouldn't try to force every piece of documentation into it. If authors would like to use some other format, it should be possible to do so. Documentation in an arbitrary XML format could ship with some default CSS. Thus, if a help browser has no inherant knowledge of a particular XML format, it can fall back to the stylesheet shipped with the documentation. Of course, this would require us to have a generalized XML rendering component (GRE). I probably have more things to say on the subject, but I can't remember them at the moment. -- Shaun _______________________________________________ desktop-devel-list mailing list desktop-devel-list gnome org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
--- End Message ---
Attachment:
signature.asc
Description: This is a digitally signed message part