NAME

kjb_help - Implements a simple help system.

SYNOPSIS

#include "l/l_help.h"

Example compile flags (system dependent):
  -DLINUX_X86_64 -DLINUX_X86_64_OPTERON  -DGNU_COMPILER 
   -I/home/kobus/include
   -L/home/kobus/misc/load/linux_x86_64_opteron -L/usr/lib/x86_64-linux-gnu
  -lKJB                               -lfftw3  -lgsl -lgslcblas -ljpeg  -lSVM -lstdc++                    -lpthread -lSLATEC -lg2c    -lacml -lacml_mv -lblas -lg2c      -lncursesw 


int kjb_help
(
	const char *program_name,
	const char *topic_line
);

DESCRIPTION

This routine implements a simple help system. It uses help files of a special but simple format. The format is, by convention, documented at the begining of each help file. In case no sample help file is available, the format is desribed below. If a help file has been succesfully set with set_help_file(), then that help file is used. If not, then a default help file is looked for on the basis of the program name argument. In this case, the current directory, the users help directory, and a shared help directory are searched, in that order for a file named <program_name>.help. Currently, the help directory is "~/doc/help", and the shared help directory is "~iis/doc/help", but these locations are easily changed without forcing an update of the documentation. The routine also takes a help topic as a argument. If it is null, or empty, then the top of the help topic tree is used, which by convention is equivalent to "introduction" and <program_name>. If the topic is the special topic "topics", then a list of topics is printed. Finally, if the topic is the special topic "help", then help on using help is provided. If the high level input module "get_command_text()" is being used for input, then help is called as part of pre-processing, and the code calling get_command_text() will never see a command "h" or "help". Thus there is no need to implement a user help command in this case. However, kjb_help() can be additionally called in other contexts with no ill affect.

RETURNS

ERROR if there are problems and NO_ERROR otherwise. If there is no help on the requested topic, then a message is printed to that effect, but it is not considered an error. One possible cause of error is if the help file is not available.

NOTE

It is a waste to implement a user help command (as well as many other features) if get_command_text() is being used to get input.

FILE

The help file format is as follows. Formatting is largely under the control of the first column. Lines with # in the first column are comment lines Lines starting with / indicate the start of a help topic. Whatever follows the / is the topic title, up to another /, which indicates the start of an alternate topic title. There must be an "introduction" topic, which is the top of the topic tree. If the user does not specify a help topic, then this one is used. By convention, the program name is a synomym, and thus is an alternate name. Lines starting with & indicate a "subroutine call" to the help topic which follows the &. When the help routine gets to one of these lines, a menu is created for all the & topics. Text is left justified at the indent level in this file. Thus a new line is started whenever the indent changes. This file thus specifies the left indent, but not the number of lines. Since the help reader does line justification, formatting in the help file is not critical. Lines starting with | are protected from the formatting described in the preceeding paragraph. This is necessary for making tables. The "|" is not printed. Phrases within + are highlighted where screen support allows, and become underlined (or bold) in the man pages. To get a double "+" use two. This is proabably not the best choice, adn could change. Lines starting with @ are used to restrice the lines that follow to a specific processing routine. If the @ is followed immediately by "help", then the subsequent lines are seen by "help", but not other readers of the file, such as the man page generator. Use "@all" to go back to normal mode. Lines beginning with % are used to restrict the lines that follow to a specific system. The % should be followed by one or more system names (unix, dos), or "all" to reset back to lines relevant to all systems.

set_help_file(3), get_command_text(3)

DISCLAIMER

This software is not adequatedly tested. It is recomended that results are checked independantly where appropriate.

AUTHOR

Kobus Barnard

DOCUMENTER