mkagidx.readme
==============

Introduction
------------

mkagidx updates the index of AmigaGuide documents. An existing index will
be deleted before processing the file. If the document does not contain an
index, a new node called "TheIndex" will be added.

The source code is included (HiSoft Basic 2).

Requirements
------------

This utility needs Amiga OS Release 2.0+ and 512 KB RAM. (Ensure that your
C: directory contains the SORT command.)

Usage
-----

The program must be run in the CLI. Simply call mkagidx with the file name
of an AmigaGuide document as the first argument. If you specify a second file
name, the resulting AmigaGuide document will copied to a new file rather than
replacing the old one (the old icon is copied, too).

Note:  mkagidx only uses links for creating the index. (The node definitions
       are ignored.)

How it works
------------

mkagidx needs three passes for updating an existing index node.

Pass #1: mkagidx looks for an existing index and saves the current AmigaGuide
         document to T:Temp.guide after deleting the old index. If no index
         node exists, a line like the following is added to the document:
         
           @Index TheIndex
         
         This line tells AmigaGuide (MultiView) that the index node is called
         TheIndex.
         
Pass #2: The new index is created by writing all links to the file "T:Index".
         All leading, trailing, and duplicate spaces are supressed. Node
         definitions are ignored.
         
Pass #3: The file T:Index is sorted and then linked to T:Temp.guide. All
         sections of the index are prefaced by a capital letter (A, B, C, and
         so on). Duplicate entries are removed. Finally, T:Temp.guide is
         copied to the original or a new AmigaGuide document. The temporary
         files are deleted.

Notes for programmers
---------------------

  o SUB shell is used to execute a CLI command.
  o FUNCTION replace$ returns satz$ after replacing wort$ by neu$.
    example: replace$("Hello","ello","i!") returns "Hi!".
  o FUNCTION NumArgs& processes the command string and extracts the argument
    strings. The resulting value is the argument count. The command string
    may contain spaces and quotes.
    Note: You *must* DIMension the array Arg$() before using this function.
  o All SUBs and FUNCTIONs must be declared befrore using them.
    
Distribution
------------

This utility is placed in the public domain and may be freely distributed.

Author
------

Send bug report and / or suggestions to:

  Frank Reibold
  Ottberger Weg 13
  D-31737 Rinteln
  GERMANY

Have fun!