Club Amiga de Montreal

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

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 622a.lha / ADoc_v7.04 / ADocEnglish.doc.pp / ADocEnglish.doc

Wrap

Text File | 1992-04-03 | 21.1 KB | 549 lines

ADoc v7.04 - User's guide This file describes release 7.04 of the utility ADoc. This program is public domain, and permission is granted to freely distribute and copy it, provided no charge or fee is ask for, and no modification is done to this package. ADoc is copyright (c)1990-1991-1992 by Denis GOUNELLE, any commercial usage or selling of this program, without written authorization, is ABSOLUTLY FORBIDEN. By mutual agreement, Serge HAMMOUCHE is authorized to distribute ADoc as he likes. "PowerPacker 2.3b" is (c)1989 by PowerPeak and Nico FRANCOIS. "PowerPacker Pro 3.0b" is (c)1990 by PowerPeak and by UGA Software. The "powerpacker.library" library is (c)1990 by Nico FRANCOIS. AREXX is (c)1987 by Bill Hawes. No warranty is made that there's no errors in this program. 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. Table of contents: ------------------ 1. Introduction 2. How does it work. 3. User's guide 3.1 Running ADoc from the CLI. 3.2 Running ADoc from the WorkBench. 3.3 User's guide. 3.4 The term request. 4. Advanced concepts 4.1 Using several documentation files. 4.2 How to rely several files to a documentation file. 4.3 How to create several indexes. 4.4 How to extend the character set. 4.5 Using "powerpacker.library". 4.6 The AREXX mode. 4.7 Using Commodore AutoDoc files. 4.8 The "Special" menu. 5. Error messages. 1. Introduction. ---------------- ADoc is an utility that allows you to manage all kinds of documentation files. Its major feature is automatic search for a word selected by a mouse click. Also, ADoc can work on several documentation files at the same time, on Commodore AutoDoc files, and has an AREXX port. +--------------------------------------------------------+ | CAUTION !!! | | | | The doc file format has changed from releases 3.xx and | | 4.xx to releases 5.xx. To make old doc files work read | | the documentation file to know what is the new format, | | modify your old docs (this should not take you lots of | | time...) and re-create the index files. | +--------------------------------------------------------+ You can send me your suggestions or criticism writing to: M. GOUNELLE Denis Boite 71 6, rue des cailloux 92110 CLICHY - FRANCE Many thanks to Jean-Yves PROUX, Jean-Philippe RAPP and Helmut J. ESENWEIN for their numerous suggestions, to Simon HEWINSON for the english translation of the "Amiga.doc" file. Thanks again to Jean-Philippe RAPP for gaving me the opportunity to test ADoc with 2.02 release AutoDoc files. 2. How does it work. -------------------- ADoc works on a documentation file created with a text editor. This file will contain a list of terms and each term will look like this: term explanation line 1 explanation line 2 . . . . . . explanation line n The first character of each term MUST be at column 1, and the explanation lines MUST begin at least with a space or a tab character. It's the only way ADoc can make a distinction between a term and its explanation. Also, the first and second line of the documentation file MUST be empty (or begin with a space or tab character, for more informations see sections 4.2 and 4.4). The term string can't be more than 32 characters long and can't contain any spaces or tabs. The following are valid characters: single letters (upper or lower case), digits, stressed lowercase letters (ASCII codes between 217 and 246) and underline. However, you can extend this character set (see section 4.4). ADoc won't complain if a term is defined several times in a file : the explanation lines will just be put together when the text for this term will have to be displayed. If you define the term "AboutThisDoc", the corresponding text will automatically be displayed at startup time. You can't use more than 32767 terms for each documentation file. An explanation line can't be more than 256 characters long (however, only the first characters will be displayed). The number of explanation lines for a term is unlimited. You can include the following ANSI sequences in your explanation lines: ESC[0m Normal character set ESC[1m Boldface on ESC[3m Italics on ESC[22m Boldface off ESC[23m Italics off Once the documentation file has been created, ADoc will built an index file allowing to access a term almost instantly. The name of this index file will be the documentation file name plus an ".index" suffix. +-------------------------------------------------------+ | CAUTION !!! | | | | You MUST re-build your index file each time you | | modify the documentation file. | +-------------------------------------------------------+ 3. User's guide. ---------------- ADoc can be run from WorkBench or from the CLI. By default, the documentation file is "Amiga.doc", but in both cases you can specify another filename. 3.1 Running ADoc from CLI. -------------------------- From the CLI, ADoc is invoked using a command line of the form: ADoc -i [-f<file>] or ADoc [-c][-e][-f<file>][-l][-n][-q][-A][<term>] The first command line invokes ADoc for creating a documentation file index; the second one allows to interrogate the documentation file. Five options are avalaible: -i if specified, ADoc only creates the documentation file index. This option MUST be the first one in the command line. -c tells ADoc to ignore letter case (in search as well as in term request). Should be specified before any -f option. -e if specified, ADoc opens its own screen, instead of using the Workbench's screen. Please take notice that ADoc always open its own screen when WorkBench's screen default font is not "topaz8". -f<file> if specified, ADoc look for this documentation file. If no full pathname was specified, ADoc looks for the file first in the current directory, and then in the "ADOC:" directory. -l if specified, ADoc opens a screen in interlaced mode. If you didn't specify -e option, and your Workbench's screen is not in interlaced mode, ADoc will open its own screen. -n asks ADoc to don't sort index when displaying term request. Should be specified before any -f option. -q asks ADoc to don't display "AboutThisDoc" term at startup time. -A if specified, sets AREXX mode (see section 4.6). The -i and -e options can't be used with this option. When using the second command line, you can specify a term of the documentation file to be searched first (optional). 3.2 Running ADoc from Workbench. -------------------------------- From Workbench, ADoc is inwoked by four ways : - by double-clicking on its icon (then ADoc will use the default documentation file) - by clicking on a documentation file icon which default tool is ADoc. - by clicking on ADoc icon, holding down the SHIFT key, and then double-clicking on a documentation file icon - by clicking on a documentation file icon, holding down the SHIFT key, and double-clicking on ADoc icon. When ADoc is run from the Workbench, it always opens its own screen. You can specify options in the "TOOL TYPES" field of ADoc icon, or file icon. The syntax is : ADOC=[INTERLACE]|[NOSORT]|[CASE]|[QUICK] The INTERLACE parameter asks for a screen in interlace mode. The NOSORT parameter asks ADoc to don't sort index when displaying term request. The CASE parameter tells ADoc to ignore letter case when searching, or in term request. The QUICK parameter asks ADoc to don't display the "AboutThisDoc" term at startup time. 3.3 User's guide. ----------------- When opening the help file, ADoc searchs for the "AboutThisDoc" term. If it exists, the corresponding text is displayed in a window and ADoc waits for this window to be closed to continue. If ADoc was invoked either from Workbench, or from CLI and the term was not specified in the command line, the program displays a requester with a list of the known terms. See section 3.4 for term request description. When you have specified the term to search, a window will appear with the text corresponding to the term. If the text is too large to be fully displayed, only the first page will be displayed, and two arrow gadgets will apeared on the title bar of the window. These gadgets allow to move your text in the window, and will be automatically added or removed if required when the window is resized. To close the window, click on the close gadget or press the ESCAPE key. Now, you can click twice on a word of the explanation text: that will run the searching function for this word automatically. If the word couldn't be found the screen will flash, otherwise the text will be displayed in a new window. If you want to get the text for a term, and this term is not is any displayed text, you need to select the "Other term" command from the "Project" menu: ADoc will display a requester with the list of known terms within (see section 3.4 for term request description). In both cases, if you selected a term relied to a window, this window will be put in the foreground. You can print the text relied to a term by selecting the "Print" command from the "Project" menu. In the eventuality your text has some escape sequences, these will (of course) be correctly interpreted by the printer. You can iconify ADoc by selecting the "Iconify" command from the "Project" menu. Then, all the windows will be closed (if ADoc opened its own screen, it will be closed too) and a small window will appear on the left top corner of the Workbench's screen. Now, either you can quit ADoc by clicking on the window close gadget, or you can awake it by pressing the right mouse button. At this moment, ADoc will suggest you to 're-open' all the windows that were opened when you have iconified it. By selecting "NO" you'll get the term request. You can move ADoc from a screen to another one by selecting the "Front Screen" command from the Project menu. To do it, move the screen where you want ADoc to display in front of all the other screens, drag it down and move ADoc screen just behind. Choose now the "Front Screen" command: all the windows will be moved to the foreground screen. Please take notice that this command won't work if default font of destination screen is not "topaz8", or if ADoc screen is in interlace mode while destination screen doesn't. You can quit ADoc either by closing each window (ADocs stops when the last window is closed) or by choosing the "Quit" command from the Project menu. When a YES/NO requester is displayed, you can answer "YES" by pressing the RETURN key, or answer "NO" by pressing the ESCAPE key. 3.4 The term request -------------------- The term request allows you to select a term with your mouse. If you click on a term, this term will be (red) highlightened. Click once again on it to confirm your choice, or click on another term if you changed your mind. You can also make your choice with the keyboard. If you press a key, this letter will be added to the current prefix (displayed in a box at the bottom of the window), and the display of the term list will start with the first term beginning with this prefix. ADoc will try to complete the prefix as far as possible. If you press the BACKSPACE key, the last letter of the prefix will be removed, and the display updated. If you press the RETURN key, the first term corresponding to the prefix will be taken as your choice. If you press the ESCAPE key, the window will be closed and the request aborted. 4. Advanced concepts. --------------------- 4.1 Using several documentation files. -------------------------------------- To do it, only you need to specify the names of the files you want to use: from Workbench, by selecting the icon of these files, from the CLI by typing a comand line of the form: ADoc [options] -fname1,name2,...nameN [<term>] You can specify several -f options and other options between them, like : ADoc -fname1,name2 -c -fname3 -n -fname4 which cause ADoc to load name1, name2, name3 and name4 files. The index of name1, name2 and name3 files will be sorted in the term request (ignoring letter case for name3 file), but not the index of name4 file. If you don't specify the full path name for a file, it is supposed to be in the current directory or in the "ADOC:" directory. By specifying a directory name (or, from Workbench, by selecting a directory icon), all the files of this directory will be used (except files whose filename extension is ".info" or ".index"). As usual, when one or several index files don't exist, Adoc will ask for creating them. Practically, ADoc works as usual. Here is additional features: - when opening EACH file, ADoc will search for the "AboutThisDoc" term and display the corresponding text, then wait for the window to be closed to continue. - ADoc looks for a selected word in ALL documentation files it is using - if a term is defined in several files, all the lines will be put together and displayed in the same window - when ADoc displays a requester, you can change the "display" by pressing on the right mouse button: alternately, you'll get either the list of terms of the current documentation file, or a list of files that ADoc is using at this moment. So, you can select a term in any documentation file. ADoc won't load twice the same file. Two files are considered as identical EITHER if their names are identical OR if their indexes have been created at the same date and time. Date value is stored in the index file when you created it, so this value will change only if you re-create this index file. 4.2 How to rely several files to a documentation file. ------------------------------------------------------ Also, it's possible for you to connect one or more files to a documentation file. In this case, when this documentation file is opened, automatically, at the same time, ADoc will load the relied files. To use this function, only you need to specify the name of every file you want to rely to the documentation file, separated with commas, in the first line of this file. If the first command line is empty, or begins by a space or tab character, no file will be relied to the doc file. Except if you specify a full path name, ADoc will search for the associated files first in the current directory, then in the "ADOC:" directory. If you specified a directory, every file in this directory will be be associated to the documentation file (except files whose filename extension is ".info" or ".index"). 4.3 How to create several indexes. ---------------------------------- You can specify several files even when you are using -i option, e.g. the command line will look like this: ADoc -i -fname1,name2,...nameN In this case, ADoc will create an index for every file you specified, then it stops. 4.4 How to extend the character set. ------------------------------------ Sometimes, it would be useful to extend the character set to use in a term. The second line of a doc file is reserved for this use. If this line doesn't begin neither with a space nor with a tab character, all the characters of this line will be added to the allowed set until ADoc reads one of the following character : space, tab, newline, form-feed, slash. Note that this extension is made separately for every file. This means that if you are using several doc files simultaneously, the allowed characters will change from a file to another, according with those you specified in the second line of every file. 4.5 Using "powerpacker.library". -------------------------------- ADoc can load any files compressed with "PowerPacker 2.3b" or with "PowerPacker Pro 3.0b", according you have set up "powerpacker.library" in the "LIBS:" directory of your hard disk or floppy disk. Index file doesn't need to be created before compression. ADoc will refuse to load an encrypted file. After ADoc has uncompressed the file, it will be copied in a temporary file in the "T:" directory. This temporary file will be deleted at the end of working session. Using compressed files can require a lot of memory (especially if you put the "T:" directory in your RAM: disk), so I suggest you to compress several "little" files (30 to 50 Kb) rather than one big file (more than 100 Kb). 4.6 The AREXX mode. ------------------- If you specify -A option when calling ADoc, you'll get the AREXX mode: an AREXX compatible message port named "ADoc_rexx" is opened, and ADoc waits for messages on this port. You can't specify -e nor -i options whith the -A option. Note that ADoc won't be able to go in AREXX mode when it have to open it's own screen, so you can't specify -e option with -A option. Also, if ADoc is run from WorkBench, or if you specify -l option and the WorkBench screen is not in interlaced mode, the AREXX mode will be silently disabled. The messages can be : quit : ADoc closes the message port and terminates. wakeup : ADoc closes the message port and goes to normal Intuition mode. ?term : ADoc searches this term, and if found, goes to normal Intuition mode to display the corresponding text. Any other message will be ignored. Here comes an example of AREXX program, that ask for help on "alias" and terminate ADoc : /* Ask for help on "alias" */ address "ADoc_rexx" "?alias" "quit" Please note the " characters arround commands ! In normal Intuition mode, you can go to AREXX mode with the "AREXX mode" command in Project menu: all opened windows will be closed, and ADoc will wait for messages on it's port. When you use ADoc in AREXX mode, don't forget that ADoc will go back from normal Intuition mode to AREXX mode when you close the last opened window. To terminate ADoc, use the "Quit" command in Project menu. 4.7 Using Commodore AutoDoc files. ---------------------------------- This release of ADoc is able to recognize and use Commodore AutoDoc files. In most cases, you won't have to modify these files, but you should verify their format : there must be at least two empty lines at the top of the file, and each term must start in column 1. You will find, sometimes, that the empty lines are missing and that each term is preceded by a "form-feed" (CTRL-L) character. The AutoConvert programm (included in ADoc distribution) will automatically convert such files in the good format (NOTE: AutoConvert must be used from CLI only). In any other case, you will have to modify the files by yourself. ADoc has been tested with the 45 AutoDoc files for system release 2.02 : 27 didn't need any modification, 11 needed to be converted by AutoConvert, and the remaining 7 had to be hand-modified. 4.8 The "Special" menu. ----------------------- The "Info" item will tell you how much files, terms, windows and lines are available. The "Open file" item allows you to open a new doc file at any time. A file requester will appear, so you will be able to select the file to open. The files which names end by ".info" or ".index" are hidden. Click on "ABORT" or close the window to abort. The "Close file" item allows you to close a doc file you don't need, in order to free some memory. You will be asked for confirmation but remember that you'll always be able to open it again with the "Open file" item. The "Close windows" item allows you to close all the help windows opened at the current time. You will be asked for confirmation, and the term requester will appear after all windows have been closed. 5. Error messages. ------------------ I've put the section where you will find more information on error message in brackets. - Bad arguments (3.1) Error in command line. - Can't open <name> Ressource <name> couldn't be opened. Ressource can be a documentation file (verify if this file does exist) or an index file (see sections 3.1 and 3.3 to create it). - Line too long <line> (see section 2.) The indicated line is more than 256 characters long. - Term too long <name> (see section 2.) The specified term is more than 32 characters long. - No text for <term> (see section 2.) No explanation line for this term. - Empty file <name> The file you specified is empty, or no term was found in this file. - Read error <name> An error occurred while ADoc was reading this file. - Write error <name> An error occurred while ADoc wrote this file. - Bad index file <name> (see sections 2., 3.1 and 3.3) The index file you specified is incorrect. You MUST re-create it. - Bad association for <name> (see section 4.2) The first line this file (the line that gives you a list of all the relied files) is wrong or incorrectly spelt. - Crypted file <name> (see section 4.5) The file you specified was crypted with PowerPacker.