docs/help-parsing.txt

   1 This document was originally posted to gnome-doc-list by Jonathan Blandford.
   2 The original mail is available at
   3 http://mail.gnome.org/archives/gnome-doc-list/2001-September/msg00000.html.
   4
   5 Only minor corrections have been applied to the original and there are still
   6 some inaccuracies in here, but it is just for the developers' reference at the
   7 moment.
   8
   9 OVERVIEW:
  10 =========
  11
  12  * Have installation of xml as the main supported format, with
  13    scrollkeeper supplying metadata
  14  * Allow installation in places other than where GNOME is installed
  15  * Allow applications to install HTML as a fall back
  16  * Allow applications to show system help as well as
  17    application-specific help
  18  * Define ghelp URI scheme
  19  * Have generic method of launching the help system
  20  * Define a simple API -- 3 functions.
  21  * Assume that the help-browser links with the same gnome-libs that the
  22    app links with -- or at least the same prefix.
  23
  24 User documentation has been a somewhat messy, non-standard process in
  25 the past.  This document aims to specify exactly how help should work,
  26 rather than rely on the common usage.  It will describe what is
  27 necessary for an application to install and show user documentation,
  28 what a help-browser author needs to consider during implementation, and
  29 where core gnome documentation should go.  It is not really a tutorial
  30 -- one of those needs to be written at some point.
  31
  32 NOT COVERED:
  33 ============
  34  * man/info/other legacy formats
  35  * API or developer documentation
  36  * Popup help/"What's this?"/tooltips, etc.
  37  * Correct use of xml beyond specifying which DTD to use
  38  * Tools involved with modifying above xml.
  39
  40 PART 1:  GHELP URI SCHEME
  41 =========================
  42
  43 The ghelp URI scheme is a fairly simple scheme.  This scheme provides a
  44 way of mapping to a help file with an optional offset.  Here are a few
  45 examples:
  46
  47 1:  ghelp:nautilus
  48 2:  ghelp:AisleRiot2/Klondike
  49 3:  ghelp:///opt/gnome/share/AisleRiot2/help/it/Klondike.xml?winning
  50 4:  ghelp:/usr/share/oldapp/help/index.html
  51
  52 There are three basic ghelp styles.  The absolute path, the relative
  53 path, and the index path.  In the examples above, the last two are
  54 absolute, the second one is a relative path, and the first one is an
  55 index path.  Please note that, as this is a URI scheme, all the rules of
  56 escaping/valid characters for URI's apply.  A quick definition of the
  57 URI scheme follows:
  58
  59   1) The absolute ghelp URI:
  60
  61   The basic form of the absolute ghelp URI scheme follows the "generic URI
  62   semantics" as defined in RFC 2396. That is:
  63
  64            <scheme>://<authority><path>?<query>
  65
  66   where <scheme> is 'ghelp'.  It is expected that only local files are
  67   supported for GNOME 2.0, though it is conceivable that we could host
  68   documentation off of gnome.org at some point in the future.  As
  69   expected, the common variant with the //<authority> missing is
  70   allowed (ie: Example 4)
  71
  72   1.1) The <query>
  73
  74   The query in the file is the location in the file to display.  For
  75   example, with xml, it would apply to the "id" of the section to
  76   display.  In HTML, it would go to an anchor name.  One confusing side
  77   effect of this with xml is that the id of a section can be defined in
  78   a different file due to entities.  Thus, in the example 3 above, the
  79   actual file being read may be different if the winning section is
  80   defined outside of Klondike.xml
  81
  82   2) The relative ghelp URI scheme:
  83
  84   The basic form of the relative URI scheme is:
  85
  86                      ghelp:<appid>/<file>[?<query>]
  87
  88   In general, this form can be turned into an absolute scheme with a
  89   little work on the help browser's part.  The primary use of a relative
  90   URI is for cleanliness of URI so that the user could enter it by hand.
  91   It also gives you a language independent way of referring to a
  92   document.
  93
  94   2.1) The <appid>
  95
  96     The appid is the id of the application and the location of the help
  97     files.
  98
  99   2.2) The <file>
 100
 101     The file listed here is a little different from the absolute URI
 102     scheme as the extention is optional.  The help browser is expected
 103     to try appending ".xml", ".sgml", and ".html", when looking for the
 104     file before falling back to <file> without the extention.
 105
 106   2.3) The <query>
 107
 108     Identical to the <query> in 1.1
 109
 110   2.4) Converting a relative ghelp URI to an absolute URI:
 111
 112     To convert URI schemes, the help browser must convert the
 113     <appid>/<file> part to the <path> field.  The basic way of doing this
 114     is to do
 115     <path> = <GNOME_DATADIR>/<appid>/<LOCALE>/<file>[<extention>]
 116
 117
 118     where <GNOME_DATADIR> is the datadir prefix where the
 119     help-browser/GNOME is installed and <LOCALE> is the current locale.
 120
 121     extention = ( ".xml" | ".sgml" | ".html" | "")
 122
 123     An interesting thing about doing the conversion is that it requires
 124     the application doing the conversion to check to see if the file
 125     exists.
 126
 127   3) The index ghelp URI scheme:
 128
 129   The basic form of the index URI scheme is:
 130
 131                              ghelp:<appid>
 132
 133   This is purely a convenient URI scheme for users interested in looking
 134   up help for an application.  The actual information supplied is up to
 135   the help browser, but it is expected that they will look up
 136   information on the file using scrollkeeper (or possibly another
 137   mechanism) and display it.  It is optional for a help browser to
 138   implement.
 139
 140 PART 2:  APPLICATION HELP
 141 =========================
 142
 143 All user documentation should be written in docbook-xml version 4.1 and
 144 should follow the styleguide put out by the documentation project [1].
 145 Documentation can and should be translated to multiple languages when
 146 possible.  The DTD to use is:
 147
 148 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBookXML V4.1.2//EN"
 149                   "http://www.oasis-open.org/xml/4.1.2/docbookx.dtd">
 150
 151 All applications using gnome-libs should initialize using
 152 gnome_program_init.  Additionally, they will need to pass in the
 153 GNOME_PARAM_APP_DATADIR argument, so that the help system knows where to
 154 look for help.  Those programs using the
 155 GNOME_PROGRAM_STANDARD_PROPERTIES macro will do so automatically.
 156 Documentation should then be installed into the
 157 ${DATADIR}/${APPNAME}/help/${LOCALE}/ directory.
 158
 159 For example, consider the help documents for the Italian version of a
 160 copy of AisleRiot2 installed in /opt/gnome.  These documents would be
 161 found in the  /opt/gnome/share/AisleRiot2/help/it/ directory.
 162
 163 In addition to installing the actual documentation, the developer should
 164 also install meta information about the document using scrollkeeper.[2]
 165 This is just a small bit of metadata so that the help-browser can find
 166 information about the documentation.
 167
 168 There are 3 proposed API calls for libgnome:
 169
 170 gboolean gnome_help_display         (GnomeProgram  *program,
 171                                      char          *doc_name,
 172                                      char          *link_id,
 173                                      GError       **error);
 174 gboolean gnome_help_display_desktop (GnomeProgram  *program,
 175                                      char          *doc_name,
 176                                      char          *link_id,
 177                                      GError       **error);
 178 gboolean gnome_help_display_uri     (char          *help_uri,
 179                                      GError       **error);
 180
 181 The first two calls basically construct the appropriate URI, and then
 182 call gnome_help_display_uri [3].  The difference between the first two
 183 calls is that the first is used to display the help for the user
 184 documentation, while the second is intended to show installed help that
 185 comes with GNOME (such as the glossary).  One assumption made here is
 186 that this desktop documentation is installed with the same prefix as the
 187 gnome libraries and help-browser.
 188
 189 One thing about gnome_help_display is that it will try to create a
 190 relative ghelp URI if possible and fall back to an absolute one if
 191 necessary.  It will never try to create an index ghelp URI.
 192
 193 PART 3: LAUNCHING THE HELP BROWSER:
 194 ===================================
 195
 196 We use gnome-url to launch the help-browser, allowing us to customize
 197 the application used to display help.  The actual mechanism for doing
 198 this needs to be determined[4].  As there is no clear help-browser for
 199 GNOME 2.0 at this point, we can select a help-browser later on (or
 200 change it if need be).  Fortunately there are currently at least four
 201 possible candidates for a help browser that I know of (devhelp,
 202 encompass, galeon, and nautilus).
 203
 204 PART 4: IMPLEMENTING THE HELP BROWSER:
 205 ======================================
 206
 207 The help browser must implement the following things:
 208
 209  * support showing both relative and absolute ghelp URI's
 210
 211  * be able to display docbook xml and HTML
 212
 213 Additionally, the following would be nice:
 214
 215  * scrollkeeper support to generate an index of topics, and support
 216    of index ghelp URIs.
 217
 218  * indexing of keywords/search of documents
 219
 220 TODO:
 221 =====
 222
 223  * I'm not sure at all about the name 'ghelp' for the URI scheme.
 224    Perhaps 'gnome-help' would be better.  Then again, the gnu project
 225    seems to have taken over the world-wide 'g' namespace.
 226
 227  * We use '?' to go to a section id in the URI scheme.  Would '#' be
 228    better?
 229
 230  * Write API documentation for the 3 functions.
 231
 232
 233 FOOTNOTES:
 234 ==========
 235
 236 [1] More information on actually writing the documentation can be found
 237 at <A  HREF="http://developer.gnome.org/projects/doc/">http://developer.gnome.org/projects/doc/</A>  FIXME: need better link
 238
 239 [2] More information on scrollkeeper can be found at
 240 <A  HREF="http://scrollkeeper.sourceforge.net/">http://scrollkeeper.sourceforge.net/</A>.  It would be really nice to have a
 241 tutorial there, or somewhere.
 242
 243 [3] This actually calls gnome_uri_show_full.  That's okay -- this is
 244 just a convenience function at this point.  If we decide not to use
 245 gnome-url, we can change it in the future.
 246
 247 [4] There is one in gnome-url.  I don't understand it b/c I'm tired
 248 now.  I need to get Martin to explain it to me sometime. (-:
 249