ADoc - User's Manual AboutThisDoc This manual describes release 5.00 of the utility ADoc. This program is Copyrigth ©1990-1997 by Denis GOUNELLE. Any commercial usage or selling without author's written authorization is strictly forbidden. You can copy and spread this program under the following conditions: - all the files are provided - the files are not modified in any way - you don't charge more than $6 for copy fee In spite of several tests, no warranty is made that there are no errors in ADoc. YOU USE THIS PROGRAM AT YOUR OWN RISK. In no event will I be liable for any damage, direct or indirect, resulting of the use of ADoc. Foreword ADoc is an utility that allows you to visualize "hypertext" documents. If you want to know what it means and to see what ADoc can do, just click twice on the word that follows : Explanation. Criticisms and suggestions will always be welcomed. Write to: M. GOUNELLE Denis 27, rue Jules GUESDE 45400 FLEURY-LES-AUBRAIS FRANCE denis.gounelle@ramses.fdn.org Explanation CONGRATULATIONS ! You've just understood how it worked ! When you double-clicked on a single word in the text, ADoc has searched the text associated to this word, in the documentation file, and opened a new window to show you this text. What makes ADoc different from other programs of this type : - you can double-click on any word in the text, and ADoc will search for it (no more trouble because the document's author has forgotten an hypertext link !). - this implies that there is no need to define hypertext links in the document (no more headaches for the author, who had to define and maintain theses links in all the document !) - ADoc displays several windows at the same time (unless you ask him not to do so) and handles several document files at the same time. - ADoc can use straight files in the AutoDoc and AmigaGuide format. - ADoc has a lot of little tricks and useful functions, like string searching in all the opened files, an AREXX port, and so on... (read the documentation, this time !) Installation ADoc can be used on any Amiga computer under release 2.04 (V36) or greater of the operating system. ADoc is now localized, so it can adapt itself to your favorite language. All you have to do is to copy the good catalog file into the directory corresponding to your language. For exemple, if your default language is french, copy the "français.catalog" into the "SYS:Locale/Catalogs/Français" directory, under the name "ADoc.catalog." ADocFileFormat 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. 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 192 and 253). However, if needed, you can extend this character set (see below AdvancedConcepts). The term amount for each file as well as the text line amount for each term are limited only by the available memory on your system). 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. From the CLI, you can specify the following arguments : PUBSCREEN name Asks ADoc to use the given public screen. By default, ADoc opens a new custom screen, sized like the Workbench screen. screen. REXXPORT name Specifies the name of the AREXX port to open (will be put to upper-case). By default, the port's name is "ADOC_REXX". ICONNAME title Specifies the name of the icon, when ADoc is iconified. OPTIONS MAKEIDX|QUICK|AREXX|ONEWINDOW Specifies program's options. MAKEIDX Tells ADoc the only operation to perform 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. AREXX Asks ADoc to go in AREXX mode. More information on how to use ADoc with AREXX in TheAREXXMode section below. ONEWINDOW Asks ADoc to open only one window at a time. FONT name Asks ADoc to use the given font rather than the default text font. Name must take the form , for ex. "topaz8". ADoc is able to use any non proportional font. If the given font name is "REQUEST", ADoc will open a font requester so that you can select the font to use. CASE YES|NO Asks ADoc if it must differentiate lower and upper characters when processing files. This only will concern files whose name is given after this option. SORT YES|NO Asks ADoc if it must 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 FONT, CASE, SORT, and TABSIZE options only concern files you specified after these options. ADoc will open files in this given order. Unless you indicate a 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 : PUBSCREEN=name REXXPORT=name ICONNAME=title OPTIONS=[MAKEIDX|QUICK|AREXX|ONEWINDOW] FONT=name TABSIZE=n SORT=YES|NO CASE=YES|NO 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 : FONT=nom TABSIZE=n SORT=YES|NO CASE=YES|NO For more information about these options, see the RunningADocfromCLI section. Note these options only will concern the file corresponding to the icon. StartingADoc As explained above, ADoc starts by opening the specified file(s). 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. You can specify several file names in the "ADocFile" variable, just as from command line (for example: setenv ADocFile "exec.doc dos.doc"). Then, ADoc attempts as well to open the index file corresponding to each doc file. 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 try to open the 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 ADoc may have some troubles later with this file (if it's content has 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 either the term list of the sole opened file, or the list of the opened files. 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 at the bottom of the requester. 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. We'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 key, the last prefix character will be deleted and the list will be updated too. If you press the 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 CASE=NO option. You can close the requester without selecting a term both by pressing the key and by clicking in the close gadget either. If no window is open at this time, the program will abort (except if running in AREXX mode). 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). To switch from a list to another, press the key. 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. The term requester has a menu with the following options : Open term see TheProjectMenu below Search see the Search section below Iconify see the TheProjectMenu below Quit this one allows to quit ADoc. The term requester uses the font specified in the last FONT argument. So, if you want to use a different font for this requester, you just have to append a FONT argument as the last argument. HowToManageWindows When you select a term, ADoc opens a window to display the corresponding text. 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. Use the scroller at the right of the window to scroll this text. By default, these windows have standard close, dragging, back and front, and sizing gadgets. Each window has three menus too : there are "Project", "Tools" and "Options" menus (I'll describe these ones in TheProjectMenu, TheToolsMenu and TheOptionsMenu sections, below). Finally, note ADoc recognize the following keys : ESC closes the current window UP scrolls one line up DOWN scrolls one line down SHIFT-UP scrolls one page up SHIFT-DOWN scrolls one page down ALT-UP go to the first page ALT-DOWN go to the last page CTRL-UP shows the previous term CTRL-DOWN shows the next term 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. All term windows (and the term requester as well) are declared as "AppWindows" (application windows). This mean that you can drop Workbench's icons on these windows : the file(s) corresponding to these icons will be scanned, and added to the opened files list. TheProjectMenu 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. Other term Bring up the term requester (see above TheTermRequester). Find Allow to start a search operation (see the Search section) Iconify Leave ADoc sleeping : all the windows will be switched off and then ADoc will open an icon on the Workbench's screen. For "awaking" ADoc, you just have to double-click on this icon : all the windows will be brought back. The icon will be the same as the program's one : if you start ADoc twice, from two different directories, containing different icons, then each program will have a different icon. The icon will be declared as an "AppIcon" (application icon). This mean that you can drop Workbench's icons on it : the file(s) corresponding to these icons will be scanned, and added to the opened files list. About... Display some informations about ADoc. Quit Allow to quit ADoc (asks you to confirm it). TheToolsMenu Print Print the text of the current window. Note : the possible ANSI sequences will be correctly interpreted by the printer. Save as Save the text of the current window. Note : the possible ANSI sequences will not be written to the file. Close all Allow to close all the windows at the same time. TheOptionsMenu One window If this option is selected, ADoc will open only one window at a time. Search ADoc can search for a string into : - the current term (when you select the "Find" menu item of a term window). In this case, if you have selected a word in a term window, this word will be taken as the default value for the string to find. - all the terms of a file (when you select the "Find" menu item when the term requester shows a file's term list) - all the terms of all the files (when you select the "Find" menu item when the term requester show's the file list). In the first case, once the search is completed, the window's content will be redrawn and any occurence will be put in bold characters. The display is also moved so the line with the first occurence will be at the top of the window. In the two other cases, a requester appears so you can follow the search progress. The "Abort" gadget of this requester 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 the list of found terms. That list is sorted, and kept in memory until you stard a new search. AdvancedConcepts In your documentation files, you can define aliases, that is a manner to associate a same text to several terms, without having to repeat the text several times. An application of aliases could be the documentation of a function library : often you will define several functions together. With aliases, you can allow access to the definition by the name of each function, but the text is defined only once. An alias definition follow the syntax: name1 alias name2 The first character of "name2" must, as for any term definition, be at column one. There must be at least one space or tabulation between the three words. The word "alias" must be in lower case characters. The effect of such a definition is that when the user will ask to get the "name1" term, ADoc will automatically display the "name2" term instead. Aliases appear in the term requester, and in the search function. You must be aware that there is *NO* recursivity check between aliases ! -------------------- 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). Unless you indicate a full path, firstly files will be looked for in the directory of the calling file, then in the "ADOC:" directory. -------------------- 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. TheAREXXMode ADoc always opens a compatible AREXX port, named "ADOC_REXX". Messages on this port can take the following forms : QUIT quits ADoc HIDE iconifies ADoc SHOW "wakes up" ADoc if it is iconified REQUEST brings up the term requester TOFRONT put ADoc screen in front of all screens TOBACK put ADoc screen in back of all screens FIND term start searching for a given term, and display the corresponding text if it is found OPEN file allows to open one or several files while running ADoc CLOSEALL closes any opened window Here is an example asking for help for the term "alias" : /* Ask for help for "alias" */ ADDRESS "ADoc_rexx" "FIND alias" IF RC = 10 THEN SAY "not found !" 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 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. AutoDoc_files_support ADoc can recognize and use files in the AutoDocs format. Any known variant of this file format is supported. AmigaGuide_files_support ADoc can recognize and use files in the AmigaGuide format. As ADoc doesn't handle spaces in term names, they are replaced by underscore characters. Links within text are displayed in boldface. As names are truncated to 32 characters, some links may fail. The @TAB et @FONT commands (both global and local), the @TITLE command, font style changes, external links, the escape character ('\') are automatically handled. Unless the "QUICK" option has been specified at program startup, ADoc will automatically display the "MAIN" node when opening the file. History v5.00, 06-Apr-97, 75108 bytes o Rewritten from scratch, in C++, using the SAS/C 6.57 o New GUI using the "gadtools.library" o Can use any public screen o Can use a different font for each opened file o New iconification handling o Better support of AutoDoc and AmigaGuide files o All the windows are "AppWindow"s o Show the progression of index creation, of string search