FileBrowser Version 1.00 (Freeware Version) Copyright (c) 1988, David O. Tinker All Rights Reserved Table of Contents Page A. Introduction --- 1 1. Why FileBrowser? --- 1 2. Terms of Distribution --- 1 3. FileBrowser Features --- 2 B. Hardware and Software Requirements --- 2 1. Systems Tested --- 2 2. Memory Requirement --- 3 3. Technical Specifications --- 3 C. Installing and Running FileBrowser --- 4 1. Installing FileBrowser: --- 4 2. Running FileBrowser --- 4 D. FileBrowser Commands --- 5 1. FILE --- 5 2. PRINT --- 6 3. BROWSE --- 6 4. SEARCH --- 6 a) Hints on using SEARCH --- 7 5. SHELL --- 8 6. EDIT --- 8 7. QUIT --- 8 E. License and Warranty Disclaimer --- 9 F. Acknowledgements --- 10 G. Registration Form --- 11 __________________________________________________________________ FileBrowser 1.00 Manual - Page (i) A. Introduction 1. Why FileBrowser? Like many micro-computer users, I find that I often have to deal with text files - LARGE text files: source code files, software manuals, documents downloaded from such sources as Usenet, BIX (tm), etc.; as a university teacher, I have to cope with large numbers of documents crossing my desk daily - in many cases these can easily be obtained in electronic form, and the future prospect is that more and more documents will be distributed online. Short of actually printing these documents (which is time- consuming and often not wanted), I found that the only way to read them was to load them into an editor or word-processor. Yet only in very rare cases do I actually want to edit the file I am reading - sometimes the file must NOT be edited. Again, occasions often arise when I want to have a text file readily available for display on the console screen, while I am carrying out some other task (e.g. telecommunications, number crunching). Some editors may be used for this, or one might use a pop-up notepad program such as Sidekick(tm) - but these are costly and often "overkill" solutions to a simple problem. Besides, when I use Sidekick(tm) I want to use the Notepad to make notes on, not to store a static file! To cut this story short, I found I needed a cheap and effective file browser program! And so the idea for FileBrowser originated. The outcome of that idea is in your hands now. I use this program every day (not surprisingly, since I wrote it to do what I wanted), and I hope you find it meets your needs as well. It's certainly cheap! 2. Terms of Distribution This program is "Freeware", which means it is NOT in the Public Domain - it's copyrighted - but there is no charge for its use. You use it under the terms of a fairly non- restrictive license, which is included in this document: you'd better read the license agreement, because if you use this software you are implicitly assenting to its terms! Registration of your license is optional and free, but you are strongly encouraged to do so, for several reasons. First, I'd like to see where, how and by whom it is being used. Second, FileBrowser is currently being developed into an application with lots more bells and whistles (this will be shareware); I'd like to tell you about this when it's finished. Please complete the registration form in this document and send it in - it will only take a moment and cost you one stamp. FileBrowser 1.00 Manual - Page 1 I had a lot of fun writing FileBrowser, and in a small way it might repay the computer-user community for all the education and enjoyment I have received from Public Domain and Shareware programs, whose costs do not adequately reflect the effort and skill their authors put into them. 3. FileBrowser Features FileBrowser allows you to load an ASCII or Wordstar (tm) file into a buffer in RAM and scroll through it. You can scroll and page forwards or backwards through the file, or jump ahead or back any number of lines, or use an auto- scrolling feature which rolls the text forward or back at an adjustable speed. If you want to copy some lines to another file, you can do so, or you can print a block of lines. When browsing a big text file, I often want to locate a specific section that's in there *somewhere*, so FileBrowser has the ability to look for strings of text (it finds them quite rapidly too). If you really *do* need to edit the file, FileBrowser allows you to exit to the editor of your choice, work on it, then re-load the edited file. Finally, you can leave the file in RAM and load another DOS shell, so that you can go on to other tasks and still return to your place by typing 'exit' at the DOS prompt. This is a great feature for folks working with a two-floppy system, as it means you can remove the disks containing the FileBrowser programs and the original file. (You will need to have the original file and the accessory program FBE.COM available if you want to use FileBrowser's "edit and return" feature). FileBrowser is easy to use: all the commands may be exe- cuted from a pop-up menu line, or using simple one-key commands, and you get feedback from the program as to what it is doing and what it expects next; it can detect a number of input errors and either correct them or give you an error message. On-line help is readily available for all commands. If you have a color monitor, you can see all these features in vivid yet tasteful color (:-). B. Hardware and Software Requirements 1. Systems Tested FileBrowser has been successfully tested on IBM-PC (tm) XT and AT microcomputers and several 100% compatible machines. It has been run using both CGA and EGA graphics adapter cards for color display (a monochrome monitor may also be used with these cards); since the I/O does no direct writes to video memory, I see no reason why it could not be run using other FileBrowser 1.00 Manual - Page 2 graphics cards - but I make no claims or guarantees (see Warranty Disclaimer, below). You can certainly use FileBrowser on a two-floppy XT system, but file-loading is slow - a hard disk is better, and it really shines on an AT-class machine! FileBrowser requires MS-DOS (tm) or PC-DOS (tm) version 2.11 or later. This software is compatible with Microsoft Windows (tm), (though it was not written as a Windows appli- cation), and with Borland's Sidekick (tm). 2. Memory Requirement In order to calculate memory usage by FileBrowser, use the following formula: M = 72 + 2.9*F where M is the memory required (KBytes) and F is the size of the file (ASCII) to be loaded, in KBytes. This gives an approximate estimate only, and actual requirements may vary slightly. Thus if you have 580K of free memory remaining after loading DOS, the maximum file size which may theoretically be loaded is 175K. I have never had a text file that large, but have successfully used FileBrowser with a 125K file (which takes a while to load!). 3. Technical Specifications FileBrowser consists of the following files: FB.EXE : Main program executable file. FBE.COM : Auxiliary program required to load an external editor. HELP.FB : FileBrowser On-Line Help file. (Warning: do not edit this file - it is best to make it read-only). FB.MAN : Documentation (this file). README.FB : Brief description of FileBrowser. The source code for FB.EXE and FBE.COM is entirely written in C. It was compiled with the Aztec C86 (tm) compiler, version 3.4a, (using the 'large code, large memory' model in the case of FB.EXE). While the license for this software contains a legal disclaimer of liability for damages, the author does not believe that any portion of FileBrowser can lead to any damage whatsoever to computer hardware or magnetic disk media. In particular, FileBrowser does no direct writes to core or video memory, and all I/O is executed by C language standard I/O functions which operate via DOS calls. This has FileBrowser 1.00 Manual - Page 3 a cost in speed, but ensures safety and portability to the maximum number of systems. C. Installing and Running FileBrowser 1. Installing FileBrowser: The first step in installing FileBrowser is to make a working copy containing all the files, and put the original disk away in a safe place! If you are running FileBrowser on a two-floppy system, simply copy the files FB.EXE, FBE.COM and HELP.FB to a disk and use in the default drive. For hard disk users, place the files FB.EXE, FBE.COM and HELP.FB in any suitable directory that lies on the DOS path. If you intend to use an external editor with FileBrowser, it may be necessary to set the DOS Environment variable 'EDITOR' using the command: set EDITOR= where is the calling name of a text editor pro- gram. As a default, FileBrowser attempts to use the 'VI' text editor to edit files, but you may substitute another editor as described above; alternately, you may just rename your editor to 'VI.EXE' or 'VI.COM' as appropriate. Whatever editor you choose must be on your DOS path, and must be capable of loading a file from the DOS command line. You could even use the EDLIN editor supplied with DOS! (The VI editor is not supplied with this distribution). 2. Running FileBrowser FileBrowser is started with the command line: FB [-options] [d:][\path\]FILENAME[.EXT] where FILENAME.EXT is the file to be loaded, with drive (d:) and path specification if necessary. If a FILENAME is omit- ted, a Title Screen appears, with copyright information and brief Usage instructions (if the -c option is used, the Title Screen is in color). The "options" currently available are 'q','c','m','w' and 't', as follows. Options may be specified in any order. q : (Quiet Load) - Omit display of title screen before loading the file. FileBrowser 1.00 Manual - Page 4 c : Use colour windows instead of black-and-white. Only one of 'c' or 'm' may be specified. m : Use black-and-white windows. (This is the default option). w : load a Wordstar (tm) document file: if omitted, the file is assumed to be an ASCII file. (The extended ASCII character set is supported). t : Do not expand tabs. The 'Tab' character will appear as a distinctive graphic (ASCII 09). If omitted, tabs are expanded to spaces. As an example, to load a Wordstar (tm) file in color without displaying the title screen first, you would use the command: 'fb -qcw wsfile.doc' Filebrowser has a maximum line length of 79 characters - characters in excess of this limit are wrapped to the next line. (Column 80 is reserved for special purposes in future versions). D. FileBrowser Commands All FileBrowser commands may be executed by choosing from a Menu (which is activated by pressing the "Ins" key after starting FB.EXE). In addition, all commands except SHELL may be executed from BROWSE mode using a one-key command. When the Menu line is visible, on-line help on any command may be obtained by selecting the command with the cursor keys, and pressing the 'F2' function key. 1. FILE The FILE command is used to copy part of the current file to a new file. You will be prompted for the new filename (which can include optional drive and path, e.g. d:\path\file.ext). If the file specified already exists, you have the option of overwriting it or appending text to it. If you enter an illegal file name, an error message will pop up. Press any key to remove the error message. After you have specified a file name, you will observe that the top line of text in the main window is highlighted in reverse video, and a blinking cursor appears on the next line. You may move the cursor down to subsequent lines - as this is done, the line above the cursor is marked. When you have marked the desired number of lines, press the "Esc" key, and the marked lines will be copied to the designated file (in ASCII format). FileBrowser 1.00 Manual - Page 5 The FILE command may be given while in 'Browse' mode by simply pressing the "F" key; 2. PRINT The PRINT command is equivalent to the FILE command except that the marked portion of the file is copied to the line- printer (device PRN), instead of to a disk file. Note that the version of the current file that is printed is the one in the FileBrowser buffer - due to line truncation, tabs expan- sion, removal of Wordstar (tm) characters, this may *not* be identical to the file on your disk! The PRINT command may be given while in 'Browse' mode by simply pressing the "P" key; 3. BROWSE The BROWSE command is used to view the current file - it just causes FileBrowser to enter 'Browse' mode, (which is the default mode). There are several options: - To scroll through the file, use the Up and Down arrow keys to move up or down a line; use the 'PgUp' and 'PgDn' keys to move up or down by one page. The 'Home' and 'End' keys move to the beginning or end of the file, respectively. - To move forward or back by lines (where is an integer): first press the "+" key, then enter the value of (you will get a prompt to do this on the bottom line of the screen), then press the Down arrow, or Up arrow as desired. - To automatically scroll forward or backward, press the "*" key (asterisk), followed by the Down arrow or Up arrow key. To select the speed, type an integer from 0 to 9. [9 = fast, 0 = slow, 5 = medium]. Press any key to stop scrolling. When entering a value from the keyboard, use the Escape key to cancel input. If the screen gets mangled for any reason, press Ctrl-L (^L) to redraw it. 4. SEARCH FileBrowser incorporates a simple pattern matching func- tion, which may be used to locate a string of text in a file. A "pattern" can contain "words", (a "word" is defined as a FileBrowser 1.00 Manual - Page 6 string of alphanumeric characters), and the wildcard symbol "*". It should be carefully noted that a "word" in a search pattern is just a literal string of characters - NOT an English word. Thus the pattern "mat" will match all of the English words containing the letters 'm', 'a, and 't' in se- quence, e.g "match", "doormat", "matter". Words in a pattern cannot contain embedded punctuation characters. The symbol "*" matches any number of words, (including no words!). Thus, the pattern "the * fox" will match all of the strings: "the fox", "the brown fox", "the quick brown fox". The symbol "*" is only legal inside a pattern, not as a prefix or suffix. When 'SEARCH' is invoked, you will be prompted to input a pattern. FileBrowser will automatically process your input into a legal pattern (you will have a chance to correct errors). The search then proceeds forward from the Top Line displayed in the main window, and is on a line-by-line basis (patterns extending over two lines are not found). At each successful 'hit', the line which matches the pattern will be highlighted and blinking, and you will be asked if you wish to continue. Press 'y' to continue, 'n' (or just hit the 'Return' key) to terminate the search. If you wish to restore a highlighted line to normal, use the Ctrl-L (^L) command to re-draw the screen. Note: The SEARCH command may also be given by simply pressing the "S" key. a) Hints on using SEARCH - When searching for a given string of text in a file, it is sometimes better to use a word stem rather than a word: for example, the pattern 'enzyme' will match the words "enzyme" and "enzymes", but the pattern 'enzym' will also match "enzymology". For the maximum number of hits, the second pattern may be preferred. - If you are searching for a string consisting of two English words in sequence, it is a good idea to place a '*' in the pattern, in case the two words in the file are separated by more than one whitespace character. - FileBrowser does not like to scroll past the last line of a file, which ends up at the bottom of the screen. You may sometimes wish to "scroll up" the last lines of a file: to do so, use the SEARCH command to 'search' for a pattern which occurs only in the last line. The SEARCH operation will move the last line to the top of the FileBrowser 1.00 Manual - Page 7 screen, and you can then scroll the desired number of lines back onto the screen using the Up arrow key. 5. SHELL The 'SHELL' command suspends FileBrowser and returns to the DOS operating system. To alert you that you have loaded another shell, the cursor will change to a small flashing box instead of the normal flashing underscore. You may now carry out disk maintenance operations, run another program, etc. The FileBrowser environment remains resident in memory; to return to FileBrowser, type the com- mand 'EXIT' at the DOS prompt. 6. EDIT The "EDIT" command allows you to edit the current file using the text editor of your choice. You may specify the editor by setting the DOS environment variable "EDITOR" (see section D:1). If the environment variable "EDITOR" is not set, FileBrow- ser will attempt to load the "vi" text editor. Whatever text editor you choose, it must be one that can accept the file name in the command line, e.g. "vi myfile.doc". When the "EDIT" command is given, FileBrowser writes a short Batch file in the same directory as the file being browsed, loads the batch file and exits; the batch file then loads the editor, and after exiting from the editor, re-loads FileBrowser with the edited version of the file. The aux- iliary program FBE.COM is required in order to execute the EDIT command. The "EDIT" command may be given while in 'Browse' mode by simply pressing the 'V' key. 7. QUIT This command is used to exit permanently from FileBrowser. To exit temporarily, use the SHELL command. You may also exit from FileBrowser when in 'Browse' mode by pressing the "Esc" key. When the QUIT command is given by either method, you will be asked to confirm that you really do wish to leave File- Browser. If the 'y' key is pressed, FileBrowser exits to DOS, after first displaying a public service announcement (:-). It is also possible to exit quickly from FileBrowser, by passing the closing blurb, by pressing 'Ctrl-Break'; this is effective whenever FileBrowser is expecting Keyboard input, FileBrowser 1.00 Manual - Page 8 i.e. in BROWSE, FILE and SEARCH modes. E. License and Warranty Disclaimer The FileBrowser software package, Version 1.00, including the files FB.EXE, FBE.COM, HELP.FB, FB.MAN and README.FB, is Copyright (c) 1988 by David O. Tinker, (All Rights Reserved). This software is hereby licensed for use and distribution subject to the following terms: 1. All the files FB.EXE, FBE.COM, HELP.FB, FB.MAN and README.FB must be distributed to-gether. 2. No alteration of any portion of this software may be made, and specifically, the Copyright notice must remain intact. 3. No charge may be made for any copy of FileBrowser, Version 1.00, save only that distributors of Public Domain and Shareware software libraries, whether in the form of mag- netic media or in electronic form by remote access, are permitted to charge their normal disk fee, access fee or membership fee for distribution of software collections incorporating FileBrowser , Version 1.00. 4. FileBrowser, Version 1.00 may not be included in any commercial software distribution other than libraries of Public Domain and Shareware software as described in item 3, above, without the express written permission of the author. 5. Use of this software is entirely at the risk of the user; users of this software agree to absolve and hold harmless the author, David O. Tinker, from all claims of liabili- ty for damages arising from use of this software, including but not limited to, special, incidental, con- sequential or other damages, loss of profit or any other commercial damage. 6. The author reserves the right to alter the terms of this license without notice, save that users licensed prior to such alteration will not be charged any fee for this license. 7. Use of this software specifically implies assent to the terms of this licence. The intent of this license is that this software be used and enjoyed without undue restriction, and that it not be sold for profit, but that the sole rights of the author to main- tain and make any and all improvements or alterations to this product be preserved. FileBrowser 1.00 Manual - Page 9 THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. F. Acknowledgements The term "DOS" refers to the products Microsoft MS-DOS (tm) or IBM PC-DOS (tm). MS-DOS (tm) and Microsoft Windows (tm) are trademarks of Micro- soft Corporation. PC-DOS (tm) and IBM-PC (tm) are trademarks of the IBM Corpora- tion. Wordstar (tm) is a trademark of MicroPro International Corpora- tion. Sidekick (tm) is a trademark of Borland International Inc. BIX (tm) (BYTE Information Exchange) is a trademark of McGraw Hill, Inc. A small portion of the source code for FB.EXE, specifically related to the Search algorithm, was adapted from the Public Domain 'Strings' library written by Richard A. O'Keefe (1984). FileBrowser 1.00 Manual - Page 10 Page 11 G. FileBrowser - Version 1.00 License Registration Form. Completion of this form will be of assistance to the author, and ensure that you will be advised of the availability of new versions of FileBrowser and future software products. Information contained in this form will be strictly confidential, and will not be distributed by the author to any other party. Name:___________________________________________________________ Title:__________________________________________________________ Company:________________________________________________________ Mailing Address:________________________________________________ ________________________________________________ (Country):_________________ (Postal or ZIP Code):____________ E-Mail Address:_________________________________________________ Nature of Business:_____________________________________________ I will use FileBrowser: At Home:__________ At Work:_________ On how many computers belonging to you or your company will FileBrowser be used? ____________ Specify Type of Computer (Make, Model) and Video Display (e.g. CGA, EGA, Hercules, Color, Monochrome): ________________________________________________________________ How did you obtain FileBrowser? (Check appropriate category). Downloaded from a BBS:________ From a Usenet Posting:__________ From a Software Distributor:_______ (Specify):______________________ From another user:________ Other (Specify):________________________ I hereby assent to the terms of the license for use of FileBrowser Version 1.00 Signature:____________________________ Date:___________________ Please use the reverse of the registration form to make any comments or suggestions, report bugs, etc. After completion of the form, please mail to: David O. Tinker, RR 2, Group Box 50, GORMLEY, Ontario, Canada. L0H 1G0 FileBrowser 1.00 Manual - End