[Author]
 [Introduction]
 [Functions]
     [fli_load_help_browser()]
     [fli_terminate_help_browser()]
 [Example]
     [Initial actions]
     [How the help text is shown]
     [How the help text is removed]
 [Format of the help file]
     [Anchors and links]
     [Sections]
     [Control sequences]
 [Caveats]

[Author]

@C4@i@lAuthor

Karel Kubat (karel@icce.rug.nl)

[Introduction]

@C4@i@lIntroduction

The helpbrowser functions are designed to provide an easy way to load
program-specific help information into a three-browser form, where the user
can select helptext sections from (a) a "table of contents" browser, (b) an
"index" browser, or (c) from links in the actual text.

The helpbrowser functions do NOT implement a full hyperlink help system (use
http browsers for that ;-) but just a simple-to-use system for short
helptexts.

Before using the help browser functions, you'll need:

    a. A helpfile. This file must be organized in a special way, parse-able by
    the helptext functions.

    b. A form, with three predefined browsers in it: a contents-, an index-
    and a text browser. You'll probably want to put a `done' button in the
    form as well.

[Functions]

@C4@i@lFunctions

There are two top-level functions: fli_load_help_browser() and
fli_terminate_help_browser(). A few internally used functions exist (e.g., to
parse the helpfile), but they are not described here.

[fli_load_help_browser()]

@C4@ifli_load_help_browser()

@iFunction prototype
    int fli_load_help_browser (FL_FORM *form, FL_OBJECT *textbrowser, 
	FL_OBJECT *contentsbrowser, FL_OBJECT *indexbrowser,
	char const *filename)

@iArguments
    form - the form containing the text/contents/index browsers
    textbrowser - browser object to receive helptext to view
    contentsbrowser - browser to receive table of contents
    indexbrowser - browser to receive index
    filename - file containing help text definition

@iReturn value
    0 - text loaded
    1 - file could not be opened
    2 - memory allocation failed

@iActions of the function

    Fills the contents and index browsers and defines its own callback
    routine, but DOES NOT put the form on the screen. The caller must do that.
    The textbrowser will be filled with user-elected text information. NOTE
    THAT the three browsers must be of the type FL_SELECT_BROWSER, since
    the user must be able to make a selection from the shown text.

[fli_terminate_help_browser()]

@C4@ifli_load_help_browser()

@iFunction prototype
    void fli_terminate_help_browser (FL_OBJECT *browser)

@iArguments
    browser - one of the used browsers, i.e., the textbrowser,
    contentsbrowser or indexbrowser from the fli_load_help_browser()
    call.

@iActions
    Does internal bookkeeping. Does NOT remove the form from the screen,
    the caller should do that if requested.

[Example]

@C4@i@lExample

Note again that you need a form with three selectable browsers, before you can
use the helpbrowser functions. The three browsers must be in a predefined
form.

In this example, we'll assume that a button `help' exists in one of the forms
which are on-screen, which, when pressed, fires up the helpform. The helpform
itself shows the help information and can be de-activated with a `quit help'
button.

[Initial actions]

@C4@iInitial actions

As mentioned before, you need a form with three browsers to receive the help
text itself, its table of contents, and the index. Usually, it's a good idea
to create a form that looks a bit like this:

	browser for	    browser for
	contents	      index

	Largest browser for the helptext
	itself

The form's largest browser should be the one to receive the actual help text.
The contents- and index-browsers are smaller; the index browser can be
actually the smallest.

Since the whole form can be dismissed (as assumed in this example), the form
should furthermore contain a `done' button. This is no prerequisite per se:
situations can arise where a help browser should be on-screen permanently.
	
[How the help text is shown]

@C4@iHow the help text is shown

This section presents a code example of the actual showing of help text.

Let's assume that a button `help' has a callback function, that fires up a
predefined helpform with the three browsers, and puts it onscreen. This
function calls fli_load_browser_helpfile(). Example:

    /* dohelp() is called when the user presses a `help' button */
    /* -------------------------------------------------------- */
    
    /* the help filaname */ 
    #define HELPFILE "/usr/local/etc/myhelp.dat"

    extern FL_FORM
	*help;			    /* form containing 3 browsers */
    extern FL_OBJECT
	*help_browser,		    /* 3 FL_SELECT_BROWSER type */
	*help_contents_browser,     /* browsers in the form */ 
	*help_index_browser;
    
    void dohelp (FL_OBJECT *ob, long d)
    {
	static char
	    *notloaded [] =	    /* failure message */
	    {
		"Sorry, help unavailable.",
		"The help file was not found or could not",
		"be loaded.",
	    };
	register int
	    i;			    /* counter */
    
	/* deactivate help button */
	fl_deactivate_object (ob);

	/* load browser */
	if (fli_load_help_browser (help, help_browser, help_contents_browser,
				   help_index_browser, HELPFILE))
	    for (i = 0; i < (sizeof (notloaded) / sizeof (char *)); i++)
		fl_add_browser_line (help_browser, notloaded [i]);

	/* show the form */
	fl_show_form (help, FL_PLACE_SIZE | FL_PLACE_MOUSE, FL_FULLBORDER,
		      "HELP!");
    }

Following this call, the help screen is shown and information is automatically
displayed in it. Assuming that the XForms loop cycle is already running (i.e.,
that the program is already in a fl_do_forms() loop), this is all that's
needed.

[How the help text is removed]

@C4@iHow the help text is removed

You'll probably want the help form to finish somehow. To achieve this, you
need to define a `stop help' button in the helpform, calling the following
callback function:

    /* help_done(): called when user presses `done with help' button */
    /* ------------------------------------------------------------- */ 

    extern FL_OBJECT
	*help_button,		/* button that fires up help */
	*help_browser;		/* any of the browsers in the helpform */
    extern FL_FORM
	*help;			/* help form itself */ 
	
    void help_done (FL_OBJECT *ob, long d)
    {
	/* re-activate help button, was deactivated in dohelp() above */
	fl_activate_object (help_button);

	/* terminate help browser */
	fli_terminate_help_browser (help_browser);

	/* remove help form from the screen */ 
	fl_hide_form (help);
    }

That's all that's to it, given the right format of the helpfile. That is
discussed in section [Format of the help file].

[Format of the help file]

@C4@i@lFormat of the help file

The helpfile contains three types of information: anchors, links, and other
(textual) information. Furthermore, the helpfile has two sections: the table
of contents (which is only partly displayed) and the actual helptext itself
(which is fully displayed).

[Anchors and links]

@C4@iAnchors and links

Nomenclature: anchors, links and textual information.

@iAnchor

    An ANCHOR is text in square brackets, occurring at the first column of
    the file. It just defines that some sections starts at this point. Example
    (the | character means: beginning of line):

	|[Introduction]
	|
	|@C1@lIntroduction

    This means: an anchor called Introduction starts here, defined by
    [Introduction]. This actual section begins with one empty line, followed
    by the text `Introduction', color red, large font. (Actually, since this
    document also has an introductory section, you could click on it and jump
    to the intro.)

@iLink

    A LINK looks the same as an anchor, but does not occur on the first
    column. Example:

	| See further section [Introduction].

    This link of course points to the introduction section, defined by an
    anchor [Introduction].

    Links have furthermore an important role because they must be used at the
    top of the helpfile to define the table of contents, but that is discussed
    below in [Sections].

@iTextual information

    TEXTUAL INFORMATION is just everything except for anchors or links; such
    as this line of text.

[Sections]

@C4@iSections

The helpfile must contain two sections: the (partly displayed) table of
contents, and the (displayed) actual helptext.

@iThe table of contents

The first section MUST BE the table of contents, and contain links to the rest
of the document.  Example (the | character again denotes the leftmost column):

	|   [Introduction]
	|	[Copyright notice]
	|   [Program invocation]
	|	[Flags]
	|	[File arguments]

This table of contents must occur at the top of the file. It has links, since
the [...] items don't start at the first column. Furthermore the links are
indented, but that's only for cosmetical reasons. This cosmetical reason is
the following: the contents browser will contain the linknames, without the
braces, but with leading spaces. When you therefore use an indentation in the
table of contents to suggest subsectioning, the contents browser will also
show this indentation.

The help-browser functions use this table of contents to fill the contents
browser with links (without the [] around the link names). Furthermore, this
table is also used to construct the index: that is simply a sorted list of the
mentioned links, without any indentation. (Therefore, you can choose to make
the index browser somewhat smaller than the contents browser -- the index
browser doesn't need space for indentation).

@iActual helptext

The second section of the file is the actual information, which must contain
anchors and information to show to the user. This section by definition starts
with the first anchor of the file. Note that the anchors themselves are NOT
shown in the text browser, so it's a good idea to provide a title for the
text, as in:

    |[Introduction]
    |
    |@C4@l@iIntroduction
    |
    |Welcome to ..........

This example shows (a) an anchor, with (b) the name repeated underneat in
blue, large italic font. The name is repeated because the anchor itself will
not be displayed. Following the name, the actual contents of this section
starts.

If you provide links in this section, then the links are shown WITH the
surrounding square brackets (this in contrast to the table of contents, where
the square brackets are removed).

[Control sequences]

@C4@iControl sequences

The `control sequences' which you can use in a text browser to change the
appearance of text are documented in the XForms guide. Below is a summarizing
table:

@f	@b	boldface
@f	@i	italics
@f	@f	fixed font
@f	@l	large font
@f	@s	small font
@f	@c	centered text
@f	@r	right-aligned text
@f	@_	underlined
@f	@Cn	color code, only some are shown:
@f		    @C0 is black
@f		    @C1 is red
@f		    @C2 is green
@f		    @C3 is yellow
@f		    @C4 is blue
@f		    @C5 is magenta
@f		    @C6 is cyan
@f		    @C7 is white
@f		    @C8 is tomato
@f		    @C9 is indian red
@f		   @C10 is slate blue

[Caveats]

@C4@i@lCaveats

@iDead anchors

    Remember that an anchor is not shown in the text, and that the information
    following it never appears unless a link with the same name is somehow
    selected. In general, you should state all anchors in the table of
    contents at the top of the file.

    An exception might be a `footnote'-like comment, with its own anchor and
    without link in the table of contents --- but with a link somewhere in the
    running text.

@iDead links

    Once the user clicks on a link, the corresponding section is searched for
    in the helpfile. If it is not found, the text browser remains emptly. So,
    when you see an empty browser after clicking some text, CHECK THE LINK
    NAME!