mu
 Help information about: Usage Examples and Suggestions
 Examples: ^A ^B ^C ^D ^E
 
              E╔════════════════════════════════════════════════╗
              E║      CUsage Examples and Application NotesE      ║
              E╚════════════════════════════════════════════════╝


   For additional information about ways of using InContext, the user can
   consult two sources.  CUsage ExamplesB are found here in the help system.
   Studying these examples will help you pick up ideas and will increase your
   understanding.  A usage example describes a particular approach to
   organizing a portion of your computer-based work environment.  One or
   more ways of achieving this organization are then described, typically
   ranging from a very simple implementation to a more sophisticated one.

   Both Usage Examples and Application Notes are constantly being added and
   updated.  Registered users can obtain a full, current set from the Rams
   Island BBS.

 CApplication Notes

   CApplication NotesB ("CAppNotesB") have a different purpose, though they can
   also be a useful source of understanding and examples.  Application notes
   help you incorporate other programs into your work environment.  Some of
   these programs may be used as tools (a viewer, print utility, or
   whatever), while others may represent the applications that you use to do
   your actual work (word processors or spreadsheet programs, for example).
   A starter set of application notes comes with the shareware version of
   InContext.  Additional "AppNotes" are available to registered users,
   through our BBS or by mail.

   The starter AppNotes are found in the "APPNOTES.LZH" archive in the
   InContext directory.  This is an archive containing a collection of
   "app" files.  The "app" files are themselves archives, which must be
   extracted before you can make use of them.  To examine one, you should
   first "Edit" the APPNOTES.LZH file.  Select the AppNote you're interested
   in, and extract it.  Then exit the editor.  You will find that the
   extracted "app" object can be selected and edited.  You will find a text
   file ("txt" class) to read, and perhaps an action definition or template,
   if those are relevant.

 CAvailable Usage Examples

 ZmuaB       CJ Example A -- External Editors and Viewers CB.

 ZmubB       CJ Example B -- Document Archive CB.

 ZmucB       CJ Example C -- Phone List CB.

 ZmudB       CJ Example D -- Object Deletion CB.

 ZmueB       CJ Example E -- Installing a Print Spooler CB.
mua
 Usage Example A: External Editors and Viewers

 
              E╔════════════════════════════════════════════════╗
              E║ CUsage Example A: External Editors and ViewersE  ║
              E╚════════════════════════════════════════════════╝


   InContext has its own internal text editor and text/hexadecimal viewer.
   These are provided for two reasons:

      CB  Some users may not have their own editor or viewer, and they
         would be unable to make effective use of InContext without them.

      CB  Some users may prefer to use the internal editor and viewer
         because they are much faster to invoke than external programs.

   However, the internal editor and viewer are clearly much simpler than
   other text editors and viewers the user might have access to, and most
   users will prefer to use external editors and viewers.  The procedure
   for substituting your own preferred tools is fairly simple.

 CSubstituting an External Editor

   To substitute a different editor ("myeditor", as an example):

      CB  Change the definition of the "editText" macro from "!edit %f"
         to "myeditor %f" (or whatever similar command is used to invoke your
         editor in the preferred way).  This change will cause your editor to
         be invoked whenever the "edit" action from the "Common" action list
         is selected.

      CB  Change the definition of the "edit-all" action from the "Group"
         action list.  This will allow use of your editor on a group of
         objects.  You probably will want to do this only if your editor
         behaves acceptably if it is accidentally invoked on a non-text file.
         You will especially want to do this if your editor can be invoked
         on multiple files.

         If your editor can handle multiple files, then replace the entire
         "edit-all" procedure with "myeditor %m" (or whatever similar command
         is used to invoke your editor in the preferred way).

         If your editor cannot handle multiple files, then replace only the
         "!edit %F" command with "myeditor %F" (or something similar).

   If you prefer to substitute your editor only for large files, and use the
 ZmcaemB  internal editor for small files, change the CJ incEdit macro CB instead.

 CSubstituting an External Viewer

   To substitute a different viewer ("list", for example):

      CB  Change the definition of the "viewText" macro from "!view %f"
         to "list %f" (or whatever similar command is used to invoke your
         viewer in the preferred way).  This change will cause your viewer to
         be invoked whenever the "view" action from the "Common" action list
         is selected.

      CB  Change the definition of the "view-all" action from the "Group"
         action list.  This will allow use of your viewer on a group of
         objects.  You will especially want to do this if your viewer can be
         invoked on multiple files.

         If your viewer can handle multiple files, then replace the entire
         "view-all" procedure with "list %m" (or whatever similar command
         is used to invoke your viewer in the preferred way).

         If your viewer cannot handle multiple files, then replace only the
         "!view %F" command with "list %F" (or something similar).

 CMore Complex Editor Procedures

   You may have occasion to define a more complex procedure for invoking your
   editor.  Consider, for example, the following procedure:

        menu c:\tools\brief.mnu
        b -u150 -L%l %f
        menu off
        !relogDir c:\brief\backup

   This procedure invokes the Brief editor ("b").  Because Brief supports
   variable screen sizes, this procedure makes use of its -L argument to
   specify the current number of display lines.

   Before Brief is invoked, though, the procedure invokes the Microsoft Mouse
   Menu program using a mouse menu definition defined for that editor.  The
   Mouse Menu program is a TSR (Terminate-and-Stay-Resident) program that
   allows the use of a mouse with programs not designed to support a mouse.
   This program remains resident in memory while Brief is executing, and is
   then unloaded from memory.  Because Brief saves backup copies in the
   directory C:\BRIEF\BACKUP, that directory is relogged each time Brief is
   invoked.  That causes InContext to have a current log for the files that
   are backed up in this way.

   A comment on TSR's is in order (for advanced users).  Notice that, in the
   above procedure, a TSR is loaded and removed in a procedure that is
   executed from CwithinB InContext.  This means the TSR occupies memory
   only when it is actually in use.  If it were invoked CoutsideB InContext,
   it would occupy memory all the time.  TSR's can be invoked from within
   InContext if they are capable of being turned off (as by "menu off"
   above) and sometimes even if they aren't.  This is possible because
   InContext uses memory swapping and contains some interrupt-vector
   protection.  This capability is not guaranteed, but you can try it for
   any TSR you happen to use to see if it works.
mub
 Usage Example B: Phone List

 
              E╔════════════════════════════════════════════════╗
              E║       CUsage Example B: Document ArchiveE        ║
              E╚════════════════════════════════════════════════╝


   A very handy facility to have is a document archive, which can be
   rapidly accessed from any work context.  One possible use for such an
   archive is to hold on-disk software documentation (user manuals), but
   other uses will be discussed below.

 CA Simple Approach

   This can be easily accomplished by:

      CB  Placing the documents in a compressed "archive" file, using the
         LHA program.  This can be done manually, or in a more automated
         way discussed below.

      CB  Creating a "Do" procedure that views the archive.

   Suppose, for example, you have a collection of software manuals (examples
   which you certainly do have are INCONTXT.DOC and LHA.DOC).  You might
   create a document directory, such as C:\DOCS, and place these manuals
   there.  Then go to that directory and archive each one (select F ADction B
   and "Archive").  When asked what archive, respond "DOCUMENT".  These steps
   will result in the creation of a single file which contains, in highly
   compressed form, the text of your software manuals.  The name of the file
   is DOCUMENT.LZH.  When you are comfortable that this has been done
   correctly, you should delete the original documents, retaining only the
   archive.

   Now create a new Do procedure, perhaps called "Document".  Give it a
   Description such as "View Document Archive".  For the procedure
   definition, use the following:

      !viewLZH c:\docs\document.lzh

   Whenever you select this procedure (by typing "DD" for "Do", "Document"),
   the internal LHA viewer will be invoked on the document archive.  You
   will be able to select the desired document and view it, extract it, or
   several other choices.  If you extract it, a copy of the original document
   will be placed in the directory in which you are currently working.

 CHandling Multiple Archives

   It is easy to extend this to handle multiple archives, by just adding a
   menu to the definition of the Do procedure.  A simple example is:

      !menu "Which archive would you like to view?"
         !choice "Document"
            !viewLZH c:\docs\document.lzh
         !choice "Letters"
            !viewLZH c:\personal\letters.lzh
      !endMenu

   This example assumes two archives, one containing documents and the other
   an archive of correspondence.  A correspondence archive might be handy if
   you write letters from different work contexts, and want to be able to
   keep them all in one place.  Note, however, that there is no protection
   here against inadvertently using the same name for two letters, and thus
   losing the older one.  You would need to check for duplication of names
   yourself, before adding a new letter to the archive.

   This approach is especially convenient when you want to write a new letter
   that is similar to one you wrote before.  Simply view the Letters archive,
   select the older letter, and extract it.  A copy of it will now be in the
   current directory.  Rename it and edit it, and you have the new letter.

 CAutomatic Archiving by Class

   If you have a document archive in which new material is added often, such
   as a correspondence archive, you may want to make the addition of such
   material more automatic.  One way of doing this is to redefine the
   "Archive" action for a particular class.  Thus, the Archive action for
   the "ltr" class might have the following procedure definition:

      lha u c:\personal\letters %f
      !pause
      !delete
      
   Anytime this archive action is executed, the selected "ltr" object will
   be added to the letters archive without prompting the user for the archive
   name.

   If you have several different object classes, all of which are letters,
   you might make the above procedure a macro ("arcLtr", for example), and
   use the macro to define the "Archive" action for each of the classes.
   You might, for example, have both a personal and a business letter class
   with different letterhead.

 CSaving to Desired Archive by Menu Selection

   An alternative approach is to redefine the common archive action (i.e.,
   the "Archive" action in the "Common" action list), so that its procedure
   presents you with a choice of destination.  The procedure definition might
   be:

      !menu "In which archive should object '%f' be placed?"
         !choice "Document"
            lha u c:\docs\document %f
         !choice "Letters"
            lha u c:\personal\letters %f
            !choice "Other"
            !query 1 "Enter name of LHA archive" 12
            !verify "OK to archive '%f' to '%1'?"
         lha u %1 %f
      !endMenu
      !pause
      !delete

   As you can see, lots of variations are possible.  You should be able to
   adapt these ideas to your own situation.
muc
 Usage Example C: Phone List

 
              E╔════════════════════════════════════════════════╗
              E║          CUsage Example C: Phone ListE           ║
              E╚════════════════════════════════════════════════╝


   If you keep your phone list on a computer, you're well aware that you
   may have to consult it at any time, and from anywhere.  The "Do" Command
   exists for such cases.  When you select a procedure from the Do list,
   it is executed regardless of your current spatial context.

 CA Simple Approach

   A simple approach is to define a Do procedure (call it "Phones", for
   example) which invokes the internal editor on the file in which you keep
   your phone numbers.  If your phone list file is "c:\personal\phones.txt",
   then the definition of the "Phones" procedure might be:

      !edit c:\personal\phones.txt

   Whenever you now select "Do" and "Phones" (by typing "DP", for example),
   you'll find yourself editing the phone list.  When you finish, you will
   still be in the work context you were in before the Do command.

 CSearching the Phone List

   Once you're editing the phone list, you can type Alt-S to search for a
   particular name.  If you do this often, you might want to expand the
   "Phones" procedure as follows:

      !keyStuff "\@S"
      !edit c:\personal\phones.txt

   This simply automates the selection of the editor's @Search command, so
   that you are immediately presented with an "Enter search string" query.
   It does this by using the internal CkeyStuffB command to pre-load the
   keyboard buffer with the Alt-S character, as if you had typed it
   yourself.
mud
 Usage Example D: Object Deletion

 
              E╔════════════════════════════════════════════════╗
              E║       CUsage Example D: Object DeletionE         ║
              E╚════════════════════════════════════════════════╝


   Different users have different preferred approaches to the deletion of
   files.  Experienced users may prefer immediate deletion with, perhaps,
   only a single verification.  Other users may prefer a second verification
   before such a drastic action.  Many users may prefer that deleted material
   be placed in a holding area from which recovery is possible, if desired.
   All of these behaviors are readily achievable with InContext.

   Deletion of individual objects is controlled by the procedure used to
   define the "Delete" action in the "Common" action list.  Deletion of
   groups of objects (a whole class, a whole view, or all the files in the
   current directory) is controlled by the definition of the "Del-all"
   action in the "Group" action list.  The discussion below describes
   various alternative forms that these procedure definitions might take,
   in order to achieve various deletion behaviors.

 CThe Default Approach

   The default approach simply asks the user if it's OK to delete the object,
   and deletes it if the reply is "Yes".  (Based on the setting of one of the
   "Miscellaneous" options, there may be a second verification query before
   deletion occurs.)

   This behavior is achieved, for individual objects, by the procedure:

        !delete

   and for groups of objects, by the procedure:

        !deleteGroup

   The individual-object deletion procedure might have been written in the
   following way:

        !verify "OK to delete '%f'?"
        !delete %f noquery

 CThe "Hair Trigger" Approach

   As they say in the TV commercials, DON'T TRY THIS AT HOME!  However, just
   for the sake of completeness, please note that the procedure:

        !delete noquery

   would produce immediate, irrevocable deletions without querying the user.

   Similarly, the procedure

        !forEachObject
           !delete %F noquery
        !endFor

   would immediately delete a whole group of objects.  It is unlikely that
   anyone would actually want to use these particular definitions, but it
   is instructive to look at them.

 CUsing a Trash Can

   A more likely alternative to the default behavior is the incorporation
   of a "trash-can" directory.  The idea here is that deleted material is
   not actually immediately removed from the disk.  Instead, it is simply
   moved to a holding area (e.g., "C\JUNK").  This means that you can
   recover such material, even after the deletion, provided you have taken
   no action, in the meantime, to delete it from the holding area.

   To achieve this behavior for the deletion of individual files, create a
   "trash-can" directory, such as C\JUNK, and change the procedure for the
   "Delete" action (in the "Common" action list) to:

        !verify "OK to delete '%f'?"
        !rename %f c:\junk\%f

   This will cause the object to be moved to the C:\JUNK directory after the
   user verifies his intention to delete.  The analogous procedure for the
   "Group" action list is:

        !verify "OK to delete these objects?"
        !forEachObject
           !rename %F c:\junk\%F
        !endFor

   Each of these procedures will result in movement of the selected objects
   to the C:\JUNK directory if there is not already an object of the same
   name in that directory.  If there is, the user will be asked if it's OK
   to replace the object that's already in the C:\JUNK directory.  A "No"
   answer here would terminate the deletion action.

   If you don't want to be asked about such replacement, the word "noquery"
   can be added to each of the "rename" commands just above.  For example,
   the procedure for individual objects becomes:

        !verify "OK to delete '%f'?"
        !rename %f c:\junk\%f noquery

   With this procedure, the user won't be asked before old objects in the
   JUNK directory are replaced by more recent deletions.  This means that
   only the last object of a given filename will be kept.

   With any of these procedures, the deleted object can be recovered by
   going to the JUNK directory, selecting the object, selecting the "Take"
   action, and carrying the object back to the desired directory.

   These procedure definitions allow objects to be deleted from anywhere
   CexceptB the JUNK directory itself.  For that, it's probably best to
   define a "Do" procedure (perhaps called "Cleanup") such as:

        !verify "OK to empty JUNK directory?"
        del c:\junk
        !relogDir c:\junk
mue
 Usage Example E: Installing a Print Spooler

 
              E╔════════════════════════════════════════════════╗
              E║  CUsage Example E: Installing a Print SpoolerE   ║
              E╚════════════════════════════════════════════════╝


   The print action used as a default by InContext has the following rather
   primitive procedure definition:

        copy %f prn:
        echo  >prn:

   This procedure uses a DOS copy command to copy the to-be-printed file to
   the standard printer output defined for your system (usually LPT1).  After
   the file has been copied to the printer, a page-eject character is sent,
   using the DOS "echo" command.  (The funny-looking character () is
   Control-L, which is the normal page-eject character.)

   This is used as the default print procedure because the successful use of
   a print spooler (such as the DOS "PRINT" command) takes a little bit of
   setting up.  This would be true for the use of a print spooler from inside
   CanyB DOS shell.

   A print spooler is a program that prints files in the "background", while
   other work goes on in the foreground.  Its advantage is that you can go on
   working while your printer prints.  Without a print spooler, you must wait
   for the entire print operation to be completed before your computer again
   becomes available for other work.  Since spoolers avoid this waiting, you
   may want to set up your system so that printing occurs via a spooler.

   The problem with print spoolers is that they are "Terminate-and-Stay-
   Resident" programs (TSR's).  The first time you invoke the DOS "PRINT"
   command, for example, it loads a print spooler into memory, where it is
   intended to remain until you turn off or reboot your computer.

   Many TSR's can be invoked from CwithinB InContext, without any
   difficulties.  For example, a mouse menu driver might be loaded any time
   you invoke your editor, so that an "edit" procedure might look like this:

        menu myedit
        myeditor %f
        menu off

   With this arrangement, the "menu" program, a TSR, would be loaded into
   a portion of the memory freed when InContext "swaps out".  The TSR would
   be in memory and active while the "myeditor" program is operating, but
   would be unloaded from memory before returning.  When InContext regains
   control, things would be as if the TSR had never been loaded.  (This does
   not work for all TSR's.)

   The problem with print spoolers is that you want them to be resident in
   memory CwhileB InContext is operating, and not just when InContext has
   invoked some other program.  That means that the TSR must be loaded CbeforeB
   InContext is invoked.  Thus, the procedure for setting up your system to
   use the DOS "PRINT" command and its associated print spooler is:

      CB  Add the command "PRINT" to your AUTOEXEC.BAT file.  This causes
         the resident portion of the DOS print spooler to be loaded into
         memory, and to remain there.

      CB  Change the definitions of the "printTxt" macro and the
         "incPrint" macro to:

              print %f

         This will cause the DOS print command to be used for each print
         operation.

   Similar procedures should work for other print spoolers.
