Yelp

Yelp is the help viewer in Gnome. It's what happens when you hit F1. Together with gnome-doc-utils, Yelp serves as a DocBook viewer, a man page viewer, and an info page viewer. This page serves as a development workspace for Yelp and gnome-doc-utils. For the content that goes into Yelp, see the GNOME DocumentationProject.

Bug Squad

See our bug lists

Notes for yelp:

Crashes should always have Severity set to critical.
Portability issues should always have Priority set to Urgent and have the keyword 'portability'.
The 'Help converters' and 'stylesheets' components are deprecated.

Notes for gnome-doc-utils:

Portability issues should always have Priority set to Urgent and have the keyword 'portability'.
Portability issues in the build utilities should also have Severity set to blocker.
Anything that causes 'make distcheck' to fail should have Severity set to blocker.
Just to emphasize the above two points: gnome-doc-utils contains build utilities that are used by lots of other packages. Failures in the build utilities mean build failures in other packages. Therefore, these are very serious problems, and they need to be addressed as quickly as possible.
Although xml2po is maintained in gnome-doc-utils, it has a separate product in bugzilla. Please move xml2po bugs to the xml2po product.

Shaun is notoriously bad at watching bugzilla. Do feel free to nag him on IRC about outstanding patches.

Scrollkeeper Patches

Note:Scrollkeeper is dead. Rejoice. However, if you prefer to use scrollkeeper, you'll need thee patches:

Patch one:http://bugzilla.gnome.org/attachment.cgi?id=69293

Patch two:http://bugzilla.gnome.org/attachment.cgi?id=69294

Patch three:http://bugzilla.gnome.org/attachment.cgi?id=69295

These fix various array bounding checks. They can be applied to the scrollkeeper source directory by changing directory into it (from the terminal) and running the commnad:

patch -p1 < FILENAME

for each patch file. Rebuild scrollkeeper and install should allow yelp to function correctly. If you are still having trouble, please file a bug.

Hackers

There are many tasks in Yelp and gnome-doc-utils (and the rest of the GNOME documentation project) that are up for grabs. If you're interested in any of these, or anything else, either drop by irc.gimp.org #docs or send an email to gnome-doc-devel@gnome.org and let us know. We'll be happy to help you get started.

A little note about the IRC channel: We are spread around the world and often do not appear to respond immediately. If you do come in past and speak to us, but get no answer, leave a message and we will check the logs (hint: leaving an email address or sending an email to the list will get you a response)

Yelp Tasks (as of 2.21)

General

The deep history framework is very basic just now. Some tasks include
- For now, the title of the entry is the window title. This isn't ideal. Instead, there is should be (and probably is) a method of getting the frag title from the pager. This should be hooked up and made to work properly
- There is / was a request that different types of entry (man page, info page, html etc.) should have a little icon to show which type of doc it is
  - This also applies to bookmark entries
Clean up dead code
- There have been lots of changes of late to yelp. This may have left dead code paths / files around. Finding them and eliminating them would be great
- With the new pager system integrated, this applies even more now.
Improve the debugging stuff
- A new debugging infrastructure has been added. There are several places where this isn't being used well (printing, searching, info pages at least). Add in proper debugging calls at appropriate points. Pretty much everywhere now.
Improve the dbus stuff
- Yelp now uses dbus based activation. This provides many advantages
- One is that we should be able to offer external signals for apps to load a help page via dbus
- Similarly, when yelp isn't running, the dbus signal should activate yelp and show the desired page
Improve performance
- Yelp should load as near to instantly as possible. It should display pages as quickly as possible
- Profile the code, find any bottlenecks and work around them
Add a finalize handler to YelpWindow (gnomebug:140632)

Brain-dumping:

Make reload not suck (ctrl - r) (also applies to forward and back history)
Make yelp document-orientated
- Make search do in-current-document by default (when a document is loaded) and add a "search all documentation" link to the results / somehow
- Make the "Home" icon go to the index of the loaded document (when opened explicitely via an app) and add a new "Go to TOC" menu option
Rework the TOC into something spectacularly pretty. Use new fd.o categorisations from rarian

Printing

Yelp has now moved to Gtk printing (instead of libgnomeprint). This has caused some problems. There are also some long standing requests

Settings arn't saved between instances
Printed manuals need work on the stylesheets to improve printing
- This has improved substantially with 2.19 however still needs work
- This will require work within gnome-doc-utils

Man Pages

Man pages are now on by default. We do a good job an lots of man pages, but some suck rather badly.

Pick a man page on you're system
Load it in yelp and man programs
Compare
Fix yelp output

I started some work on a new parser, based on groff markup codes in bug #477788. Either make our system better or work on that.

Info Pages

There are still some issues with info pages. Not entirely sure where they are any more, but you should be able to find them. In addition, it'd be really, really sweet if we had a yelp-info-print pager that could bind all the sections together and allow printing the entire document as one.

Other

There are many other tasks, big and small, that could be undertaken in a wide variety of different areas. If you want to know more, or if you want to work on something in particular, let us know and we'll try and help you out.

Project Mallard

Project Mallard is the code-name for a new help system currently being planned. The main page can be found at ProjectMallard. It has many facets (mmm. Lovely word) to it, so if you want to help out on any of the aspects of it, give us a shout and we can point you in the right direction.

New API

The new API has now been integrated into head. This gives a generic overview of how it works (although, I don't know how up to date it is)

The YelpPager API that's in Yelp right now was my first attempt at modularizing the transformations and getting logic outside of YelpWindow. It suffers from a few problems, though:

It's needlessly complex. Windows have to check states, watch page emissions, etc.
It assumes a single transformation run on a document. This makes it hard to do on-demand page loads.
Pages are always returns as strings, making potential implementations of some document types sub-optimal.
Pagers have no idea what's watching which pages, making it hard to clean up resources.

The following summarizes a new API I'm working on, the YelpDocument. Documents are simple opaque objects that returns pages via callback functions. Nothing outside the document ever needs to know about transformation status.

YelpWindow
- YelpWindow::new_window_requested (YelpWindow *window, gchar *uri)
- yelp_window_load (YelpWindow *window, gchar *uri)

YelpDocument

This is the replacement for YelpPager. Instead of checking the state of a pager and watching page emissions, YelpWindow will just be able to grab a document and ask for a page, providing a page load callback function. The callback is then called whenever the page is ready, possibly immediately.
The class itself is abstract. All the real work will be done by subclasses like YelpDBDocument, YelpManDocument, and YelpInfoDocument.

yelp_document_get_page requests a page. It takes callback functions for page loading, page title loading, and error handling. It returns a request ID, which can be used by yelp_document_cancel_get to cancel the request.

gint
yelp_document_get_page (YelpDocument     *document,
                        const gchar      *page_id,
                        YelpPageLoadFunc  page_func,
                        YelpPageTitleFunc title_func,
                        YelpPageErrorFunc error_func,
                        gpointer          user_data);

yelp_document_cancel_get cancels a page request. Page requests are persistent. As long as window is viewing a page, it should have an open request. If the underlying document does a refresh, it need only call the page load function.
```
void
yelp_document_cancel_get (YelpDocument *document,
                          gint          req_id);
```

The callback functions:

void
(*YelpPageLoadFunc)  (YelpDocument *document,
                      gint          req_id,
                      const gchar  *page_id,
                      YelpPage     *page,
                      gpointer      user_data);

void
(*YelpPageTitleFunc) (YelpDocument *document,
                      gint          req_id,
                      const gchar  *page_id,
                      const gchar  *title,
                      gpointer      user_data);

void
(*YelpPageErrorFunc) (YelpDocument *document,
                      gint          req_id,
                      const gchar  *page_id,
                      const GError *error,
                      gpointer      user_data);

YelpPage
yelp-directory
yelp-settings

This page belongs to the GNOME Documentation Project series, it concerns writing documentation for GNOME. Perhaps you can help out, or would like to consult the GNOME documentation.

CategoryDocumentationProject

live.gnome.org