diff options
| -rw-r--r-- | ChangeLog | 20 | ||||
| -rw-r--r-- | docs/help-parsing.txt | 249 | ||||
| -rw-r--r-- | src/devhelp-parser.c | 4 | ||||
| -rw-r--r-- | src/scrollkeeper-parser.c | 30 | ||||
| -rw-r--r-- | src/yelp-section.c | 7 | ||||
| -rw-r--r-- | src/yelp-section.h | 4 | ||||
| -rw-r--r-- | src/yelp-window.c | 2 |
7 files changed, 306 insertions, 10 deletions
@@ -1,3 +1,23 @@ +2001-12-05 Malcolm Tredinnick <malcolm@commsecure.com.au> + * src/yelp-section.[ch]: + - add a scheme member to YelpSection. Will usually be NULL, + except when adding URIs from Scrollkeeper. + (yelp_section_new): pass in scheme as the last param. + (yelp_section_copy): pass in extra param to yelp_section_new. + + * src/devhelp-parser.c, src/yelp-window.c: pass extra param in + calls to yelp_section_new(). + + * src/scrollkeeper-parser.c: + - parse extra param to yelp_section_new(). + (sp_parse_doc): strip off the scheme from ScrollKeeper (usually + "file:") before adding "ghelp:" to the URI. But save it in case + we want act based on this scheme later. + (sp_strip_scheme): new function to strip schemes. + + * docs/help-parsing.txt: New file, describing what we have to + handle. Mostly because I keep forgetting. + 2001-12-04 Christian Meyer <chrisime@gnome.org> * configure.in: Added "de" entry to ALL_LINGUAS. diff --git a/docs/help-parsing.txt b/docs/help-parsing.txt new file mode 100644 index 00000000..5d1d93a6 --- /dev/null +++ b/docs/help-parsing.txt @@ -0,0 +1,249 @@ +This document was originally posted to gnome-doc-list by Jonathan Blandford. +The original mail is available at +http://mail.gnome.org/archives/gnome-doc-list/2001-September/msg00000.html. + +Only minor corrections have been applied to the original and there are still +some inaccuracies in here, but it is just for the developers' reference at the +moment. + +OVERVIEW: +========= + + * Have installation of xml as the main supported format, with + scrollkeeper supplying metadata + * Allow installation in places other than where GNOME is installed + * Allow applications to install HTML as a fall back + * Allow applications to show system help as well as + application-specific help + * Define ghelp URI scheme + * Have generic method of launching the help system + * Define a simple API -- 3 functions. + * Assume that the help-browser links with the same gnome-libs that the + app links with -- or at least the same prefix. + +User documentation has been a somewhat messy, non-standard process in +the past. This document aims to specify exactly how help should work, +rather than rely on the common usage. It will describe what is +necessary for an application to install and show user documentation, +what a help-browser author needs to consider during implementation, and +where core gnome documentation should go. It is not really a tutorial +-- one of those needs to be written at some point. + +NOT COVERED: +============ + * man/info/other legacy formats + * API or developer documentation + * Popup help/"What's this?"/tooltips, etc. + * Correct use of xml beyond specifying which DTD to use + * Tools involved with modifying above xml. + +PART 1: GHELP URI SCHEME +========================= + +The ghelp URI scheme is a fairly simple scheme. This scheme provides a +way of mapping to a help file with an optional offset. Here are a few +examples: + +1: ghelp:nautilus +2: ghelp:AisleRiot2/Klondike +3: ghelp:///opt/gnome/share/AisleRiot2/help/it/Klondike.xml?winning +4: ghelp:/usr/share/oldapp/help/index.html + +There are three basic ghelp styles. The absolute path, the relative +path, and the index path. In the examples above, the last two are +absolute, the second one is a relative path, and the first one is an +index path. Please note that, as this is a URI scheme, all the rules of +escaping/valid characters for URI's apply. A quick definition of the +URI scheme follows: + + 1) The absolute ghelp URI: + + The basic form of the absolute ghelp URI scheme follows the "generic URI + semantics" as defined in RFC 2396. That is: + + <scheme>://<authority><path>?<query> + + where <scheme> is 'ghelp'. It is expected that only local files are + supported for GNOME 2.0, though it is conceivable that we could host + documentation off of gnome.org at some point in the future. As + expected, the common variant with the //<authority> missing is + allowed (ie: Example 4) + + 1.1) The <query> + + The query in the file is the location in the file to display. For + example, with xml, it would apply to the "id" of the section to + display. In HTML, it would go to an anchor name. One confusing side + effect of this with xml is that the id of a section can be defined in + a different file due to entities. Thus, in the example 3 above, the + actual file being read may be different if the winning section is + defined outside of Klondike.xml + + 2) The relative ghelp URI scheme: + + The basic form of the relative URI scheme is: + + ghelp:<appid>/<file>[?<query>] + + In general, this form can be turned into an absolute scheme with a + little work on the help browser's part. The primary use of a relative + URI is for cleanliness of URI so that the user could enter it by hand. + It also gives you a language independent way of referring to a + document. + + 2.1) The <appid> + + The appid is the id of the application and the location of the help + files. + + 2.2) The <file> + + The file listed here is a little different from the absolute URI + scheme as the extention is optional. The help browser is expected + to try appending ".xml", ".sgml", and ".html", when looking for the + file before falling back to <file> without the extention. + + 2.3) The <query> + + Identical to the <query> in 1.1 + + 2.4) Converting a relative ghelp URI to an absolute URI: + + To convert URI schemes, the help browser must convert the + <appid>/<file> part to the <path> field. The basic way of doing this + is to do + <path> = <GNOME_DATADIR>/<appid>/<LOCALE>/<file>[<extention>] + + + where <GNOME_DATADIR> is the datadir prefix where the + help-browser/GNOME is installed and <LOCALE> is the current locale. + + extention = ( ".xml" | ".sgml" | ".html" | "") + + An interesting thing about doing the conversion is that it requires + the application doing the conversion to check to see if the file + exists. + + 3) The index ghelp URI scheme: + + The basic form of the index URI scheme is: + + ghelp:<appid> + + This is purely a convenient URI scheme for users interested in looking + up help for an application. The actual information supplied is up to + the help browser, but it is expected that they will look up + information on the file using scrollkeeper (or possibly another + mechanism) and display it. It is optional for a help browser to + implement. + +PART 2: APPLICATION HELP +========================= + +All user documentation should be written in docbook-xml version 4.1 and +should follow the styleguide put out by the documentation project [1]. +Documentation can and should be translated to multiple languages when +possible. The DTD to use is: + +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBookXML V4.1.2//EN" + "http://www.oasis-open.org/xml/4.1.2/docbookx.dtd"> + +All applications using gnome-libs should initialize using +gnome_program_init. Additionally, they will need to pass in the +GNOME_PARAM_APP_DATADIR argument, so that the help system knows where to +look for help. Those programs using the +GNOME_PROGRAM_STANDARD_PROPERTIES macro will do so automatically. +Documentation should then be installed into the +${DATADIR}/${APPNAME}/help/${LOCALE}/ directory. + +For example, consider the help documents for the Italian version of a +copy of AisleRiot2 installed in /opt/gnome. These documents would be +found in the /opt/gnome/share/AisleRiot2/help/it/ directory. + +In addition to installing the actual documentation, the developer should +also install meta information about the document using scrollkeeper.[2] +This is just a small bit of metadata so that the help-browser can find +information about the documentation. + +There are 3 proposed API calls for libgnome: + +gboolean gnome_help_display (GnomeProgram *program, + char *doc_name, + char *link_id, + GError **error); +gboolean gnome_help_display_desktop (GnomeProgram *program, + char *doc_name, + char *link_id, + GError **error); +gboolean gnome_help_display_uri (char *help_uri, + GError **error); + +The first two calls basically construct the appropriate URI, and then +call gnome_help_display_uri [3]. The difference between the first two +calls is that the first is used to display the help for the user +documentation, while the second is intended to show installed help that +comes with GNOME (such as the glossary). One assumption made here is +that this desktop documentation is installed with the same prefix as the +gnome libraries and help-browser. + +One thing about gnome_help_display is that it will try to create a +relative ghelp URI if possible and fall back to an absolute one if +necessary. It will never try to create an index ghelp URI. + +PART 3: LAUNCHING THE HELP BROWSER: +=================================== + +We use gnome-url to launch the help-browser, allowing us to customize +the application used to display help. The actual mechanism for doing +this needs to be determined[4]. As there is no clear help-browser for +GNOME 2.0 at this point, we can select a help-browser later on (or +change it if need be). Fortunately there are currently at least four +possible candidates for a help browser that I know of (devhelp, +encompass, galeon, and nautilus). + +PART 4: IMPLEMENTING THE HELP BROWSER: +====================================== + +The help browser must implement the following things: + + * support showing both relative and absolute ghelp URI's + + * be able to display docbook xml and HTML + +Additionally, the following would be nice: + + * scrollkeeper support to generate an index of topics, and support + of index ghelp URIs. + + * indexing of keywords/search of documents + +TODO: +===== + + * I'm not sure at all about the name 'ghelp' for the URI scheme. + Perhaps 'gnome-help' would be better. Then again, the gnu project + seems to have taken over the world-wide 'g' namespace. + + * We use '?' to go to a section id in the URI scheme. Would '#' be + better? + + * Write API documentation for the 3 functions. + + +FOOTNOTES: +========== + +[1] More information on actually writing the documentation can be found +at <A HREF="http://developer.gnome.org/projects/doc/">http://developer.gnome.org/projects/doc/</A> FIXME: need better link + +[2] More information on scrollkeeper can be found at +<A HREF="http://scrollkeeper.sourceforge.net/">http://scrollkeeper.sourceforge.net/</A>. It would be really nice to have a +tutorial there, or somewhere. + +[3] This actually calls gnome_uri_show_full. That's okay -- this is +just a convenience function at this point. If we decide not to use +gnome-url, we can change it in the future. + +[4] There is one in gnome-url. I don't understand it b/c I'm tired +now. I need to get Martin to explain it to me sometime. (-: + diff --git a/src/devhelp-parser.c b/src/devhelp-parser.c index c5627f88..25b08ac8 100644 --- a/src/devhelp-parser.c +++ b/src/devhelp-parser.c @@ -284,7 +284,7 @@ devhelp_parser_parse_book (DevHelpParser *parser, const GnomeVFSURI *uri) } root = yelp_section_add_sub (NULL, - yelp_section_new (name, index_uri, NULL)); + yelp_section_new (name, index_uri, NULL, NULL)); root_node = root_node->xmlChildrenNode; @@ -381,7 +381,7 @@ devhelp_parser_parse_section (GNode *parent, xmlNode *xml_node) } node = yelp_section_add_sub (parent, - yelp_section_new (name, uri, NULL)); + yelp_section_new (name, uri, NULL, NULL)); gnome_vfs_uri_unref (uri); diff --git a/src/scrollkeeper-parser.c b/src/scrollkeeper-parser.c index 86f38098..5ae7c6a1 100644 --- a/src/scrollkeeper-parser.c +++ b/src/scrollkeeper-parser.c @@ -54,6 +54,8 @@ static void sp_parse_toc_section (GNode *parent, const gchar *base_uri); static gchar * sp_get_xml_docpath (const gchar *command, const gchar *argument); +static void sp_strip_scheme(gchar **original_uri, gchar **scheme); + /* MetaDataParser */ static gboolean sp_parse (MetaDataParser *parser); @@ -311,7 +313,7 @@ sp_parse_book (ScrollKeeperParser *parser, g_print ("Parse book: %s\n", name); root = yelp_section_add_sub (NULL, - yelp_section_new (name, NULL, NULL)); + yelp_section_new (name, NULL, NULL, NULL)); for (cur = node->xmlChildrenNode; cur; cur = cur->next) { if (!g_strcasecmp (cur->name, "sect")) { @@ -350,7 +352,7 @@ sp_parse_section (GNode *parent, xmlNode *xml_node) } node = yelp_section_add_sub (parent, - yelp_section_new (name, NULL, NULL)); + yelp_section_new (name, NULL, NULL, NULL)); for (cur = xml_node->xmlChildrenNode; cur; cur = cur->next) { if (!g_strcasecmp (cur->name, "sect")) { @@ -373,6 +375,7 @@ sp_parse_doc (GNode *parent, xmlNode *xml_node) gchar *format; GNode *node; gchar *docsource; + gchar *scheme; /* gchar *index_location; */ for (cur = xml_node->xmlChildrenNode; cur; cur = cur->next) { @@ -389,6 +392,7 @@ sp_parse_doc (GNode *parent, xmlNode *xml_node) else if (!g_strcasecmp (cur->name, "docsource")) { xml_str = xmlNodeGetContent (cur); docsource = g_strdup (xml_str); + sp_strip_scheme(&docsource, &scheme); link = g_strconcat ("ghelp:", docsource, NULL); g_free (xml_str); } @@ -400,7 +404,7 @@ sp_parse_doc (GNode *parent, xmlNode *xml_node) } node = yelp_section_add_sub (parent, - yelp_section_new (title, link, NULL)); + yelp_section_new (title, link, NULL, NULL)); sp_parse_toc (node, docsource); @@ -484,7 +488,7 @@ sp_parse_toc_section (GNode *parent, xmlNode *xml_node, const gchar *base_uri) /* } */ node = yelp_section_add_sub (parent, - yelp_section_new (name, base_uri, link)); + yelp_section_new (name, base_uri, link, NULL)); for (; next_child != NULL; next_child = next_child->next) { if (!g_strncasecmp (next_child->name, "tocsect", 7)) { @@ -532,3 +536,21 @@ scrollkeeper_parser_new (void) return META_DATA_PARSER (parser); } + +static void +sp_strip_scheme(gchar **original_uri, gchar **scheme) +{ + gchar *new_uri; + gchar *point; + + point = g_strstr_len(*original_uri, strlen(*original_uri), ":"); + if (!point) + { + scheme = NULL; + return; + } + *scheme = g_strndup(*original_uri, point - *original_uri); + new_uri = g_strdup(point + 1); + g_free(*original_uri); + *original_uri = new_uri; +} diff --git a/src/yelp-section.c b/src/yelp-section.c index 63621b2f..4704fc6d 100644 --- a/src/yelp-section.c +++ b/src/yelp-section.c @@ -28,7 +28,8 @@ #include "yelp-section.h" YelpSection * -yelp_section_new (const gchar *name, const gchar *uri, const gchar *reference) +yelp_section_new (const gchar *name, const gchar *uri, const gchar *reference, + const gchar *scheme) { YelpSection *section; @@ -37,6 +38,7 @@ yelp_section_new (const gchar *name, const gchar *uri, const gchar *reference) section->name = g_strdup (name); section->uri = g_strdup (uri); section->reference = g_strdup (reference); + section->scheme = g_strdup (scheme); return section; } @@ -63,7 +65,8 @@ yelp_section_copy (const YelpSection *section) { return yelp_section_new (section->name, section->uri, - section->reference); + section->reference, + section->scheme); } void diff --git a/src/yelp-section.h b/src/yelp-section.h index 81a78962..ab332604 100644 --- a/src/yelp-section.h +++ b/src/yelp-section.h @@ -33,11 +33,13 @@ struct _YelpSection { gchar *name; gchar *uri; gchar *reference; + gchar *scheme; }; YelpSection * yelp_section_new (const gchar *name, const gchar *uri, - const gchar *reference); + const gchar *reference, + const gchar *scheme); GNode * yelp_section_add_sub (GNode *parent, YelpSection *section); diff --git a/src/yelp-window.c b/src/yelp-window.c index dc688834..03bec2e5 100644 --- a/src/yelp-window.c +++ b/src/yelp-window.c @@ -400,5 +400,5 @@ yelp_window_open_uri (YelpWindow *window, priv = window->priv; yelp_view_open_section (YELP_VIEW (priv->yelp_view), - yelp_section_new (NULL, str_uri, NULL)); + yelp_section_new (NULL, str_uri, NULL, NULL)); } |