
                       N O T E B A S E   v. 1.2
                       ------------------------

                         INTRODUCTORY TUTORIAL


Please proceed through the following to get a feel for the product.

 1) Extract files in self-extracting file NB012.EXE to a special
    sub-directory - \NB is suggested (you will probably already have
    done so).

 2) At the DOS prompt, enter the command:

           notebase appdev

    After the obligatory Shareware nag screen (apologies), NoteBase
    will open files APPDEV.NBD (the database) and APPDEV.NBM (its memo
    file) and automatically generate five indexes named APPDEV_1.NBI,
    APPDEV_2.NBI etc.

 3) NOTEBASE'S MAIN SCREEN
    ----------------------
    NoteBase's opening screen lists Topics on the left and their
    Sub-Topics on the right.

    At this moment the file contains ONLY the Topic titles shown at
    left - there's nothing in their Sub-Topics.

    Please tap <F1> and read the help topic 'NoteBase's Main Screen' to
    get the concept of the use of the cursor keypad.

    The on-screen help you are viewing is available throughout NoteBase
    and is context-sensitive. While help is displayed

      . Cursor down/up scrolls through the currently-displayed topic
      . Numeric keypad +/- move the display forward/backward one
          help-screen through the currently-displayed topic
      . PgDn/PgUp displays the beginning of the next/previous topic
      . If '<^F1> Other' appears alongside the topic heading a pick
          list of related topics can be summoned by tapping <Ctrl-F1>
      . <Alt-F1> displays an index of help topics as a pick list

    Tap <Esc> to return to the program from the on-screen help.

    To familiarise yourself with another aid which you are likely to
    find useful, tap <Alt-O> to summon a list of available options,
    scroll through it, then tap <Esc> to return to the program.

 4) READING IN AN ASCII FILE
    ------------------------
    First, we'll read one of the disk files you have just extracted -
    DCTY.PRG - into a new Sub-Topic for its appropriate Topic.

    Cursor through to Topics list to 'Clipper 5.2'. Ordinarily, when
    there are already Sub-Topics in existence, you would tap <right> to
    change focus to the Sub-Topics list. If you tap <right> now (while
    there are no Sub-Topics) a message will appear advising you of this
    fact and asking whether you would like to add one. Select 'YES'
    from the dialog box.

   [Note that tapping <right> when one or more Sub-Topics already exist
    will move the focus to the Sub-Topic panel. A new Sub-Topic can be
    added by tapping <Alt-S> while the focus is on either the Topics
    panel or the Sub-Topics panel.]

    A dialog box with four options will appear. Select 'ASCII FILE' and
    when the entry panel 'Sub-Topic title:' appears enter 'Directory
    listing function' and tap <Enter>.

    A prompt will now appear asking you to enter the ASCII file's path
    and name, or suggesting that you tap <F10> for a Directory pick
    list. Please tap <F10>, scroll the highlight to the entry
    'DCTY.PRG' and tap <Enter>. The path and filename should now appear
    in the entry panel - tap <Enter> to accept it. The entry panels will
    disappear from the screen and you will notice the Sub-Topic title
    that you entered under the heading 'Sub-Topics' at the right of the
    screen.

    File DCTY.PRG has been read from disk and stored in compressed
    format in the APPDEV file.

 5) VIEWING A SUB-TOPIC
    -------------------
    To view the Sub-Topic we have just saved, tap <right>. Notice that
    the Sub-Topics panel's background has now changed to cyan while the
    Topics panel's background has changed to normal white, indicating
    the switch of focus to Sub-Topics.

    When 'Directory listing function' is highlighted tap <Enter>. A
    pick list of NoteBase's more frequently used options, which serves
    as an aide memoire, appears with the highlight already resting on
    its most likely-to-be-used option - 'Edit/View Sub-Topic in screen
    editor' - so just tap <Enter> again to select it.

    The file you just read in from disk will appear in a screen editor.
    (The file is in fact an early version of the function in NoteBase
    which we accessed just now with <F10> to put a directory pick-list
    on the screen, differing only slightly from the current one.) It is
    in 'edit' mode in case a user wants to write or change something.

    This editing screen is absolutely 'raw' - no bells or whistles
    whatever. You will see how you can substitute your preferred ASCII
    editor shortly. The assumption is that you would prefer to use the
    search and alter etc etc commands with which you are already
    familiar than have to learn a new set. This 'scratchpad' editor is
    just a quick and easy way to look at something or to enter a line
    or two of text.

    Please tap <Esc> to close the edit screen without saving any
    changes.

    Now let's use your ASCII text editor to look at this newly-entered
    Sub-Topic in a more articulate environment. Tap <Enter> again with
    the highlight on 'Directory listing function' and when the
    'Frequently-used options' picklist appears select its SECOND option
    - 'Edit/View Sub-Topic in your ASCII editor'. You will be asked to
    enter the path and name of the editor. Please do this and tap
    <Enter>. The Sub-Topic should now appear in your ASCII editor.

   [The act of entering your text editor's path and name should not
    need to be done again as it will have been saved to disk in
    NoteBase's configuration file - NB.CFG.]

    Use whatever means you need to exit from your text editor without
    saving any changes you may have made. NoteBase's screen should
    reappear as you left it.

    What NoteBase just did with both the scratchpad editor and your own
    ASCII editor was retrieve and expand the compressed Sub-Topic and
    present it for viewing or editing. Had you made any alterations the
    altered Sub-Topic text would have been compressed and stored in
    place of the previous version.

    There is a shortcut key to jump straight into your text editor
    which you might like to try. With the highlight still on 'Directory
    listing function' tap <^Enter> (Ctrl-Enter). You should be back in
    your ASCII editor again.

    Use whatever means you need to exit from your text editor and get
    back to NoteBase again.

 6) DIRECTLY ENTERING A NEW SUB-TOPIC
    ---------------------------------
    Let's just enter a couple of shorties.

    Making sure that the Topic highlight is still on 'Clipper 5.2' but
    without worrying whether the Topic panel or Sub-Topic panel has
    focus, tap <Alt-S>. A dialog box will ask whether you wish to
    insert a new Sub-Topic before or after 'Directory listing
    function'. Select 'AFTER' and from the dialog box which follows
    select 'ENTER DIRECTLY'. Enter the title 'TRANSFORM() in 5.2d' and
    tap <Enter>, then in the no-frills entry screen that appears
    type the following line-for-line:

      "If you find some unexpected things happening when you compile
       a 5.2c application in 5.2d, check to see whether you are calling
       TRANSFORM() anywhere using the picture function "@R". There
       seems to be an undocumented fix in 5.2d for an apparently
       unacknowledged bug for which you may previously have devised a
       workaround, which now doesn't work."

    Tap <^W> to save the entry.

    Move the focus back to Topics and the highlight to 'Clipper Summer
    '87'.

    Tap <Alt-S> and select 'ENTER DIRECTLY'. As a Sub-Topic title, type
    in "EMM386.EXE" and tap <Enter>.

    In the entry screen type:

      "Remember to add the parameter NOVCPI as well as NOEMS when using
       an application with DOS 6."

    and tap <^W> to save it. The highlight should now be resting on the
    new Sub-Topic title.

 7) ENTERING KEYWORDS
    -----------------
    With the Topics highlight on 'Clipper Summer '87', the focus on
    Sub-Topics (tap <right> if necessary) and the Sub-Topics highlight
    on 'EMM386.EXE', tap <Alt-K> to list any keywords already entered
    for this Sub-Topic. Of course, there'll be none at this stage
    because we haven't entered any, so the list will read 'NO KEYWORDS
    FOR THIS SUB-TOPIC'.

    Tap <Alt-A> to add a keyword and when the entry panel prompt 'New
    keyword:' appears, type 'NOVCPI' and tap <Enter>. The new keyword
    will be visible in the keyword list.

    Let's enter a second one - tap <Alt-A> again and enter "NOEMS".
    The second keyword now appears in the keyword list.

    Now let's go back and enter keywords for the Clipper 5.2 entries.
    Tap <Esc> to remove the keyword list, move the focus back to Topics
    by tapping <left>, highlight 'Clipper 5.2' and tap <right>. With
    the highlight on 'Directory listing function' tap <Alt-K> - of
    course there will presently be no keywords for this Sub-Topic.

    Tap <Alt-A> to add a keyword, enter 'Clipper Functions' and tap
    <Enter>. The new keyword will appear in the keyword list.

    Tap <Esc> to remove the keyword list then <down> to move the
    highlight to the 'TRANSFORM...' Sub-Topic, then summon a list of
    the Sub-Topic's keywords with <Alt-K>. Tap <Alt-A> to add a new
    keyword.

    Notice that the bottom line of the entry panel reads "<Alt-L>ist
    current keywords for selection". Tap <Alt-L>. A pick list of ALL
    currently-entered keywords appears. For keyword searches to work
    effectively, absolutely identical keywords should be used to
    identify similar subjects. This pick list serves both as a reminder
    list and as a means of ensuring identical usage by tapping <Enter>
    on an existing keyword to copy it into the entry panel.

    Tap <Esc> to remove the pick list panel, type 'TRANSFORM()' and
    tap <Enter>. Tap <Esc> to remove the keyword panel.

 8) FINDING ENTRIES BY KEYWORD
    --------------------------
    Tap the appropriate keys to move the focus back to Topics.

    The hotkey to find entries by keywords is <Alt-F>. With the
    highlight on no Topic in particular, tap <Alt-F>. A pick list of
    the four unique keywords entered will appear. Move the highlight
    to 'NOEMS' and tap <Enter>. A list of matches for 'NOEMS' will
    appear - in this case showing only one such entry, which will
    already be highlighted. Tap <Enter> to select it. Notice that the
    Topics highlight and the Sub-Topics highlight move to the entries
    that were highlighted in the pick list, and that the
    'Frequently-used options' picklist is presented. You can now tap
    <Enter> or <^Enter> to have the highlighted Sub-Topic (which was
    found by its keyword) displayed in NoteBase's 'scratch' editor
    or in your ASCII text editor, respectively.

    If you have tapped either <Enter> or <^Enter>, use the appropriate
    keystrokes (as described earlier) to return to the NoteBase Main
    Screen.

   [NOTE THAT entering keywords needs a somewhat methodical approach.
    If multiple entries with a common thread are to have keywords, the
    keywords should be IDENTICAL, as mentioned earlier. In that way,
    when you select the one keyword from the unique list presented when
    <Alt-F> is tapped, a list of ALL entries for which that single
    keyword has been entered will be presented for you to identify the
    entry you are seeking and move directly to.]

 9) CHANGING THE SEQUENCE IN WHICH TOPICS ARE LISTED
    ------------------------------------------------
    Do whatever is necessary to move the focus back on to Topics. We'll
    move 'Visual Objects' up under 'Clipper 5.2' to have all three
    CA products adjacent to one another.

    Place the highlight on 'Visual Objects' and tap <Alt-M> to mark it.
    The highlight for this entry changes colour to indicate that it has
    been marked.

    Move the highlight to 'Clipper 5.2' and then tap <Alt-Ins>. A
    dialog box will ask whether you wish to move Visual Objects before
    or after Clipper 5.2. Select 'AFTER'. The screen refreshes with
    Visual Objects in its new position.

    Moving Sub-Topics is achieved in an identical way.

10) ADDING A NEW TOPIC
    ------------------
    We'll add a Topic in readiness for the next version of Clipper.
    With the focus of Topics, tap <Alt-T>, then move the highlight to
    'Clipper 5.2' and tap <Enter>.

    In the entry box which appears, type 'Clipper 5.3' and tap <Enter>.
    Select 'AFTER' from the dialog box which follows.

    The new entry should now appear in the list of Topics.

11) EXPORTING TOPICS AND/OR SELECTED SUB-TOPICS
    -------------------------------------------
    Let's say that we felt some of our entries might be valued by other
    programmers using NoteBase to accumulate valuable programming hints
    etc. The key point above is 'some' rather than all - if the latter
    we could just provide a copy of our database but it would then
    contain everything and we might not want to pass on some items of a
    particularly personal nature.

    NoteBase's Export option allows whole Topics (ie all of their
    Sub-Topics) or just selected Sub-Topics to be exported - in both
    cases complete with their keywords.

    Move the Topic highlight to 'Clipper 5.2' and tap <right>. With the
    highlight on 'Directory listing function' tap <Alt-M> to mark it.

   [You may have noticed an asterisk appearing alongside 'Topics' when
    we marked 'Visual Objects' earlier and can see one alongside
    'Sub-Topics' now that we have marked an entry here. I won't go into
    details here, but please just note that you can read about the
    significance of these asterisks in the help topic 'Marking entries
    for Export/Moving' in due course.]

    The Sub-Topic's colour will change. This means that only that
    Sub-Topic is marked for export - the TRANSFORM() Sub-Topic will not
    be included.

    Tap <left> to return the focus to Topics, highlight 'Clipper Summer
    '87' and tap <Alt-M>. The entire Topic (which in this case only
    includes one Sub-Topic) is marked for export.

    Now export the marked items by tapping <Alt-X> with the focus on
    Topics, responding 'YES' to the confirmatory dialog box that
    follows.

    A dialog box will now appear asking whether any Binary files which
    might be encountered in the items to be exported should be
    compressed when saving. Whether or not to compress will depend on
    the sort of Binary files involved, for reasons which will become
    more clear later in this demonstration. As there are no Binary
    files involved in what we are presently doing, select 'NO'.

    Type 'CLIP' in the entry panel as the NoteBase file name and tap
    <Enter>. A message will confirm that NoteBase files CLIP.NBD and
    CLIP.NBM have been written to disk. Tap a key to acknowledge the
    'OK' option and remove the dialog box.

    At this stage the marked Topics and Sub-Topics retain their
    'marked' colours, in case you wish to do something else with some
    or all of them. You can either toggle a single marked item by
    moving the highlight to it and tapping <Alt-M> again or you can
    unmark ALL marked items by tapping <Alt-U> and responding Yes to
    the question asked. Please do that now.

    Exported NoteBase files can be imported with the <Alt-I> option. It
    wouldn't make much sense to do that here because we still have
    those entries in our database, and the Topics and Sub-Topics in the
    file being imported would be added to the file. NoteBase makes no
    attempt to determine whether something being imported might already
    be on file - that's for the user to determine and do something
    about. But we could take a look at what has been written by using
    the option to change to another NoteBase file.

    With the focus on Topics, tap <Alt-O> to display a list of all
    available options. (<Alt-O> can be used anytime you are uncertain
    about an option or can't remember its hotkey.) Scroll down until
    the entry 'Change to another NoteBase file' is highlighted. Note
    that this option's hotkey is <Alt-N>, which we could have used had
    we known about it, but now that we are here we can just tap
    <Enter>.

    A panel will appear, prompting the entry of a NoteBase file name.
    Tap <F10> to use its option to select from a pick list of files,
    move the highlight to CLIP.NBD and tap <Enter> to copy its name to
    the panel and <Enter> again to conclude the entry. Select 'YES'
    from the cautionary dialog box which is then displayed. The
    exported file should now appear.

    If you move the highlight to 'Clipper 5.2' you will notice that
    only the Sub-Topic you marked has been included.

    With the focus on Topics, tap <Alt-F> for a full pick list of
    keywords from which to find an entry and tap <Enter>. Notice that
    the keywords associated with the Sub-Topics of the APPDEV.NBD file
    which we marked for export were included. Highlight 'NOEMS' and tap
    <Enter> three times (once to select it, then to select the entry in
    the pick list of all entries with that keyword, then to select the
    default entry in the 'Frequently used options...' pick list). The
    entry you typed into APPDEV should now be visible in NoteBase's
    scratchpad editor.

   [As you develop your own NoteBase files and start to use the keyword
    facility extensively you may occasionally find it useful to tick
    two or more keywords when the full list is displayed with <Alt-F>
    by tapping <space> rather than <Enter> so that Sub-Topics matches
    subsequently listed will include either just those for which ALL
    keywords ticked have been used or for which any ONE keyword ticked
    has been used.]

    Tap <Esc> to close the scratchpad editor and return to the main
    screen. Now let's return to APPDEV by tapping <Alt-N>, typing in
    APPDEV and tapping <Enter> and selecting 'YES' from the cautionary
    dialog box which appears.

12) OTHER NOTEBASE OPTIONS
    ----------------------
    Rather than guide you through remaining options it might be better
    to describe briefly one or two of them and then leave you to
    experiment for yourself by tapping <Alt-O> when either the Topics
    list or Sub-Topics list has focus to display a scrollable pick
    list of available options and their hotkeys and using them on an
    as-needed basis. But briefly:

       Edit Topic/Sub-Topic titles by highlighting and tapping <Alt-E>.
       Delete Topics (& their Sub-Topics) or Sub-Topics by highlighting
          and tapping <Alt-Del>.
       Change the video display to 43/50 or back to 25 lines per screen
          by tapping <Alt-V> when the focus is on Topics.
       Shell to DOS when the focus is on either Topics or Sub-Topics by
          tapping <Alt-H>.
       Write a Sub-Topic to a disk file by highlighting it, tapping
          <Alt-W> and entering a file name.
       Casually viewing, editing or deleting a disk file without
          leaving NoteBase <Ctrl-F10>.

13) READING & WRITING BINARY FILES
    ------------------------------
    The term BLOB (Binary Large Object) seems to be gaining increasing
    usage to describe Binary files of various types (executables,
    images etc).

    NoteBase is able to store BLOBs as Sub-Topics, optionally
    compressing them as it stores to save disk space.

    While it is possible to store a very large number of ASCII text
    Sub-Topics of individual sizes up to 64Kb under any Topic (I
    stopped experimenting when I dummied up 1,400 such entries), there
    is a limit of ONE BLOB per Sub-Topic.

    When you save a BLOB, NoteBase displays an identifying beta
    character () at the right of the title and notes the name of the
    file and its normal length in bytes. This information can be read
    by highlighting the Sub-Topic and tapping <Enter> or <^Enter> to
    view it in either NoteBase's scratchpad editor or your ASCII
    editor.

    BLOBs which are already compressed (eg .LZH etc) will not be able
    to be further compressed - in fact, selecting the option to
    compress such files as they are stored will probably result in the
    file occupying more space than it would if stored as is. NoteBase
    detects this fact and offers the chance to re-store such BLOBs
    uncompressed.

    Not all users are likely to have any given BLOB I might suggest you
    use in an example, so I will leave you to make your own selection
    with the following guidelines:

    Start off by highlighting the Topic under which you wish to store a
    BLOB, then tap <Alt-S> as you would to add any Sub-Topic
    (indicating the new Sub-Topic's position if asked). Select 'BINARY
    FILE' from the dialog box which follows and type in the Sub-Topic's
    title. Type in a path and file name when asked (or tap <F10> and
    navigate through your disks' directories until you can highlight
    the file you want) then tap <Enter>. Opt to compress the BLOB while
    storing if you think this likely to save space (depends on your
    file).

    NoteBase will report that it is reading the file. If compression
    results in a saving over the file's normal size, the saving will be
    reported, otherwise you will be advised of the loss of space which
    has occurred and given the option to re-store without compression.

This has been a brief introduction to NoteBase. Please read the
on-screen help for more detailed information. If you prefer you can
print it as a paginated User Manual by using the hotkey <Alt-P> while
the focus is on Topics. You will be asked whether to print the manual
directly or write it to a formatted disk file - I suggest the latter so
that you can examine its contents in your ASCII editor prior to
printing and satisfy yourself that your printer can handle the graphics
characters in the manual. Alternatively, you can write individual help
topics to a disk file called HLPTOPIC.TXT (additively) by displaying
help with <F1>, finding the required topic and tapping <Alt-P> while it
is displayed.

While I have developed this programme with my own needs as an
application developer in mind (and I hope those of other developers
also), I think NoteBase could be put to a multitude of uses. If you
have any suggestions you would like to make about specific uses please
feel free to contact me via one of the following means:-

Phone:(Intnl): +61 9 455-1004                    S.R. Eddy & Associates       ph
  Fax:(Intnl): +61 9 455-2004                           267 Acourt Road       ph
CompuServe ID: 100033,3272                          CANNING VALE, PERTH       ph
     Internet: reddy@perth.dialix.oz.au        WESTERN AUSTRALIA   6155       ph


Richard Eddy, January 3, 1995.
