Please consider a donation to the Higher Intellect project. See or the Donate to Higher Intellect page for more info.

ADoc Users Manual

From Higher Intellect Wiki
Jump to navigation Jump to search

			      ADoc - User's Manual

	  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
	  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
	  You can also send a message to  the  following  Internet  address  :
  "[email protected]". 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

	  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.

	  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 :

			  text line 1
			  text line 2
			  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
  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 :

      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.
      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

  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.

      Tells ADoc the only operation to do is to create the index files.

      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

      Asks ADoc to go in AREXX mode. More information on how to use ADoc  with
      AREXX in TheAREXXMode section below.

      Asks ADoc to open only one window at a time.

      Asks  ADoc  not  to  differentiate  lower  and  upper  characters   when
      processing files. This only will concern files whose name is given after
      this option.

      Asks ADoc not to sort the indexes of files whose name is specified after
      this option.

      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).

  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 :


  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 :


  For  more  information  about  these  options,  see  the  RunningADocfromCLI
  section. Note these three options only will concern the  file  corresponding
  to the icon.

	  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.

	  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.
	  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.

  Other term 
      Bring up the term requester (see above TheTermRequester).

      Print the text contained in the active window. Note : the possible  ANSI
      sequences will be correctly interpreted by the printer.

      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.

      Displays some useful keys and their meaning (same as pressing  the  HELP

      Display some infos about ADoc. Click inside this window or press  a  key
      to continue.

      Allow to quit ADoc (asks you to confirm it). 
  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.



	  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.

      Allow to start searching (see the Search section below).

      Display the account of avalaible files and terms, just as the account of
      opened windows and displayed  lines.  To  continue  click  on  the  "Ok"
  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. 
	  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.

	  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 :

.		[email protected]<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 :

.		[email protected] 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
	  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 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.

	  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.

	  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.

	  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