@database "Ax.guide"
@master "Ax.guide"
@author "Paul A. Schifferer"
@(c) "Copyright © 1996-7 Isengard Developments"
@$VER: Ax.guide 1.02 (4.10.97)
@wordwrap

@node Main "Ax: Table of Contents"

        @{i}Ax@{ui}
        Version 1.02

        Written by Paul A. Schifferer
        Copyright © 1996-7 Isengard Developments
        All rights reserved.

        @{b}@{i}Table of Contents@{ui}@{ub}

                 @{u}Legal@{uu}

        @{"     I. " link Terms} Terms
        @{"    II. " link Disclaimer} Disclaimer of Warranty

                 @{u}Starting@{uu}

        @{"   III. " link Intro} Introduction
        @{"    IV. " link Required} System requirements
        @{"     V. " link Install} Installing Ax
        @{"    VI. " link Registration} Registration
        @{"   VII. " link Bugs} Undocumented features
        @{"  VIII. " link Beta} Beta-testers' note
        @{"    IX. " link UsingWB} Using Ax from the Workbench
        @{"     X. " link UsingShell} Using Ax from the Shell

                 @{u}Operation@{uu}

        @{"    XI. " link MainWindow} The Main Window
        @{"   XII. " link BrowseThread} The Browse Window
        @{"  XIII. " link SearchThread} The Search Window
        @{"   XIV. " link ParseThread} The Parse Window
        @{"    XV. " link MaintThread} The Maintenance Window
        @{"   XVI. " link FTPThread} The FTP Control Window
        @{"  XVII. " link ConfigThread} The Configuration Window
        @{" XVIII. " link ARexx} The ARexx Interface

                 @{u}Miscellaneous@{uu}

        @{"   XIX. " link Misc} Miscellaneous
        @{"    XX. " link Caveats} Caveats

                 @{u}Appendices@{uu}

        @{"     A. " link UpdateDB} 'UpdateDB' utility
        @{"     B. " link History} Program history
        @{"     C. " link me} Author information
        @{"     D. " link Acks} Acknowledgements
@endnode

@node Terms "Ax: Terms"
@{fg shine}Terms@{fg text}

You may copy and distribute verbatim copies of the programs' executable code and documentation as you receive it, in any medium, provided that you conspicuosly and appropriately publish only the original, unmodified programs, with all copyright notices and disclaimers of warranty intact and including all the accompanying documentation, example files and anything else that came with the original.

You may not copy and/or distribute these programs without the accompanying documentation and other additional files that came with the original.   You may not copy and/or distribute modified versions of these programs.

You may not disassemble, decompile, re-source or otherwise reverse engineer the programs.

You may charge a fee to recover distribution costs.  The fee for diskette distribution may not be more than the cost to obtain a public domain diskette from Fred Fish.
@endnode

@node Disclaimer "Ax: Disclaimer of Warranty"
@{fg shine}Disclaimer of Warranty@{fg text}

THERE IS NO WARRANTY FOR THE PROGRAMS, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING, THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAMS "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.   THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAMS IS WITH YOU.  SHOULD THE PROGRAMS PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY REDISTRIBUTE THE PROGRAMS AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAMS (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAMS TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

SO THERE.
@endnode

@node Intro "Ax: Introduction"
@toc Main
@{fg shine}Introduction@{fg text}

This program came about as a result of my search for a decent database/search tool for the Aminet.  Since the Aminet INDEX is a rather large, unwieldy document, it can quickly become a pain in the back areas browsing through it.  And searching through the Aminet archives online isn't very efficient.

The purpose of Ax is to cut down trees.  Or maybe its purpose is to turn the INDEX file, as well as RECENT files, into a reasonable database that allows you to find the software that you're looking for.

Ax's features include:

- Fully multi-threaded operation, allowing multiple operations on one or more databases concurrently, as well as asynchronous download of files (while connected to the Internet) via ARexx.

- Operates in any display environment via use of Intuition's public screen system.

- Amiga User Interface Style Guide compliant with a very stylish and elegant ClassAct user interface.

- On-line help (requires AmigaGuide).

- Reasonably fast search mechanism.

- The ability to keep your own personal Aminet database current by merging new RECENT files into the current database without having to constantly download new INDEX files.

- An ARexx interface that will allow you to control Ax in an automated fashion, as well as communicate with FTP clients to download files.

- And much more!
@endnode

@node Required "Ax: System requirements"
@toc Main
@{fg shine}System requirements@{fg text}

Ax requires version 2.04 or higher of the Amiga OS (2.1 or higher for Locale support).  It is designed to take advantage of some features available in higher versions, if they are available.

Ax requires the ClassAct GUI toolkit, which is included with the program archive.

Ax also requires a @{"stack size" link StackSize} of at least 10,000 bytes.

Given the current size of the Aminet INDEX, about 7-10 megabytes (MB) of disk space is needed to store the database.
@endnode

@node StackSize "Ax: Setting the stack size"
@toc Main
@{fg highlight}From the Workbench@{fg text}

You can check that the icon's stack size is set properly by clicking once on the icon, then selecting Information from the Workbench's Icon menu.  In the upper left corner of the Information window is an integer gadget marked "Stack:".  If the value in this gadget is less than 10,000, click in it, change it to 10000, press Return, and click the button marked Save.  Now you may run Ax.

@{fg highlight}From the Shell@{fg text}

You can check this by entering
@{b}
     stack
@{ub}
at the prompt.  This will tell you the size of your Shell's stack.  If it's less than 10,000, then enter
@{b}
     stack 10000@{ub}.

This will change the stack size so it's large enough for Ax to run.
@endnode

@node Registration "Ax: Registration"
@toc Main
@{fg shine}Registration@{fg text}

Ax is a free product.  A labor of love, if you will.  I really like this program, and judging from some of the e-mail I've gotten, some of you do too. :)

The only registration I ask of you is that you drop @{"me" link me} a line, good or bad, about what you think about Ax.  If you don't like it, by all means, tell me why.  Maybe I can make that change that'll make you happy.  If you do like it, say so, and give me suggestions for improvement.
@endnode

@node me "Ax: Author information"
@toc Main

The official support site for Ax (and other programs I've written) is:

http://www.geocities.com/SiliconValley/Pines/3517

Visit there often to see what's developing.

The address to which you can send me money, postcards, a spare Amiga, or anything else is:

Paul A. Schifferer
515 11th Street
Edwards, CA  93523
USA

I can also be contacted via Internet at:

gandalf@hughes.net
@endnode

@node Install "Ax: Installing Ax"
Included in the archive is an installer script to be used with the Commodore Installer.  If you don't have it, it can be retrieved from the Aminet.

If you are using an older version of Ax, you can install this version over it.  Your old database will need to be updated, though.  Included is a small utility to do this for you, called @{"UpdateDB" link UpdateDB}.
@endnode

@node Bugs "Ax: Undocumented features"
@toc Main
@{fg shine}Undocumented Features@{fg text}

Some people call these things 'bugs'.  If you happen to notice one of these little critters, let me know, please!  I've done my best to make sure all the bugs were discovered and removed, but I can't find them all.  If finances are favorable, I may send you the next release at my cost.  (See @{"Beta-Testers'" link Beta} Note.)

Please, if you send me bug reports, make sure to let me know the type of system you're running it on (CPU, RAM, etc.), which executable you were using, what other programs were running with it (especially commodities and system enhancers, since they tend to gum up the works sometimes), and what you were doing at the time of the bug occurrence/system crash.
@endnode

@node Beta "Ax: Beta-testers' note"
@toc Main
@{fg shine}Beta-Testers' Note@{fg text}

This release is in general public distribution.

If you wish to be a beta-tester for future versions of this program, or for any other program I may release, drop @{"me" link me} a postcard or e-mail.  I will put you on the list of beta-testers, for which you will receive notification of test-releases and get your fingers first on the newest and neatest stuff.

Ax has been tested on the following systems:

@{b}A2000@{ub}
Derringer 030/882 @ 33 MHz (20MB)
Amiga OS 3.1 (V40)
Picasso IV
DataFlyer IDE w/ Western Digital 1.2GB HD
GVP Impact Series II SCSI HardCard w/ Quantum 80MB HD

@{b}A1200@{ub}
68030/882 @ 50 MHz (6MB)
Amiga OS 3.0 (V39)
880MB HD

@{b}A1200@{ub}
Blizzard 1220/IV
Amiga OS 3.0 (V39)

@{b}A3000@{ub}
68030/882 @ 25 MHz (6MB)
Amiga OS 3.1 (V40)
Quantum P40S SCSI w/ 40MB HD
Quantum Fireball SCSI-2 w/ 1.2GB HD
Python SCSI-2 4GB DAT
OpalBoard Rev 2.4
A2065 Ethernet

@{b}A2000@{ub}
68030/FPU (4MB)
Amiga OS 2.1 (V38)
A2630
GVP SCSI-2 Host Adapter w/ Quantum 120MB HD
Masoboshi Smartcard w/ 2MB RAM

@{b}A500+@{ub}
68EC030/882 @ 40 MHz (6MB)
Amiga OS 3.1 (V40)
GVP A530 Series II w/ Quantum 170MB HD

@{b}A1200@{ub}
Blizzard 1260 (8MB)
Amiga OS 3.0 (V39)
1.3GB HD
@endnode

@node UsingWB "Ax: Using Ax from the Workbench"
@toc Main
@{fg shine}Using Ax from the Workbench@{fg text}

Ax requires a @{"stack size" link StackSize} of at least 10,000 bytes to run.

To start Ax from the Workbench environment, simply double-click on its icon.  Ax's behavior can be modified by using ToolTypes.  The following ToolTypes are supported:

@{b}SETTINGS=@{i}file@{ui}@{ub}
This indicates the settings file to use for Ax's configuration.  If not specified, Ax will first look in its program directory, then ENV:/ENVARC: for a settings file.

@{b}PUBSCREEN=@{i}name@{ui}@{ub}
Use this ToolType when you want to open Ax on another program's existing public screen.  The name you supply is the name of the screen on which to open.

@{b}PORTNAME=@{i}name@{ui}@{ub}
This ToolType gives the name for Ax's ARexx port, which defaults to AX.  Note that you cannot change Ax's FTP ARexx port name, which defaults to AXFTP.

@{b}HELPFILE=@{i}file@{ui}@{ub}
This ToolType gives the location of Ax's online help file, Ax.guide.  It will override the location set in the settings file.

@{b}QUIET@{ub}
Using this option tells Ax not to present its initial copyright banner.
@endnode

@node UsingShell "Ax: Using Ax from the Shell"
@toc Main
@{fg shine}The Shell@{fg text}

Before you start Ax, you must make sure your Shell's @{"stack size" link StackSize} is at least 10,000 bytes or greater.

To start Ax from the Shell, simply enter its name at the command line, and the program will begin execution.  The following options are available from the Shell:

@{b}SETTINGS=@{i}file@{ui}@{ub}
This indicates the settings file to use for Ax's configuration.  If not specified, Ax will first look in its program directory, then ENV:/ENVARC: for a settings file.

@{b}PUBSCREEN=@{i}name@{ui}@{ub}
Use this ToolType when you want to open Ax on another program's existing public screen.  The name you supply is the name of the screen on which to open.

@{b}PORTNAME=@{i}name@{ui}@{ub}
This ToolType gives the name for Ax's ARexx port, which defaults to AX.  Note that you cannot change Ax's FTP ARexx port name, which defaults to AXFTP.

@{b}HELPFILE=@{i}file@{ui}@{ub}
This ToolType gives the location of Ax's online help file, Ax.guide.  It will override the location set in the settings file.

@{b}QUIET@{ub}
Using this option tells Ax not to present its initial copyright banner.
@endnode

@node MainWindow "Ax: The Main Window"
@toc Main
@{fg shine}The Main Window@{fg text}

This is the main window, where you wield Ax.

The top part of the window is copyright information.

Next down is a group marked 'Processes'.  The top section is a listbrowser display with a scroll bar in the window's border.  This shows what threads are running in Ax, such as Browse, Search, etc.  You can select any running thread with the mouse and then manipulate it with the five buttons contained in the 'Processes' group.  The list is subdivided into columns, showing (in order): the type of thread, its thread number, the thread's priority, flags, and the current status of the thread.  The following flags may be visible: 'S' for a thread that is suspended, 'H' if its window is hidden.

The five buttons in this group are:

     @{" Abort     " link ThreadAbort}
     @{" Suspend   " link ThreadSuspend}
     @{" Resume    " link ThreadResume}
     @{" Show      " link ThreadShow}
     @{" Hide      " link ThreadHide}

The bottom section of the main window contains several buttons for initiating certain threads in Ax that allow you to manipulate one or more databases.  They are as follows:

     @{" Browse    " link BrowseThread}
     @{" Search    " link SearchThread}
     @{" Parse     " link ParseThread}
     @{" Maint.    " link MaintThread}
     @{" FTP       " link FTPThread}
     @{" Configure " link ConfigThread}
     @{" Help      " link AxHelp}
     @{" Snapshot  " link Snapshot}

Note that at the beginning of the Browse, Search, Parse, and Maintenance threads, Ax will ask for a database directory on which to operate, if the 'Always use this?' option is off in the @{"Configuration" link ConfigThread} window.  Otherwise, the default database will be used.
@endnode

@node ThreadAbort "Ax: Killing a thread"
Pressing this button for a selected thread will send a KILL (Ctrl-C) signal to that thread.  Under normal circumstances, any thread should respond quickly, clean up and terminate.
@endnode

@node ThreadSuspend "Ax: Suspending a thread"
Pressing this button for a selected thread will send a SUSPEND signal to the thread.  Browse threads and threads in certain stages cannot be suspended.  Parse, maintenance, and search threads that are searching can be suspended.

This button has no effect if the thread is already suspended.
@endnode

@node ThreadResume "Ax: Resuming a thread"
Pressing this button for a selected thread will send it a RESUME signal.  If the thread is not suspended, this signal will be ignored.
@endnode

@node ThreadShow "Ax: Showing a thread's window"
Pressing this button for a selected thread will send it the SHOW signal.  This signal tells the thread to open its window (if it's hidden) and/or bring it to the front of the screen.
@endnode

@node ThreadHide "Ax: Hiding a thread's window"
Pressing this button for a selected thread will send it the HIDE signal.  If possible for the thread, its window will close and will remain hidden.  Some threads cannot have their windows hidden at all or during certain stages of execution.
@endnode

@node BrowseThread "Ax: Browse"
@toc Main
@{fg shine}Browse@{fg text}

This button initiates a thread that allows you to poke through a database at your leisure.

A window will pop up with three scrolling lists and some buttons.

The first list, marked 'Category' should contain the main breakdown of areas in the database.  Clicking on one of these causes Ax to update the 'Sub-category' list with the breakdown of areas in that category.

The next list, 'Sub-category' shows the areas for the chosen category you wish to look through.  Selecting an item from here will cause the third list to be updated with all the available files in that area.

The final list, 'Files' lists all the files in the chosen category and sub-category.  Clicking on any one of these files brings up a @{"File Details" link FileDetailsWindow} window, which shows you more information about the file.

The buttons at the bottom have the following functions:  'Mark' sets or resets the marked tag on the selected file(s).  'Download' submits the selected file(s) for download to the FTP download queue.  'Delete' sets the deletion tag for the selected file(s).  'Edit' brings up the @{"File Details" link FileDetailsWindow} window for a closer look at the selected file(s).

Click the close gadget in the window to terminate this thread.
@endnode

@node SearchThread "Ax: Search"
@toc Main
@{fg shine}Search@{fg text}

Clicking this button allows you to kick off a search through a database for something you're looking for.

The next window that pops up allows you to specify the @{"criteria" link SearchCriteria} of the search.

A progress window will appear during the search process.

This window contains a listbrowser showing the results of the search, updated as the search finds files.

Below it is a group of buttons.  From left to right, the buttons and their functions are:  'Mark' set/resets the marked tag on the selected file(s).  'Download' submits the selected file(s) to the FTP download queue.  'Save' brings up the @{"Save search results" link SaveSearchResults} window, allowing you to save the results to a file on disk.  'Delete' sets the deleted tag for the selected file(s).  'Edit' brings up the @{"File Details" link FileDetailsWindow} window.

Below this is a group labeled 'Progress', which contains a progress bar, and two buttons marked 'Stop' and 'Abort'.  The 'Stop' button stops the current search and allows you to look through the results.  The 'Abort' button terminates the search, closes the window and shuts down this search thread.

At the bottom of the window is a button marked 'Do another search'.  Pressing this button will terminate any search in progress (if necessary), close the window and return you to the @{"Search Criteria" link SearchCriteria} window, with all the current search settings still intact.

When the search is complete, the 'Progress' group will disappear, and you can look through the search results at your leisure.
@endnode

@node SearchCriteria "Ax: Search Criteria Window"
@toc SearchThread
@{fg shine}Search Criteria@{fg text}

This complex mess allows you to set the search parameters.  Here is a description of each of the criteria fields for searching.

@{b}Category
Sub-category@{ub}
These two string gadgets let you specify what areas of the database to search.  Note that the patterns used here are AmigaDOS patterns.  Please refer to 'Using the System Software', Chapter 7 (for 2.x users), or 'Amiga OS: DOS', Chapter 3 (for 3.x users), for an explanation of the use of pattern matching.

There is a popup chooser button on the far right of each of these gadgets.  The chooser for Category will reflect all main categories currently in the database.  The Subcategory chooser's selections change based on the contents of the Category gadget to reflect all possible sub-categories in the chosen categories.  (Sounds confusing, eh?)  Each selection from the appropriate chooser will @{i}add to@{ui} the contents of the corresponding gadget, building a valid AmigaDOS search pattern.  The only exception is the '#?' pattern.  Selecting this will @{i}replace@{ui} the entire contents of the respective gadget.

@{b}Marked entries
Deleted entries
Downloaded entries@{ub}
These three choosers allow you to specify whether Ax should ignore or use the corresponding flags set for each entry in determining whether to search it or not.  Seting 'Ignore' tells Ax to disregard that flag; 'Only' says that entries @{i}must have@{ui} this flag set; and 'Exclude' says that entries @{i}cannot@{ui} have this flag set.

@{b}Keys@{ub}
This group consists of a listbrowser, some buttons, a chooser, and a string gadget.

The listbrowser shows the keys currently being used.  It is split into two columns, the left showing the key type, the right showing the actual key text.  Select any key in the list to edit it.

The 'New' button creates a new key entry.  It will appear at the end of the list.

The 'Del' deletes the currently selected key entry in the listbrowser.

The 'Clear' button removes all key entries from the list.

The chooser next to the string gadget has three choices in it: AND, OR and NOT.  These determine how the key will be used in the search.  AND keys must be present in the entry being searched in order to be considered a match.  OR keys don't have to be present, but will register a match if they are.  NOT keys negate a match if the key is present, i.e., if the key text is in the entry, it will @{i}not@{ui} match.  It doesn't make sense to use an OR key if it's the only key specified.

The string gadget lets you type in the text to use for the currently selected key.

@{b}Size
Age@{ub}
These two groups let you check for file size and age in the search.  In the chooser, 'Ignore' says to disregard this criterium; the other chooser settings enable to corresponding integer gadget to the right and allow you specify the size/age in bytes/weeks.

@{b}Flags@{ub}
This last unmarked group has some miscellaneous flags that determine other things about the search.

'Search comments?' tells the search mechanism to match keywords in the optional comments field as well as the filename and description.

'Case sensitive?' tells the search to make lettercase an issue when matching keywords.

'Sort entries?' tells Ax to sort alphabetically the found entries in the display window.

'Save last search?' keeps the last search results in the display list.  This gadget is only enabled if a search was previously done in this thread, and you've chosen to come back to the Search Criteria window by clicking 'Do another search'.

@{b}Search
Cancel@{ub}
These two buttons either activate or cancel the search, respectively.
@endnode

@node MaintThread "Ax: Maintenance"
@toc Main
@{fg shine}Maintenance@{fg text}

@{b}NOTE@{ub}  @{i}This process makes placement and content changes to the database.  It is advised that it not be used while other operations are being performed on the same database.@{ui}

This thread first opens a window asking what types of maintenance to perform on the requested database.

@{b}Categories
Sub-categories@{ub}
These two string gadgets allow you to enter an AmigaDOS pattern of categories and subcategories you would like deleted from the database.  One or both of these gadgets must contain something for the deletion to be activated.  An empty gadgets defaults to '#?' if the deletion is activated.  That is, if you enter 'misc' in Sub-categories, but nothing in Categories, then Ax will attempt to delete ALL entries in any sub-category called 'misc' in ANY category.  See your AmigaDOS manual for valid patterns.

@{b}Age@{ub}
This group handles deleting entries according to age.  The chooser lets you select how this is handled.  'Ignore' means this option is skipped.  'Older than', 'Exactly' and 'Younger than' tell Ax to delete entries if they fall into the criteria specified, using the value in the integer gadget to the right.

@{b}Tags@{ub}
These tags determine how entries are handled based on any tags they may have set.  'Ignore' means to leave the entry as is.  'Unmark' means to clear the appropriate tag and keep the entry.  'Delete' means to remove the entry from the database.

@{b}Time stamps@{ub}
Setting this option tells Ax to reset the timestamp on the entry.  This sets an internal modification date/time stamp in the entry and sets the entry's Age to 0.

@{b}Okay@{ub}
Press this button to start the maintenance process.

A @{"progress indicator" link Progress} will appear telling you what is occurring.  You may abort the process at any time.
@endnode

@node SaveSearchResults "Ax: Save search results"
@toc SearchThread
@{fg shine}Save search results@{fg text}

This window contains a few gadgets whereby you can save search results to a file on disk.

@{b}Filename@{ub}
This gadgets allows you to specify the filename of the file to create, which will contain the results.

@{b}Entry format@{ub}
This string gadgets contains text and %-style formatting codes that determine how the entry information will be saved.  Press the selection button at the far right to select from a list of available codes.

@{b}Save what?@{ub}
This radiobutton set lets you choose whether only selected entries or all entries on the search window will be saved.

@{b}Save@{ub}
Press this button to save the file.
@endnode

@node ParseThread "Ax: Parse"
@toc Main
@{fg shine}Parse@{fg text}

This is the first thing you will need to do to set up Ax (besides Configuring it).  This is also where you will add new entries from RECENT files to your database.

Initially, you'll be greeted with a window where you specify @{"pertinent information" link ParseInfo} for the parse operation.  Once you've done this, Ax will begin parsing the selected file.

A @{"progress indicator" link Progress} will appear that tells you the approximate completion percentage of the parse, and how it's processing the entries.  Press 'Abort' at any time to stop.

Ax will then begin parsing the INDEX/RECENT and creating/updating entries.  The current (28 Dec 96) Aminet INDEX file is almost 2-3MB in size, and on my lowly 7MHz Miggy, it takes about 2 hours to create the database, with no exclusions.  On my 33 MHz Miggy, it takes a little over an hour, excluding mods.  So be warned.

When all is done, Ax will let you know how many files were added, updated or skipped.
@endnode

@node ParseInfo "Ax: Parse Information"
@toc ParseThread
@{fg shine}Parse Information@{fg text}

This window is where you input the information Ax needs to parse INDEX/RECENT files.

@{b}Parse type@{ub}
The first gadget is a radiobutton that specifies the type of parse.  The only noticeable difference between an INDEX parse and a RECENT parse is the format of the text file.  INDEXes have an Age column, indicating the time the file has been on the Aminet.  RECENT files, like those received from the Aminet mailing lists, do not.  It's somewhat important to specify the right type of parse.  It is not critical, but specifying the wrong type will result in inaccurate ages and funky-looking descriptions.

@{b}Filename@{ub}
This string gadget lets you input the @{i}filename only@{ui} of the file to parse.

@{b}What should I do with duplicates?@{ub}
This chooser lets you pick how Ax should handle incoming entries.  'Update' means to check if the entry currently exists, and if so, update the information, i.e., age, description.  Your comments and any flags set will not be affected.  This is the default for parsing RECENTs.  'Discard' tells Ax to forget about the new entry and just keep the old.  'Add' does no checking for duplication, and is the fastest method for parsing.  It is the default setting for parsing INDEXes, and should be set when creating a new database.

@{b}CD@{ub}
This gadget allows you to specify the CD the entries are on.  This is handy when parsing the INDEX files of Aminet CDs.  This value will show up in the @{"File Details" link FileDetailsWindow} window, if appropriate.

@{b}Category parsing@{ub}
This group lets you specify limitations to the parse.

The 'Start' and 'End' gadgets let you specify a category name at which to start and end parsing, inclusive.  For example, if you put 'comm' in the Start and 'text' in End, then when Ax encounters an entry belonging to the category 'comm' it will start processing entries until it hits the last entry in 'text'.  On a normal Aminet INDEX, this would skip the first category, 'biz', and the last, 'util'.  Note that if a blank line is encountered, Start/End processing is reset and Ax will begin looking for the Start category again.  This is the facilitate the parsing of RECENT files, which are subdivided into days separated by a blank line.  Blank entries on these gadgets mean that type will not be processed, i.e., something in Start but nothing in End means it will being processing at the Start category but won't look for an End category.

The 'Include' gadget accepts and AmigaDOS pattern of categories (and subcategories) to @{i}include@{ui} in the parse.  A blank gadget is the same as '#?' (all categories).  Refer to your AmigaDOS manual for valid patterns.  This inclusion can be used in conjunction with Start/End processing.

@{b}Parse
Cancel@{ub}
These two buttons activate or cancel the parse process, respectively.
@endnode

@node FTPThread "Ax: FTP Control"
@toc Main
@{fg shine}FTP Control@{fg text}

This window is where Ax will communicate with external FTP clients to retrieved any files that you have in the queue.  The window is organized as follows:

@{b}Site@{ub}
This string gadget lets you specify which Aminet to use to retrieve the files.  It defaults to the Default Site from the @{"Configuration window" link ConfigThread}.

@{b}Base directory@{ub}
This string gadget holds the path specification to where the base directory of the Aminet is (on the site you specified above).  Category and sub-category names are relative to this path.  It defaults to the Default Base Directory from the @{"Configuration window" link ConfigThread}.

@{b}Download directory@{ub}
This string gadget holds the path specification of where you want files to be stored locally on your computer when they're downloaded from the Aminet.  It defaults to the Default Download Directory from the @{"Configuration window" link ConfigThread}.

@{b}Queue listing@{ub}
This listbrowser shows the files that are currently in the queue awaiting retrieval.  Files can be sent to this queue from nearly any process in Ax.

@{b}File information@{ub}
This group, which include the @{i}Name@{ui} and @{i}Path@{ui} displays and the @{b}Remove@{ub} button, tell you a little bit (but not much) about the selected file in the queue.  The @{i}Name@{ui} display shows the same name as in the queue.  The @{i}Path@{ui} display shows the path (Category/Sub-category) of the file.  Clicking the @{b}Remove@{ub} button will remove this file from the queue.  This action is irrevocable.

@{b}Retrieve@{ub}
Clicking this button tells Ax to begin retrieving the files.  This will kick off the selected ARexx/AmigaDOS script to begin retrieving the files.  In the case of the supplied ARexx scripts, they will act as an interface between Ax and your chosen FTP client.

@{b}Stop@{ub}
Currently, this button is not implemented.

@{b}Clear@{ub}
This button will clear the ENTIRE file queue.  Be careful, this action is irrevocable.

@{b}Status indicator@{ub}
This display shows the current status of the FTP process.  The supplied ARexx scripts will send messages back to Ax while they're executing, indicating what is currently happening.  These messages will be displayed in this gadget.

@{b}Snapshot@{ub}
Pressing this button will snapshot the FTP control window at the current size and position.
@endnode

@node Progress "Ax: Progress Indicator"
@{fg shine}Progress Indicator@{fg text}

This window is used by some of Ax's threads to let you know what's going on during the thread's execution.

@{b}Status bar@{ub}
This is where text will appear tells you what's happening.  In some cases, it also doubles as a fuelgauge type indicator, showing a percentage of completion.

@{b}Abort@{ub}
This button allows you to abort the current thread.  Actions taken prior to pressing abort are, in most cases, irrevocable.
@endnode

@node ConfigThread "Ax: Configure"
@toc Main
@{fg shine}Configure@{fg text}

This brings up a window in which you may configure certain things about Ax.  The window is subdivided into 5 areas, which you may access via the tabs at the top.

@{u}General@{uu}

@{b}Public screen@{ub}
Which public screen should Ax open on?

@{b}ARexx port@{ub}
The name Ax should use for its ARexx port.  Note that this only affects the main ARexx port.  Ax's FTP ARexx port is hardcoded with the name AXFTP.  This may change in the future, or it may not.

@{b}Help file@{ub}
The location of Ax's .guide file.  There never really seems to be a standard place for them, so specifying it here will let Ax know where to look.  If it can't be found, then context-sensitive online help will be deactivated.

@{b}Backfill pattern@{ub}
If you would like a pattern in Ax's windows, specify it here.

@{b}Show button text?@{ub}
Check this box if you want text to be show in Ax's image buttons.

@{b}Use MagicWB-style buttons?@{ub}
Check this box if you would like to use MagicWB-style imagery in the image buttons, instead of the other four-color images.

@{b}Beep on error?@{ub}
Check this box if you want Ax to beep when it displays an error requester.

@{u}Database@{uu}

@{b}INDEX directory@{ub}
Where do you normally keep your INDEX/RECENT files?  The picker button brings up an ASL requester that lets you choose a directory.

@{b}Database directory@{ub}
What is the default directory to keep the database?  There's also a picker button for this.

@{b}Always use this?@{ub}
If this item is checked, Ax will not ask every time you wish to do something to a database, but simply use the database specified in Database directory (above).

@{b}ASCII file save format@{ub}

@{b}Sort entries?@{ub}
Checking this box will cause entries to be sorted in the Browse window and default-enable sorting for searching.  This does not affect sorting of entries in the actual database, just results.

@{u}Parse@{uu}

@{b}Comment characters@{ub}
These are any possible characters that can be used to comment out a line
in the INDEX/RECENT file.  Anything after one of these characters is
ignored during parsing.

@{b}Start category@{ub}
@{b}Include categories@{ub}
@{b}End category@{ub}
See @{"Parse information" link ParseInfo} for details on what may be specified in these gadgets.

@{b}After INDEX is parsed,@{ub}
This chooser lets you decide what will happen to the INDEX/RECENT file after it's been parse.  'keep.' says to leave it where it is.  'ask.' says to ask you first whether it should delete it.  'delete.' says to just delete it.

@{u}Retrieval@{uu}

@{b}Open FTP window?@{ub}
Check this box if you would like the FTP thread started when Ax first starts.

@{b}Use internal FTP?@{ub}
(Not implemented.)  Checking this box will cause Ax to use it's own internal FTP capability instead of relying on an outside FTP client.

@{b}FTP script@{ub}
This group lets you specify the type and name of script to use for FTP file retrieval.  The chooser lets you pick the type of script to use, ARexx or AmigaDOS.  The string gadgets and picker let you pick the actual script to use.

@{b}Default site@{ub}
This is the site Ax will attempt to access, or tell the FTP client to connect to, to retrieve the files.

@{b}Default base directory@{ub}
This is the base directory Ax will CD into, or tell the FTP client to go to, when connected to the site.  Filename categories and subcategories are relative to this path.

@{b}Default download directory@{ub}
This is the directory on your machine where files will be put when they're retrieved.

@{b}Attempt immediate retrieval?@{ub}
Checking this will tell Ax to immediately try to retrieve files in the queue.  This happens both when the FTP thread is started and when a new file is added to the queue.

@{b}Remember queued entries?@{ub}
Checking this box will tell Ax to save the contents of the queue upon exit.  This way file that are not yet retrieved can be gotten at a later time.

@{u}Priority@{uu}
This entire section lets you set the priority of various parts of Ax.  Since the programs runs in multiple threads, you can set each TYPE of thread's priority.

Once you have set Ax up the way you like it, click on either Save or Use.

'Save' saves your settings in a file called 'Ax.prefs', so they will be remembered the next time you boot up your Amiga.

'Use' only keeps these settings for the current session of Ax.

'Cancel' disregards any changes you've made and keeps the old settings.
@endnode

@node AxHelp "Ax: Help"
@toc MainWindow
@{fg shine}Help@{fg text}

This button will attempt to start the AmigaGuide help file 'Ax.guide' (what you're reading right now actually).  The location of this file is settable in the @{"Configuration" link ConfigThread} window.
@endnode

@node Snapshot "Ax: Snapshot"
@toc MainWindow
Pressing the button tells Ax to remember the window position (and in most cases, size) of the window.  Most windows in Ax have this button.
@endnode

@node FileDetailsWindow "Ax: File Details Window"
@{fg shine}File Details Window@{fg text}

This window shows you information about the file entry in the database.  The following information is displayed:

'Name' gives the name of the file.  This field is editable.

'Size' tells you how big the file is Kilobytes, Megabytes, or Gigabytes (uh huh!).

'Location' gives you the relative path of the file in relation to the base directory of the Aminet.

'Description' tells you the short description of the file, as shown in the INDEX file.  This field is editable.

'Comments' is a field for your own use.  Put whatever notes you want about the file in question.  This field is optionally searchable.  This field is editable.

'Age' tells you how long the file has been on the Aminet.  Note that this number is an effective calculation using the current date and the age given in the INDEX file.  If your current date and/or INDEX date are incorrect, this calculated date will be incorrect as well.

Some fields may be changed by you.  Just click in that field's string gadgets and enter what you want.  When you close the window, the entry will be updated.  Note that there is no undo.

Currently, there are three flags in use by Ax.  These are 'Marked', 'Deleted' and 'Downloaded'.  These flags are shown a group box in the bottom right corner of the window.

'Marked' means you have explicitly placed a mark in this file for later use.

The 'Deleted' flag can also be explicitly placed by you, instructing Ax to later remove the file from the database (via maintenance).  Be careful.  As of yet, there's no way to recover deleted files or to manually enter them into the database.

The last flag, 'Downloaded', can be explicitly set by you, and is also set by the FTP thread.  It marks the file as having been downloaded from the Aminet.  This is useful if you want to search for files, but exclude ones you've already downloaded.

There is also a button at the bottom of the window.  The button is the 'Download' button.  Pressing this submits the file to the FTP download queue for later retrieval.
@endnode

@node ARexx "Ax: ARexx"
@toc Main
@{fg shine}ARexx@{fg text}

This section deals with Ax's ARexx ports.  There are two, and each accepts its own set of commands.

@{u}AX@{uu}

@{i}Quit@{ui}

     Syntax:  Quit
Description:  Tells Ax to shutdown.

@{i}Parse@{ui}

     Syntax:  Parse [DATABASE=@{i}database@{ui}] [INDEX|RECENT=@{i}index-file@{ui}] [DUPS=@{i}dup-type@{ui}] [CD=@{i}string@{ui}] [START=@{i}category@{ui}] [INCLUDE=@{i}pattern@{ui}] [END=@{i}category@{ui}]
Description:  Tells Ax to parse (without GUI) an INDEX/RECENT file.  DATABASE tells which database directory to use.  Valid values for @{i}dup-type@{ui} are:  UPDATE, ADD, and DISCARD (see @{"Parse information" link ParseInfo} for details).  CD is any string for the CD value.  See @{"Configure/Parse" link ConfigThread} for information on START, INCLUDE, and END.

@{i}Process@{ui}

     Syntax:  Process [BROWSE] [SEARCH] [PARSE] [MAINT[ENANCE]]
Description:  Starts an instance of the specified thread.

@{i}StartFTP@{ui}

     Syntax:  StartFTP
Description:  Tells Ax to initiate the FTP thread, if it's not going.

@{i}ErrorReq@{ui}

     Syntax:  ErrorReq @{i}text@{ui}
Description:  Displays a requester with the specified text.

@{u}AXFTP@{uu}

@{i}Quit@{ui}

     Syntax:  Quit
Description:  Tells the FTP thread to shutdown.

@{i}GetFilename@{ui}

     Syntax:  GetFilename [ABS[OLUTE]|REL[ATIVE]]
Description:  Gets the path and filename of the currently selected file in the queue.  ABSOLUTE returns the base directory prepended to the path.  RELATIVE returns only the category/subcategory prepended to the filename.

@{i}GetPath@{ui}

     Syntax:  GetPath [ABS[OLUTE]|REL[ATIVE]|CAT[EGORY]|SUB[CATEGORY]]
Description:  Gets the path of the currently selected file in the queue.  ABSOLUTE gets the entire path, including base directory.  RELATIVE gets only the category/subcategory.  CATEGORY and SUBCATEGORY get only the respective part of the path.

@{i}Site@{ui}

     Syntax:  Site [@{i}site@{ui}]
Description:  Sets (or returns) the current site to retrieve files.

@{i}BaseDir@{ui}

     Syntax:  BaseDir [@{i}dir@{ui}]
Description:  Sets (or returns) the base directory of files for the FTP retrieval site.

@{i}DownloadDir@{ui}

     Syntax:  DownloadDir [@{i}dir@{ui}]
Description:  Sets (or returns) the current local download directory for files.

@{i}ResetFilelist@{ui}

     Syntax:  ResetFilelist
Description:  Sets the current file to the top of the queue.

@{i}RemoveFile@{ui}

     Syntax:  RemoveFile
Description:  Removes the currently selected file from the queue.

@{i}NextFile@{ui}

     Syntax:  NextFile
Description:  Moves the current file indicator to the next file in the queue.

@{i}SetFile@{ui}

     Syntax:  SetFile [NOT]DOWNLOADED|[NOT]MARKED|[NOT]DELETED
Description:  Sets the specified flags in the database entry for currently selected file in the queue.  Returns error code 5 if the entry couldn't be updated.

@{i}Status@{ui}

     Syntax:  Status @{i}text@{ui}
Description:  Sets the status display in the FTP window to the specified text.

@{i}FlagQueueFile@{ui}

     Syntax:  FlagQueueFile
Description:  Sets a flag on the current FTP file.

@{i}ClearQueue@{ui}

     Syntax:  ClearQueue ALL|FLAGGED
Description:  Clears the FTP file queue.  ALL clears all the files.  FLAGGED clears only files that have been flagged by FlagQueueFile.

@endnode

@node UpdateDB "Ax: UpdateDB utility"
@toc Main
@{fg shine}UpdateDB@{fg text}

If you are upgrading Ax from version 0.2 or earlier, you need to use this utility on your existing database.  The database format changed between 0.2 and 1.0, so this program takes care of switching over, while preserving all your existing flags and such.  Ax 1.0 and beyond cannot recognize the old database format, so this MUST be done to use your database with this version of Ax.

The command line syntax for UpdateDB is:

     @{b}UpdateDB@{ub} @{i}database@{ui} [TO=@{i}dir@{ui}] [QUIET]

@{i}database@{ui} tells UpdateDB the directory in which your database is stored.  This argument is required.

The TO argument tells UpdateDB where you want to put the new database.  By default, UpdateDB will keep the database in the same directory, overwriting the old one.  If you're paranoid about this, use the TO option.

The QUIET argument tells UpdateDB to not say anything about what it's doing.  By default, UpdateDB will tell you each file as it's updated.

UpdateDB cannot be used from the Workbench.

@endnode

@node Misc "Ax: Miscellaneous"
@toc Main
@{fg shine}Miscellaneous@{fg text}

This chapter basically covers, well, miscellaneous things that usually can't be place anywhere else, plus just some tidbits of information.

@{fg shine}The Future@{fg text}

The following items are on my to-do list for future versions of Ax.  If you think of an item that is not in this list, please feel free to drop me an e-mail or postcard.

- XPK support (it's coming soon!).

- Manual entry of items into the database.

- INDEX comparison.

- Internal FTP client.

- Directory caching.

@{fg shine}Authenticity@{fg text}

If you want to be sure that the files in this archive are authentic, I have enclosed below my PGP public key.  All binaries and documentations are accompanied by a PGP signature file, which can be used to verify the authenticity of each file.

Note that this key has changed since release 0.2 of Ax.  The old key is no longer valid and should not be used!

-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: 2.6.2

mQBtAzFM4HgAAAEDAMrjdVJRvZT93v/e9lKPtEdNsnyFpC66+lJ3tcqy62dcbQKl
2kze/s3vpxDN8DBhs/WeoxPQFmMFekT8BdkxELznxLGPOil1ylPCaNQY2juwQfVP
AMYKGbTTzufh5uYGvQAFEbQnUGF1bCBBLiBTY2hpZmZlcmVyIDxnYW5kYWxmQGh1
Z2hlcy5uZXQ+
=gVLn
-----END PGP PUBLIC KEY BLOCK-----

@endnode

@node Caveats "Ax: Caveats"
@toc Main
@{fg shine}Caveats@{fg text}

Ax does not use any locking mechanism on databases, per se, to prevent changes caused by another thread.  The Amiga's shared and exclusive file locking mechanism is the only thing that prevents one thread from altering a file in use by another thread.  The database is stored broken into files by category and sub-category, so while one sub-category is being used or altered, it can be safely assumed that another thread will not do anything to it until the current thread is through.

It should be noted that threads do not maintain locks on sections of the database for the entire duration of their execution.  So, browsing a sub-category in one thread, then altering it in another maintenance thread at the same time, then making a change in the original browse thread may yeild unpredictable results.  The database management functions make some effort to prevent overwrites of this nature, but are not foolproof, so some care must be taken when executing multiple concurrent threads in Ax.
@endnode

@node History "Ax: Program history"
@toc Main
@{fg shine}History@{fg text}

@{b}1.02@{ub} 4 Oct 1997 - Incremental upgrade.

@{u}Bugs fixed@{uu}

- Fixed all windows with scrollers in their borders.  Seems ClassAct scrollers don't take too well to being placed in window borders.

@{u}Changes@{uu}

- Updated some information in the About windows.

- Incorporated fixed UpdateDB into this archive.

@{b}1.01a@{ub} 15 Mar 1997 - UpdateDB bug fix (separate release: 1.02a).

@{u}Bugs fixed@{uu}

- An array used for command line argument parsing would overflow during initialization.  Fixed.

@{b}1.01@{ub} 15 Mar 1997 - Incremental upgrade.

@{u}Bugs fixed@{uu}

- Turns out I left the entire FTP control window section in the documents blank.  Oops.  Fixed.

- The ASL requester in the configuration window had some flags set wrong, and wasn't responding to input.  Fixed.

- Fixed some bugs in the Installer script.

- If the About window was open when the program exited, it would be left open and abandoned.  Fixed.

- The file list's scroll bar in the Browse window would sometimes not update its position upon changing categories.  Fixed.

@{u}Changes@{uu}

- Changed the default database directory to "PROGDIR:Database".

- The Retrieval settings in the configuration window now has a gadget for FTP client path.  This way you can easily select where your FTP program is, instead of having to change the ARexx script.

@{b}1.0@{ub} 26 Feb 1997 - Public release.

@{u}Bugs fixed@{uu}

- It seems that the maintenance function never really worked all that well.  It's been totally rewritten from scratch.

- Parsing is now more intelligent about handling the file format of the INDEX/RECENT files.

@{u}Additions@{uu}

- The search mechanism now handles searching by flags, multiple keywords, AND, OR and NOT, age and scanning of the added Comments field.  And it's still pretty fast.

- An ARexx port.  (Two actually.)

- FTP support, via ARexx scripts (with a dedicated ARexx port) that allow file retrieval using most major Amiga FTP clients.

@{u}Changes@{uu}

- The most noticeable change is the interface itself.  Ax now uses the ClassAct interface, which I think is very slick and is very flexible.

- The second big thing is that the database format has changed.  The 'UpdateDB' utility is included to bring your old Ax 0.2 database into the present.

- Ax is now fully multi-threaded, so the main window has changed to accommodate this functionality.

- INDEX and RECENT files are no longer considered separate operations.  They've been merged into one, smarter, parsing function.

- Task priority is indiviually settable for each type of thread, as well as the main process and the ARexx process.

@{u}Deletions@{uu}

- Not really much deleted, except for the bugs. :)

@{b}0.2@{ub} 12 Mar 1996 - Second beta release.

@{u}Bugs fixed@{uu}

- The most notorious was a bug in the 'Merge RECENT' code that caused Ax to forget it was merging a RECENT file and just add entries with reckless abandon.  The bug:  an '=' (assign value) instead of an '==' (equality comparison).  ARGH!  It's fixed now.

- The Install script didn't install the library correctly.  Fixed.

- Ax's icon was a Project, not a Tool.  Easily fixed, but very annoying...

- Accidentally left some line-debugging information in the executable, which made it 50% bigger than it should be and a mite slower.  Removed.

@{u}Changes@{uu}

- Ax now asks if you want to delete the INDEX/RECENT file after it's done with it.

@{u}Additions@{uu}

- Priority setting in Configure.  Lets you specify the priority (range -20 to 20) at which Ax will run.

- 'Skip categories': allows you to specify categories to ignore during parsing.

- A switch that keeps Ax from asking which database you want to use for everything you do.  Handy if you only use one.

@{b}0.1@{ub}  25 Feb 1996 - First beta release.  Wheeee! :)

@endnode

@node Acks "Ax: Acknowledgements"
@toc Main
@{fg shine}Acknowledgements@{fg text}

I'd like to thank the following people:

My wife, Michelle, who has been a great help in the design of Ax.

My beta-testers (Chris J. Cote, Eberhard Hafermalz, Jari Karjalainen, Jarkko Vatjus-Anttila, Michael Griggs, Miroslaw Wyszkowski, Rasmus Maagaard, Sammy Dirksz, Steve Boswell, Steve Lee, Volker Schleifstein), who have been encouraging, and given me lots of great ideas to use (some of which still need to be implemented :), and for taking the time to test the program.  Thanks, guys.

Christopher Aldi, for help with ClassAct.

Steve Provencher, for some awesome computer games (Warcraft, Quake) on his home network, even though they're not Amigas. :)

Andy Toth, for discussion and support.

Robin Holmes, for holding high the Amiga banner at work!  LONG LIVE THE AMIGA!

Quikpak, Phase 5, PIOS, Eagle, Softwood, and all the other companies that are still sticking by the Amiga.  It's not over yet.
@endnode

@node nothing "Ax: nothing"
@{fg shine}Nothing!@{fg text}

What'd you think a button marked 'nothing' was going to do???
@endnode