@database "Ax.guide"
@master "Ax.guide"
@author "Paul A. Schifferer"
@(c) "Copyright © 1996 Gandalf's Middle-Earth Software Wizardry Labs"
@$VER: Ax.guide 0.3 (29.3.96)
@width 79

@node Main "Ax: Table of Contents"

                                     Ax
                                 Version 0.3

                        Written by Paul A. Schifferer

       Copyright © 1996 Gandalf's Middle-Earth Software Wizardry Labs
                             All rights reserved.


                   @{" Terms                            " link Terms}
                   @{" Disclaimer of Warranty           " link Disclaimer}
                   @{" Introduction                     " link Intro}
                   @{" System requirements              " link Required}
                   @{" Registration                     " link Registration}
                   @{" Undocumented features            " link Bugs}
                   @{" Beta-testers' note               " link Beta}
                   @{" Using Ax from the Workbench      " link UsingWB}
                   @{" Using Ax from the Shell          " link UsingShell}
                   @{" The Main Window                  " link MainWindow}
                   @{" Miscellaneous                    " link Misc}
                   @{" Program history                  " link History}
@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 conspic-
uosly 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:

- Operates in any display environment (supports any screen display available
  in the display database).

- Amiga User Interface Style Guide-compliant.

- 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.
@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.  It is designed to
take advantage of some features available in higher versions, if they are
available.  As yet, Ax does not have Locale support.

Ax requires the use of Olaf Barthel's gtlayout.library V24 or highter, which
is included with the program archive.

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

Given the current size of the Aminet INDEX, about 4-5MB 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 16,000, click in it,
change it to 16000, 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 16,000, then enter
@{b}
	stack 16000@{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 technically @{i}giftware@{ui}.  (I hate all the different -ware terms.)  I
don't believe or subscribe to the current shareware philosophy.  If I wanted
(read: demanded) money for my work, I would release it as a commercial
product.  I've written and released this program in this form because I
believe the Amiga is an awesome computer, and I want to lend my support to its
(hopefully) long and glorious life.  I want to make your use of the Amiga
productive, efficient, and most of all enjoyable.  All I want is a 'thank you'
or 'great job'.  (Of course, I don't object to receiving money :) (see below),
but I'm not going to get nasty about it, like some other authors.)

But enough blithering; here's the bottom line:  This program is NOT crippled
in any way, shape or form, thus no fee is required to make it fully
functional.  You have it in all its splendor and glory.  Use it, enjoy it.  If
you like it, send me a postcard, or a program you've written, or something to
say 'thanks'.

If you want to, you can send @{"me" link me} $5US, which will get you the next release sent
right to you.  The money's only to cover disk and mailer costs (and a teeny
profit :).  Another $5US will get you a nicely typeset, printed manual.
@endnode

@node me "Ax: My address(es)"
@toc Main
The address to which you can send me money, postcards, a spare Amiga, or any-
thing else is:

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

I can also be contacted via Internet at:

gandalf@hughes.net    <-- preferably

or

pschiff@pablo.elan.af.mil
@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 distribution as a beta version.  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 test-releases via Snail mail, FidoNet
or the most cost-effective means for me to get the program to you.
@endnode

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

I'd like to thank the following people:

@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 16,000 bytes to run.

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

PUBSCREEN=name     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.  This ToolType may
                   be specified in a project icon, and will be effective only
                   for that document.

QUIET              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 16,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:

PUBSCREEN name     Use this option 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.

QUIET              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.  There are several buttons in
this main window that allow you to manipulate the database.  They are as
follows:

	@{" Browse       " link BrowseDatabase}
	@{" Search       " link SearchDatabase}
	@{" Parse INDEX  " link ParseINDEX}
	@{" Merge RECENT " link MergeRECENT}
	@{" Maintenance  " link Maint}
	@{" Configure    " link ConfigAx}
	@{" Help         " link AxHelp}
	@{" About        " link AboutAx}
	@{" Quit         " link QuitAx}
@endnode

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

This button allows you to poke through the database at your leisure.  You
will be asked which database to use.

Then another window will pop up with three scrolling lists.  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 'Directory'
list with available directories in that category.

The next list, 'Directory' is the directory for the chosen category you
wish to look through.  Selecting a directory 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
directory.  Clicking on any one of these files brings up a the @{"File Details" link FileDetailsWindow}
window, which shows you more information about the file.

Click to close gadget in the window's title bar to return to the main
window.
@endnode

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

Clicking this button allows you to kick off a search through the database
for something you're looking for.  You will be first asked for a database
to search.

The next window that pops up allows you to specify the parameters of the
search.  The gadgets available are as follows:

@{b}Get marked entries?@{ub}
Checking this item tells Ax to collect only the previously marked entries
from the database.  The 'Keyword' and 'Case sensitive' will be ghosted in
that case.  If it's not checked, Ax will search according the Keyword (as
discussed below).

@{b}Keyword@{ub}
This is a word or phrase to search for in the database.  It will be applied
against the filename and short description.  Currently, it's an all-or-
@{"nothing" link nothing} key.  Ax doesn't yet support AND and OR type searching.

@{b}Case sensitive?@{ub}
Ax doesn't regard letter case normally during the search.  Checking this
box will cause it to match exactly according to letter case.

@{b}Category@{ub}
This is an AmigaDOS-style pattern of what categories to search through.  For
instance, '#?' searches all categories.  All AmigaDOS-style patterns are
supported.

@{b}Directory@{ub}
This is directory within the selected category to search.  AmigaDOS-style
patterns are supported here as well.

@{b}Sort entries@{ub}
Setting this checkbox tells Ax to sort alphabetically the results of the
search.  Otherwise, they will be presented in the order found.

@{b}Preserve previous search results?@{ub}
The results from previous searches (in the current Ax session only) are
remembered.  If you wish to add this search to those, keep this box checked.
Otherwise, the previous list will be erased.

A progress window will appear during the search process.  You may abort at
any time and view the search results so far compiled.

When the search is complete, if anything was found, a window will appear
that lists the results by filename, size and short description.  Clicking
on any one of these files brings up the @{"File Details" link FileDetailsWindow} window.
@endnode

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

This button lets you perform maintenance on your database.  This basically
entails pruning duplicated entries and/or deleting unwanted categories from
the database.

A window will appear that lets you choose what sort of maintenance to perform
on the database.

The first gadget, 'Delete categories', is a text gadget.  Enter the category
names, separated by spaces, that you wish to remove from the database.
Note that these are ENTIRE categories.  You cannot remove individual
directories.  If this gadget is blank, no categories will by removed.

The next gadget is a checkbox, marked 'Delete duplicates'.  Checking it will
tell Ax to search the database for duplicated entries with a particular
category and directory, and remove them.

Entries marked "DeleteTag" (see the @{"File Details window" link FileDetailsWindow}) will also
be removed.

Clicking 'Okay' will begin the maintenance operation.  Clicking 'Cancel'
will take you back to the main window.

When Ax is finished, it will tell you how many entries were removed from the
database.  If you wish to abort at any time, just press the "Abort" button
in the progress window.
@endnode

@node ParseINDEX "Ax: The Main Window/Parse INDEX"
@toc MainWindow
@{fg shine}Parse INDEX@{fg text}

This is the first thing you will need to do to set up Ax (besides
Configuring it).  It will first ask you for the INDEX file to use.  This
should be the INDEX file you get from the Aminet.

Next, you will be asked in which directory you wish to place the created
database.  Directory creation is enabled in the ASL requester, so you can
use that to create a new directory if you need to.  Make sure you place
a database in its own blank directory.  That is how Ax differentiates one
database from another.

Ax will then begin parsing the INDEX and creating entries.  The current
Aminet INDEX file is almost 2MB in size, and on my lowly 7MHz 68000 A2000,
it takes about 2 hours to create the database.  So be warned.  Ax doesn't
check for duplicates in order to keep parsing time to a minimum.

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

@node MergeRECENT "Ax: The Main Window/Merge RECENT"
@toc MainWindow
@{fg shine}Merge RECENT@{fg text}

Use this button to add new entries to an existing database.  The first thing
you need to do is specify the RECENT file to use.

Then you will be asked to which database to apply the RECENT file.

Finally, Ax will ask you what to do with duplicate entries.  You can choose
from the following things:

@{b}Update@{ub}
This will update the existing entry in the database with the new
information.

@{b}Discard@{ub}
This tells Ax to ignore the duplicated entry and keep the old one.

@{b}Add anyway@{ub}
This will tell Ax to add all entries, regardless of duplication, which
effectively turns off duplicate checking.  This can give a slight speed
increase.

Duplicates are only checked in their own category and directory, not
globally across the database.
@endnode

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

This brings up a window in which you may configure certain things about Ax.
The following items are in this window:

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

@{b}INDEX Location@{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 database?@{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}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}Skip categories@{ub}
In this gadget, you can specify particular categories that you wish to be
skipped during parsing operations, i.e., parsing the initial INDEX or adding
RECENTs to the database.  This can speed things up considerably.  You can
specify as many categories as can fit in this gadget.  They must be
separated by spaces.

@{b}Sort entries@{ub}
This setting will let you have Ax sort Search and Browse results
alphabetically.

@{b}Priority@{ub}
This allows you to set the priority of Ax.  This can be helpful if you want
to set it running in the background, since it can take a while to do things;
or set its priority high to hog all the CPU time and get the job done
quicker. :)  The current allowed range is -20 to 20.

@{b}Beep on error?@{ub}
Should Ax sound the bell and/or flash the display when an error occurs?

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' in both the ENV: and
ENVARC: directories, 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: The Main Window/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).  This file should be in the same
directory as Ax or in the logical directory HELP: in order to work properly.
@endnode

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

Pressing this button pops up a window or two giving you some information
about the program and @{"me" link me}.  How nice.
@endnode

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

I don't really think this button need explanation, but since you insist....

It quits the program.

Okay, are you happy now? :)
@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.
Information displayed is like so:

             Name (name of the file)
             Size (size in Kilobytes, Megabytes, or Gigabytes (uh huh!))
         Location (where to find the file)
Short description (the short description from the INDEX)
              Age (how many weeks (and years?) the file's been there
---------------------------------
            As of (when the entry was place into your database)
            Flags (described below)

Currently, there are two flags in use by Ax.  These are 'Marked' and
'DeleteTag'.  'Marked' means you have explicitly placed a mark in this file
for later use.  The only implementation for marking is for the search
engine.  (Other implementations may be used in the future.)

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

There are also some buttons at the bottom of the window:

@{b}Remove@{ub}
Set or unset the 'DeleteTag' flag for this file.  This action is immediate,
meaning the database entry will be changed when the button is pressed.

@{b}Mark@{ub}
Set or unset the 'Marked' flag for this file.  This action is also
immediate.

@{b}Close@{ub}
Stop looking at this file.
@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.

- Multiple keyword, AND and OR type searching.

- Manual entry/deletion of items into the database.

- ARexx support.

- File lists with automatic FTP retrieval of files from Aminet.

- INDEX comparison.

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


@endnode

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

0.3 29 Mar 1996 - Final beta release.

                 Bugs fixed:

                 - The 'Remove' button wasn't working in the file details
                   window.  Fixed.

                 - Ax wasn't displaying anything during a parse when it was
                   skipping files.  Fixed.

                 - The 'Abort' button would sometimes not abort a parse.
                   Fixed.

                 Additions:

                 - Ax can now sort Search and Browse results.  There is an
                   option in Configure now to turn it on, which is the
                   default.

                 Changes:

                 - The File Details window no longer displays the modification
                   date of the entry.  The creation date now reads 'As of',
                   which is the date the entry was either created or modified.
                   It also allows a more logical reference of the file's Age.

0.2 12 Mar 1996 - Second beta release.

                 Bugs fixed:

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

			  Changes:

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

			  Additions:

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

0.1  25 Feb 1996 - First beta release.  Wheeee! :)

@endnode

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

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