It is still under construction and content may change. Do not rely on the information on this page.
Over the past few months, there has been considerable discussion over the display of documentation on the desktop, and the delivery of that content. This page is intended to capture some of the presentation options; delivery is a separate issue.
Yelp
Currently, the Release Notes and About Fedora are displayed using Yelp and are delivered together in a single package. The user selects Help from the System menu and a window opens showing the title and short description of a number of topics including the Release Notes and About Fedora. Depending on what applications the user has installed, there may be other topics displayed.
Clicking on a title opens the document in the same window in an html-like fashion.
Both the opening screen and the document are displayed in the language chosen by the user at logon time.
Characteristics of Yelp
Yelp is a straightforward, easy to use model. Fedora Project provided documentation is integrated with other help in a very user friendly fashion. Presentation of all documents is consistent. Yelp is relatively slow, performance deteriorating rapidly with document size.
Requirements for Yelp
Yelp documents are in XML. Publican-produced XML is perfectly adequate. Each language requires an "omf" file to connect the language to the appropriate document. Local language content of the omf is taken entirely from the Publican strings, so no additiona translation is required. See Example OMF for an example.
Advantages
- Fedora documents are found in Help, alongside Gnome documents, where the user can easily find them
- Yelp handles rendering, so there are no issues with style sheets, branding, etc,
- We have long experience with yelp so there are few surprises
- User automatically gets the document in his local language if it is available
Disadvantages
- Yelp has some size limitations. At this time it is not entirely clear whether this is a limitation on some specific item such as index entries or an absolute document size limitation
- Since yelp handles rendering, there is no control over document style
- Yelp does not produce document indices when requested
- Yelp can be slow. For larger documents, very slow. Breaking the document into multiple files does not help.
- Yelp does not display the Publican-produced revision history
- Publican cannot currently package multiple languages, and at this time, it appears it will not address yelp packaging in the future.
- Yelp addresses only Gnome and does not help other desktops
Possible Improvements to Yelp
- Fork Publican to provide useable packaging
- Integrate with khelpcenter
- Repair limitations/bugs