DataMuseum.dk

top - metrics - download

    Length: 2217 (0x8a9)
    Types: TextFile
    Names: »README«

└─⟦52210d11f⟧ Bits:30007239 EUUGD2: TeX 3 1992-12
    └─⟦c319c2751⟧ »unix3.0/TeX3.0.tar.Z« 
        └─⟦036c765ac⟧ 
            └─⟦this⟧ »TeX3.0/TeXcontrib/gnutex/Help/README« 

TextFile

These are the files for the customizable help facility.

Contents:
	help.3		The man page for help().
	help.h		Include file showing return status values.
	help.c		The source for help() itself.

	Makefile	Makes `htest', the help testing program.
	htest.c		Source for htest.
	helpfile	Sample help file.
	alt-helpfile	Other help file; contains help info for "alternate" key

Suggestion:  format the man page (nroff -man help.3 | lp) and read it,
then read the comments in the prologue to the code.  Help-file writers
might want to look at the helpfile, and run htest to see how it looks.
Run the help test by typing "make", then "htest".

The basic idea for this routine is to provide a help interface like
Edit/1000:  you ask for help, it prints out the help text for that
subject only.  You can set up the help file so that several synonyms
will cause the same help text to appear.  You can provide context-
sensitive help by setting up the calling routine to use a different
file depending on the context or desired verbosity level.

Advantages to using this help code over using `more' on a help file:

1.  No "skipping" messages or unsightly "(73%)" prompts from `more'.
You get the help text on only the subject you asked for, instead of
being left in the file and being forced to type "q".

2.  Help keywords (the subject that the user asks about) can be made
case-insensitive if you provide keywords in both cases in your help
file.  `more' insists on exact matches.

3.  Various speed hacks.  Faster than vfork()+exec(), much faster than
system().  Doesn't re-open your help file if the user asks for help
more than once on the same file.

Disadvantage of this help code over `more':

The code as written doesn't scroll, it just cats the text to your
screen.  This means that you should try to fit everything on 23 lines
or less.  (This is not considered a real problem, especially because
you can end an entry with "Get help on <whatever detail you mentioned>
for more information", and because a screenful is an awful lot of
material for a user to digest.)

Future directions:

The routine could be sped up even more by replacing the stdio calls
with open/read/write/close, but it runs quite swiftly even now.