PRODUCT   :  R:BASE                  VERSION      :  3.1
   From Robert Saunders, Business Systems Consulting, 59 E. Linden Ave.,
   Suite B7, Englewood, NJ 07631. You can reach Bob at 201-568-3919.
   Each R:BASE application should have internal documentation to benefit
   those who develop and maintain the application and external
   documentation to benefit those who use the application.
   Using tools provided in R:BASE 3.1, you can create useful
   documentation with a minimum time investment.
   Internal Documentation
   Internal documentation is vital because in six months, or even two
   weeks, you'll be back trying to figure out what you did, and how you
   did it. Internal documentation includes descriptions and explanations
   for each table, column, form, and report as well as comments in R:BASE
   I frequently take over a client's system that was originally set up by
   someone else. Usually it was a consultant who won the lottery and
   moved to Tahiti or some such story. If the application has internal
   documentation, my job is easier, so it costs the client less money.
   At a minimum, internal documentation should include these items:
     o  Descriptive names for variables, tables, columns, forms, and
     o  Explanations attached to each table, column, form, and report.
     o  Liberal comments in macros, entry/exit procedures (EEPs), and
        other R:BASE programs. You should require application developers
        to place explanatory comments, enclosed in *(---), every few
        lines in all R:BASE programs. Comments in the code will save you
        hours of work when you want to make changes. Forget that old saw
        about comments slowing down your program. It barely makes a
   External Documentation
   Most systems I see have no user's manual, tutorial, or other help
   screens - nothing is written down. People pay consultants thousands of
   dollars for such systems. When the person trained to use it leaves the
   organization, there's nothing to show the next person how to use it.
   You should always require documentation, both internal and external,
   with every application. Would you buy R:BASE without a manual?
   Taking Snapshots of the Screen
   Using R:BASE 3.1 features, it's easy to put together a simple manual
   and tutorial. Use the SNAP command or press [Ctrl-F1] to take
   snapshots of the screen at each point in the program. A snapshot saves
   a screen image in a file.
   At any point in an application, whether you're developing it or using
   it, you can press [Ctrl-F1], and a  menu will pop up. Choose "Take a
   Snapshot," and R:BASE will ask you to name the snapshot file. That's
   all there is to it.
   Snapshots taken by pressing [Ctrl-F1] can be edited, but snapshots
   taken with the SNAP command can't. This is because SNAP adds screen
   characters such as colors to the file. Use the DISPLAY command to view
   shapshots taken by SNAP.
   Take Snapshots of Everything
   Press [Ctrl-F1] to take snapshots of forms, reports, and menus and
   store them in a set of files. Snap them empty and snap them when they
   contain sample data. To view or print the snapshot files, use RBEDIT
   or DISPLAY. For example, the following prints a snapshot file
     DISPLAY tranform.snp
   You could use RBEDIT to edit the snapshots to add comments, but it
   might be better to print them as is, and then hand write the comments.
   That way it will be obvious what's part of the form and what's a
   Also take snapshots of all the menu actions in an Application EXPRESS
   application. To do this, start Application EXPRESS, and choose the
   application as if you were going to modify it. Then press [Shift-F3]
   for the menu. Choose the menu you want, and then press [Shift-F3]
   again. The menu actions will appear. Press [Ctrl-F1], and take a
   snapshot. Then go on to the next menu and do the same until you've
   snapped all the actions associated with each menu. Use these snapshots
   and the snapshots of the actual menus to make the manual.
   Making a Manual
   To read snapshot files taken by [Ctrl-F1], you can use any text editor
   or a word processor set to text (DOS, non-document, or ASCII) mode.
   To combine the files using RBEDIT, enter the SET BELL OFF command at
   the R> prompt. Then start RBEDIT, and bring up the first snapshot
   file. Go to the end of that file by pressing the [End] key. Then press
   [Ctrl-F1]. From the menu box, choose "Play back a Script," and enter
   the name of the snapshot file you want to merge. Continue until all
   the snapshot files are combined. To insert a snapshot file into the
   middle of a file, you must first press [F10] several times to create
   enough blank lines for the new file. If your editor can't combine
   files easily, you can use the DOS COPY command to combine the files:
     COPY file1+file2 file3
   This adds FILE1 and FILE2 together to make FILE3. Make sure there are
   no spaces around the plus sign.
   After combining the snap files, add text explaining how to use the
   forms, reports, and menus. Then print the new manual.
   Making a Tutorial
   You can use the same file (the one containing all the combined
   snapshots) to make a tutorial by using it with a program that shows
   one screen at a time. There are some powerful, complicated, commercial
   packages that will do this, but there are also some simple,
   inexpensive ones. There's even one (DISPLAY.EXE) that's free. It's in
   the public domain, written by P.J. Ponzo, Department of Applied Math,
   University of Waterloo, Ontario N2L 3G1, Canada.
   After adding a dozen or so simple dot commands to an ASCII file, you
   can use DISPLAY.EXE to make your ASCII file into a self-running demo
   with questions and pauses where desired.
   Don't confuse the DISPLAY.EXE program with the R:BASE DISPLAY command.
   They are totally separate. The DISPLAY command is part of the
   RBASE.EXE file, so it works in R:BASE. To run DISPLAY.EXE, you need to
   enter DISPLAY at a DOS prompt.
   DISPLAY.EXE is available from many user groups. It comes with EXPLAIN,
   a documentation file. Enter DISPLAY EXPLAIN at the DOS prompt to get
   the explanation. both DISPLAY.EXE and EXPLAIN are included in the ZIP
   file (MRIM1091.ZIP) that contains this October 1991 issue of Microrim
   ONLINE. Remember DISPLAY.EXE is not a Microrim product, so Microrim
   does not endorse, recommend, or support it. If you have questions,
   call the author, P.J. Ponzo, not Microrim.
   To run DISPLAY.EXE, you must have a file named ANSI.SYS. It comes with
   your DOS operating system. After making sure the file is in your root
   directory, add the following statement to the CONFIG.SYS file located
   in your root directory:
   The ANSI.SYS file allows for colors and some simple graphics. I was
   amazed by DISPLAY.EXE. It is small (24K), straight-forward, and the
   easiest way possible to make a tutorial from snapshot files.
   If you have R:BASE 3.1A or higher, you can use the new ZIP RETURN
   command in R:BASE to zip out of R:BASE and run DISPLAY.EXE. This means
   you can even include your tutorial as a menu choice. With tools like
   these, anyone can make manuals and tutorials quickly and easily. In
   the long run, good documentation will save you many more hours than it
   takes to create.