
                            FINITE STATE KERNEL CREATOR
                                    Version 2.1

                 Copyright (C) 1997, 2000, 2001 James A. Cureington 
                             tonycu@users.sourceforge.net


                                   COMMAND HELP

                (see about box for complete copyright information)



MENU BAR                                                          (main section)
################################################################################


                                                                   (sub section)
     File ======================================================================

          New ------------------------------------------------------------------
               Create a new FSK.  One may wish to define the default function
               and transition state in the FSK Defaults window, launched from 
               the Edit menu, to specify the default function and transition 
               state for the action-blocks of the new FSK.

               The initial number of states and events are required to create
               a new FSK, while the return type and description are optional
               in this window.


          Open -----------------------------------------------------------------
               Open an existing FSK.  The current path is displayed at the top
               of the window.  Available directories are displayed in the
               left scroll window and FSK files in the right.  Double snap a
               directory to enter it, double snapping the ".." takes you
               back one directory level.  Double snapping an FSK file loads
               it.
       

          Save -----------------------------------------------------------------
               Save the current changes to the FSK under the current filename.


          Save As --------------------------------------------------------------
               Save the current FSK to a specified file.  Enter the name to
               save the FSK under in the text entry box.  The current path
               is shown below the filename entry box. Available directories 
               are displayed in the scroll window.  Double snap a directory to 
               enter it, double snapping the ".." takes you back one directory
               level.  If the specified FSK file does not end in ".fsk", ".fsk"
               is appended.


          Print ----------------------------------------------------------------
               Print various FSK documents to files in ASCII text.  The 
               following documents may be printed:

                    1) State Table
                    2) Event Descriptions
                    3) State Descriptions

               To print documents, select the check button the the left of each
               document you wish to print.  Then enter the file and directory 
               to print each FSK document to, and select PRINT. 


          Generate Code --------------------------------------------------------
               Generate C source code implementing the FSK.  Enter the file 
               and directory to generate the source code to and select 
               GENERATE.  If the specified filename does not end with ".c", 
               a ".c" is appended to the filename.  

               The transition history is the length of a circular buffer that
               retains the state transitions.  If left blank, state transition 
               history is not retained.  The state transition is printed when 
               the vAbortFsk function is called.  The vAbortFsk function is 
               usually called from invalid action-blocks in the FSK.

               If the FSK receives an event outside those specified in the
               FSK, vAbortFsk is called.  However, if the "user defined
               error handler" is activated and an event outside the FSK is
               received, a transition to state zero with an event of zero 
               occurs.  This gives the designer the flexibility of handling 
               all possible events in the FSK.  The user defined error handler
               is activated in the Source Settings window launched from the 
               Edit menu.

               Some validation of the FSK is performed before the code is
               is generated.  Such as checking for duplicate state and event 
               names, and infinite states.  An infinite state is one that
               does not have an action-block that transitions out of the 
               state.  For example, if all the action-blocks in state zero
               transitioned to state zero, there is no way for the FSK to ever 
               transition out of state zero.  Hence, state zero is an infinite
               state.  The existence of an infinite state only causes a 
               warning message.


          Run FSK --------------------------------------------------------------
               Interactively run the FSK.  Enter the initial state and event,
               then select TRANSITION.  After the first transition, the state
               number and name cannot be manually changed.  Enter an event 
               number or name and select TRANSITION to cause a state transition 
               out of the current state to the next state based on the given
               event.  The new state number and name are displayed.


          FSK Info -------------------------------------------------------------
               Provides various information on the current FSK.  The 
               information includes:

                    1) Name of the FSK
                    2) Complete FSK path
                    3) Date the FSK was last saved 
                    4) Number of events
                    5) Number of states
                    6) Indication of whether the current FSK is modified

               NOTE: The date the FSK was last saved is also the referred to
                     as the "Last Modified" date.  The last modified date is 
                     the last time the FSK file was saved (modified).


          Quit -----------------------------------------------------------------
               Quit the FSKC CASE tool.  If the current FSK has been modified,
               a window prompts to save and exit, exit without saving, or
               cancel the quit.



                                                                   (sub section)
     Edit ======================================================================

          Find -----------------------------------------------------------------
               Find a state, event, or function.  Enter the state, event, or
               function name to find, and select the appropriate button.  
               State and event names are automatically converted to upper case.
               If the state or event is found, it is positioned in the
               viewable area of the window.  When searching for a function, all
               the action-blocks that contain the function are shown in terms
               of their "event,state" location.


          FSK Defaults ---------------------------------------------------------
               Set the FSK defaults.  The defaults include the state to 
               transition to and the function to call from each action-block
               of newly inserted states and events.

               The defaults can be set before creating a New FSK to give
               each action-block the same initial transition state and 
               function.


          Source Settings ------------------------------------------------------
               Set source code information.  The FSK return type may be 
               edited in this window.  The "user defined error handler" can
               be activated or deactivated.  If the user defined error handler 
               is activated and an event undefined by the FSK is received, a 
               transition to state zero with event zero occurs.  This gives 
               the designer the flexibility of handling all possible events in 
               the FSK.  

               Header files are specified in the text entry window separated by
               a space.  For example, entering the following in the entry 
               window
        
                    <linux/signal.h> <linux/types.h> <common.h> "my_header.h"

               will produce the following statements in the generated FSK 
               source file.

                    #include <linux/signal.h> 
                    #include <linux/types.h> 
                    #include <common.h> 
                    #include "my_header.h"

               The stdio.h header file is automatically included in each
               FSK.


          FSK Description ------------------------------------------------------
               Edit the FSK description.



                                                                   (sub section)
     Options ===================================================================

          Show Command Palette -------------------------------------------------
               Displays a command palette containing several often used 
               commands.  The commands include:

                    1) Find               (binoculars)
                    2) Generate Code      ("C"ode)
                    3) Print              (printer)
                    4) Run FSK            (stick figure running)
                    5) Save               (disk)


          Hide Command Palette -------------------------------------------------
               Hides the command palette.



                                                                   (sub section)
     Help ======================================================================

          On Commands ----------------------------------------------------------
               Displays this window.


          About ----------------------------------------------------------------
               Displays window containing FSKC version, acknowledgments,
               copyright information, etc.



MOUSE MENUS                                                       (main section)
################################################################################

                                                                   (sub section)
     State-block Mouse Menu ====================================================
          The state-block mouse menu is activated by pressing mouse button
          three while over the state to apply the command to.  The state-block
          mouse menu contains the following commands:

               1) Undo
               2) Cut
               3) Copy
               4) Paste After 
               5) Paste Before 
               6) Insert After 
               7) Insert Before
               8) Delete 

          When a command is selected, the mouse menu disappears.  To cancel
          the mouse menu, select any block with mouse button one.

          The transition state of each action-block in the copy buffer is 
          adjusted as states are cut, pasted, inserted, deleted, etc.  If 
          an action-block refers to a state that has been deleted, its value
          changes to unassigned "*".  

          For example, if an action-block in the copy buffer transitions to 
          state zero and a state is inserted or pasted before state zero,
          the transition state in the copy buffer action-block is incremented 
          by one.

          If an action-block in the copy buffer transitions to state one and 
          state zero is deleted, the transition state in the copy buffer 
          action-block is decremented by one.


          NOTE: If a state is inserted after the last visible state, the
                state blocks are *not* shifted to the left.  Hence, to see
                the newly inserted state, use the scroll bar to move
                the states to the left by one state.

          NOTE: The undo command reverts the last edit regardless of the type
                of block the edit was performed on.



                                                                   (sub section)
     Event-block Mouse Menu ====================================================
          The event-block mouse menu is activated by pressing mouse button
          three while over the event to apply the command to.  The event-block
          mouse menu contains the following commands:

               1) Undo
               2) Cut
               3) Copy
               4) Paste After 
               5) Paste Before 
               6) Insert After 
               7) Insert Before
               8) Delete 

          When a command is selected, the mouse menu disappears.  To cancel
          the mouse menu, select any block with mouse button one.

          NOTE: If an event is inserted after the last visible event, the
                event blocks are not shifted up.  Hence, to see the newly 
                inserted event, use the scroll bar to move the events up 
                by one.

          NOTE: The undo command reverts the last edit regardless of the type
                of block the edit was performed on.



                                                                   (sub section)
     Action-block Mouse Menu ===================================================
          The action-block mouse menu is activated by pressing mouse button
          three while over the action-block to apply the command to.  The 
          action-block mouse menu contains the following commands:

               1) Undo
               2) Copy
               3) Paste
               4) Clear

          When a command is selected, the mouse menu disappears.  To cancel
          the mouse menu, select any block with mouse button one.

          NOTE: The undo command reverts the last edit regardless of the type
                of block the edit was performed on.



EDITING                                                           (main section)
################################################################################

                                                                   (sub section)
     Editing State-blocks ======================================================
          State-blocks are edited by placing the mouse pointer over the 
          state-block to edit and pressing mouse button one.  An edit
          window appears containing an entry field for the state name and
          description.  The state name is automatically converted to upper 
          case.  The description is used in the state description document.
          Since the names are used in "#define" statements, they should only
          contain characters that are valid for the #define directive.


                                                                   (sub section)
     Editing Event-blocks ======================================================
          Event-blocks are edited by placing the mouse pointer over the 
          event-block to edit and pressing mouse button one.  An edit
          window appears containing an entry field for the event name and
          description.  The event name is automatically converted to upper 
          case.  The description is used in the event description document.
          Since the names are used in "#define" statements, they should only
          contain characters that valid for the #define directive.


                                                                   (sub section)
     Editing Action-blocks =====================================================
          Action-blocks are edited by placing the mouse pointer over the 
          action-block to edit and pressing mouse button one.  An edit
          window appears that allows the following values to be modified:

               1) Function name and parameters
               2) Transition State
               3) Iterative
               4) Description

          The function name and parameters are specified in the following
          format:

               myFunction(struct MyInfo strMyInfo, int i1, "a string", 
                             NAME_LEN, extern char* pch1);

         
          The above function will cause the following variables to be 
          defined in the FSK source code.

               struct MyInfo strMyInfo;
               int i1;
               extern char* pch1;


          And the function call will be

               myFunction(strMyInfo, i1, "a string", NAME_LEN, pch1);


          NOTE: Any data type specifiers prefixed or appended to the formal 
                parameter names are carried over to the actual parameter 
                names.  That is, "myFunc(int *i, char *pch)" will produce the
                "myFunc(*i, *pch)" for the function call - probably not what 
                one desires.  Hence, separate the parameter name from its
                data type definition; myFunc(int* i, char* pch).


          Pointers to data elements in the strMyInfo structure may be 
          modified by myFunction.  The pch1 variable can be initialized 
          outside the FSK since it's declared as extern.  The reverse is
          also true, functions can define FSK variables as extern in order 
          to gain access to them.  


          NOTE: The use of extern is frowned upon by some software 
                engineering organizations.


          Selecting the iterative check button causes the return value from
          the called function to be used as the event after the state 
          transition.  In other words, the function in the action-block does
          not return to the calling function, but transitions to the state
          specified in the action-block and uses the return value as the
          event in the newly entered state.  The return type of functions in 
          iterative action-blocks should return an unsigned int.
          

          NOTE: Parameters are not extensively checked for errors.  This
                is left up to the compiler.  For example, "function(int i,,)"
                causes the function call to be "function(i,i,i)".  It does 
                check for a limited set of parameter errors, however.


