ADoc - User's Manual
AboutThisDoc
This manual describes release 4.00 of the utility ADoc. This program
is (c)1990-1994 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.
AREXX is (c)1987 by William Hawes.
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 is (c)1990 by Nico FRANCOIS
>>> 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.0 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 and
AmigaGuide files, as well as "PowerPacker" compressed files.
Criticisms and suggestions will always be welcomed. Write to:
M. GOUNELLE Denis
27, rue Jules GUESDE
45400 FLEURY-LES-AUBRAIS
FRANCE
You can also send a message to the following Internet address :
"gounelle@alphanet.ch". Note that this mailbox is not mine, so please send
only short messages. As I don't have direct access to the messages, don't
expect an answer before a dozen of days.
Thanks to Jean-Yves PROUX and Helmut J. ESENWEIN for their numerous
suggestions, to Reza ELGHAZI for his help concerning AmigaGuide files, and
to Simon HEWINSON who translated in English the "amiga.doc" file. Special
thanks to Jean-Philippe RAPP for his ideas and his help concerning AutoDocs
files.
Installation
ADoc needs "reqtools.library" (version 2.0c or higher) to run. You
must copy this file in your "LIBS:" directory, if not yet done.
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."
The german catalog was translated by Stefan SALEWSKI.
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.
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 AdvancedConcepts).
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.
DEPTH n
Asks ADoc to use a n-planes screen (allowing 2^n colors). If you asked
to use the Workbench screen, 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.
ONEWINDOW
Asks ADoc to open only one window at a time.
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
DEPTH=n
OPTIONS=[WBENCH][LACE][MAKEIDX][QUICK][AREXX][ONEWINDOW]
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
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, or press the <TAB> 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.
When no window is open, the term requester has a menu with the
following options :
Open window see TheSpecialMenu below
Search see the Search section below
Iconify see the TheProjectMenu below
Quit this one allows to quit ADoc.
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. In
this case, the window which was activated when opening a new window is
called the "parent window" of the new one.
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 ADoc recognize the following keys :
HELP list keys and their meaning
ESC close the current window
UP previous page
DOWN next page
BACKSPACE open parent window
Shift-UP previous term
Shift-DOWN 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.
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.
Help...
Displays some useful keys and their meaning (same as pressing the HELP
key)
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.
[1mCAUTION:
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). [22m
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.
One window
If this option is selected, ADoc will open only one window at a time.
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
Since v4.00, you can associate an IFF picture to a term. This
picture will be loaded at the same time as the text, and will be displayed
in the same window. In order to use this fonctionnality, you just have to
add a special line in the term's text :
. adoc@<position> <picture's name>
where <position> is "top", "bottom", "left" or "right". The picture will be
displayed in the given border. For example, if you enter :
. adoc@right doc:exec/schema1.pic
the picture "doc:exec/shema1.pic" will be displayed next to the right border
of the window.
ADoc is able to load pictures in a different screenmode and/or
colors numbers than the current screen. The screen's palette will be
modified with the picture's palette.
The release 1.40 of ADoc introduced the concept of aliases, that is
a manner to associate a same text to several terms, without having to repeat
the text several times. 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 !
An application of aliases could be the documentation of a function
library : often you will define several functions together. With the
aliases, you can allow access to the definition by the name of each
function, but the text is defined only once.
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.
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 ADoc moves all it's windows to the front screen
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 a other file while running ADoc
The return code (RC variable) will be set to zero, except in the
following cases: bad request (return code 20), "OPEN term" request with
"term" not found (return code 5), "request" request and no term choosen
(return code 5). Here is an example asking for help for the term "alias" :
/* Ask for help for "alias" */
ADDRESS "ADoc_rexx"
"FIND alias"
IF RC = 5 THEN SAY "not found !"
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.
AutoDoc_files_support
ADoc can recognize and use the AutoDocs files from Commodore. In
most cases, no change are 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.
AmigaGuide_files_support
ADoc can now recognize AmigaGuide files, build their index files,
and display their contents. The different syntaxes of the "@node" directive
are handled :
@node name
@node "title"
@node name "title"
In the latter case, an "name" alias is automatically defined for the "title"
term. The "@title" directive is also handled.
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. Note that ADoc handles
inter-files links, like:
@{"foo" link help:general/bar}
To allow such links, delimiters are automatically set to ":/." for
AmigaGuide files.
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
-6 bad picture specification
-7 error while loading picture