********************************************************************
* Documentation for PUFF V3.05 - Dave Mitchell April 1988 *
********************************************************************

PUFF is a directory and file browser which pops up on demand. It
takes up between 29 and 42K of memory when resident (depending on
installation options). It runs under DOS 2 or 3 on any model PC and
will work on both Mono and Color adapters. Once installed you pop it
up at any time by pressing the hot-key which by default is Alt-D.
This gives you the ability to browse directories and both ASCII and
non-ASCII files within other programs such as word processors, spread-
sheets, debuggers or even at the DOS prompt. It's intended to be very
easy to use and contains several screens of on-line help accessible
via the F1 key so you shouldn't need to read this document to use it!
PUFF makes it possible to do things like:
- browse the source of a program while debugging it
- check the name of a file in a directory before loading it into
a spread-sheet
- quickly move up and down a directory tree looking for a file
- check when you last saved a particular file
- copy part or all of one file into an editor or word processor
- see how much room there is on a diskette before saving a file
- erase, copy or rename files at any time

There are three reasons why PUFF may not be able to pop up when
you want it to:

- the application that's currently running is not asking for a
keystroke. PUFF won't pop up in long-running "batch" programs
like compiles or assemblies.
- the current display is in a graphics mode. PUFF can only pop up
in text modes.
- at the time you ask PUFF to pop up, DOS is busy. PUFF checks
to make sure that nothing dangerous (such as file I/O) is going
on when you ask it to pop up.

Despite all my efforts, PUFF is still not entirely "crash-proof".
See the section on THINGS TO AVOID for more details.

SUMMARY OF CHANGES
PUFF Version 3 is a major rewrite of PUFF. Many new features
have been added and a few have been dropped. Here's a summary:

General Changes:
- support for larger screens (43-line etc)
- some support for enhanced keyboard (although PUFF doesn't know
names such as F11, F12 etc, they can be set as the hot-key)
- better bw80 support (treated as Mono not Color)
- all PUFFSET customising functions now included
- the directory/file buffer is now 6 or 12K
- the PUFF box can be quickly moved to screen corners using Home,
End PgUp and PgDn keys
- when pasting, line feeds can be ignored or pasted
- the normal cursor is suppressed when PUFF is popped up
- PUFF now always pops up on the current DOS screen (can't force
Mono anymore)
- PUFF no longer supports 40-column screens

In Directory Browse:
- new popup menu of commands via "?"
- attributes can be shown (instead of size)
- date/time are properly country-dependent
- sorting is almost twice as fast
- original DOS order can be restored
- new commands allow copy, erase and rename of files (and rename
of directories and moving of files)
- can now switch directly to another directory via 'N' command
- customise options menus available directly via 'O' command

A number of commands have had to change "name":
D does Directory Refresh (was R for Refresh) since R is Rename
T forces TEXT mode file browse (was A for ASCII) since A now
toggles Attribute/size display

In File Browse:
- new popup menu of commands via "?"
- can now switch directly to another file via 'N' command
- customise options menus available directly via 'O' command
- browsing is almost twice as fast
- searching is almost twice as fast
- search string can always be entered in hex or text
- search can be case sensitive or not as required
- in text mode, the cursor moves as in a normal editor

A number of commands have had to change "name":
T goes from HEX to Text mode (used to be A for ASCII)
A switches to ASCII rather than EBCDIC when in HEX mode (was
T for Translate) since T goes to Text mode
R does repeat search (was N for Next) since N goes to New file

INSTALLING PUFF
When invoked, PUFF looks for its profile in the current and root
directories of the current drive. The profile, a file called PUFF.PRO,
can be created or tailored using PUFF itself (see the section
"Customising PUFF"). Use SUBST, EXT, SRCHDIR or a similar program if
you want to put it somewhere else. If PUFF can't find its profile it
uses default values.

The PUFF command looks like this:
PUFF [hotkey] [initvu] [/n][/e][/s][/b][/l][/q][/x][/h]
or
PUFF ?

The second form will give you a brief description of PUFF and the
syntax of the first form.
All the parameters in the first form of the command are optional.
The first, the hot-key, is Alt-D by default but PUFF will accept:

a-x where x is any letter a-z (26 Alt keys)
c-x where x is any letter a-z (26 Ctrl-keys)
fn where n is any number 1-10 (10 Function keys)
a-fn where n is any number 1-10 (10 Alt-Function keys)
c-fn where n is any number 1-10 (10 Ctrl-Function keys)
s-fn where n is any number 1-10 (10 Shift-Function keys)

The default hot-key can be changed by creating a new PUFF profile.
See the section "CUSTOMISING PUFF" for details. Function keys F1
and F2 have special uses inside PUFF so they should not be used as
hot-keys.
The second parameter, initvu, lets you specify the name of a file
which PUFF will display on first popping up (rather than displaying
the main menu). Note PUFF will treat anything it doesn't recognize
as a hot-key as an initvu specification. If your initvu option
could be mistaken for a hot key (e.g. "F2") then you MUST specify
the hot-key too. If the name matches a set of files (e.g. it
contains an asterisk), then PUFF will popup in directory browse.
The /r option lets you `remove' a copy of PUFF that is already
resident. This can be useful in BAT files that invoke programs
incompatible with PUFF, as a way of ensuring that PUFF is not present.
If you attempt to install PUFF when it already resident PUFF will
not re-install itself but will tell you what the hot-key of the
already installed version is.
The /n (Normal) option restricts PUFF to the top 25 lines of the
screen. This reduces memory requirements by about 4K.
The /e (EGA) option allows PUFF to use up to 50 screen lines (on an
EGA, VGA or MCGA), but increases memory requirements by about 4K.
The /s (Small) option forces PUFF to use only 6K of buffer space,
reducing its memory requirements at the cost of performance.
The /b (Big) option makes PUFF use 12K of buffer space, by doubling
the sizes of PUFF's directory and file buffers. This allows PUFF to
handle directories with up to 555 files. If there are less than 275
files then PUFF does not have to re-read the directory when returning
from a file browse, improving performance considerably. The extra
file buffer makes scrolling through a file faster too, since the file
is read in 4k rather than 2k chunks.
The /l (Loud) option makes PUFF install itself `noisily', producing
a banner which gives its version number and buffer sizes.
The /q (Quiet) option makes PUFF install itself `quietly', without
any banner or messages.
The /x (eXclude) option excludes the installation of on-line help.
This makes PUFF take up less storage (about 3K less at present but
this might increase if more help is added) but means that inside PUFF
only a single screen of help is available.
The /h option (Help) includes the on-line help.
PUFF.COM is about 23K in size but takes up 29-42K when installed.

PUFF'S MAIN MENU
When you press the hot-key PUFF will test to see if it's safe to pop
up. It won't pop up if DOS is doing something that it would be
dangerous to interrupt. If you try to pop up when the screen is in a
graphics mode, PUFF will beep instead (earlier versions looked for a
Mon screen in this case).
When popped up, the main PUFF menu offers the following options:
.Browse Current Directory
.Select Directory for Browsing
.Customise (set options)
.Write new profile (save options)
.Quit (pop-down)
.Remove PUFF from Memory

The current directory is shown at the bottom of the menu. One of
the options will be high-lighted. The cursor up and down keys move
this bar and the Enter or Cursor Right keys select the high-lighted
option. You can also select an option by typing the first letter on
the line (B for Browse, R for Remove and so on).
F1 will usually give context-sensitive help (unless the /x option
has been used).
PUFF treats the Esc key as a general "cancel" or "quit" key. PUFF
will also let you `exit immediately' by pressing the hot-key rather
than Esc. You can do this at any time (except when help is being
displayed or input being requested).
If you leave PUFF this way you will return to where you left off
when you pop up PUFF again.
Most of the time PUFF responds to the F2 key by copying the active
screen to the alternate display - if you've got one! This allows you
to save the PUFF screen on the other display and then consult the
data it contains when you return to the original application. Note
that the attributes are `not' copied since some color attributes can
cause unpleasant blinking on a Mono display.

BROWSE CURRENT DIRECTORY
This option will cause PUFF to display the current directory. On
entry to PUFF this will be the current directory on the current drive
(unless PUFF has been customised - see "CUSTOMISING PUFF" below).
Twelve lines are shown, with the current line at the centre. Each
line shows the filename, size and date/time stamp. Sub-directories
are indicated by . Instead of filesize, PUFF can display the
file attributes.
The order in which the files are initially displayed is by default
the same order as a DOS DIR command would display, but you can make
it by name, extension, date or size by forcing PUFF to do a sort
before it displays the list. See the section on "CUSTOMISING PUFF"
for details.
PUFF displays file dates in either MM/DD/YY (US) format, DD/MM/YY
(European) format or in YY/MM/DD format (Japanese etc). and times in
12- or 24-hour clock style, depending on the COUNTRY code setting in
CONFIG.SYS, just as the DOS DIR command does.
In directory browse PUFF responds to keys as follows:
? pops up a command menu
A (Attribute) toggle between display of attributes or file size
C (Copy) copies current file
D (Display) refresh directory buffer (eg after erase/rename/copy)
E (Erase) erases current file
F (Free) display free space available on drive
H (HEX) as Right, but forces display to HEX mode
M (Move) moves current file
N (New) allow switch to new directory directly
O (Options) access the options menus
P (Paste) paste a file name or its contents into
the current application
Q (Quit) quit (return to Main Menu)
R (Rename) renames current file
S (Sort) sort current directory by Name, Extension,
Size, Date or back to DOS order
T (Text) as Right, but forces display to text mode

Up move up 1 line (towards start of directory)
Down move down 1 line
PgUp move up 11 lines
PgDn move down 11 lines
Ctrl-Home move to first entry
Ctrl-End move to last entry
Left browse parent directory (if any)
Right browse selected sub-directory or file
Enter same as Right
+ switch to next drive (eg from A: to B:)
- switch to previous drive (eg from B: to A:)

Esc return to Main Menu
F1 give help about directory browse mode
F2 copy active screen to other display

Some of these commands demand a bit more explanation.

THE ? COMMAND
Because it's easy to forget just what letter keys PUFF responds to,
the new "?" command pops up a command menu. You can then select a
command by moving the hilighting bar, or by typing its first letter.
The cursor Up, Down, PgUp, PgDn, Home and End keys all move the bar.
The bottom line of the menu shows an up and/or down arrow if more
unseen options lie above the first line or below the last line seen.
As well as selecting an item, you can pop-down the menu by
pressing Esc.

COPY, ERASE, MOVE and RENAME
Erase will ask you if you are sure before doing the erase and all
four commands can be cancelled by pressing Esc. If you erase, move
or rename files, PUFF leaves the entries in the display, but replaces
the filesize field with the word , or . When
marked like this a file or directory cannot be browsed, renamed or
copied. The 'D' command will properly refresh the display.
Note that you can `move' files to another directory and rename
`directories' as well as files (you can't erase or move directories
though, and PUFF does not support RemoveDir).
When copying, moving or renaming be careful. If the new name does
not begin with a drive specifier or backslash PUFF will prefix the
name you give with the current PUFF directory (which may not be the
same as the current DOS directory).
When moving or renaming the new name may just be a drive letter
followed by a colon or a path ending with a backslash. In these
cases, PUFF will use the old filename.extension for the target file.

THE DISPLAY COMMAND
The Display command causes PUFF to re-read the directory. This is
useful when you have changed diskettes while PUFF is popped up, or if
you have popped down using the hot-key and then created, modified or
erased some files so that when you pop up again the directory will not
be up to date. Pressing D will cause the directory to be re-read.

THE FREE COMMAND
The free space display, which was automatic in earlier versions of
PUFF, is now produced using the F command. This change was made
because computing free space can take quite a while, particularly on
a fixed disk with a lot of directories and files.

THE NEW COMMAND
This option lets you switch to another directory directly rather
than having to use the cursor left and right keys to traverse the
directory tree.

THE OPTIONS COMMAND
This lets you access the two customizing menus from within directory
browsing. This makes it quicker to move the PUFF box around, change
the hot-key or screen colours since PUFF no longer has to re-read the
directory when you go back.

THE PASTE COMMAND
The Paste command causes PUFF to pop-down and then "paste" key-
strokes into the application program that was running when PUFF was
popped up. You can paste the name (i.e. filename.ext), the full name
(i.e. drive:\path\filename.ext) or the contents of the file (see the
section on the "PUFF FILE BROWSER" for how to paste just part of the
contents of a file). The keystrokes will appear where the cursor was,
just as if you had typed them in.
When you pop PUFF up again you will go back to the directory
display, as though you had popped down using the hot-key.
Pasting the contents of a file can be used as a sort of BAT or input
redirection facility or to copy one file into another in an editor
that does not support paths.
In general PUFF treats each byte in the file as a separate keystroke.
It stops at Ctrl-Z and treats a X'00' byte as a signal that the
following byte is an Extended ASCII code. Thus the sequence X'003B'
would cause PUFF to send back the code for function key F1 (whose scan
code is 59 = X'3B'). For a list of the codes associated with the
cursor keys, Alt-keys and various function/shift combinations see the
BASIC Manual (Appendix D) or the Technical Reference Manual.
Some editors treat a carriage return as a signal to go to the start
of the current line and require a different key to be pressed to
`insert' a blank line. PUFF can be made, through its profile, to
return some other keystroke instead of the carriage return (X'0D') to
force a new line to be inserted and can filter out Line Feeds if
needed. Thus you can make PUFF treat a carriage return as an F9
(which inserts a line in PE) or F2 (which does the same in KEDIT). For
more details, see the section on `CUSTOMIZING PUFF'.
Note that to paste into most editors you must also make sure the
cursor is in the data area rather than on the command line (unless the
keystroke file includes something like an Esc to switch the cursor
over).
During pasting PUFF responds to the following keys:
space bar - pause until another key is pressed
+ - speed up pasting
- - slow down pasting
any other key - terminate pasting and return to normal
keyboard input

THE SORT COMMAND
Sorting is done in alphabetical order for Name, and in reverse order
for Size (big files first) and Date (newest files first). Sorting by
extension actually sorts by name within extension. The current sort
order is displayed on the `Browsing Directory' line. Note that PUFF
now lets you go back to the original DOS order after sorting if you
want.

OTHER COMMANDS
The Left and Right keys also deserve a bit more explanation. If PUFF
was popped up when the current DOS directory is C:\TOOLS then this is
the directory that PUFF will display. Pressing the Left cursor key
will cause PUFF to display the root directory while pressing Right or
Enter when the current high-lighted line is a subdirectory called
EDITORS will cause PUFF to display the C:\TOOLS\EDITORS directory. If
the current line is a file then PUFF will display that (see "PUFF FILE
BROWSER" later).
PUFF tries to be intelligent about these keys. If you move right
and then left again, you should get back to the line you came from in
the higher directory (eg the EDITORS line) even if the directory has
been sorted or files have been copied, erased or moved. If you start
in a sub-directory and move left then PUFF should be bright enough to
find the right line.
The + and - keys also try to be intelligent. On a single floppy
system, such as an XT, the A and B logical drives are mapped onto a
single physical drive. Any reference to B when the current drive is A
will cause DOS to display a message "Insert diskette for drive B".
PUFF tries to avoid this by skipping over the logical drive which is
not current. Thus + will skip from A to C and - from C to A if the
current drive is A. If the current drive is B then - will not try to
skip to A.
One final point. PUFF has only a small 6K buffer (12K with /B
option) so it can only store up to about 275 (or 555) directory
entries. If the directory has more entries only the first 275 (or
555) will be shown. PUFF will display a message if there are too many
files to display all of them. This message will only appear the first
time you browse a given directory, but the 275 (or 555) will always be
followed by a "+" if there are more files. You can use the "Select
Directory for Browsing" option to select a subset of files from a
large directory.

PUFF FILE BROWSER
From directory browsing you can select a file for viewing by
pressing Cursor Right, Enter, T or H. For PUFF a text file is one
which has a Carriage Return/Line Feed at the end of each record and a
Ctrl-Z at the end of the file. The file browser operates in one of
two modes:
Text in this mode each line on the screen shows a file line. Long
lines are truncated but PUFF allows sideways scrolling so
that long lines can be viewed. The screen tells you which
file line and column the cursor is at.
This is the default mode for text files and is forced if you
use the T command.
HEX in this mode the screen is divided up into three vertical
parts. On the left is the offset from the start of the file
(in Hex), in the middle are 8 bytes of data in Hex while on
the right are the same 8 bytes in ASCII (or in EBCDIC if
EBCDIC translation is turned on). In Zoom mode there are 16
bytes of data on each line.
This is the default mode for non-text files and is forced if
you use the H command.
If you enter the file browser using Enter or Cursor Right, PUFF
guesses what sort of file is being browsed using an extremely simple
algorithm. If the last byte of the file is Ctrl-Z or Line Feed it
assumes the file is text and goes into text mode, if not it uses HEX
mode. Alternatively you can force the mode by using T or H.

TEXT MODE COMMANDS
The following commands are available in ASCII mode:

? pops up a command menu
E (Expand) expand/compress tab characters
(tabs at every 8th column)
G (Goto) go to line n
H (Hex) switch to HEX mode
N (New) allow switch to new file directly
O (Options) access the options menus
P (Paste) paste file contents
Q (Quit) quit (return to directory browser)
R (Repeat) repeat search for string
S (Search) search for a text string
Z (Zoom) switch to Zoom mode or back
' search for a hex string
/ search for a text string

Up move cursor up 1 line (towards start of the file)
Down move cursor down 1 line
PgUp move up a screenful
PgDn move down a screenful
Ctrl-PgUp move up 100 lines
Ctrl-PgDn move down 100 lines
Ctrl-Home move to first line
Ctrl-End move to last line

Left move cursor left 1 column
Right move cursor right 1 column
Tab move cursor right 10 columns
BackTab move cursor left 10 columns
Ctrl-Right move cursor right a screen width
Ctrl-Left move cursor left a screen width
Home move cursor to column 1
End move cursor to end of line

Esc return to directory browsing
F1 give help about ASCII file browse mode
F2 copy active screen to other display

As with the directory browser, the new ? command pops up a
command menu.
One new feature of text mode is that the current position is shown
by a normal blinking cursor which is moved by the cursor keys (just
as in most editors). Earlier versions of PUFF always made the current
position the top left of the window, which made searching and
scrolling unfriendly to say the least!

HEX MODE COMMANDS
The following commands are available in HEX mode:

? pops up a command menu
A (ASCII) switch to ASCII
E (EBCDIC) switch to EBCDIC
N (New) allow switch to new file directly
O (Options) access the options menus
P (Paste) paste file contents
Q (Quit) quit (return to directory browser)
R (Repeat) repeat search for string
S (Search) search for a HEX string
L (Low) toggle Low Hex display on and off
T (Text) switch to text mode
Z (Zoom) switch to Zoom mode or back
' search for a hex string
/ search for a text string

Up move up 8/16 bytes (towards start of the file)
Down move down 8/16 bytes
PgUp move up a screenful
PgDn move down a screenful
Ctrl-PgUp move up 1024 bytes
Ctrl-PgDn move down 1024 bytes
Ctrl-Home move to first byte
Ctrl-End move to end of file
Left move up 1 byte
Right move down 1 byte

Esc return to directory browsing
F1 give help about HEX file browse mode
F2 copy active screen to other display

As with the directory browser, the new ? command pops up a command
menu.
Note that PUFF tries to keep a count of the current file line in all
modes. So if you switch from ASCII into HEX mode, scroll about and
then return to text mode the line number should be correct. However
if you jump directly to the end of the file (using Ctrl-End) PUFF will
not know the line number unless you have previously scrolled there. In
such a case the line number will show as ????.
The current version of PUFF can be confused by attempting to display
non-ASCII files in ASCII mode, particularly if the resulting lines
appear to be more than 255 bytes long.
The maximum size file you can browse is about 100 Megabytes!
The Low Hex translate option lets you suppress the display of
characters with ASCII codes below X'20'. These characters cause
problems if you try to print the screen since they are treated by
printers as control characters (form feed, line feed etc).
EBCDIC translate lets you view a file, in the right-hand column, in
EBCDIC form. Thus X'F1F2F3' will appear as the string '123'. This
option can be useful when viewing Displaywrite files which are stored
in EBCDIC form. PUFF displays the state of the toggle on the
"Browsing HEX file" line.

PASTING WITHIN FILE BROWSE
When browsing a file you can make PUFF paste the file contents using
the 'P' command. PUFF will then ask if you want to paste just the
current line, the rest of the file or to go back to the start and
paste the whole file. Note that in the first two cases pasting starts
at the cursor position (rather than the beginning of the current line).

SEARCHING IN PUFF
The Search command lets you search for an ASCII or HEX string. The
'S' command expects a text string in text mode and a hex string
(pairs of hex digits optionally separated by blanks) in hex mode. The
/ expects a text string (and can be useful in HE mode) while the '
command expects hex digits (and can be useful in text mode). The
search starts at the current position in the file and you can
terminate the search at any time by pressing any key. See the section
Data Entry in PUFF for details of how the search string may be
edited.
Depending on the option setting searching can be case-insensitive or
not. In the former case a search for "The" will stop at "the" or "THE"
as well. Accented characters above X'7F' are also treated in this
way, using the standard DOS rules for equivalence (so the upper and
lower case c cedilla - x'80' and x'87' are treated as equivalent).
The Repeat command will find the next occurrence of the string. In
text mode, it starts on the current line, at the byte after the
current column. In HEX mode, it starts at the byte after the current
position which is essentially the same.
Note that you can enter a search string in one mode (eg text) and
then use Repeat in the other mode and PUFF will still search for the
same string.

ZOOM MODE
The Z command switches between the normal PUFF browser and full-
screen mode. In full-screen mode PUFF responds to the same set of
commands but obviously displays more of the file at once - 25 or more
lines of 80 columns. In ZOOM mode, the PgUp and PgDn keys are
adjusted so that they still scroll a pageful (i.e. for PgDn what was
the bottom line becomes the top). The Ctrl-Left and Ctrl-Right keys
in text mode are similarly adjusted.

SELECT DIRECTORY FOR BROWSING
This lets you select any directory for browsing. PUFF will accept
most combinations of drive, path and filespec information, so the
following are all valid:
C:\ all files in root directory on C
C: all files in current directory on C
C:\*.COM all COM files in root directory on C
C:\TOOLS\ all files in TOOLS subdirectory on C
C:\TOOLS ditto
TOOLS\ displays all files in TOOLS subdirectory
of current directory on current drive.
TOOLS ditto
TO*.* all files/sub-directories beginning with
TO in current directory on current drive

If the selected drive/directory has no files PUFF will beep and
display a message.
Entering a blank line will cause the current directory to be reset
to the value it had on entry to PUFF. You can cancel this option by
pressing Esc.
See the section "DATA ENTRY IN PUFF" for details of how a filespec
may be edited.

CUSTOMIZE (SET OPTIONS)
The choices on this menu are described in detail in the section
"CUSTOMIZING PUFF".

WRITE A NEW PROFILE (SAVE OPTIONS)
This causes PUFF to write a new profile, using the current value of
all options. Thus once you have set these to the values you like and
created a new profile, the next time you install PUFF the options
will all get the appropriate values.

QUIT
This option causes PUFF to pop down out of sight. The same effect
is produced by pressing Esc.

REMOVE PUFF FROM MEMORY
This will work only if PUFF was the last DOS extension you installed
that takes over INT 16H, the Keyboard interrupt (other programs that
do this include GWNOTE, PCCALC, PSRD, KQE and the BelleSoft Pop-Ups).
You can cancel this option by pressing Esc.

CUSTOMISING PUFF
The customising facilities are available from the main menu (via 'C'
for Customise) or from directory of file browsing (via 'O' for
Options). The customise menu offers the following choices:
Set initial view options (a submenu)
Move PUFF Menu
Change Pop-Up key
Beep Tone/Duration
Normal screen colour
Emphasised screen colour
Paste Enter key
Ignore linefeeds

Date/time of copyfile

Quit

SET INITIAL VIEW OPTIONS
This sub-menu is described offers the following choices:

Set initial drive/directory
Expand Tabs
Zoom to full screen
Directory Order
LoHex characters
Hex display encoding
Attribute or Size
Case Sensitive search
Quit

Most of these settings determine the values of the appropriate
variables when a new directory or file is entered, though all can
altered while file browsing using the appropriate commands.
The first option is different however. It corresponds to the
"InitVu" option on the PUFF command, and determines which drive,
directory or file PUFF displays when popped up. A setting of
"Current" makes PUFF pop up at the main menu, using the current DOS
directory on the current DOS drive as a starting point. Entering a
drive letter and/or a directory here will cause PUFF to use that
drive/directory as a starting point instead and PUFF will initially
pop up in directory browsing (rather than the main menu). If the name
resolves to a file (rather than a directory) then PUFF will initially
pop up in file browsing.
The defaults for these options are:
.the current DOS drive and directory are used
.tabs are initially expanded in text mode.
.zoom mode is used.
.the initial order in which a directory is displayed is the order
given by a DOS dir command
.hex characters below X'20' (which because they are used for
printer control can disrupt a Print Screen operation) are
displayed "as-is" rather than as ".".
.HEX file encoding defaults to ASCII.
.file sizes rather than atttributes are displayed.
.searching is not case-sensitive.

MOVE PUFF MENU
This option lets you move the pop-up PUFF menu around the screen
using the left, right, up and down keys or to one of the four screen
corners using the Home, PgUp, End or PgDn keys. You can fix it in a
new position by pressing Enter. You can cancel this option by
pressing Esc.

CHANGE POP-UP KEY
This lets you change the pop-up key by pressing the new one. The
new key can be any key with an Extended ASCII code associated with it
(i.e. it includes combinations like Alt-1 and Ctrl-PgUp). Be careful
though, it's not very sensible to make it F1 or F2 or one of the
cursor keys. PUFF will not let you choose ENTER as a pop-up key.
You can cancel this option by pressing Esc.
PUFF tries to display the name of the selected key, but the names
it knows are limited to the 92 keys listed above in the section
"INSTALLING PUFF". Any other key will be displayed as "Unknown".

BEEP TONE/DURATION
The cursor keys are used to change the nature of PUFF's beep. Note
that here the Esc key is used to reset things to the defaults, the
only exit from this option is via Enter (which fixes the values).

SCREEN COLOR
The cursor keys are used to change the screen attributes. 'Normal'
means the default PUFF color, 'Emphasised' is what PUFF uses to
indicate a selected option or hilight an error message. Here again
the Esc key is used to reset things to the defaults, the only exit
from this option is via Enter (which fixes the values).

PASTE ENTER KEY AND IGNORE LINEFEEDS
The first of these determines how Carriage Returns are to be
treated during pasting. PUFF lets you replace them with some other
key. This is particularly useful when pasting into an editor that
requires some special key to be pressed to insert a new line into the
file. By default they are left as Carriage Returns. PUFF tries to
display the name of the selected key, but the names it knows are
limited to the 92 keys which can be assigned to the hot-key and the
Enter key. Any other key will be displayed as "Unknown".
If the Enter key (or whatever it's been replaced by) does the
necessary "insert new line" fucntion, linefeeds should be ignored.
However, in some editors both Enter and Linefeeds should be pasted.
The first creates a new line (but may move the cursor to align with
the first non-blank on the line above) and the second moves the cursor
back to the start of the line.

DATE/TIME OF COPYFILE
When copying a file, PUFF let's you choose whether the date/time
stamp on the new file should be the same as the old file (this is
what the DOS COPY command does) or the current date and time.

DATA ENTRY IN PUFF
PUFF allows editing of data input rather like DOSEDIT. This
facility is available when you use the "Select Directory for Browsing"
option or the "SEARCH" command in the file browser.
A small buffer of previously entered strings is maintained and during
data entry PUFF responds to the following keys:

Up retrieve previous stored string
Down retrieve next stored string
Home move cursor to start of string
End move cursor to end of string
Left move cursor one column to the left
Right move cursor one column to the right
Ins toggle insert mode (cursor shape changes)
Del delete character at the cursor
Backspace delete character before the cursor
Enter pass current string to PUFF
Esc cancel data entry

The "ring" of stored strings is limited to 256 bytes. The normal
cursor is a blinking underscore. In insert mode it's a blinking solid
rectangle.

SOME DESIGN DETAILS
One of my main aims in writing PUFF was to fit it into a small
amount of memory (originally 20-24K). This has significantly affected
the design in a number of places. The purpose of this section is to
outline some of the key aspects of PUFF's design, so that the
interested user can understand why it does (or doesn't do) certain
things in a particular way.

USE OF STORAGE
The PUFF.COM file, which is about 23K in size, is made up of:
.Resident Code - this occupies about 12K.
.Resident Data - this occupies about 5K and includes
messages, menus, tables etc.
.Initialization Code - this code, about 2K in size, is overwritten
by PUFF's buffers when PUFF is resident.
.Initialization Data - these messages and tables occupy about 1K
and are overwritten by PUFF's buffers.
.Help screens - these occupy about 3K and are overwritten
by PUFF's buffers if the /X option is used.

When resident, PUFF needs space for:
.Screen Buffer - this is 4K in size. Before PUFF pops up it
stores the existing screen in this buffer
(2K of data and 2K of attributes). If the
/E option is used the buffer is enlarged to
8K to allow 43 or even 50-line screens to
be used.
.Directory/File Buffer - without the /b option, this is 6K in size.
The first 2K is reserved for directory use,
so there is no need to re-read the directory
when leaving file browse if the directory
has less than 93 entries. In Directory
Browse, PUFF uses 22 bytes for each entry,
so the buffer will hold about 275 entries.
Any sorting is done in place. In File
Browse 4K of this is split into two 2K
buffers. This is to avoid the excessive
file I/O that would occur with a single
buffer when scrolling back and forth near a
buffer boundary.
If the /b option is used the buffer is
doubled to 12K, with room for 555 entries.
The first 4K is reserved for directory use,
so there is no need to re-read the
directory when leaving file browse if the
directory has less than 186 entries. The
file browser uses the last 8k as two 4K
buffers which halves the number of file I/O
operations and thus improving scrolling
speed.
.Data Buffers - these are used to store the current file
and directory names, to hold the search
string during searches, and to build lines
to be displayed on the screen. They occupy
about 2K.
Thus the total resident size is made up of:
12K resident code
5K resident data
3K help screens
10K-20K screen and file buffers
2K data buffers

PERFORMANCE
Because of its limited buffer space, certain operations take some
time. For example, PUFF may have to rebuild and re-sort the directory
whenever you leave the file browser, or go up from a sub-directory to
its parent. Similarly, when scrolling or searching through a file,
PUFF has to read each 2K or 4K chunk in turn, which takes some time.

SCREEN I/O
The low level video driver routines in PUFF, give particularly good
performance on the Color Graphics Adapter. The routine used to move
the PUFF menu about the screen is rather primitive, and looks very
unsightly on a Color Display. However it is very small and since the
menu is not moved very often it does not seem worth the space to
improve it.

TEXT FILE HANDLING
PUFF can be confused if attempts are made to display, in text mode,
files which do not conform to its expectations:
.a CR/LF sequence at the end of each record
.a Ctrl-Z at the end of the file (and nowhere else)
.a maximum record length of 255 characters

PUFF counts lines by looking for CR/LF sequences, and the line
counter will be wrong if some other line terminator is used. Similarly
PUFF displays the End of File message when it detects a Ctrl-Z, so
files with embedded Ctrl-Z's will confuse it.

DETERMINING RESIDENCY
PUFF tests to see if it is already resident by following the storage
allocation chain. This points it to each PSP in memory and it checks
the code after each PSP to see if it is a copy of itself.
The logic to do this is based on undocumented pointers in the Memory
Control Blocks and PSPs, but seems reliable in DOS 2 and DOS 3. At
worst another copy will be loaded when it should not be.

Trapping INT 16 (Keyboard Request)
PUFF takes over INT 16 and intercepts all application requests for
keystrokes. The way this is done should be totally transparent except
that in text modes, no application program will ever see PUFF's hot-key
(since this will cause PUFF to pop up, or if already popped up, to pop
down again).
Note that in general PUFF can co-exist peacefully with other
applications which intercept INT 16.

Trapping INT 28 (DOS Idle Interrupt)
PUFF intercepts INT 28 so that it can avoid popping up when DOS is
usy. This is based on techniques described in PC Magazine for April
14th 1987 (Instant Acccess to Directories by Jeff Prosise - pages
313-334). PUFF should be able to co-exist peacefully with other popups.
Prior to Version 2.3, PUFF hooked the INT 21H vector and was DOS
version-dependent. The new technique should be much safer.

ERROR MESSAGES
The following is a list, in alphabetical order, of the messages
that PUFF displays:
- Can't go any deeper - press any key. - This message appears if
you try to go deeper than eight levels into the directory tree.
In fact, due to the limited width of PUFF's window you may not
be able to see the full directory name before you get this deep
(though PUFF does in fact maintain it internally).
- Error copying file - press any key. - This message is displayed
if PUFF detects an error when trying to copy a file. Possible
reasons include a write-protected disk or an attempt to copy a
file to a non-existent directory.
- Error erasing file - press any key. - This message is displayed
if PUFF detects an error when trying to erase a file. Possible
reasons include a write-protected disk or an attempt to erase
a read-only file or a directory.
- Error in Hex string - Press any key. This message is displayed
if a HEX search string contains an odd number of digits or a
character other than a valid hex digit or blank.
- Error reading file - Press any key. This message is displayed
if PUFF detects an error when reading a file.
- Error renaming file - press any key. This message is displayed
if PUFF detects an error when trying to rename a file. Possible
reasons include a write-protected disk or an attempt to move a
file to a non-existent directory.
- Error writing Profile - Some sort of error occurred while PUFF
was trying to create PUFF.PRO, such as a write-protected diskette.
- File is empty - press any key. - This message is displayed if
you try to browse or paste a zero-length file.
- No file(s) found - press any key. - This message is displayed
if you try to browse an empty disk or directory or switch to
browing a non-existent file
- No search to repeat - press any key. - This message is displayed
if the Repeat command is issued without there being a preceding
search.
- Not a file - press any key. - This message is displayed if you
try to paste the contents of a directory.
- Search interrupted - press any key. - This message is displayed
if searching is terminated by the user pressing a key.
- String not found - press any key. - This message is displayed
if a search is unsuccessful.
- Too many files - press any key. - This message is displayed if
there are more files in the selected directory than PUFF's
buffer can hold (275 or 555 if the /b option is used).
- Unsafe to remove PUFF - This message is displayed if an attempt
is made to remove PUFF when another resident program has taken
over INT 16 or INT 28 since PUFF was installed.

The following messages can appear during PUFF initialisation:
- Bad or missing PUFF profile - Either the PUFF.PRO file could not
be found in the current or root directories or it did not contain
the necessary fields (in particular the string PUFF3 at the start).
If no PUFF.PRO can be found, PUFF uses default values.
- Invalid option - the PUFF command was followed by a / which was
not followed by a valid option (B, E, H, L, N, Q, R, S and X are the
valid options).
- No resident version to remove - PUFF was invoked with the /R option
and no resident version could be found.
- PUFF does not support this version of DOS - PUFF will not run under
DOS 1. PUFF should now run under all later versions of DOS,
including the OS/2 Compatability Box.
- PUFF is already installed - An attempt was made to install PUFF
when PUFF was already resident.
- Resident version cannot be removed - PUFF was invoked with the /R
option but another DOS extension prevented the resident version
from being removed.
- Resident version removed - PUFF was invoked with the /R option
and a resident version has been successfully removed
- Warning - PUFF profile needs updating - PUFF was run with an out
of date profile, so some new options will be set to their default
values. Writing out the profile will allow these new options to
be set as you would like.

FORMAT OF PUFF.PRO
The profile is a small file, 107 bytes long, containing the
following fields:

Content Offset Length Default Value (in Hex)

marker 0 5 5055464633 ('PUFF3')
hot-key scancode 5 2 0020 (Alt-D)
normal mono attrib 7 1 20 (normal)
hilite mono " 8 1 70 (reverse video)
normal color " 9 1 1e (yellow on blue)
hilite color " a 1 78 (black on grey)
beep tone b 2 4B
beep duration d 2 4B
top box line f 1 1
left col (80 cols) 10 1 28 (decimal 40)
quiet install 11 1 0 ()= No, 1= Yes)
ega allowed 12 1 0 (0= No, 1= Yes)
help included 13 1 0 (0= Yes,1= No)
buffer size 14 1 0 (0= 6K, 1=12K)
zoom files? 15 1 1 (1=no, 0= yes)
expand tabs? 16 1 0 (0= no, 1= yes)
directory order 17 1 0 (0=DIR, 1=size, 2=date
(3=name, 4=extension)
ASCII/EBCDIC 18 1 0 (0= ASCII, 1= EBCDIC)
low hex switch 19 1 0 (0= display, 1= suppress)
attr/size 1a 1 0 (0= size, 1= attributes)
case sensitivity 1b 1 0 (0= insensitive, 1= sensitive)
paste CR key 1c 2 0D1C (Carriage Return)
linefeed 1e 1 0 (0= ignore, 1=paste)
initial view 1f 72 0 (0 = use current)
(else drive/path/filespec)

Date format 68 1 0 (-1 means ask DOS, 0 = mmddyy)
(1 = ddmmyy, 2 = yymmdd)
Time format 69 1 0 (-1 means ask DOS, 0= 12h, 1= 24hr)
Date/Time of copy 6a 1 0 (0= current time, 1= original time)

Note that this profile is incompatible with that used by earlier
versions of PUFF.
The profile is loaded into PUFF.COM at offset 3 from the start
of the program, overlaying the default values contained there.

THINGS TO AVOID
The architecture of PC/DOS does not allow programs like PUFF to be
legal, decent and honest. There is no official way in which a resident
program can get control, even at the DOS prompt, and issue DOS calls.
In writing PUFF I've had to make use of a number of dirty tricks and
to use undocumented interfaces. Even so PUFF is safe most of the time.
Here are a few things which can cause problems:

Displaying COM files and other arbitrary files in ASCII mode
(the main symptom will be peculiar behaviour of PUFF's line counting)
Pasting keystrokes from a non-ASCII file (anything could happen
here since PUFF will return absurd and impossible values as keystrokes).
Popping up PUFF when DOS has issued a critical error message
(e.g. Abort, Retry or Ignore ).