/*------------------------------------------------------------------*/
/*                                                                  */
/*  PEEK-A-BOO documentation file                 /V1.7/07-FEB-94/  */
/*                                                                  */
/*------------------------------------------------------------------*/

/*------------------------------------------------------------------*/
/*                                                                  */
/*  Help on File Viewer                       /File: PEEKABOO.HLP/  */
/*                                                                  */
/*------------------------------------------------------------------*/



Credits:
   See at the bottom of this file.



Contents of this distribution (PEEK_V17.ZIP):
   PEEKABOO.PRG  - the executable,
   PEEKABOO.HLP  - this document.



Covered topics in this document:
   FUNCTIONALITY
                 - An Introduction
   PROGRAM USE
                 - Starting PEEK-A-BOO
                 - Selecting another file to load
                 - Text scrolling
                 - Ending the program
   INTERACTING WITH PEEK-A-BOO
                 - User Input
   SEARCH CAPABILITIES
                 - Line search
                 - String search
                 - Clearing highlighted blocks and search buffer
   USE OF HELP
                 - Displaying the version number of PEEK-A-BOO
                 - Using help
                 - Locating the help document
   COMMAND SUMMARY
   NEW IN VERSION 1.7
                 - Variable TAB size for ASCII files
                 - Binary file display
                 - Save window positions
                 - Peekaboo.inf
                 - PEEKABOO environment variable
   ACCESSORIES AND THE SCROLLING BUG
	FURTHER INFO
	              - Disclaimer
	              - Info about the author





/*------------------------------------------------------------------*/
/*                                                                  */
/*                    FUNCTIONALITY:                                */
/*                                                                  */
/*------------------------------------------------------------------*/


     Displays a file in a GEM window.
     It was written GEM-conform, so it should run on all ATARI
     ST(E)/TT/Falcon, under MULTIGEM, (MULTI)TOS.


An Introduction:
----------------

PEEK-A-BOO can be used as accessory and as a desktop program.
It does not need any external files (like resources) in order to work.
Any ASCII- or binary text can be loaded to be displayed in a GEM
window, with full slider / cursor movement control.
The program uses no text-cursor; it is only a viewer, not an editor.

When installed as a desktop icon, you can drop a file on the icon and
the program will start up with that file already loaded. In other
words, the program can take a filename as argument.

In fact, it will accept a whole list of argument-files: this list of
files can then be viewed one after the other.
For instance: type "peekaboo  *.doc" inside a command interpreter like
mintshell...
However, you need an interpreter with command line extension, because
peekaboo will not expand arguments.

The currently viewed filename is shown in the info-line, together
with the file-length.
Default TAB spacing for ASCII files is 3 characters.





/*------------------------------------------------------------------*/
/*                                                                  */
/*                     PROGRAM USE:                                 */
/*                                                                  */
/*------------------------------------------------------------------*/


Starting PEEK-A-BOO:
--------------------

To start the peekaboo program, double-click the peekaboo.prg window
icon or drag a file to the peekaboo desktop icon.

To use the program as a desk accessory, simply rename the extension
.PRG to .ACC and copy peekaboo.acc plus peekaboo.hlp to the root
directory of your boot drive (C: -  or A: if you have no harddisk).
Reboot your computer and look in the DESK menu for the entry
"Peek-A-Boo". Select it and you'll get a fileselector box.

When PEEK-A-BOO runs you have the following options:


Selecting another file to load:
-------------------------------

*) Pressing <CNTRL>-O will normally open the file-selector box.
   However: if the program was started with file-arguments, the next
   file in the argument list will be loaded automatically. When all
   file arguments have been processed, a file-selector will appear.

Text scrolling:
---------------

*) Use of the sliders is obvious; the slider sizes reflect the total
   length of the file (vertical) and the maximum line-length in the
   file (horizontal).

*) <HOME> / <SHIFT>-<HOME> will take you to the beginning / end
   of the file;

*) <ARROWUP> / <ARROWDOWN> scrolls one line of text;

*) <SHIFT>-<ARROWUP/DOWN> scrolls a page.

Ending the program:
-------------------

*) Pressing <CNTRL>-Q will do the job very definitely.
   In case of use as an accessory, the current file in memory will
   be abandoned.

*) ONLY when using the accessory version:
   Pressing <CNTRL>-U will close the window but will not release the
   file in memory. Upon repeated activation of the desktop accessory
   the current file will again be displayed.
   Because of the habits of accessories, this will only be
   possible as long as you don't start or end a main application
   on your desktop in the mean time.





/*------------------------------------------------------------------*/
/*                                                                  */
/*                 INTERACTING WITH PEEK-A-BOO:                     */
/*                                                                  */
/*------------------------------------------------------------------*/

User Input:
-----------

PEEK-A-BOO is an interactive program. It communicates with you,
the user, not by using dialog boxes but by using the infoline of
the GEM window.

The program can be in one of two states: 'quiet mode' and
'dialog mode'.
In 'quiet mode' the infoline of the program window contains useful
information about the text file you are currently viewing.
When the program is in dialog-mode it displays an appropriate prompt,
as well as your input as you type it in.
The following rules apply when the program is in dialog-mode:

*) <ESC>         erases the visible input line;

*) <BACKSPACE>   deletes the last character in the input line;

*) <RETURN>      starts processing of the input line.

Why would you want to communicate with PEEK-A-BOO ?





/*------------------------------------------------------------------*/
/*                                                                  */
/*       PEEK-A-BOO offers some interactive search capabilities:    */
/*                                                                  */
/*------------------------------------------------------------------*/


Line search:
------------

You may jump to any desired line number in the currently viewed file,
by pressing <CNTRL>-L and entering either:

*) An absolute number (e.g. 2, or 445 etc.)

*) A number relative to the current topline, represented by a dot
   (e.g:   .+14    , or:   .-23    , etc. )

*) A number relative to the end of text, represented by a dollar sign
   (e.g:   $-274).

followed by a <RETURN>.

After pressing <CNTRL>-L, the current topline number will be displayed
in the window's infoline; After entering the desired line number, this
line will be displayed as the topline in the window;
In case of non-existing line number the text will scroll to the end of
the document;

String search:
--------------

You can look for the occurrence of a search string in the current
document. Searching can be performed downward (towards the end of
document) or upward.
The search string is stored in a 'search buffer' in case you want to
look repeatedly for a piece of text.

Searching for text in an ASCII-file is case-insensitive! This is not
true for binary files.
When a search is unsuccessful the system bell will sound.
Tough luck for anyone who turned off the bell...

When a matching pattern is found in the text, this match will be
displayed in highlight (that is, in reverse video). If the matching
pattern was not visible in the window before, the window contents will
be adjusted, so that the text line containing the highlight will be
displayed in the middle of the window.

A search string is limited to one line. There is a number of possible
ways to search for text.

Direct search
-------------

(A search string is entered using the keyboard):

*) A search string can be entered manually after pressing <CNTRL>-F;
   The current contents of the search buffer are then displayed in the
   info-line of PEEK-A-BOO's window.
   Typing errors can be corrected by using <BACKSPACE> ; pressing
   <ESC> will erase the current set of characters in the buffer.
   A <RETURN> will start the search, beginning at the first text line.
   An alertbox is displayed when the pattern is not found.

Indirect search
---------------

(A search string is created by highlighting a part of text in the
window; in this case the searching is not started immediately):

*) The search string can be selected with the mouse, by pressing the
   left mouse button over a desired portion of text in the window and
   moving the mouse; when the mouse button is released, the highlighted
   string will be stored in the search buffer.
   (You can check that by pressing <CNTRL>-F wich always displays the
   current search buffer).

*) By double-clicking in the PEEK-A-BOO window you are able to select
   a single word to search for. Valid characters in this case are
   alpha-numericals (A-Z, a-z, 0-9) and the underscore: '_'.
   The highlighted word will be stored in the search buffer.

*) Pressing <CNTRL>-I when the mouse is inside the PEEK-A-BOO window
   has the same effect as double-clicking at that position.


There is a number of ways to search repeatedly for the pattern in the
buffer after you found an occurence:
A repeated search starts at the first position behind a highlighted
part of text (taking the search direction into account of course);

*) Pressing <CNTRL>-G searches in the default direction;
   multiple use of <CNTRL>-G will loop you up and down the file
   endlessly (should you enjoy doing so) and the bell will sound
   every time you reach the beginning or end of the file.

*) Pressing <CNTRL>-<ARROWUP> searches upward until beginning of file;

*) Pressing <CNTRL>-<ARROWDOWN> searches downward until end of file;


Clearing highlighted blocks and search buffer:
----------------------------------------------

*) Pressing <RETURN> or the left mouse button will clear the
   highlighted block;

*) Pressing <UNDO> or the right mouse button will clear both block
   and buffer.





/*------------------------------------------------------------------*/
/*                                                                  */
/*                           USE OF HELP:                           */
/*                                                                  */
/*------------------------------------------------------------------*/


Displaying the version number of PEEK-A-BOO:
--------------------------------------------

*) Pressing <ALT>-H will pop up an alertbox with program information.


Using help:
-----------

Pressing <HELP> can have two different results:

*) This document is displayed in a separate window if peekaboo can
   locate it. The helpfile must be named "PEEKABOO.HLP".
   All peekaboo functions are available in this windows.

*) An alert box saying "Can not load file!" pops up if this help
   document can not be located.

Locating the help document:
---------------------------

The obvious choice is to keep PRG and HLP file in the same directory.
Contemplate on how the program locates the associated helpfile:

*) PEEK-A-BOO was installed as accessory.
   In this case the help document is searched in the current directory
   and in the root directory of the boot drive C: (or A: if the C:
   drive is unavailable).
   Normally, this is where all the accessories are located.

*) PEEK-A-BOO is run from the desktop.
   In this case the help document must be located in the default
   directory or the root directory of the current drive for the
   program to find it.
   When you started the program by double-clicking it in a desktop
   window, the default directory is the directory where the PRG itself
   is located.
   If an environment variable PATH exists, all the search paths that
   are defined in PATH will be used for the search as well.
   If an environment variable PEEKABOO exists, this has priority over
   the PATH environment. See also the chapter "New in version 1.7".




/*------------------------------------------------------------------*/
/*                                                                  */
/*                           COMMAND SUMMARY                        */
/*                                                                  */
/*------------------------------------------------------------------*/


All key sequences are listed here for completeness and as a reference.

<CNTRL>-F             Find a text string
<CNTRL>-G             Repeat search for text string
<CNTRL>-H             Close window and remove file from memory
<CNTRL>-I             Find word under mouse cursor
<CNTRL>-O             Open new file
<CNTRL>-Q             Quit Peekaboo
<CNTRL>-U             Close window but do not remove file from memory
<CNTRL>-<ARROWUP>     Repeat search in upward direction
<CNTRL>-<ARROWDOWN>   Repeat search in downward direction

<ALT>-H               Display program info
<ALT>-S               Write current settings to PEEKABOO.INF
<ALT>-T               Change/display TAB setting

ENTER                 Clear highlighted area -or- end input mode
ESC                   Clear input line when in input mode
HELP                  Show this helpfile
UNDO                  Clear all search buffers and search modes




/*------------------------------------------------------------------*/
/*                                                                  */
/*                           NEW IN VERSION 1.7                     */
/*                                                                  */
/*------------------------------------------------------------------*/


Variable TAB size for ASCII files:
----------------------------------

Peekaboo expands TAB characters into spaces. The default expansion is
3 spaces. By pressing <ALT>-T you are able to enter a new tab spacing
which takes immediate effect. This new spacing will be saved in the
info file PEEKABOO.INF when you quit peekaboo.

Binary file display:
--------------------

In case peekaboo loads a file that is not a plain ASCII file, this
file will be displayed as binary data: a representation of the data
in hexadecimal format, flanked by the equivalent extended ASCII
characters.
Searching in binary data is limited: The search string is an ascii-
string and can not contain null ( 0x00 ) characters. Highlighting
parts of the window text with the mouse is only possible in the right
(ascii) region of the window.

Save window positions:
----------------------

Peekaboo remembers its window positions by storing them in an info
file named PEEKABOO.INF
Note: a window's relative placement with respect to the desktop area
is stored so that this method is resolution-independent.

PEEKABOO.INF:
-------------
In version 1.7 of Peekaboo the size of this file is 40 bytes.
Currently the window positions and tab size are stored in it.
The file is updated on every exit of the program. When run as an
accessory, the file is updated whenever you end the accessory by
pressing <CNTRL>-Q or when you end a main application.

You can force an update of PEEKABOO.INF at any time by pressing
<ALT>-S.

PEEKABOO environment variable:
------------------------------

Peekaboo can locate the .HLP and .INF files more easily when an
environment is set, like for instance under MultiTOS; or using a
program like setenv.prg for single tasking TOS.
All directories that are defined in the PATH variable are searched.
In case an environment variable PEEKABOO exists, this variable has
priority over the PATH variable.
The PEEKABOO environment variable must contain the directory in which
you installed the peekaboo files, for instance:
PEEKABOO=E:\TOOLS\PEEKABOO\






/*------------------------------------------------------------------*/
/*                                                                  */
/*                ACCESSORIES AND THE SCROLLING BUG:                */
/*                                                                  */
/*------------------------------------------------------------------*/


Some TOS versions (including MultiTos) display a bug when you want
to move the window scrollbars of a desktop accessory with your mouse.

I want to recommend everybody to use the two progams by Martin Osieka:
gemram16.prg and winx22.prg that solve the above problems and add a
load of exciting new features to your desktop manager. These versions
work not only for German TOS, but for UK TOS as well.





/*------------------------------------------------------------------*/
/*                                                                  */
/*                        Further  Info                             */
/*                        -=-=-=-=-=-=-                             */
/*                                                                  */
/*   HISTORY:                                                       */
/*   v1.4          200992        First public version.              */
/*   v1.5          260893        Fixed accessory termination bug.   */
/*   v1.6          200993        Less BEG_UPDATE screen holdups;    */
/*                               Fixed numerous annoying buggies;   */
/*                               Added HELP facility.               */
/*   v1.7          300194        Rewritten completely; now uses     */
/*                               multiple windows and will display  */
/*                               binary files as well. File-loading */
/*                               is much faster.                    */
/*                                                                  */
/*------------------------------------------------------------------*/
 *                                                                  *
 *  This program is written on a TT (Tos 3.06) using Pure-C v1.1.   *
 *  It is hereby placed in the public domain.                       *
 *  This means that you are free to make copies of the distribution *
 *  file PEEK_V17.ZIP and pass it on to friends and relatives.      *
 *  No fee in any form may be charged to anyone who receives a copy *
 *  - except for costs of distribution media such as floppy disks.  *
 *  The copyright of this program will remain with me alone!        *
 *  PRG and HLP files may not be copied seperately and              *
 *  all files must remain in the distribution in unchanged form.    *
 *                                                                  *
 *                                                                  *
 *  >>>If you like this software, please let me know.               *
 *     Send a message, or a present, or pay me a visit;             *
 *     whatever, I'll be greatly pleased by it!                     *
 *                                                                  *
 *                                                                  *
 *                                                                  *
 *                      DISCLAIMER:                                 *
 *                      -=-=-=-=-=-                                 *
 *  If you use these programs, you do so at your own risk.          *
 *  In no way will I accept responsibility for equipment damage,    *
 *  data loss, or any other unforeseen consequence of the use or    *
 *  abuse of these programs.                                        *
 *                                                                  *
 * -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= *
 *                                                                  *
 *  For further info, bug reports and encouragements write to:      *
 *                                                                  *
 *     Eric Hameleers                                               *
 *     Botenlaan 12                                                 *
 *     5652 CA Eindhoven                                            *
 *     The Netherlands                                              *
 *                                                                  *
 *     Internet email:    eha@dasc.nl                               *
 *                                                                  *
 *  In the Netherlands:                                             *
 *  Leave a message for Eric Hameleers in the Atari Benelux BBS     *
 *                                            tel : 03473-77584     *
 *                                                                  *
 *------------------------------------------------------------------*/
