DIYHelp allows you to build your own help indices using your own keywords and topic labels. It does this by searching a directory tree that you specify for files containing a keyword. All of the files that are found are placed in a list. Each element of this list contains the full path to the file, and a descriptive label. Initially, the descriptive label is the filename, but may be edited to whatever the user wishes. As the user becomes more familiar with the material, they may wish to further alter the descriptive labels. In this document, help index refers to the current list of keywords and file descriptions in the program. Help file refers to a text file containing this information that may be read by the DIYHelp program.
One advantage of DIYHelp is that it doesn't try to display the information itself. DIYHelp maintains an editable list of browsers that will display many different information formats. You can configure DIYHelp to the browsers that are available on your system.
Formally, DIYHelp is a two-level hierarchical list. The initial selection
covers a broad area of the field of knowledge, and the subsequent selection
displays a file of information on a specific topic. Obviously, this is a
limitation. If we limit the number of items on any list to ten, we are limited
to only 100 specific topics. However, as DIYHelp is able to maintain many help
indices, each help index may be dedicated to a particular area, effectively
providing three levels. Some users will be happy to have one huge help index,
while others may prefer a large number of very specific help indices.
This configuration tells the program that
The second part of the help file describes the keywords and files as follows:
For this simple help file, there are seven keywords. The first keyword is
associated with only one link in the
Then change to the
to reflect this and save the file. For instance, if you want the executables to
be in
DIYHelp requires a Tcl/Tk interpreter and of course the
If you wish to add the keyword and file descriptions to the current help list,
after a search, press the Add keyword button below the Current
keyword window.
The field at the top right of the DIYHelp window labeled Top
search directory is the path to a directory. This directory is the top of
the directory tree that will be searched for keywords to build a help list. You
may enter a directory path into the entry window, or click on the Top
search directory button to browse the directory structure. If this is left
blank, the search will begin from the top of the local directory tree.
This is usually unwise, as such a search may take a long time.
The field below this, labeled Search directory name,
allows you to specify only certain directory names in the search. For example,
HTML files may be stored in a subdirectory named
If you look at this file in an HTML browser, you will see that it looks a lot
like the help index. Each browser has a list of extensions under it that tell
DIYHelp what files to pass to it. At the bottom is
If you wish to delete a keyword, highlight that keyword and
press the Delete keyword button below the list. This will remove the
keyword and all associated file descriptions from the help list.
Currently, the browser must be closed before DIYHelp will respond again.
The filename itself may not be very helpful in deciding
what sort of information that file contains. In the DIYHelp help file, all of
the filenames would be the same, as all of the file descriptions are linked to
this file. A file description may be edited by selecting it and pressing the
Edit button below the Help files list. An editing window will
appear, and you may change the description to something more informative.
Pressing the <Return> key or the OK button will change the file
description. Pressing the Cancel key will leave the current description
intact.
Enter the top level directory to search in the
Top search directory field, the specific
name of directories that you would
like to search below the top level directory in the Search directory name
if applicable, the file mask in the Search
mask field to select particular files if desired and change the browser if
that is necessary.
Now enter a keyword in the Current
keyword field and press <Return>. When the program has completed the
search for that keyword, a list of filenames will appear in the Help
files list or a message notifying you that no files were found containing
that keyword.
If one or more filenames were found, it is time to select those that are useful.
It is possible that files were found that are not the proper type for the
browser. Say that you wanted to use an HTML browser but noticed that PDF files
had been included in the list. You could immediately delete those files from
the list (although you might want to build a separate list that used a PDF
browser in which they would be included).
View the files remaining in the list one by one. Delete those that do not
relate to the keyword in the way that you intended. For instance, if you wanted
to build a help list with the keyword save that related to saving files,
you would probably delete any files that dealt with bank savings accounts or
sales at the local shopping center. You may want to
edit the file descriptions as you go.
When you are satisfied with the file descriptions associated with that keyword,
click on the Add keyword button to add that keyword to the list. Repeat
these steps for as many keywords as you would like to add to the list. When you
have added as many as you want, save the list to
a help file. Remember, when you save the help list, you will also save the
configuration described in the fields at the top of the window.
Try editing the file description by clicking on the Edit button after
selecting
Now look at this file. The following lines should have been added:
Notice that in this line, the full path of the file is included, and there is no
name tag. You may continue to expand and refine your help files in this way.The help file structure
DIYHelp indices are written in HTML and have two parts. The first is the
"indexing information", that describes the top directory to be searched
and optionally the specific directories below it. A typical configuration
section (from the diyhelp.dyh file) is shown below.<html>
<!- this is a generated file - if you edit it, adhere to this format!>
TOPDIR=/usr/local/diyhelp
SEARCHDIR=data/usr/local/diyhelp
is the top of the directory tree to be searched. The specification for
for the subdirectories to be searched means that DIYHelp will search only
directories named data, if left blank, it searches all directories
beneath TOPDIR in this case. Similarly, DIYHelp searches all files
that look like text.<dl>create
<dd><a href="./diyhelp.htm#diybuild">new help file</a></dd>
</dl>
<dl>delete
<dd><a href="./diyhelp.htm#delhelp">help file</a></dd>
<dd><a href="./diyhelp.htm#delkw">keyword</a></dd>
</dl>
<dl>edit
<dd><a href="./diyhelp.htm#browser">browser</a></dd>
<dd><a href="./diyhelp.htm#edit">edit strings</a></dd>
<dd><a href="./diyhelp.htm#fileedit">help file description</a></dd>
<dd><a href="./diyhelp.htm#filemask">file mask</a></dd>
<dd><a href="./diyhelp.htm#searchdir">search directory name</a></dd>
<dd><a href="./diyhelp.htm#topdir">top directory</a></dd>
</dl>
<dl>file
<dd><a href="./diyhelp.htm#filedesc">explanation</a></dd>
</dl>
<dl>keywords
<dd><a href="./diyhelp.htm#keyword">explanation</a></dd>
</dl>
<dl>open
<dd><a href="./diyhelp.htm#open">help file</a></dd>
</dl>
<dl>save
<dd><a href="./diyhelp.htm#save">help file</a></dd>
</dl>
diyhelp.htm file,
while the third keyword is associated with six links. Note that the links would
typically be to different files, not all to one file as in this example. See
Building a help list and Adding to a help list.
Comments may be added to help files by inserting lines beginning with a hash
"#" character. Currently, they will be lost if the help file is saved by the
DIYHelp program. As the help files are HTML written in plain ASCII text, they
may be edited and saved in any text editor.Installing the program
DIYHelp is distributed as a compressed file. Typically, this file should be
placed in the directory where the diyhelp directory will be
created. On UNIX systems, this will probably be /usr/local. The
file is then uncompressed, creating the diyhelp directory and
placing all the uncompressed files therein. The usual method would be:/usr/local> tar -zxvf diyhelp.tgzdiyhelp directory and enter make.
This will set the home directory to the correct value and copy the two
executable files to a directory in the PATH, often /usr/local/bin.
One is the shell script hidegrep.
This script is needed to conceal grep from the Tcl/Tk interpreter,
which reports a nonexistent error otherwise. The other is the startup script
diyhelp. If you want these files in a directory other than
/usr/local/bin, edit the line in makefile reading:set EXECDIR /usr/local/bin/opt, edit the line to read:set EXECDIR /optgrep
program. If these are available, the program should be ready to run. Enter
diyhelp on the command line and the program should start.
Basic usage
When DIYHelp starts, it will automatically load its own help
file if no other help file is specified on the command line. This help file is
especially created for DIYHelp, and cannot be recreated by using the "Search"
facility. The file diyhelp.dyh shows how the system works by
making use of links to this file (diyhelp.htm).Indexing information
The field at the top left of the DIYHelp window is labeled
Current keyword. The DIYHelp program will search for this word in all of
the files in all of the directories that are defined by the fields on the top
right of the window. Performing a search will result in a list of the files
that contain this word being displayed in the list labeled Help files.
A search will be performed when you press the <Return> key while editing
the Current keyword field or click on the Search button as long as
there is something in the Current keyword field.html for each of a
number of directories that you would like to search. By specifying this, you
can avoid having DIYHelp search directories in which you know there is no useful
information.Browsers and file types
When DIYHelp is asked to display a help file, it starts a browser program to
display the file. DIYHelp tries to identify the file type by the extension. Thus
if the file has the extension *.htm or *.html, it will
start an HTML browser with that file. The file browsers.cnf is read
when DIYHelp starts up to get the information on browsers.<html>
<!- this is a generated file - if you edit it, adhere to this format!>
<dl>netscape
<dd>htm</dd>
<dd>html</dd>
</dl>
<dl>acroread
<dd>pdf</dd>
</dl>
<dl>gv
<dd>ps</dd>
<dd>eps</dd>
</dl>
<dl>startless
<dd>*</dd>
</dl>
</html>
startless. This
is the default browser for any file extension that isn't listed in
browsers.cnf. It starts up less in a terminal window.
If you would like to use another browser for HTML, you may just change
netscape to that browser. Also, if you have a file browser that
will handle other useful file types, you can add a section describing the
extensions that it will handle.Keyword display
The list at the lower left of the DIYHelp window shows the
Keywords included in the current help list. These are the words that have
been found in the files associated with each keyword. To see the list of file
descriptions associated with each keyword, double-click on that keyword or
select the keyword and click on the List files button below the list.File description display
The list at the lower right shows the file descriptions associated with the
selected keyword. After a search is conducted, the filenames are listed here.
By double clicking on one of the file descriptions, or selecting it and clicking
on the View button below the list, the browser named in the
Browser field will be invoked to display that file.Deleting file description
A keyword may be found in files that do not have much
to do with what you want to know. File descriptions may be deleted from a help
list by selecting that file description and pressing the Delete file
button.Opening help files
Selecting Open on the File menu or pressing Ctrl-O will
bring up a listing of help files in the DIYHelp data directory.
Selecting one of these and clicking OK will open that file in DIYHelp.
Using the extension .dyh for help files will make it easier to
recognize them.Saving help files
When a help file is created or edited, it must be saved so that it will be
available the next time it is used.
Selecting Save on the File menu or pressing Ctrl-S will
save the current help list. If no file name is currently specified, you will
have to enter a new one or select an existing one that will be overwritten.
To change the name of the current help file, select Save As on the
File menu.Exiting DIYHelp
Selecting Quit on the File menu or pressing Ctrl-Q will
exit DIYHelp. If there are unsaved changes, you will be queried whether to save
them before exiting.Building a help list
To build a help list, select New on the File menu or press
Ctrl-N. If there are unsaved changes to the current help list, you will
be queried whether to save them. All of the fields except Browser will
be cleared, and the help list will be empty.Adding to a help list
As an exercise, try adding a keyword to the diyhelp.dyh list. As
the configuration should already be set to to proper values, enter the keyword
"hierarchical" in the Keyword field and press <Return>. The search
should find at least one match in this file (diyhelp.htm).
Selecting diyhelp.htm from the Help files list and clicking
View should start another HTML browser showing this file.diyhelp.htm. Change the filename to a more descriptive
label, perhaps "structure". Then add the keyword/file description to the list
by clicking on the Add keyword button. Select File->Save As
and save the new file with a different name, say newhelp.dyh.hierarchical
/usr/local/diyhelp/data/diyhelp.htm structure