Help Tools - utilities for creating a help database
---------------------------------------------------
TurboPower Software
1/90
Released to the public domain

Overview
------------------------------------------------------------------------------
This "tool box" is a collection of programs for creating, editing, modifying
and testing the text files of an Object Professional (or Turbo Professional)
help system. Most of these were created to help us with the huge Object
Professional help system (over 1 megabyte of help text). The tool box
currently consists of the following programs:

SCANHELP - scans source files and produces help text files
PRNHELP - prints help files (in "display" format) for proof-reading
MODHELP - renumbers help files
HELP - a small help testing program

These files are included here in executable form only. Source code for
PRNHELP, MODHELP and HELP is available (SCANHELP is not; it depends on source
code modified from Turbo Analyst). The source code is in a compressed file
named HLPSRC.LZH and is in Data Library 6 of the PCVENB Compuserve forum.

Below is a detailed discussion of each tool:

SCANHELP
-----------------------------------------------------------------------------
SCANHELP is used to creating help systems for program libraries (like
Object Professional or B-Tree Filer). The input is one or more Turbo Pascal
source code files; the output is corresponding help text files.

SCANHELP creates help topics for each interfaced object, method, procedure and
function in a program. The help topic consists of an automatically assigned
topic number, the object or routine declaration, and a 'See also' section of
cross-references.

Object topics have the following format:

;
;-------------------------------------------------
!TOPIC
!NOINDEX
= object();

See also:

Method, procedure and function topics have this format:

;
;-------------------------------------------------
!TOPIC
!NOINDEX
.

See also:

A "See also" list can also be created after each topic. SCANHELP has some
fixed logic for formatting this list. First, it tries to put all of your
cross-references, separated by two spaces each, onto one line prefaced by See
also:. If the cross-references won't fit, SCANHELP writes a blank See also
line, then builds a two or three column table under that line. The number of
columns is controlled by a command line option (the default is three columns).
This can be overridden by a directive in your source code (more on these
directives later).

Here are some example See also tables:

See also: ^D0001^EThisTopic^E ^D0057^EThatTopic^E

or
See also:
^D0001^EThisTopic^E ^D0057^EThatTopic^E ^D0057^EThatTopic^E
^D0001^EThisTopic^E ^D0057^EThatTopic^E ^D0057^EThatTopic^E
^D0001^EThisTopic^E ^D0057^EThatTopic^E ^D0057^EThatTopic^E

or
See also:
^D0001^EThisLongTopicName^E ^D0057^EThatLongTopicName^E
^D0001^EThisLongTopicName^E ^D0057^EThatLongTopicName^E
^D0001^EThisLongTopicName^E ^D0057^EThatLongTopicName^E

These examples show the text exactly as it appears in your help text file.
Remember that the control characters and the topic numbers aren't visible in
the final help display.

Also note that the tabs stops are fixed by SCANHELP; you can't change them.
For 2-column tables the tab stops are at columns 4 and 38. For 3-column
tables the tab stops are at columns 2, 28 and 52.

SCANHELP assumes a text width of 76 characters. It includes such a command at
the top of the first output file; and, it prevents cross-reference topics from
extending beyond that column.

The "See also" tag is always written. If you don't want it, you'll need to
manually remove it from the finished text file.

SCANHELP also creates a topic entry for the unit itself. This is always the
first topic it creates and it contains the unit name and a large
cross-reference table of _all_ known topics. This table is mostly for use in
testing and refining the help text; it is not meant to be a finished product.
The topics are listed in topic number order; no object prefixes are included.
This is the only topic that doesn't have a !NOINDEX command after it so it is
the only topic that will show up in a help index.

SCANHELP Directives
-------------------
SCANHELP has several directives for customizing its behavior. A directive is
something that you place in the source code before running SCANHELP.

All directives have the format {#L...} where:
{ } are normal comment braces
# signals that this is a SCANHELP directive
L is a command letter
... are one or more parameters for the directive

#Z+ / #Z- Toggle Private
This directive controls what symbols are included in the help text. The
default is all interfaced objects, methods, procedures and functions. If you
want to exclude one or more these symbols, then place a {#Z+} directive in
front of them and a {#Z-} directive following. The Z+ signals that all
following symbols are private and should not be included in the help text.
The Z- turns off the "private" attribute.

#X [Object.]Topic [[Object.]Topic...] Include cross-reference
This directive specifies that Topic is to be included in the "See also" list
for the current symbol.

If the topic is an ambigous method name (like Init or Done), you can
optionally include the [Object.] prefix to resolve the ambiguity. Note that
the _only_ time the [Object.] prefix is required is when the
cross-referenced method belongs to a different object, but has the same name
as a method in the current object.

You can have as many topics in one #X directive as you like. Or, you can
specify multiple #X directives. For example, the following are equivalent:

{#X TopicA TopicB TopicC}

and

{#X TopicA}
{#X TopicB}
{#X TopicC}

#C2 / #C3 Column count
This directive overrides the global column count (for the See also table)
for the current object. You would use this directive for occasional
deviations from the global column count. That is, if you specified a global
column count of three, but you have a couple of very long topic names, you
may want to specify #C2 whenever those long topic names are included in a
See also list.

SCANHELP Command line options:
------------------------------
Some of SCANHELP's behavior is customized from the command line. Here is the
command line format:

SCANHELP [options] unitname [unitname...]

Here is a description of SCANHELP's options:

/N don't show the comment after each symbol declaration

The default is for one comment immediately following a symbol declaration to
be included as the text for that help topic. If you don't want this, specify
the /N option. (SCANHELP does some minor reformatting to this comment: it
removes the comment braces and adds a discretionary period at the end.)

/T startingtopic specify the starting topic number

The default starting topic number is one. If you want to start at a different
number, use the /T option.

/I topicinc specify the topic increment value

The default topic increment value is one. That is, topics are numbered
sequentially, without gaps, from the starting topic number. If you want gaps
between your topic numbers, specify the increment here.

/2 use 2 columns for "See also" tables

The default number of columns is three. If you want to change this for all
topics, use the /2 option. If you only want to change it for a few topics,
use the #C2 option within your source file.

/S sort cross-references

The default behavior for the cross-reference table (the See also's) is to
present the cross-references in the same order they appear in the #X
directives in the source code. This gives you complete control over the format
of the table. Where you are not interested in any particular topic order,
you'll probably want to sort the table with /S.

/F fileinc specify the between-file increment value

SCANHELP can process multiple files at once. The default is to make the topic
numbers contiguous between files. This isn't desirable if you intend to
manually add some help topics to the text file. Use the /F option to specify a
gap to leave between files.

/D Don't wrap the procedure/function declarations

When word-wrapping is on, long procedure/function declarations may fall victim
to wrapping (if they extend beyond column 74). Remember that SCANHELP inserts
the object or unit name into every declaration. That means that declarations
that are less than 74 characters in the source code may be expanded beyond
that in the final help file. Using the /D option will surround all
declarations with !NOWRAP / !WRAP commands to prevent wrapping. The
negative effect of this is that your declarations may now extend slightly
beyond the viewing area of the help window. The best solution is to modify the
source code and make sure that all declarations are short enough to fit
without being word-wrapped.

SCANHELP Process
----------------
So, putting this all together, the standard process for creating a help text
is as follows:

1. Annotate source listings with # directives
2. Run SCANHELP on all files (wildcards ok)
3. Build a "main file" with !INCLUDE statements for the newly created
help text files.
4. Test and manually refine the help text

Typically, manual refinements would include adding text to the unit topic,
adding data declaration topics and adding sub-indexes to objects and units
that have too many topics to put in one index.


PRNHELP
-------
PRNHELP is a help text proof-reading aid. It produces printed listings of your
help text as it will appear in a help window. It uses different printer fonts
to distinguish between the various types of text: normal, cross-reference
topic or highlighted.

PRNHELP has only one command line option:

/X print cross-reference topic numbers

Use this option if you want PRNHELP to print the topic number in front of
every cross-reference. This is useful for checking for topic numbers of '0000'
(that is, cross-reference topics that SCANHELP wasn't able to fill in).
However, this tends to reduce the readability of the listing, particularly
when you have cross-reference topics embedded in text.

As supplied, PRNHELP assumes that you are printing to a laser printer with a
"G" cartridge. It prints the help text in the following fonts:

Default text PrestigeElite
^A FlexAttr Courier
^B FlexAttr PrestigeBold
^C FlexAttr PrestigeItalic
^D IndexMark PrestigeElite 16.66
^E XrefMark PrestigeElite Underscore

If you are using some other printer, or wish to use fonts other
than the ones that PRNHELP uses, you'll need to modify the source code. The
escape sequences are kept in two arrays: FontsOn and FontsOff. See the source
code for more information on how to change these arrays.


MODHELP
-------
MODHELP modifies the topic numbers of existing help files. Its default
behavior is to renumber the topics, starting from one and incrementing by one,
in the order in which it encounters them. This has the effect of compressing
out all the unused topic numbers. (Each unused topic number consumes 8 bytes
of space in the help file and 2 bytes of heap space in a program.)

If you used SCANHELP to create the help text files, you may have some
cross-refrences with zero topic numbers (this means that the cross-referenced
topic was not in the same file as the current topic). Whenever MODHELP
encounters such a cross-reference, it tries to fill it in from its list of
topics from all files. If MODHELP can't find an exact match, it leaves the
cross-reference at zero.

MODHELP has the following command line options:

/T topicgap amount to increment each topic (default = 1)

Use the /T option if you want a fixed gap between all help topic numbers.

/I includegap amount to increment between include files (default = 1)

Use the /I option to automatically create number gaps between include file.
This might be useful if you planned to add more topics at the end of each
file. (Note, however, that another way to insert new topics is to give them
out-of-sequence numbers, then run MODHELP on the file again to resequence the
topic numbers).

/B create backups (files HELP000.BAK - HELPnnn.BAK)

MODHELP allways overwrites the input files (well, it writes to new files, but
renames them to the original names as its final step). Specify the /B option
if you want MODHELP to rename the original files to backups before writing its
output. The backup files have the form HELPnnn.BAK, where nnn is a sequential
number starting at 0. After you've assured yourself that the new help files
are what you want, you should delete these backup files.

/F firstnumber starting number for renumbering

If the help file being renumbered is to be appended to some other file, you'll
want to set the starting topic number to something beyond the the other file's
highest topic number.

/L write topic name/number report to InFile.LST

Use the /L to write a report of all your topics and their topic numbers to a
file. This is useful for manually fixing up those inter-file cross-references
the MODHELP couldn't resolve on its own.

HELP
----
HELP is a rather simple program accepts a help file as input and displays the
help text. Use this to test and "debug" your help files.


Change History
--------------
1.01 10-8-90
SCANHELP - Changed .Z to #Z to agree with documentation
MODHELP - Fixed bug where if last xref on line was 0, a topic
match wasn't found
MODHELP - Increased topic name length to 60