                     ----------------------------------
                     ------Manual 1.0 by Josh Hays-----
                     ----------------------------------
                     -----------(Release 0)------------
                     ----------------------------------
                     -------Documentation File---------
                     ----------------------------------

                                  --------
                                  Contents
                                  --------

                     Section I. User Information
                        1. Introduction to the Package
                        2. Contents of the Package 
                        3. Usage Information
                     Section II. Manpgs syntax and implementation
                     Section III. Other Information
                        1. Version History/Planned Updates
                        2. Usage Terms/Contact Information


                         ---------------------------
                         SECTION I: USER INFORMATION
                         ---------------------------

 ---------------
 1. Introduction
 ---------------
 
     This is a program that allows one to look up information on a specific
instruction, function, program, operator, or basically any other command on
the TI-92.  Its functionality is limited by the manpgs variable, however,
which at this stage is not yet complete.  This release is primarily for
developers who wish to be able to add entries to the manual for their
program in the future.

 -----------
 2. Contents
 -----------

     The Manual package zip contains the following files:
          manual.txt   -- This text file
          manual.92g   -- 92 Group file containing Winlib binaries

     Manual.92g contains the following 92 program files:
          man.92p     -- The manual formatting and output program (the
                              one you'll be using to look things up)
          manpgs.92m  -- The variable which contains manual entries.  The
                              "meat" of the program.  Although this isn't
                              completed, I've included a small demonstration
                              version to give examples.
          addman.92f  -- A function that returns manpgs with the matrix
                              argument appended to it.
          testman.92f -- A function that tells you whether an entry is
                              already in the manual or not.
          putman.92p  -- A program that demonstrates the use of addman() and
                              testman() to add manual entries to the manual
                              only if they're not already there.

 --------
 3. Usage
 --------

     The Manual is fairly easy to use.  Assuming you have a fully functioning
manpages variable, it's just a matter of calling the man program with the
desired command (throughout this documentation file, the word "command" will
refer to any function, instruction, program, or operator).  You don't need to
use quotes; however, if it's an internal instruction or function, or a user
function or program in the folder you're in, you must add quotes around the
argument.  For example, for information on the dim() function, you would
simply do the following:

          man("dim")

     Note that you don't need to add parentheses after a function or program
name.  For that matter, you don't even need to type the entire name -- the
manual will search until it finds the first entry that contains your string
in it.  Make sure you don't leave entries ambiguous, though:

          man(pxlte)

     This could either be interpreted as "pxltest()" or "pxltext", and the
manual will stop at the first one it finds.

     The output appears on the PrgmIO screen, in a standard format.  The
first line contains the command name, left-justified, and the command type,
right-justified.  The second line contains a short description of the
command.  The third line demonstrates the syntax of the function, and the
fourth and all following lines may contain extended syntax, usage, or
copyright information.  For example, dim():

          /-----------------------------------------\
          | *dim()               *Internal Function |
          | *Dimension or length of variable        |
          | Usage: dim(x)                           |
          | Returns length of string x or dimension |
          | of list or matrix x.                    |
          |                                         |
          \-----------------------------------------/

     Once you've finished viewing the manual information, you may press <esc>
or <diamond>-home to return to the home screen at any time.  The information
remains on the screen after the program has run, so if you wish to view it
again after you've exited, press F5 from the command line on the home screen.



                 --------------------------------------------
                 SECTION II: MANPGS SYNTAX AND IMPLEMENTATION
                 --------------------------------------------

     In order for the manual to be used to its best, certain guidelines
should be followed in the creation of manual pages.  Please, if you're making 
manual pages, adhere to the following rules and suggestions.

     The manpgs var is implemented as a matrix with 3 columns and an
indefinite number of rows.  The first column contains the command name.
This is the column that gets searched when the user makes a query.  This is
a string that should contain only the command name, preceding parentheses if
the command is a function or program.  For example, "dim()", "man()", and
"pxltest()" are functions and programs, "pxltext", "clrio", and "popup"
aren't.  As the manual states, it's important to know the difference between
functions and instructions on the 92.  A function returns a value that can be
used in calculations, while an instruction generally alters something, such
as the current state of the graph screen, the flow of a program, or the
text appearing in a dialog box.

     The second column is a single string that is split into the various
lines of the manual.  The text is delimited by the polar mode angle key,
located to the right of the "M" key on the keyboard.  (If you were wondering,
I chose this character because it's not used in normal text, and is easily
accessible at one key).  The first part (before the first delimiter) equates
to line two of the manual output, the second (between the first and second
delimiters) to the third line, etc.  The first part should always be a short
yet useful description of the command.  The second will be the sytax of the
function.  The third and remaining sections, which equate to the fourth and
following lines, can be used to expand on the syntax or provide usage or
copyright information.

     The third column may contain either a number or a string.  This
determines the type of command that the entry refers to.  If you use a number
(not in a string), refer to the table below.  Otherwise you may enter the
string of your choice and the manual will display that instead of the
defaults.  It is not recommended that you do this, however, for the sake of
following the guidelines.  The numbers should be adequate:

          1 -- Internal Function
          2 -- Internal Instruction
          3 -- User Function
          4 -- User Program
          5 -- Operator
          6 -- Variable
          7 -- Special

     Time for an example.  Let's refer to our infamous dim() function.  I'll
use the "%" sign to replace the standard angle delimiter.

          ["dim()","Dimension or length of variable%dim(x)%Returns length of
          string x or dimension%of list or matrix x.",1]

     See the diagram above to see how this would be output to the user.

     The extra program, putman(), and the functions, addman() and testman(),
can be used as a base for adding matrices to the manual.  Testman() is a   
function that will return a list of binary values, 0 if a command isn't in
the manual already and 1 if a command is already there.  This is to prevent
adding pages to the manual that are already there.  You pass a single 
argument to testman: a matrix of any length and 3 columns wide.  Each number
in the list returned corresponds to the matrix row of the same position.
Addman() returns manpgs augmented vertically with with the matrix argument.
Again, any amount of rows, and three columns.  Putman(), the program, is
a demonstration of how to use addman() and testman() together to add your
pages to the manual.  Contact me for more information on how to use these
programs to your benefit in an installation program.


                       ------------------------------
                       SECTION III: OTHER INFORMATION
                       ------------------------------
 
 ----------------------------------
 1. Version History/Planned Updates
 ----------------------------------

  Release  |  Notes
  ---------------------------------------------------------------------------
   1.0 r0  |  First public version.  Contains man(), manpgs, and supplemental
           |  programs.  Manpgs is limited and incomplete.


 Planned Additions/Updates:

     Enhanced manpgs variable.  I will probably be releasing supplements of
        only the manpgs variable.  Please contact me if you would be willing
        to help out with the writing of manual pages for internal functions
        and instructions.  I'll let you know what you can help out with and
        how to do it.
     
     If you can think of anything else, let me know.

 ----------------------------------
 7. Usage Terms/Contact Information
 ----------------------------------

     If you make use of Manual, please let me know.  What I'd like to see
is a comprehensive listing of the internal functions and instructions and
also several users' programs that have manual entries as an option.

     You may use Manual freely and distribute it, unmodified from its intact,
original form.

     I can be reached through email at: johays@brownell.edu.  If you need
other contact information, let me know.  I have a web page at
http://www.brownell.edu/~johays.  Right now I have 92 information on this
server at /~johays/ti92.html.  I plan to add a support page for Manual in
the near future.  Feel free to contact me with your ideas, suggestions,
criticisms, etc.


Manual is (C)1996 Josh Hays.  All rights reserved.



