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. In Xic, the help search path can be set in the environment with the variable XIC_HLP_PATH, and/or may be set in the technology file (the technology file overrides 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. A warning message will be issued 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, outside of !!TEXT and !!HTML blocks (described below), lines with `*' or `#' in the first column are ignored, as they are assumed to be comments. Lines that begin in the first column with ``!!(space)'' (space character following two exclamation points) anywhere are also ignored, as comments. Blank lines outside of the !!TEXT and !!HTML fields are ignored. Leading white space is stripped from all lines read, which can be a problem for maintaining indentation in formatted plain text. To add a space which will not be stripped, one can 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:

Xic
Defined when running the Xic program with any feature set.

XicII Defined when running the Xic program with the XicII feature set.

Xiv
Defined when running the Xic program with the Xiv feature set.

WRspice
Defined when running the WRspice program.

Windows
Defined when running under Microsoft 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.

!!SEEALSO keyword-list
This keyword, if used, is expected to be found at the end of the topic text. 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 that follow. If a keyword in the list is not found in the database, it is silently ignored. The keywords listed must be given in a !!KEYWORD line, and not contain named anchor references (violating entries are silently ignored).

!!SUBTOPICS keyword-list
This keyword, if used, is expected to be found at the end of the topic text. 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, the order is unimportant.

The following definitions supply header and footer text which will be applied to each page. These should be defined at most once each in the database.

!!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.

The following keywords inplement a means to mark topics that are from imported or supplemental files. For example, in Xic, many of the WRspice help files are included for reference and to satisfy links in the Xic help files. There is a need to mark these pages as applying to the WRspice program, otherwise the information could be confusing. In the Xic help system, the pages from WRspice have a banner just below the header identifying the topic as applying to WRspice.

!!MAINTAG tagname
This keyword should appear once in the database, probably defined along with the header/footer. The tagname is an arbitrary short keyword which identifies the database, such as ``Xic''.

!!TAG tagname
This should be given at the top of each help file in the database. Those files that are part if the main database should have the same tagname as was given to !!MAINTAG. Files containing supplemental information should have some other tagname, e.g., ``WRspice''

!!TAGTEXT tagname
This should be given once only in the database, probably where the !!MAINTAG is defined. It is followed by HTML text, in the manner of the header and footer. This text will be inserted just below the header in topic pages that come from files with tags that differ from the main tag. For this to happen, both the tag and main tag must have been defined. In the text, the token ``%TAG%'' will be replaced with the actual tag that applies to the topic.