/***********************************************************************
 *
 * TITLE:
 *	help.h
 *
 * AUTHOR:
 *	Kevin J. Miller
 *
 * DESCRIPTION:
 *	Function definitions and structure needed for help.c
 *
 *				CHANGE HISTORY
 *
 * $Log: help.h,v $
 * Revision 1.7  1996/12/19 20:58:28  kevin
 * fixed compiler warnings
 *
 * Revision 1.6  1994/01/07 00:34:45  kevin
 * update non-posix identifiers
 *
 * Revision 1.5  1994/01/06  05:12:06  kevin
 * port for V20
 *
 * Revision 1.4  1993/04/23  20:18:18  kevin
 * InitHelp now returns status
 *
 * Revision 1.3  1993/04/20  01:24:39  kevin
 * added helpPath subresource
 *
 * Revision 1.2  1992/12/17  23:12:19  kevin
 * added showOk resource
 *
 * Revision 1.1  1991/11/09  00:36:38  kevin
 * Initial revision
 *
 ***********************************************************************
 *
 * WARNINGS:
 *
 * EXTERNAL CALLABLE COMPONENTS (PUBLIC):
 *
 * GLOBALS:
 *
 * WAIVERS:
 *
 * NOTES:
 *
 ***********************************************************************/

#ifdef Header
**
** MANUAL
**	HELP 3 "December 17, 1992"
** NAME
**	InitHelp, InitHelpMenu, ShowHelp -- OEL standard help for
**	Motif programs
** SYNOPSIS
**	#include "help.h"
**
**	int InitHelp(parent, title, filename)
**	Widget parent;
**	char *title;
**	char *filename;
**
**	void InitHelpMenu(menuBar, contents, count)
**	Widget menuBar;
**	struct help_list contents[];
**	int count;
**
**	void ShowHelp(w, key, call_data)
**	Widget w;
**	char *key;
**	XmAnyCallbackStruct *call_data;
** DESCRIPTION
**	These functions implement help buttons and a program help based
**	on the OpenLook idea of having a separate help file stored in a
**	common place that is not compiled.
**
** NROFF .RS
** NROFF .nf
** NROFF .ta 3i
** NROFF In general, for a program:	program
** NROFF The help file is:	program.info
** NROFF The resource file is:	Program
** NROFF .fi
** NROFF .ft R
** NROFF .RE
**
**	A help message is a single pane of text that pops up in response to
**	pressing a help button.  Help buttons may appear on dialogs, in which
**	case they are labeled __ Help.  In addition, a help menu is included
**	in this module.
** NROFF .SS "Help file format:"
**	The help file is a UNIX text file consisting of a series of lines.
**	There are three types of lines:
** NROFF .IP "1." 0.3i
**	Comments are lines beginning with a pound sign (#), and are ignored.
** NROFF .IP "2." 0.3i
**	Keys are lines beginning with a colon (:), followed by a legal
**	identifier.  These keys are hardcoded into your program, and are
**	used to retrieve the help text.
** NROFF .IP "3." 0.3i
**	All remaining lines are help text lines and are to be displayed in
**	the help dialog.  These lines belong to the preceding key.
** NROFF .sp
** NROFF .IP "*" 0.3i
**	Any lines in the file appearing before the first key are treated as
**	comments, and are ignored.
** NROFF .IP "*" 0.3i
**	A legal key may contain letters, digits, and the underscore.  The
**	first character may not be a digit.  This is like C identifiers.
** NROFF .LP
**	STANDARD: keys shall begin with lower case letters, be generally
**	lower case, and use upper-case letters rather than underscores to
**	separate words.  Ex.: __ textObject, __ fileFormat, __ coachDitka ...
**	For help on specific widgets, one should use the widget name.
** NROFF .SS "Using help.c:"
**	The files help.c and help.h should be copied into your working
**	directory.  The file contains three global functions, only two of
**	these need to be called.
**	
**	The function _ InitHelp should be called in the main routine before
**	entering the main loop.  The _ parent is the application shell, the
**	_ title is the title for the help dialog, and the _ filename is the
**	name of help file.  The name of the help file should be a single
**	component, and hardcoded to the name of the program with ".info"
**	appended.
**	
**	If the subresource __ helpPath is defined, the specified directories
**	are searched for the help file.  This may be a colon (:) separated
**	list, but typically only a single directory will be specified.  If
**	__ helpPath is not defined, then the __ HELPPATH environment variable
**	is checked.
**
**	If the environment variable __ HELPPATH is defined, the specified
**	directories are searched for the help file.  __ HELPPATH should be
**	a colon (:) separated list of directories similar to __ PATH and
**	__ MANPATH.
**	
**	If __ HELPPATH is not define externally, the following are used:
**
** NROFF .RS
** NROFF .nf
** NROFF .ta 3i
** NROFF /usr/lib/help:/usr/local/lib/help	- if compiled normally
** NROFF \&.:/usr/lib/help:/usr/local/lib/help	- if DEBUG is defined
** NROFF .fi
** NROFF .ft R
** NROFF .RE
**
**	The above are the standard __ HELPPATH in OpenLook, and defaulting
**	to the current directory while compiling the debug version, simpilfies
**	development since you can keep the help file in the same directory
**	as the project.  The definition of __ HELPPATH overrides the
**	__ -DDEBUG compilation option.
**
**	If the help file is found, then this function returns 0, otherwise
**	-1 is returned.
**	
**	The second function _ InitHelpMenu should be called in the main
**	after the menu bar is defined.  The  _ menuBar is the menu bar
**	widget, _ contents is an array of menu labels and help tokens, and
**	__ count is the number of help menu entries.
**	
**	In the main module, you need to declare a static array:
**
** NROFF .RS
** NROFF .nf
** NROFF .ta 0.5i
** NROFF .ft B
** NROFF static struct help_list help_menu[] = {
** NROFF 	{ "Overview", "Overview" },
** NROFF 	{ "File Menu", "FileMenu" },
** NROFF 	{ "Options Menu", "OptionsMenu" },
** NROFF 	{ "Data Files", "DataFiles" },
** NROFF 	{ "Output", "Output" }
** NROFF };
** NROFF .fi
** NROFF .ft R
** NROFF .RE
**
**	You can then call _ InitHelpMenu as follows:
**
** NROFF .RS
** NROFF .nf
** NROFF .ft B
** NROFF InitHelpMenu(menuBar, help_menu, XtNumber(help_menu));
** NROFF .fi
** NROFF .ft R
** NROFF .RE
**
**	In the above example, the first text string of each pair will appear
**	in the help menu.  The second string is the help token to search
**	for.  Thus if the user selects __ Options __ Menu, the help file will
**	be searched for the text __ :OptionsMenu.
**
**	The third global function _ ShowHelp is the help button callback.
**	
**	Assuming that you defined a help button (Widget help) you would then
**	add the callback as:
**	
** NROFF .RS
** NROFF .nf
** NROFF .ft B
** NROFF XtAddCallback(help, XmNactivateCallback, ShowHelp, "demoMode");
** NROFF .fi
** NROFF .ft R
** NROFF .RE
**	
**	For this example, the help file will be searched for the line
**	__ :demoMode, and all text line from there on to the next key will
**	be displayed.
** RESOURCES
**	If the __ helpPath subresource is defined, then it is used rather
**	than the HELPPATH environment variable.  In this case, the
**	default help path is not appended.
**
** NROFF .RS
** NROFF .nf
** NROFF .ft B
** NROFF *help.options.helpPath: /local/seg/help
** NROFF .fi
** NROFF .ft R
** NROFF .RE
**
**	There is a bug in Motif such that the __ OK button will not work
**	if the help panel is brought up after a modal popup.  By default,
**	the __ OK button will not appear.  However, if you want the __ OK
**	button, you can get it with the following subresource:
**
** NROFF .RS
** NROFF .nf
** NROFF .ft B
** NROFF *help.options.showOk: True
** NROFF .fi
** NROFF .ft R
** NROFF .RE
**
**	This is useful when running under the Open Look window manager
**	which does not support a Close button for dialogs like the
**	Motif window manager does.
#endif

#ifndef help_h
#define help_h

#ifndef lint
static const char rcsid_help[] = 
    "$Id: help.h,v 1.7 1996/12/19 20:58:28 kevin OEL $";
#endif

/*
 * structure for help menu
 */
struct help_list {
    char *label;
    char *token;
};

/*
 * global functions
 */
extern int InitHelp(Widget, char *, char *);
extern void InitHelpMenu(Widget, struct help_list [], Cardinal);
extern void ShowHelp(Widget, char *, XmAnyCallbackStruct *);

#endif