Power-Programmierung/CD1.mdf/pascal/library/dos/t_power/scanhelp/scanhelp.doc

Text File | 1991-12-01 | 11.7 KB | 277 lines

SCANHELP - Utility to produce help files from TP source code.

Version 2.00Alpha - test version of update by D.J. Murdoch to
TurboPower's utility.

This update is copyright (1991) D.J. Murdoch.  When finalized, I intend
to release it to the public domain, as TurboPower released the original
SCANHELP. Until then, I'd like to keep control of it, so this release is
*not* public domain.

REQUIREMENTS

SCANHELP produces *.TXT files suitable for input to the TurboPower
MakeHelp utility.  This utility comes with TurboPower's Turbo
Professional and Object Professional packages; if you don't have one of
those, SCANHELP isn't going to help you.

AIMS

SCANHELP was one of TurboPower's Help Tools, released to the public
domain in January 1990.  It was designed to create an outline for a help
database describing the interface to a Turbo Pascal unit; the assumption
was that the user would make major modifications to the outline to
produce a polished help system.

I wanted something different:  I wanted documentation for myself, and I
wanted it to be easy to produce.  I've found that it's too easy for
printed documentation to get out of synch with the source code when the
code is under development; even my online documentation kept falling
behind, because it was just too much trouble to go to the *.TXT file and
correct the documentation when I made a small change.

The design aim for SCANHELP 2 is thus to produce complete *.TXT files,
suitable for input to MAKEHELP.  These should be good enough for
internal use without any manual editing.  It should be possible to
customize them by working within the original *.PAS source code;
duplicate documentation should not be necessary.

Some other things I've attempted to do, with varying success:
 - produce documentation for *every* interfaced symbol
 - have a minimal impact on the source code, i.e. existing source code
   should produce reasonable help files without substantial changes
 - handle multiple source files, so cross references to other units are
   possible
 - work with Pascal scoping rules, so that cross references are easy.

THIS IS A TEST VERSION!

This version of SCANHELP is far from complete.  I'm releasing it because
I'd like to get other people's suggestions for useful features.
If you try it out, *please* send me a message saying what you like about
it and what you dislike, and let me know of any gross bugs.  (There are
lots of minor bugs; I'm not going to worry about those, until the design
stabilizes.)

Things I'd especially like to hear:

 - suggestions for different displays.  Do you violently dislike the way
   SCANHELP displays variant records?  How would you do it?
 - suggestions for essential command line options.  I haven't worked on
   those yet; what sort of options would you like?  Please suggest
   syntax.
 - suggestions for new comment directives.  I've only added #T (see
   below) to the original SCANHELP directives; what other ones would be
   really useful?

Please send comments to me (Duncan Murdoch) at one of the following addresses:

  Fidonet:    DJ Murdoch at 1:163/140.3 (1:221/177.40 starting January 92)
  Internet:   [e-mail]
  Compuserve: 71631,122

DOCUMENTATION

Below is an extract from TurboPower's documentation for the Help
Utilities.  I've marked changes with "!!".

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, function !!or other identifier!! 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.

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

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 !! only written if there are cross references
defined.!!

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 !! categorized
tables of all identifiers with global scope.  Separate lists of
constants, types, variables, and functions/procedures are given.!!

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}

!!  In order to resolve cross references, Pascal scoping rules are used.
If you have two identifers named TopicA, then the one which is in scope
will be referenced.  You can override the default using the dot syntax,
Scope.TopicA.  You can make references to topics in other units,
provided that the other source file is being scanned in the same run of
SCANHELP.  If the other unit is one that is being Use'd in your unit, no
unit override will be necessary.!!

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

#T Topic [comment]
  This directive creates a new topic and a new identifier in the current
  scope.  SCANHELP parses it as a new declaration; it'll be a syntax
  error to put this kind of comment directive in the middle of another
  one.  For example:

    type Myrec = record
      { this comment will go into the Myrec topic }
      a : word;
      { this comment will go into the Myrec.a topic }
      {#T about_myrec}
      { this comment will go into a Myrec.about_myrec topic }
      b : word;
      { this comment will go into the Myrec.b topic, with cross
      references to the other two topics. }
      {#X about_myrec a}
    end;

  You can use #X directives after #T; this will create See Also entries
  in the #T topic.  Other #X directives can refer to the #T topic, using
  the topic name, as shown after the Myrec.b comment above.

!!

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

!!  This directive is currently inoperative! !!

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.


Change History
--------------
1.01  10-8-90
      SCANHELP - Changed .Z to #Z to agree with documentation

1.02  3-7-91
      SCANHELP - Fixed "xref line too long" bug

2.00  1-Dec-91
      SCANHELP - Major changes by DJM.