/REMARK -------------------------------------------------------------------
/REMARK Revised: 9-15-93, Al Keuter
/REMARK -------------------------------------------------------------------
/REMARK (NOTE: The help file title cannot be longer than 26 characters.)
/TITLE MAKING A HELP FILE 01234567890 (This should be truncated at "6".)
/INDEX

            5*** PowerBASIC 3.0 Help File Kit Structure ***3

            Ŀ
                      How to write a help file          
                  Help file command language index      
            
/LOCAL howto
/LOCAL commands
/ENDTOPIC
/REMARK -------------------------------------------------------------------
/TOPIC howto

How to create a PowerBASIC 3.0 help file:

Create a file using PB's IDE.  Be sure to turn TAB, INDNT, and UNDNT
off as TABs are not expanded by the help system.  If you include a
TAB in your help file, you will see the tab printed on the screen as
a bullet ("  ").

Use MAKEHELP.EXE to compile your .TXT file to a .PBH file that can
be used by the IDE help system.  Press either F1 or SHIFT-F1 from
within the IDE, then continue by pressing SHIFT-F1 as often as
necessary until your help index comes into view.  Beginning with
CONTROL-F1 instead will activate the context-sensitive help you have
defined with /LOOKUP.

For descriptions of the help file commands see Help file language.

Use PGDN to see a skeleton structure that you can import to get started.
/LOCAL lookup
/LOCAL commands
/REMARK -------------------------------------------------------------------
/NEWPAGE
Example:

//INDEX
   Your index goes here:

   14023NOThe first topic14023NO
   14023NOThe second topic14023NO
//REMARK      (The <Ctrl>-C character followed by "023" places a
//REMARK      <Ctrl>-W into this import example.)
//LOCAL topic1
//LOCAL topic2
//ENDTOPIC
//TOPIC topic1
  Write some help text here
//ENDTOPIC
//TOPIC topic2
  Write some help text about your lookup word
//LOOKUP LookUpWord
//ENDTOPIC
/ENDTOPIC
/REMARK -------------------------------------------------------------------
/TOPIC commands
5Help File Commands 3

//         Allows you to enter a single "/" in the first column.
/TOPIC     Marks the start of each help topic.
/ENDTOPIC  Marks the end of each help topic.
/INDEX     Marks the beginning of the help index.
/NEWPAGE   Forces a page break within a topic or index.
/LOOKUP    Specifies the context-sensitive help keyword for a topic.
^A         Marks the beginning of an 14ANOimport14ENO block.
^C         Specifies an ASCII character to be displayed.
^E         Marks the end of an 14ANOimport14ENO block.
^W         Surrounds text to be 14WNOcross-referenced14WNO to another topic.
/LOCAL     In a topic or index references a 14WNOblock14WNO to another topic.
/REMARK    Marks a line as comment.
/TITLE     Specifies the main help title.
^F         Precedes a new foreground color.
^FNO       Resets the foreground color to the startup color.
^B         Precedes a new background color.
^BNO       Resets the background color to the startup color.
^G         Changes help text colors.
/LOCAL doubleslash
/LOCAL topicstart
/LOCAL topicend
/LOCAL helpindex
/LOCAL newpage
/LOCAL lookup
/LOCAL controla
/LOCAL controlc
/LOCAL controle
/LOCAL controlw
/LOCAL local
/LOCAL remark
/LOCAL title
/LOCAL controlf
/LOCAL controlfn
/LOCAL controlb
/LOCAL controlbn
/LOCAL controlg
/ENDTOPIC
/REMARK -------------------------------------------------------------------
/TOPIC doubleslash

///

This allows you to enter a single "/" in the first column.  Otherwise,
a line of help text beginning with "/" would be incorrectly interpreted
as a command.

//TOPIC Slash
// This help text line will be be displayed with only one leading "/"
even though it is written with two.  Beginning the line with only a
single "/" in the first column would have caused MAKEHELP.EXE to report
an error.
//ENDTOPIC
/ENDTOPIC
/REMARK -------------------------------------------------------------------
/TOPIC topicstart

//TOPIC topicname

Specifies the beginning of a help "topic".  Each TOPIC must be
terminated with a corresponding /ENDTOPIC statement.  For example:

     /TOPIC PrintStatement
              .
     (Put your help information here.)
              .
     /ENDTOPIC

The maximum length of a line which is part of a TOPIC's text is 76
characters (not including any 14WNO's which may be present in the
line).  A topic can contain no more than thirty-two screen "pages",
each page no longer than twenty-one lines.
/LOCAL topicend
/ENDTOPIC
/REMARK -------------------------------------------------------------------
/TOPIC topicend

//ENDTOPIC

Specifies the end of a help TOPIC or the INDEX.  Every /ENDTOPIC
command must be preceded by a corresponding /TOPIC or /INDEX command.
/LOCAL topicstart
/LOCAL helpindex
/ENDTOPIC
/REMARK -------------------------------------------------------------------
/TOPIC helpindex

//INDEX

Specifies the beginning of the main index screen.  The INDEX is
constructed exactly like a TOPIC and must be terminated with an
/ENDTOPIC command.  There can be only one INDEX per help file.
/LOCAL topicend
/ENDTOPIC
/REMARK -------------------------------------------------------------------
/TOPIC newpage

//NEWPAGE

Specifies the beginning of a new page (screen) of text within a
particular TOPIC.  A /NEWPAGE command should be used to break
a large TOPIC into segments, each segment containing no more than
21 rows.
/ENDTOPIC
/REMARK -------------------------------------------------------------------
/TOPIC lookup

//LOOKUP word

Specifies that the current help screen will be displayed if you
perform a keyword lookup (by placing the cursor at the beginning of
a word in the editor and pressing Ctrl-F1) on the word specified in
the /LOOKUP command.  The maximum length of a /LOOKUP word is 31
characters.  You must have at least one /LOOKUP in your help file, but
you do not need a lookup for every topic.

Avoid the following characters when constructing a keyword:

      Underscore   _
      Period       .
      Comma        ,
/LOOKUP lookup
/ENDTOPIC
/REMARK -------------------------------------------------------------------
/TOPIC controla

14ANO             <Ctrl>-P   <Ctrl>-A

Used to mark the beginning of a block of text which can be imported to
the Clipboard.  The example cannot contain a /NEWPAGE command, and must
not be larger than 21 rows.  The import block must be terminated by  ^E .

Example to import:


        PRINT "This is a test"

/LOCAL controle
/ENDTOPIC
/REMARK -------------------------------------------------------------------
/TOPIC controlc

14CNOddd          <Ctrl>-P   <Ctrl>-C    ddd     (ddd = 001 to 254)

Be sure that `ddd' is a three-digit decimal ASCII character code and
the appropriate character will be displayed at the time the help page
is expanded by the help system.  This is how the ASCII chart was done
for characters less than 32.

An example of two characters:         14CNO016      14CNO017
                                       016          017
/ENDTOPIC
/REMARK -------------------------------------------------------------------
/TOPIC controle

14ENO             <Ctrl>-P   <Ctrl>-E

Marks the end of an import block.  Use  ^A  to mark the beginning of
an import block.
/LOCAL controla
/ENDTOPIC
/REMARK -------------------------------------------------------------------
/TOPIC controlw

14WNO             <Ctrl>-P   <Ctrl>-W

Specifies that the enclosed text is to be highlighted when the help
screen is displayed, identifying it as a related help topic.  More than
one related topic may be marked, and the topics are selected by using
the arrow and <Enter> keys.  There must be a 14WNO character immediately
preceding and following the text to be highlighted (14WNOhighlight me14WNO).

Both the opening and closing 14WNO must be on the same line.


Example: Press <Enter> for help on related topic /LOCAL.
/LOCAL local
/ENDTOPIC
/REMARK -------------------------------------------------------------------
/TOPIC local

//LOCAL topicname

Connects a 14WNO text item with a help "topic".  The "topic" screen
name of the first 14WNO text item on a particular page is specified by
the first /LOCAL command on that page; the second text item's name
is specified by the second /LOCAL command, etc.  There must be exactly
the same number of 14WNO text items and /LOCAL commands on a particular
page or MAKEHELP.EXE will report an error when attempting to compile the
help file.  Example:

  /TOPIC MyFunction

  MyFunction% doesn't do anything.

  See also: 14WNOYourFunction%14WNO

  /LOCAL YourFunction
  /LOOKUP MyFunction%
  /ENDTOPIC
/ENDTOPIC
/REMARK -------------------------------------------------------------------
/TOPIC remark

//REMARK text

Specifies that the rest of the line is a comment and will be ignored.

 /REMARK -------------------------------------------------------------
 /REMARK Revised: 2-15-1996  By: My Name
 /TOPIC MyFunction

 MyFunction$ function
 
 Purpose: Scans all logical drives, searching for a file.

 Syntax:  y$ = MyFunction$(FileName$)

 If successful, MyFunction$ reports the complete path/filename of
 FileName$.  If  unsuccessful, a null string ("") is returned.
 /ENDTOPIC
 /REMARK -------------------------------------------------------------
/ENDTOPIC
/REMARK This will not be put in the help file!!
/REMARK -------------------------------------------------------------------
/TOPIC title

//TITLE text

Specifies the title which will be displayed at the top of each help
screen while your help system is active.  If no title is specified,
"PowerBASIC Help" will be displayed instead.  The maximum help title
length is 26 characters.
/ENDTOPIC
/REMARK -------------------------------------------------------------------
/TOPIC controlf

14FNOxx           <Ctrl>-P   <Ctrl>-F   xx

Changes the current foreground color to xx.  The color number (xx) must
immediately follow the <Ctrl>-F character (14FNO12 for example).  If
the color number is less than 10, use a leading zero (14FNO06).

See also: FNO  Bxx  BNO
/LOCAL controlfn
/LOCAL controlb
/LOCAL controlbn
/ENDTOPIC
/REMARK -------------------------------------------------------------------
/TOPIC controlfn

14FNONO           <Ctrl>-P   <Ctrl>-F    NO

Changes the current foreground color to the default setting which was
in effect when PowerBASIC was first loaded.

See also: Fxx  Bxx  BNO
/LOCAL controlf
/LOCAL controlb
/LOCAL controlbn
/ENDTOPIC
/REMARK -------------------------------------------------------------------
/TOPIC controlb

14BNOxx           <Ctrl>-P   <Ctrl>-B   xx

Changes the current background color to xx.  The color number (xx) must
immediately follow the Ctrl-B character (14BNO12 for example).  If the
color number is less than 10, use a leading zero (14BNO06).

See also: BNO  Fxx  FNO
/LOCAL controlbn
/LOCAL controlf
/LOCAL controlfn
/ENDTOPIC
/REMARK -------------------------------------------------------------------
/TOPIC controlbn

14BNONO           <Ctrl>-P   <Ctrl>-B    NO

Changes the current background color to the default setting which was
in effect when PowerBASIC was first loaded.

See also: Bxx  Fxx  FNO
/LOCAL controlb
/LOCAL controlf
/LOCAL controlfn
/ENDTOPIC
/REMARK -------------------------------------------------------------------
/TOPIC controlg

14GNOx            <Ctrl>-P   <Ctrl>-G    x         (x = 0 to 6)

Changes the current color to a new color chosen from any of the help
system colors listed below.

   New Colors            Affected text          x
                         
   0BlackOnLtGray         Title                  03
   1BlackOnLtGray         Border                 13
   2BrtWhiteOnBlack       Selection bar          23
   3BlackOnLtGray         Help text              3          Default3
   4BlueOnLtGray          Keyword                43
   5RedOnLtGray           Help text              5          Alternate 13
   6LtCyanOnLtGray        Help text              6          Alternate 23

 There are restrictions on where in the help file this command can be
  placed.
 The colors described here are likely to change in future PowerBASIC
  versions/revisions.
/ENDTOPIC
/REMARK -------------------------------------------------------------------
/REMARK End of help file example.
