Help Database Files

The help information is obtained from database files suffixed with .hlp found along the help search path. These directories may also contain other files referenced in the help text, such as image files. The help search path can be set in the environment with the variable SPICE_HLP_DIR, and/or may be set with the helppath variable, which will override the environment. These files have a simple format, allowing users to create and modify them. Each help entry is associated with one or more keywords, which should be unique in the database. The help system has a debugging mode, which can usually be switched on by the application, which will issue a warning message on stderr if a name clash is detected. The files are ASCII text, either in DOS or Unix format. Fields are separated by keywords which begin with ``!!''. Although the help system provides rich-text presentation from HTML formatting, entries can be in plain text. A sample plain-text entry has the form:

!!KEYWORD
excmd
!!TITLE
Example Command
!!TEXT
    This command exists only in this example.  Note that the
    !!keywords only have effect if they start in the first
    column.  The blank line below is optional.

!!SUBTOPICS
akeyword
anotherkeyword
!!SEEALSO
yetanotherkeyword

In this example, the keyword ``excmd'' is used to access the topic, and should be unique among the database entries accessed by the application. The text which appears in the topic (following !!TEXT) is shown indented, which is recommended for clarity, but is not required.

In ``.hlp'' files, lines anywhere with `*' or `#' in the first column are ignored, as they are assumed to be comments. Blank lines outside of the !!TEXT field are ignored. Leading white space is stripped, which can be a problem for maintaining indentation in formatted plain text. To add a space which will not be stripped, use the HTML escape `` ''.

The following `!!' keywords can appear in ``.hlp'' files. These are recognized only in upper case, and must start in the first text column.

!!(space) anything
A line beginning with two exclamation points followed by a space character is ignored.

!!KEYWORD keyword-list
This keyword signals the start of a new topic. The keyword-list consists of one or more tokens, each of which must be unique among all topics in the database. The words are used to identify the topic, and if more than one is listed, the additional words are equivalent aliases. The keyword-list may follow !!KEYWORD on the same line, or may be listed in the following line, in which case !!KEYWORD should appear alone on the line.

Punctuation is allowed in keywords, only white space characters can not be used. The `#' character has special meaning and should not be part of a keyword name. Also, character sequences that could be confused with a URL or directory path should be avoided. The latter basically prohibits the `/' character (and also ` \ ' under Windows) from being included in keywords. There are special names starting with `$' which are expanded to application-specific internal variables, as described below. To avoid any possibility of a clash, it is probably best to avoid `$' in general keywords.

It is often useful to include a meaningful prefix in keywords to ensure uniqueness, for example in Xic, all commands have keywords prefixed with ``xic:''.

!!TITLE string
The !!TITLE specifies the title of the topic, and should follow the !!KEYWORD specification. The title text can appear on the same line following !!TITLE, or on the next line, in which case !!TITLE should appear alone in the line. The title is printed at the top of the topic display, and is used in menus of topics.

!!TEXT
This line signals the beginning of the topic text, which is expected to be plain text. The keyword is mutually exclusive with the !!HTML keyword. The lines following !!TEXT up to the next !!KEYWORD, !!SEEALSO, or !!SUBTOPICS line or end of file are read into the display window. The plain text is converted to HTML before being sent to the display in the following manner:

1. The title text is enclosed in <H1>...</H1>.
2. Each line of text has a <BR> appended.
3. The subtopics and see-alsos are preceded with added <H3>Subtopics</H3> and <H3>References</H3> lines.
4. The subtopics and see-alsos are converted to links of the form <A HREF="keyword">title</A> where the keyword is the database keyword, and the title is the title text for the entry.

Note that the text area can contain HTML tags for various things, such as images. Also note that text formatting is taken from the help file (the <BR> breaks lines), and not reformatted at display time. The !!HTML line should be used rather than !!TEXT if the text requires full HTML formatting.

!!HTML
This line signals the beginning of the topic text, which is expected to be HTML-formatted. The keyword is mutually exclusive with the !!TEXT keyword. The parser understands all of the standard HTML 3.2 syntax, and a few 4.0 extensions. References are to keywords found in the database and general URLs. Image (.gif, etc.) files can be referenced, and are expected to be found along with the .hlp files.

!!IFDEF word
This line can appear in the block of text following !!TEXT or !!HTML. In conjunction with the !!ELSE and !!ENDIF directives, it allows for the conditional inclusion of blocks of text in the topic. The word is one of the special words defined by the application. Presently, the following words are defined:

in Xic	Xic
in WRspice	WRspice
in either, under Windows	Windows

If word is defined, the text up to the next !!ELSE or !!ENDIF will be included in the topic, and any text following an !!ELSE up to !!ENDIF is discarded. If word is not defined, the text up to the next !!ELSE or !!ENDIF is discarded, and any text following an !!ELSE is included. The constructs can be nested. A word that is not recognized or absent is ``not defined''. Every !!IFDEF should have a corresponding !!ENDIF. The !!ELSE is optional. The !!SEEALSO and !!SUBTOPICS lines can appear within the blocks.

Example:

!!HTML
   Here is some text.
!!IFDEF Xic
   You are reading this in Xic.
!!ELSE
!!IFDEF WRspice
   You are reading this in WRspice.
!!ELSE
   You are not reading this in Xic or WRspice.
!!ENDIF
!!ENDIF

!!IFNDEF word
This keyword can appear in the block of text following !!TEXT or !!HTML. It is similar to !!IFDEF but has the reverse logic.

!!ELSE
This keyword can follow !!IFDEF or !!IFNDEF and defines the start of a block of text to include in the topic if the condition is not satisfied.

!!ENDIF
This keyword terminates the text blocks to be conditionally included in the topic, using !!IFDEF or !!IFNDEF.

!!INCLUDE filename
The keyword may appear in the text following !!TEXT or !!HTML. When encountered in the text to be included in the topic, the text of filename, which is searched for in the help search path if not an absolute pathname, is added to the displayed text of the current topic. There is no modification of the text from filename.

If the filename is a relative path to a subdirectory of one of the directories of a directory in the help search path, the subdirectory is added to the search list. Thus, an HTML document and associated gif files can be placed in a separate subdirectory in the help tree. The HTML document can be referenced from the main help files with a !!INCLUDE directive, and there is no need to explicitly change the help search path.

!!REDIRECT keyword target
This will define keyword as an alias for target. The target can be any input token recognizable by the help system, including URLs, named anchors, and local files. For example:

!!REDIRECT nyt http://www.nytimes.com

Giving ``!help nyt'' in Xic or ``help nyt'' in WRspice will bring up a help window containing the New York Times web page.

!!HEADER
The text that follows, up until the next !!KEYWORD or !!FOOTER, is saved for inclusion in each page composed from the !!HTML lines for database keywords. The header is inserted at the top of the page. There can be only one header defined, and if more than one are found in the help files, the first one read will be used.

In the header text, the literal token %TITLE% is replaced with the !!TITLE text of the current topic when displayed.

!!FOOTER
The text that follows, up until the next !!KEYWORD or !!HEADER, is saved for inclusion in each page composed from the !!HTML lines for database keywords. The footer is inserted at the bottom of the page. There can be only one footer defined, and if more than one are found in the help files, the first one read will be used.

!!SEEALSO keyword-list
The keyword-list consists of a list of keywords that are expected to be defined by !!KEYWORD lines elsewhere in the database. A menu of these items is displayed at the bottom of the topic text, under the heading ``References''. The keywords specified after !!SEEALSO can appear on the same line separated with space, or on multiple lines. If a keyword in these lists is not found in the database, the normal action is to ignore the error. The application may provide a debugging mode, whereby unresolved references will produce a warning message.

!!SUBTOPICS keyword-list
This produces a menu of the topics found in the keyword-list very similar to !!SEEALSO, however under the heading ``Subtopics''. This can be used in addition to !!SEEALSO.