# gnome-help

## Name

gnome-help -- Display application and GNOME system help.

## Synopsis

    #include <libgnome/libgnome.h>

    enum        GnomeHelpError;
    #define     GNOME_HELP_ERROR
    gboolean    gnome_help_display              (const char *file_name,
                                                 const char *link_id,
                                                 GError **error);
    gboolean    gnome_help_display_with_doc_id  (GnomeProgram *program,
                                                 const char *doc_id,
                                                 const char *file_name,
                                                 const char *link_id,
                                                 GError **error);
    gboolean    gnome_help_display_with_doc_id_and_env
                                                (GnomeProgram *program,
                                                 const char *doc_id,
                                                 const char *file_name,
                                                 const char *link_id,
                                                 char **envp,
                                                 GError **error);
    gboolean    gnome_help_display_desktop      (GnomeProgram *program,
                                                 const char *doc_id,
                                                 const char *file_name,
                                                 const char *link_id,
                                                 GError **error);
    gboolean    gnome_help_display_desktop_with_env
                                                (GnomeProgram *program,
                                                 const char *doc_id,
                                                 const char *file_name,
                                                 const char *link_id,
                                                 char **envp,
                                                 GError **error);
    gboolean    gnome_help_display_uri          (const char *help_uri,
                                                 GError **error);
    gboolean    gnome_help_display_uri_with_env (const char *help_uri,
                                                 char **envp,
                                                 GError **error);

## Description

These functions provide a way to display help files that are either installed as part of the main GNOME installation or that are specific to the current application.

## Details

### enum GnomeHelpError

    typedef enum {
      GNOME_HELP_ERROR_INTERNAL,
      GNOME_HELP_ERROR_NOT_FOUND
    } GnomeHelpError;

The different error codes which can be thrown in the GNOME_HELP_ERROR domain.

`GNOME_HELP_ERROR_INTERNAL` | Something went wrong internally. This is most likely caused by a resource problem or bad installation.
`GNOME_HELP_ERROR_NOT_FOUND` | Help file does not exist.

### GNOME_HELP_ERROR

    #define GNOME_HELP_ERROR (gnome_help_error_quark ())

The class (or domain) of errors raised directly by the gnome-help module. This is used as a value in the domain field of the GError structure.

### gnome_help_display ()

    gboolean    gnome_help_display              (const char *file_name,
                                                 const char *link_id,
                                                 GError **error);

Displays the help file specified by `file_name` at location `link_id` in the preferred help browser of the user.

`file_name` : | The name of the help document to display.
`link_id` : | Can be `NULL`. If set, refers to an anchor or section id within the requested document.
`error` : | A GError instance that will hold the specifics of any error which occurs during processing, or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `error` will contain the actual error).

### gnome_help_display_with_doc_id ()

    gboolean    gnome_help_display_with_doc_id  (GnomeProgram *program,
                                                 const char *doc_id,
                                                 const char *file_name,
                                                 const char *link_id,
                                                 GError **error);

Displays the help file specified by `file_name` at location `link_id` within the `doc_id` domain in the preferred help browser of the user. Most of the time, you want to call gnome_help_display() instead.

This function will display the help through creating a "ghelp" URI, by looking for `file_name` in the applications installed help location (found by GNOME_FILE_DOMAIN_APP_HELP) and its app_id. The resulting URI is roughly in the form "ghelp:appid/file_name?link_id". If a matching file cannot be found, `FALSE` is returned and `error` is set.

Please note that this only displays application help. To display help files from the global GNOME domain, you will want to use gnome_help_display_desktop().

`program` : | The current application object, or `NULL` for the default one.
`doc_id` : | The document identifier, or `NULL` to default to the application ID (app_id) of the specified `program`.
`file_name` : | The name of the help document to display.
`link_id` : | Can be `NULL`. If set, refers to an anchor or section id within the requested document.
`error` : | A GError instance that will hold the specifics of any error which occurs during processing, or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `error` will contain the actual error).

### gnome_help_display_with_doc_id_and_env ()

    gboolean    gnome_help_display_with_doc_id_and_env
                                                (GnomeProgram *program,
                                                 const char *doc_id,
                                                 const char *file_name,
                                                 const char *link_id,
                                                 char **envp,
                                                 GError **error);

Like gnome_display_with_doc_id(), but the the contents of `envp` will become the url viewer's environment rather than inheriting from the parents environment.

`program` : | The current application object, or `NULL` for the default one.
`doc_id` : | The document identifier, or `NULL` to default to the application ID (app_id) of the specified `program`.
`file_name` : | The name of the help document to display.
`link_id` : | Can be `NULL`. If set, refers to an anchor or section id within the requested document.
`envp` : | child's environment, or `NULL` to inherit parent's.
`error` : | A GError instance that will hold the specifics of any error which occurs during processing, or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `error` will contain the actual error).

### gnome_help_display_desktop ()

    gboolean    gnome_help_display_desktop      (GnomeProgram *program,
                                                 const char *doc_id,
                                                 const char *file_name,
                                                 const char *link_id,
                                                 GError **error);

Displays the GNOME system help file specified by `file_name` at location `link_id` in the preferred help browser of the user. This is done by creating a "ghelp" URI, by looking for `file_name` in the system help domain (GNOME_FILE_DOMAIN_HELP) and it's app_id. This domain is determined when the library is compiled. If a matching file cannot be found, `FALSE` is returned and `error` is set.

Please note that this only displays system help. To display help files for an application, you will want to use gnome_help_display().

`program` : | The current application object, or `NULL` for the default one.
`doc_id` : | The name of the help file relative to the system's help domain (GNOME_FILE_DOMAIN_HELP).
`file_name` : | The name of the help document to display.
`link_id` : | Can be `NULL`. If set, refers to an anchor or section id within the requested document.
`error` : | A GError instance that will hold the specifics of any error which occurs during processing, or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `error` will contain the actual error).

### gnome_help_display_desktop_with_env ()

    gboolean    gnome_help_display_desktop_with_env
                                                (GnomeProgram *program,
                                                 const char *doc_id,
                                                 const char *file_name,
                                                 const char *link_id,
                                                 char **envp,
                                                 GError **error);

Like gnome_help_display_desktop(), but the the contents of `envp` will become the url viewer's environment rather than inheriting from the parents environment.

`program` : | The current application object, or `NULL` for the default one.
`doc_id` : | The name of the help file relative to the system's help domain (GNOME_FILE_DOMAIN_HELP).
`file_name` : | The name of the help document to display.
`link_id` : | Can be `NULL`. If set, refers to an anchor or section id within the requested document.
`envp` : | child's environment, or `NULL` to inherit parent's.
`error` : | A GError instance that will hold the specifics of any error which occurs during processing, or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `error` will contain the actual error).

### gnome_help_display_uri ()

    gboolean    gnome_help_display_uri          (const char *help_uri,
                                                 GError **error);

Displays `help_uri` in the user's preferred viewer. You should never need to call this function directly in code, since it is just a wrapper for gnome_url_show() and consequently the viewer used to display the results depends upon the scheme of the URI (so it is not strictly a help-only function).

`help_uri` : | The URI to display.
`error` : | A GError instance that will hold the specifics of any error which occurs during processing, or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `error` will contain the actual error).

### gnome_help_display_uri_with_env ()

    gboolean    gnome_help_display_uri_with_env (const char *help_uri,
                                                 char **envp,
                                                 GError **error);

Like gnome_help_display_uri(), but the the contents of `envp` will become the help viewer's environment rather than inheriting from the parents environment.

`help_uri` : | The URI to display.
`envp` : | child's environment, or `NULL` to inherit parent's.
`error` : | A GError instance that will hold the specifics of any error which occurs during processing, or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `error` will contain the actual error).