       ************************************************************
       *               TEXTSEEK  v140  (11-Oct-2003)             *
       *                     by Miss H. Bazley                    *
       ************************************************************

MISSION OF THE PROGRAM:
-------------
To seek out specified words or phrases across multiple files of any type.


HARDWARE/SOFTWARE REQUIREMENTS
-------------
Any version of RISC OS from 31 up to RISC OS 5.   A copy of the DDEUtils
module and a text editor that supports 'throwback' (Zap and StrongED both
do  Edit doesn't).   68Kb of free memory plus enough extra to load the
largest file you plan to search... plus enough memory to run the text
editor to display the throwback and results!

Textseek is freeware - please do redistribute it to as many people as
possible, and alter or appropriate any part of it for your own use as you
see fit.   However, you may not redistribute altered versions against my
will.

HOW TO USE THE PROGRAM
-------------
Drag a directory to the iconbar icon, or click on the icon to open the main
window and drag a directory onto the search path icon.   All the files in
this directory will be searched.

Type one or more words into the 'Find text' writable icon.   Press RETURN or
click on the 'Search' icon.   The main window will now close and a small
progress window pop up.   Click on the 'Stop' icon to stop the search at any
point.

After some disc activity a throwback window should appear, displaying all
the occurrences of the phrase together with the name and line number of the
file in which they were found.   Clicking on a line in this window will open
the file in question at the relevant line.

Otherwise, you will get a beep and the message 'Nothing found'.


DETAILED GUIDE:
-------------
Textseek is a WIMP front-end to a fast machine-code search routine which I
wrote because I was so frustrated with FileFind.   It uses throwback to
display the context of search results, showing a whole line of text,
detokenises BASIC before searching it, and counts the lines properly in all
files whatever their line-ending type (ASCII 10, ASCII 13 or combinations
thereof) so that throwback actually takes you to the right place!   It
doesn't fall down when searching CD-ROMs either, or cause the throwback
handler to crash by passing it strings containing control characters....


THE MAIN WINDOW
-------------
The main window may be opened by clicking on the iconbar icon;  however if
you drag a file or directory to the iconbar the window will open
automatically with the search path already filled in.

The search path:
-------------
You may type a name into the 'Search path:' icon or drag an object there to
define the directory within which the program will search.   You need not
give a full pathname  you may specify a system variable such as
<Wimp$ScrapDir>, give a simple leafname such as Apps or leave this icon
blank altogether, in which case the default (Currently Selected) directory
will be searched.   If you give the name of a file rather than a directory,
only this file will be searched.

The menu icon to the right gives access to a history of the last ten search
paths used.   Click on a menu item to repeat an earlier search.

The text to find:
-------------
You must fill in the 'Find text:' icon with up to 79 characters for which to
search.   This is a literal search  only exact matches will be found
unless you use wildcards (see below).   For example, if you type 'pink
glove' with an extra space, this would not match 'pink glove' in a file.
Do not enclose text in single or double quotes unless you actually wish to
find quotation marks within the text!

The menu icon to the right gives access to a history of the last ten search
strings used.   Click on the menu to re-enter an old search string,
restoring the substring, wildcard and case options at the same time.


There is an option set by default (see below) to allow sequences
of characters in the middle of words to be a valid match.   If you
deselect this option matching will be restricted to whole words only.

By default the search is not case sensitive, but there is an option (see
below) to make case significant in search strings.

Search options
-----------

These are saved and restored along with the search text to which they
apply;  for example the wildcard option stored along with a search string
containing wildcards.

  'Case sensitive' simply forces the letters a-z to become A-Z both in the
  text to find and in the file being searched, allowing, for example
  'Exact' to match 'exact'. Accented characters are handled correctly, e.g.
  Textseek can equate  with  or  with .

  'Enable wildcards' controls whether the characters '?' and '*' are
  interpreted literally or treated as wildcards (see below)

  'Match whole words' controls whether a string occurring in the middle of a
  word in the text is considered to be a match or not. For example, does 'put'
  match 'output'?

Wildcards
------------
Textseek uses '?' for a single-character wildcard, which will match any one
character, and '*' as a multiple-character wildcard.

It will match zero or more characters, provided that the total length of the
string found does not exceed 80 characters.   For example, draw*s would not
only match draws and drawers but also the whole of the phrase
...drawling out around her drooping cigarette the words...

Portions of words ending or beginning in * are guaranteed to match even if
the 'Allow text to match middle of words' option is not set.   A judicious
combination of these two options can be useful.  For example, ing* would
then match ingot and ingredient without also listing the frequent
occurrences of verbs ending in 'ing'.


The File type selection:
-------------
The icon labelled 'in files of type' and 'Automatically exclude' in the
Choices window display, in hexadecimal, the list of up to 10
filetypes which you have currently selected to search (or exclude from your
search).   This feature allows you to speed up operation by only checking
those files which are likely to contain the data you are looking for.

Note that if you initially drag a *file* rather than a directory into
Textseek (see above) the program assumes that you know what you are doing
and searches it anyway, whatever filetype it may happen to be.    Also,
filetypes specified in the main window will always be searched, whatever the
settings in the Choices window - so you can override the 'exclude' list on a
temporary basis if required.

The Filetypes menu:
-------------
Click SELECT on the menu icon to the right of the frame in the main or
options window to bring up the Filetypes menu which allows you to enter
filetypes into the list or to delete them (by clicking on the entry a second
time). There are four options:

  'List common filetypes' leads to a menu (which may be customised  see
  below) allowing quick entry of a useful subset of filetypes to include or
  exclude.

  'List all filetypes' leads to a full list of all filetypes currently known
  by your computer, displaying sprites where these exist  this menu is
  constantly updated as new applications are 'seen by the Filer' and because
  of this there may be a slight delay before it opens.

  'Clear current selection' clears the entire list from the display icon.

  The final option is a writable menu entry into which you can type the
  name or hexadecimal value of any filetype in order to enter it into the
  list.   You can still supply hexadecimal values even if an application
  which runs that filetype has not yet been booted, but supplying an unknown
  name will generate a 'Bad file type' error.

'Selected filetypes' pop-up window:
-------------
This window pops up unexpectedly when you click on the (recessed) icon
displaying the filetype list itself.   It displays the list in a more
human-friendly format, showing the name and sprite, if possible, of all
filetypes currently selected.   If you click anywhere outside the icon, the
pop-up window will close again.

The 'Search' and 'Stop' icons:
-------------
Click on 'Search' or press RETURN to open the throwback window and start the
search.   (Use TAB or arrow keys to navigate between writable icons.)

The main window will close until the search has finished, and the progress
window (see below) will pop up.   Clicking on the 'Stop' button on this
window will allow you to stop the search.

If you ADJUST-click on the 'Search' icon, the main window will remain open
during the search;  however, you will not be able to start another search
until the progress window has closed again (either because the search has
finished, or because you aborted it by pressing 'Stop').


THE CHOICES WINDOW
-------------

Selecting 'Choices' from the menu will open the Choices window, allowing
you to examine and alter Textseek's default settings (see below). This
window allows you to control the options that will apply to the current
search, and to exclude certain file names/types from being checked at all (see
'File type selection' above). You may also save the current settings or
restore the last version saved to disc.

Press 'Save' to save the set-up in this window (and the list of
filetypes to search currently displayed in the main window) for the next
time you run the program.   Press 'Restore' to reload the saved defaults.
Press 'Accept' to use the currently-set options without saving them, or
'Cancel' to abandon all changes and close this window.


SEARCH OPTIONS
-------------
The state of these icons controls the behaviour of the program when
searching; the settings are read every time you press the 'Search' button.

There are five options:

 'Show hexadecimal values in filetypes menu' causes filetype numbers to be
 displayed alongside their names and sprites in the filetypes menu, e.g.
 "&DDC Archive".

  'Search subdirectories' controls whether the program searches recursively
  or not, that is whether it simply searches the files in the directory
  specified or whether it also checks the contents of any directories it may
  contain and of any directories they in turn may contain... and so on.
  This option is on by default.

      'Don't search inside applications' causes the program to stop recursing
      whenever it reaches a directory whose name begins with '!'.   You would
      normally want this option on  if you are searching for data in your
      PipeDream documents you don't want to waste time searching inside the
      !PipeDream application directory itself.   However, you may want to search
      Help files within applications or the contents of misleadingly-named
      archives.

      'Don't treat image files as directories'  many types of archive and some
      other files (StrongHelp files, Doom WADs and DOS partitions for example)
      are 'image files' which behave like directories when the parent
      application is running and appear to be files when it is not.   They often
      contain many very small objects which Textseek can waste a long time in
      checking through  on the other hand, many CD-ROMs have their entire
      contents in archives!

      This option allows you to choose whether to check inside image files or
      not.   By default it is off.

  Neither of these options is applicable if recursion is disabled and thus
  they are greyed-out when the latter option is not selected.

  'Throwback to BASIC program line numbers' only works with Zap's BASIC
  mode,  since StrongED abhors line numbers in BASIC.   Using this option,
  when data is found in a BASIC file the line numbers for that file in a Zap
  throwback window will reflect the 'logical' line number assigned to that
  statement by BASIC rather than the 'physical' line number, i.e. the offset
  from the start of the file.   For all other types of file  even within
  the same throwback window  physical line numbers will be used.

  The two text icons at the bottom of this window allow you to specify
  which filetypes or file/directory names to ignore during a search. For
  example, you could instruct Textseek to ignore all JPEG files and/or the
  contents of all directories named /svn (names are not case sensitive).  If
  more than one name is listed, they should be separated by commas (with no
  spaces in between), e.g. "/svn,Data,temp"
  The contents of these icons will be saved and read back along with the
  other settings.

THE PROGRESS WINDOW
------------

The progress window is displayed while a search is actually in progress.
It indicates which file the search has currently reached and allows you to
abort a search before it has finished.   The title bar of the window
displays the string currently being searched for, and the small icons to the
left indicate the current settings of the three most important search
options. If not greyed out, the 'w' icon indicates that the search string is
only allowed to match whole words, the '?' icon indicates that wildcards are
active and the 'c' icon indicates that the search is case-insensitive.


Click on the 'Faster' button to stop the file names being listed in this
window as they are searched.   The button will now read 'Slower'.   Clicking
it again will restore the display.

Click on the 'Stop' button to abort the current search.    (The program only
multi-tasks in between files;  you may have to wait a few seconds before it
responds if it is in the middle of scanning a large file of 500Kb+).

The window closes automatically when the search is over.


THE THROWBACK WINDOW
-------------
The throwback window is under the control of the text editor, not Textseek.
It will not close when you quit Textseek (or if it crashes mid-way through a
search!);  conversely, once you have closed it you cannot reopen it by
clicking on the Textseek icon.

Click (StrongED) or double-click (Zap) on a displayed line to open the
relevant file at that line;  SHIFT-click (StrongED) or ADJUST-click (Zap) to
remove a line from the throwback window.


CONTACTING THE AUTHOR:
-------------

I may be contacted by post as

  Miss H. Bazley
  144, Merton Hall Road
  Wimbledon
  London SW19 3PZ

or via e-mail at harriet@bazleyfamily.co.uk

DARK CORNERS
-------------
The pop-up window which shows the names of the currently selected filetypes
takes its icon data directly from the main menu of filetypes - which is only
updated when it is actually displayed.   Therefore, *if* you boot up an
application and then enter its filetype manually from the writable menu
entry, it won't appear in the pop-up window until after the icons in the
main filetypes menu have been recalculated, i.e. the next time this menu is
opened, despite the fact that the new sprites are now in the Wimp pool....
Can't be bothered to fix this.

Textseek can translate BASIC keywords into plain text for you.   This means
that you can search, for example, for all BASIC files within a directory
containing EVAL.

Pressing MENU over the 'Find text' and 'Search path:' icons will act to
bring up the relevant history menu, and over the recessed filetype icon
will display the pop-up filetypes window.

Files which are loaded as raw binary data (StrongED's !Dump mode and Zap's
Code mode) don't open at the right place using throwback even though the
'line count' is technically correct.    Not much I can do about this...

If Textseek detcts that the 'Ignore filenames' icon in the <Choices> window
is empty it will avoid running the filename checking procedures (with
associated case conversion, string manipulation overheads etc.) altogether.

The hourglass may appear briefly while scanning large files.   If you
encounter a very large file of 10 Megabytes or more, an error box will
appear checking whether you really wish to search that file (as it is almost
certainly a sound or graphics format).   This size limit can be changed
(permanently) by editing the value of the system variable "TextseekLimit" in
the !Textseek.!Boot file or (temporarily) by typing e.g.
*SetEval TextseekLimit 1024*1024*5
on the command line.

It should be noted that words are defined as 'ending' when any
non-alphabetic character is encountered, where 'alphabetic' is defined as
'falling within the range ASCII 65 (A) to ASCII 122 (z).   This simplistic
definition means that the characters [\]^_` (ASCII 91 to 96) are included in
the 'alphabetic' category  for example, 'see' in  'amendment [see page 10]'
would not be considered a match unless the 'Allow text to match middle of
words' option was set, any more than the 'see' in 'oversee'.

It should also be noted that the single wildcard character ? will match any
character, including 'non-alphabetic' characters, which can occasionally
lead to some surprising extra search results.

The search history menu is generated from a file held in Choices:Textseek (or
!Textseek.Resources).   The format is as follows:
3 search flags corresponding to the options displayed on the progress window,
   'w' - match whole words only
   '?' - use wildcards
   'c' - match is case-sensitive
followed by a tab character, followed by the search text.
Blank lines are ignored.


POSSIBLE FUTURE IMPROVEMENTS
-------------
     Allow you to use 'script' files specifying a list of directories/files
to search instead of just scanning a single directory and its
subdirectories.
     Use my own WIMP procedures to replace the massive overheads of Dr
Wimp.
     Implement regexp support.