=============================================================================
AwkScan - Search Archive Magazine                                Version 1.06

Author G.C.Wraith, Front-end S.Fryatt                        14 December 2003
=============================================================================


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

  AwkScan is an application to search the Archive ArcScan magazine and disc
  index files.



Installing AwkScan
------------------

  AwkScan can be used on the Archive CD without any further installation.
  However, if your system uses RISC OS 3.6 or earlier, you may have to
  install the CallASWI module before searching will work.  If you get an
  error asking for the module when AwkScan is run, you will need to install
  CallASWI as described below.  It also requires the 32-bit Shared C Library
  to be present; this can be downloaded from
  http://www.iyonix.com/32bit/system.shtml with full installation
  instructions.

  If you wish to copy AwkScan to your hard disc or have obtained your copy
  from somewhere else, you will also need the ArcScan index files.  Copy the
  !AwkScan application to a suitable location (you may want to create a new
  directory called something like AwkScan for it to live in).  From the
  ArcScan directory of the Archive CD, copy the archive and ardiscs
  directories with their contents into the new directory with !AwkScan.  The
  installation is now complete and you can start the AwkScan application.

  It is also possible to make AwkScan read the indexes from another location
  (this is not necessary to run AwkScan).  To do this, Shift-double-click on
  !AwkScan and load the !Run file into a text editor.  Find the lines that
  read

    | These paths point to the magazine and disc data:
    | change the paths as appropriate.

    Set AwkScan$Mag <AwkScan$Dir>.^.Archive
    Set AwkScan$Discs <AwkScan$Dir>.^.ArDiscs

  and change the paths to the location of the relevant directories.

  Note that, on old versions of RISC OS with 256 character restrictions on
  system variables, AwkScan can have problems running from a directory with a
  long pathname.  The only solution (apart from upgrading to RISC OS 4) is to
  move it higher up the directory tree.



Installing CallASWI
-------------------

  On systems running RISC OS 3.6 and earlier, AwkScan needs the CallASWI
  module to be present before it can be run.  This is likely to be present
  already, as a lot of StrongARM compatible applications require the module,
  but if running AwkScan produces an error asking for CallASWI, it will need
  to be installed.

  The module is supplied in the directory with !AwkScan, in the CallASWI
  directory.  To install it, proceed as follows:

   1. Find your System directory.  On systems with the new !Boot application
      in the root directory of the hard disc, Shift-double-click on !Boot and
      open the Resources directory inside.  The !System directory should be
      in here.  On machines without the new !Boot, !System may be in the root
      directory of the hard disc.

      If you can not find it, press F12 and enter "Filer_OpenDir
      <System$Dir>.^".  Press Return twice to get back to the Desktop, and a
      directory containing !System should be open.

   2. Open !System with a Shift-double-click on it.

   3. If !System contains a directory named 310, open that and then open the
      directory inside it named Modules.  If there is no 310 directory, open
      the directory in !System called Modules.

   4. Copy the CallASWI module into the Modules directory that has been
      opened.

  CallASWI is now installed on your system and AwkScan should be able to be
  run.



Using AwkScan
-------------

  Double click on !AwkScan to install it on the iconbar.

  Click on the AwkScan icon bar icon to open the search window.  Enter a word
  or phrase to search for into the top field and click on 'Search'.  The
  ArcScan indexes will be searched and a scrolling window will open showing
  any matches that are found.

  A second word or phrase can be entered into the lower field.  Between the
  two is a pop-up menu which controls how the two pieces of text are used.
  'And' requires BOTH words or phrases to be found, 'Or' is satisfied if
  EITHER is found.

  The standard "*" and "#" wildcards can be used to stand for any zero or
  more characters and ONE character respectively.  For example, "Arch#ve"
  would match "Archive" or "Archave" but not "Archve" or "Architrave".
  However, "Arch*ve" would match all of the examples given, but not
  "Archived".  The use of wildcards can be affected by the settings in the
  choices window.

  The 'Case sensitive' switch tells AwkScan whether or not to take the case
  of letters into account when matching the pieces of text.

  The search window can be opened by clicking either Select or Adjust on the
  icon bar icon.  By default, unless it is changed in the choices window,
  opening the window with Select will leave the previous search set up while
  using Adjust will cause all the fields to be cleared.



Choices
-------

  Selecting 'Choices...' from the icon bar menu allows the way that AwkScan
  works to be changed.

  'Simple wildcards' controls the use of the "*" and "#" wildcards as
  described above.  If it is on, these work as described; if not, the wild
  cards are replaced by the more powerful (and complex) regular expressions
  as described below.

  'Select opens blank search' determines the way in which Select or Adjust
  work on the icon bar icon.  Toggling this option on and off reverses the
  actions of the two mouse buttons.

  The 'Child task memory' setting controls how much memory is used for
  searching the index.  The 640Kb default should not need changing, although
  it can be increased if necessary.



The Database
------------

  The ArcScan indexes used by AwkScan can be accessed from the 'Database'
  submenu of the icon bar menu.  To open the directories containing the
  indexes that AwkScan is using, choose 'Database->Open'.  If you update the
  indexes by dragging in new files (from the Archive CD, say), you should
  then choose 'Database->Update' to warn AwkScan that the database has been
  updated.



Search files
------------

  The database can also be searched using "search files".  These are text
  files that are dragged to the AwkScan icon.  The files describe what you
  are looking for and the results are displayed in a window as before.
  Search files are an ALTERNATIVE to the search window: using them is not a
  requirement! In fact, AwkScan will generate a search file for itself to use
  each time you start a search from the search window, although the user will
  never normally see this.

  Blank lines in search files are ignored by AwkScan.  A line of the form

    # case

  will tell AwkScan to distinguish upper and lower case for the purposes of
  searching.  The default is no case distinction.  Any other line starting
  with "#" will be ignored.  As for lines not starting with "#", AwkScan will
  produce those records in the database that match at least one of them.  So
  for example

    # Any supermarkets mentioned?
    Safeways
    Tesco
    Asda
    Waitrose

  should be self-explanatory.  This could also be written on one line as

    Safeways|Tesco|Asda|Waitrose

  To search for a record mentioning both Safeways and Tesco, use

    # Both mentioned
    Safeways && Tesco

  In fact, the non-comment nonblank lines in a search file should be a
  sequence of standard regular expressions, separated by the conjunction
  symbol "&&".  Blank spaces to either side of "&&"s are discounted.  To
  search for two consecutive ampersands use

    (&)(&)

  to avoid confusion with "&&".



Regular Expressions
-------------------

  In search files, the characters "\" "^" "$" "." "[" "]" "|" "(" ")" "*" "+"
  and "?" are known as metacharacters because they play a special role in
  describing regular expressions.

  A basic regular expression is one of:

  A non-metacharacter

    This matches itself.

  An escape sequence

    An escape sequence is any one of the following series of characters:

    * "\b" - backspace
    * "\f" - formfeed
    * "\n" - newline
    * "\r" - carriage return
    * "\t" - tab
    * "\c" - "c" any other, non-digit character - matches "c".
    * "\ddd" - "ddd" octal value giving ASCII code

    Escape sequences have to be used to denote metacharacters literally.

  ^

    "^" matches beginning of a record.

  $

    "$" matches end of a record.

  .

    "." matches any single character.

  A character class

    "[AZQ]" matches "A" or "Z" or "Q". "[A-Z]" matches any upper case letter.
    "[^0-9]" represents any non-digit character.

  Regular expressions can be combined.  For example:

  * "A|B" matches either "A" or "B".
  * "AB" matches an "A" followed by a "B".
  * "A*" matches zero or more "A"'s.
  * "A+" matches one or more "A"'s.
  * "A?" the empty string or an "A".
  * "(A)" matches the strings that match "A".

  Since items in a record in the Archive database are separated by carriage
  returns

    \r![LU]

  would produce all records having an item starting with "!L" or "!U".  To
  find a record with an item ending "ok?" use the pattern

    ok\?\r

  To match all records for, say, Issue 11, use the pattern "\r\\11." The
  pattern "\r\\11[ ]40" will match those records occurring in Issue 11 on
  page 40.



Version History
---------------


  1.00 (8 April 2002)
  -------------------

  * First release version


  1.01 (23 June 2002)
  -------------------

  * Corrected setting of "<AwkScan$ParamFile>" so that search files are no
    longer created in the same directory as !AwkScan.
  * Added support for CallASWI module in !Run file, so AwkScan will work
    correctly on all pre-RISC OS 3.7 systems.


  1.02 (24 September 2002)
  ------------------------

  * Release for Volume 15 CD


  1.05 (8 February 2003)
  ----------------------

  * 26/32-bit neutral Awk binaries used.
  * Documentation converted to ManTools format (StrongHelp/Text) for easy
    maintenance.


  1.06 (14 December 2003)
  -----------------------

  * Uses the 26/32-bit Mawk binary to resolve problem with missing volume
    numbers in reports.



Contacts
--------

  Please report bugs to gavin@wra1th.plus.com (for bugs in the search
  routines) or steve@stevefryatt.org.uk (for bugs in the desktop
  front-end).
