The Fred Fish Collection 1.5

home *** CD-ROM | disk | FTP | other *** search

/ The Fred Fish Collection 1.5 / ffcollection-1-5-1992-11.iso / ff_progs / prog_oth / adoc747.lha / ADocEnglish.doc < prev next >

Wrap

Text File | 1992-10-12 | 21.7 KB | 463 lines

AboutThisDoc This manual describes release 1.20 of the utility ADoc2. This program is (c)1990-1991-1992 by Denis GOUNELLE, any commercial usage or selling without author's written authorization is strictly forbidden. You can copy and spread this program at the following conditions: - all the files must be provided - none of the file must have been modified - you don't charge more than $6 for copy fee "PowerPacker 2.3b" is (c)1989 by PowerPeak and Nico FRANCOIS, "PowerPacker Pro 3.0b" is (c)1990 by PowerPeak and UGA Software. The "powerpacker.library" library is (c)1990 by Nico FRANCOIS. The "reqtools.library" library ist (c)1991-1992 by Nico FRANCOIS. AREXX is (c)1987 by William Hawes. In spite of several tests, no warranty is made that there's no errors in ADoc. YOU USE THIS PROGRAM AT YOUR OWN RISKS. In no event will I be liable for any damage, direct or indirect, resulting of the use of ADoc. >>> CLOSE THIS WINDOW TO CONTINUE <<< Foreword ADoc2 is a new release of ADoc, fully rewritten in order to remove some limitations and add several improvements. Note some incompatibilities arose particularly at argument level. This program works equally under 1.3 and 2.04 system releases. ADoc is an utility that allows you to manage all kinds of documentations on any subject. It is able to automatically start searching for a word selected by a mouse click, and to work on several documentation files at the same time. ADoc can also use straight the AutoDocs files of Commodore as well as "PowerPacker" compressed files. You can send comments and criticism about this program, writing at the following address : M. GOUNELLE Denis Boîte 71 6, rue des cailloux 92110 CLICHY - FRANCE Thanks to Jean-Yves PROUX and Helmut J. ESENWEIN for their numerous suggestions; thanks to Simon HEWINSON who translated in English the "amiga.doc" file. Special thanks to Jean-Philippe RAPP for his ideas and for he allowed me to test ADoc with AutoDocs files. HowDoesItWork ADoc works on documentation files, combined with a keyword (this one is named "term" in this doc). Every doc file has an index file that allows to access the wanted terms nearly immediately. (Note : as a result, each time you change a doc file, you'll have to rebuild its index file.) When ADoc is running, only is loaded in memory the index file. The name of this index file will be the doc file name plus an ".index" suffix. You can create your doc files with your favourite text editor; these files consist of a series of definitions and each definition has a syntax as follows : term text line 1 text line 2 etc... text line n At first, consider that the first two lines of a doc file have to be empty (or in extreme circumstancies begin with a space or a tab character). The first character of each term must be at column 1 and the text lines must begin with a space or a tab character. Empty lines are allowed. CAUTION: The doc file format is not the same as in versions 3.xx and 4.xx. One term can't be more than 32 character long and can't contain any blanks or tabs : valid characters are upper or lower letters, digits, underline, and accented letters (ASCII codes between 217 and 246). However, if needed, you can extend this character set (see below AdvancedTopics). The term amount for each file as well as the text line amount for each term are unlimited (or rather, this limit is so large that you'll be short in memory long before). A text line can't be more than 256 characters. In order to bring out some parts of your text, you can use the following ANSI sequences : ESC[1m boldface on ESC[3m italics on ESC[4m underline on ESC[22m boldface off ESC[23m italics off ESC[24m underline off ESC[0m normal character set RunningADocfromCLI ADoc can be run from Workbench or from the CLI. By default, the doc file is "Amiga.doc", but, of course, in both cases, you can specify another filename. From the CLI, you can specify the following arguments : WBENCH Asks ADoc to use the Workbench screen. When this argument is missed out, ADoc will open its own screen sized as the Workbench screen. On error, when opening screen, ADoc will go automatically to the Workbench screen. LACE Asks ADoc to use an interlaced screen. If you asked to use the Workbench screen, and this one is not in interlaced mode, this argument will be ignored. FONT name Asks ADoc to use a given font rather than the default one. Name must take the form <FontName><SizeY>, for ex. "topaz8". ADoc is able to use any non proportional font so long as its size is 8 at least. If ADoc can't open the requested font, it will attempt to use the default one. If this font doesn't suit or ADoc can't open it, it will try to access the topaz8 font. If it fails, ADoc will end immediately. MAKEIDX Tells ADoc the only operation to do is to create the index files. QUICK Asks ADoc not to display a text combined to the "AboutThisDoc" term, when starting. Usually, each time ADoc opens a file, it looks for the "AboutThisDoc" term in this file, and then, if this one exists, displays the corresponding text and waits for user to close the window before continuing. AREXX Asks ADoc to go in AREXX mode. More information on how to use ADoc with AREXX in TheAREXXMode section below. NOCASE Asks ADoc not to differentiate lower and upper characters when processing files. This only will concern files whose name is given after this option. NOSORT Asks ADoc not to sort the indexes of files whose name is specified after this option. TABSIZE n Tells the tab size for the files whose name is specified after this option. Default size is 8. Any other argument will be considered as a doc file name to be used. You can specify several files, by separating their names by spaces or commas (for ex. "ADoc file1 file2" or "ADoc file1,file2"). You can mix file names and options but let us remember that NOCASE, NOSORT, and TABSIZE options only concern files you specified after these options. ADoc will open these files in this given order. Unless you indicate one full path, firstly files will be looked for in the current directory, then in the "ADOC:" one. If you specify a directory name instead of file name, ADoc will open all the files in this directory (apart from ".info" and ".index" files). RunningADocFromWorkbench From Workbench, you can inwoke ADoc in several ways : - by double-clicking on its icon (then ADoc will use the default documentation file) - by double-clicking on one file icon having ADoc as default tool (field "DEFAULT TOOL") - by clicking on icons of several files, holding down the SHIFT key, and double-clicking on the ADoc icon. In all these cases, ADoc starts by looking into "TOOL TYPES" field of the program icon; this one may contain : FONT=name OPTIONS=[WBENCH][LACE][MAKEIDX][QUICK][AREXX] For more information on these options, see the RunningADocfromCLI section. Note option names must be separated by a "|" sign. After that, ADoc will open the doc files you specified; it will open them as it does from CLI except it examines the "TOOL TYPES" field of each icon. This field may contain : TABSIZE=n OPTIONS=[NOCASE][NOSORT] For more information about these options, see the RunningADocfromCLI section. Note these three options only will concern the file corresponding to the icon. StartingADoc ADoc needs "reqtools.library" v2.0c to run. You must copy this file in your "LIBS:" directory, if not yet done. As I explained above, ADoc starts by opening some specified file(s). At this time, ADoc attempts as well to open the index file corresponding to each doc file. If you didn't specified any file to open, ADoc will look if the "ADocFile" variable is defined : if so, it's value is used as a file name. Otherwise, the default file name is "Amiga.doc". You can specify several file names is the "ADocFile" variable, just as from command line (for example: setenv ADocFile "exec.doc dos.doc"). If ADoc can't find the index file, it will offer to create it. If you refuse, this doc file will not be usable but, in spite of it, ADoc will attempt opening other files. If ADoc detects a doc file was changed after an index was created, it will offer to update the index file. If you refuse, in spite of it, the doc file will be opened but later ADoc will be able to detect errors if the file contents was changed. Note the date of index file creation is stored in the index file itself. Once all files are opened, ADoc will display a requester; this one indicates the term list of first open file. We'll describe how to use this requester in the TheTermRequester section. TheTermRequester A term can be pointed out by a mouse click on it. Now this term is displayed in a different colour. If you click a second time on it, the requester is switched off and ADoc displays in a window the text corresponding to that term. I'll describe how to use these windows in HowToManageWindows section. To choose a term, you can use the keyboard too. If you press any key, the key letter will be added to the current "prefix" (displayed in a rectangle below the term list), and ADoc will display the list starting from the first term that begins with this prefix. ADoc will complete this prefix as far as possible. If you press the <BACKSPACE> key (above the <RETURN> key), the last prefix character will be deleted and the list will be updated too. If you press the <RETURN> key, ADoc will display the text corresponding to the first term that begins with this prefix. Note ADoc will not differentiate upper and lower letters when the current file is indicated after a NOCASE option. You can close the requester without selecting a term both by pressing the <ESC> key and by clicking in the close gadget either. If no window is open at this time, the program will abort. In fact, a term requester can allow you to select from among three lists : the term list of the current file, the list of the opened files (if you have several opened files) and the list of terms that ADoc found during the previous search operation (provided a search was made before, see the Search section below). At the bottom, on the right corner of term requester, you have a letter showing what a list is displayed : term list (T), file list (F), list of found terms (S). To pass from a list to another, click the right mouse button, holding down one of the <SHIFT> keys. When the file list is displayed and you select a file in this list, ADoc returns automatically to the term list and displays the list of terms in that file. When no window is open, the term requester has a menu with three options. The first one allows you to start a search (see the Search section below), the second one allows to iconify ADoc (see the TheProjectMenu below) and the last one allows to quit it. HowToManageWindows When you select a term, ADoc opens a window to display the corresponding text. When a term is defined several times either in a single file or in several different files, all text lines will be joined in a queue and displayed in one window. The window height is dependent on the amount of lines ADoc must display. If there are too many lines, only the first page will be displayed and ADoc will add two arrow gadgets (on the right top corner) for scrolling this text. Of course, you can have several windows opened at the same time. By default, these windows have standard close, dragging, back and front, and sizing gadgets. If you change the size of a window, ADoc, if needed, will add or remove automatically the arrow gadgets. Each window has three menus too : there are "Project", "Tools" and "Special" menus (I'll describe these ones in TheProjectMenu, TheToolsMenu and TheSpecialMenu sections, below). Finally, note you can close a window by pressing the <ESC> key and use the cursor <UP> and <DOWN> keys for scrolling a text page by page. When you click on a word, this one will be displayed in a different colour. If you click again on the same word, ADoc will automatically start searching for the corresponding term in all open files. If this fails, screen flashes, otherwise a new window will be brought up. TheProjectMenu Other term Bring up the term requester (see above TheTermRequester). Print Print the text contained in the active window. Note : the possible ANSI sequences will be correctly interpreted by the printer. Iconify Leave ADoc sleeping : if ADoc opened its own screen, this one will be closed, all the windows will be switched off and then ADoc will open a small window on the left top corner in the Workbench's screen. If you click on the close gadget of this window, ADoc will ask you to confirm it before you abort. For "awaking" ADoc, activate this window and click the right mouse button. Normally, ADoc keeps in memory all the text lines to be able switching on quickly all the windows when it would be awaken. The one drawback is that all possible memory will not be freed, so, when you ask ADoc to iconify itself, ADoc will ask you if you want to close all windows. If you say yes, the memory will be completely freed and when ADoc will be awaken, it will bring up the term requester. About... Display some infos about ADoc. Click inside this window or press a key to continue. Quit Allow to quit ADoc (asks you to confirm it). TheToolsMenu Front Screen Allow to use ADoc in a already open screen (for ex. that one of your text editor). Only you need to move the screen -where you want switch on ADoc- in front of any screen, drag it down to unfold the screen where ADoc is. Now, select this item : ADoc will close all the open windows and reopen these ones in the foreground screen. CAUTION: Of course, you'll have a "Guru" if the screen where you placed ADoc is closed before you quitted ADoc (or placed this one on another screen). Note this command will not work if you did not specify a font (see above the RunningADocfromCLI section) and the font of your front screen doesn't suit. Close all Allow to close all the windows at the same time. After it asked you to confirm, ADoc will close every window and display the term requester. Find Allow to start searching (see the Search section below). Information Display the account of avalaible files and terms, just as the account of opened windows and displayed lines. To continue click on the "Ok" gadget. TheSpecialMenu Open file Allow to open an additional doc file. A file requester is brought up so that you can specify what a file must be opened. Close file Allow to close the current file (i.e. the file where is defined the term displayed in the active window). After it asked you to confirm, ADoc will close all the windows relied to this file and will close it. Note this command will work only if at least two files are opened. Search In the text lines, ADoc has the capability to search up to four strings simultaneously and display then the list of the relied terms. When you select the "Search" item in the "Tools" menu, a window is switched on with four string gadgets. You have also an "CANCEL" gadget, to abort this operation, a "OK" gadget, to start your search, and an "Options" menu : low = UPP Ask ADoc not to differentiate upper and lower letters when searching. All strings Normally, ADoc is looking for all terms containing one of the strings you introduced. On the contrary, this item allows you to search for terms contaning ALL strings you specified. All files Ask ADoc to search in all open files, not only in the current file. When you start your search, a requester appears. The "Stop" gadget allows you to break this search. As soon as the search finished, screen will flash if no term was found. Otherwise, the term requester will be switched on and will display a list of found terms. That list is sorted, and kept in memory until you stard a new search. AdvancedConcepts ADoc can combine automatically several doc files. For that, it's enough to specify the name of file(s) to be combined, in the first line of file which you want associate them with. If this line is empty or begins with a space or tab, its contents will be ignored. File names have to be separated by spaces or commas. You can indicate a directory name; in this case all the files of that directory will be opened (except ".info" and ".index" files). To extend the character set you can use in a term, it's enough to specify additional characters in the second line of your doc file. If this line is empty or begins with a space or tab, its contents will be ignored. Otherwise, all characters of that line (up to first space, tab, slash or form feed) will be added to the default character set. Note this character set extension only will concern that file. ADoc has the possibility to load directly any compressed "PowerPacker" file, providing you have set up "powerpacker.library" in your LIBS: directory. It's not necessary (but recommended) to create the index file before you compress a doc file. ADoc will refuse to load an encrypted file. After ADoc has decompressed a file, this will be copied in a temporary file in the "T:" directory. So, using compressed files can arise some memory problems, especially if you put T: directory in your RAM: disk. This temporary file will be deleted when you close it. ADoc has the possibility to recognize and use the AutoDocs files of Commodore. In most cases, no change is needed, but it is recommended to verify their format : you must have at least two empty lines at the beginning, followed by the table of contents and every term must start at column 1. In some cases, you won't find empty lines at the beginning, and terms will begin at column 2 and will be preceded by a "form feed" character (i.e. CTRL-L). The program "AutoConvert", distributed with ADoc, will allow you to convert those files into a correct format (Note : this program can only be used from CLI). In all other cases, you'll have to convert these files by yourself. TheAREXXMode ADoc always opens a compatible AREXX port, named "ADoc_rexx". Messages on this port are waited for at the same time as Intuition messages on text windows, and can take the following forms : quit quit ADoc request bring up the term requester fscreen bring ADoc in the front screen ?term start searching for a given term, and display the corresponding text if it is found @file allows to open a other file while running ADoc Any other message will be ignored. There is an example asking for help for the term "alias" : /* Ask for help for "alias" */ address "ADoc_rexx" "?alias" Note quotes surrounding commands ! If you launch ADoc with the option AREXX, the program operation will be quite different : once ADoc opened the doc file(s), it will not switch on the term requester but will display a message "Waiting for an AREXX message" and will wait for messages on the AREXX port (or for CTRL-C to abort it). Moreover, when the last window will be closed, the program will not end itself but go back waiting for AREXX messages. TheADocMessages When an error occurs, ADoc displays in a small window a name (usually, a filename) and an error code. This one is either an AmigaDOS error code or an internal code. In the first case, see your AmigaDOS Manual (or use the command "Fault") to have more information on this error code. There are the internal error codes : -1 empty file -2 read error -3 file is wrong (bad format, etc...) -4 file is compressed and there is no "powerpacker.library" -5 a problem occured while decrunching