Introduction
************

Motivation
==========

When Amiga appeared first the only storing-device was the floppy with its 880k of space for datas: hard-drives, flopticals, CDs were unknown.

Nowadays the situation is very different: the most recent Amigas come equipped with data storage units bigger than the original double-density drive...  the powerful A3000 comes with a hard-disk (from 50Mb to 100Mb inside, also the little A600 have an internal controller for IDE hard-drives (from 20Mb to 80Mb!), for 'older' models like A500 and A2000 a great number of companies deliver different units, with different features and sizes... also the A1000 owners have hard drives now!

With the increasing of the storage space, a lot of untidy users have been losing their files in the maze of directories, assignments, and devices made by themselves!!

``Where is that document? Where the picture? I'm sure they were here!! I can't find them... HELP!''

CERCA is made to scan a unit/path given by the user looking for a file-name or for a pattern, which indicates the matches with the full path. Besides CERCA can display some information on file found, like name, size, protection flags, date and file type from a list of about 70 types (see Recognized file types), and it gives the opportunity to make operations on the indicated file simply by programming 4 user-gadgets.

     NOTE: CERCA is the imperative form of the Italian verb 'cercare', whose meaning is 'to search'.

Basics
======

CERCA is a 2.04-only utility that tries to take advantage of some important features of the new system software (like pattern matching).

You can't use it under 1.x Amigas!

I drew the interface making it as simple as possible, all the functions have a key short-cut and the program offers a quite flexible configurability.

CERCA is font sensitive: it uses the WorkBench font in whatever it makes.

The program can also be run from Shell (dropping some functions...:-( ).

Running
*******

Installation
============

You can install CERCA by double clicking on the icon Install. CERCA needs two files to run:

Cerca.config
     (not obligatory) that is the configuration file (I supply a file for example in the archive). It must be placed in the envarc: directory.

Cerca.guide
     (not obligatory) that is the AmigaGuide© format of this documentation (to view it press the help key). So, if you have the library, you must set the environment variable AmigaGuide/Path to search in the directory where Cerca.guide is placed. Open a shell and type SetEnv AmigaGuide/Path "S: Sys:My_Docs".

Besides, if you want, you can enable ALL the pattern matching routines (e.g.: *, *.??, etc.) with StarBurst, a program by W.G.J. Langeveld & Sebastiano Vigna that enables the * wildcard (you can find the program in the CERCA's archive).

From Workbench
==============

Couldn't be easier. Open the drawer where CERCA is placed in, double click on CERCA's icon and wait for the loading (Wow, which newness!!).

From CLI
========

You can run CERCA from CLI but in this manner you will lose some important features of the program. In fact the line command is

P=Pattern/A,D=Dir/A,F=Files/S,I=Dirs/S,B=Both/s,R=Root/S,X=Recursively/S

where:

P=Pattern/A
     is the search pattern specified by wildcards (obligatory);

D=Dir/A
     is the device/volume/assign where CERCA will search the file (obligatory);

F=Files/S
     is a switch to specify that you want to search only files;

I=Dirs/S
     is a switch to specify that you want to search only dirs;

B=Both/s
     is a switch to specify that you want to search both files and dirs;

          Note: Only one of the three switches above can be specified or you will get an error!.

R=Root/S
     is a switch to specify that you want to search only in the directory specified with Dir;

X=Recursively/S
     is a switch to specify that you want to search for the file in all the subdirectories of the one specified with Dir;

          Note: Only one of the two switches above can be specified or you will get an error!.

          If you don't specify any switch, CERCA uses the built-in configuration: Files Recursively.

     Examples:

     Cerca #? SYS:
          Search all the files in the SYS: directory and in all of its subdirectories;

     Cerca #?.info Ram: F R
          Search all the files with .info as suffix only in the Ram Disk directory;

     Cerca Amiga dh2:data F
          Search the file Amiga in dh2:data and in all of its subdirectories;

     Cerca Amiga dh2: F I X
          Cerca will generate an error because you can't specify F and I togheter.

Using Cerca
***********

The interface
=============

CERCA's interface presents three string fields, a list gadget with its scrollers and two banks of four buttons.

  * In the first field you can type the file to look for or the pattern to use.

  * The next one displays the device/path you want to look in.

  * The last one contains the name (with path) of a file to operate on, selected from the above list which presents all the found matches.

  * The first bank of buttons is that of CERCA actions:

     GO
          Start scanning the path indicated in Path gadget looking for File to search contents.

     STOP
          Abort the GO operation in any moment of the scan.

     INFO
          Give information about the file selected in the listview.

     SELECT
          Clicking on it a file requester will open. The path selected will be inserted in the Path gadget and used in searching.

The above four gadgets are customizable by the user: you can associate the program you want to each button (see Settings Menu, for more info).

CERCA has menus which reproduces every first bank action and permits you to configure the other four and to save/load the configuration file. CERCA's window is resizable, that means that if you drag the bottom-right border of it, it will resize on your favourite dimensions in any moment.

Mouse Usage
===========

Using CERCA with the mouse isn't hard at all. The only thing you must do with the keyboard is typing the file pattern, the other operations have their button or menu to be activated.

Keyboard Usage
==============

Every CERCA action can be accessed by keyboard: the key short-cuts for actions are indicated in the buttons themselves by an underlined letter or in the relative menu.

To activate the string fields press once the f key: the cursor will prompt in the File to search gadget, pressing Tab you will move to the next string-gadget, pressing Shift-Tab to the previous.

By pressing the help key you'll invoke AmigaGuide© with this document displayed in hypertext. (Cerca.guide must be in your envarc:AmigaGuide/Path description).

Menus
=====

Being an Amiga program, CERCA offers a couple of pulldown menus...

Project Menu
------------

Go
     Same as the GO button, will start the searching. (short-cut RAmiga-G)

Stop
     Same as the STOP button, will stop scanning the path. (short-cut RAmiga-S)

Info
     Same as the INFO button, will give information about the found file. (short-cut RAmiga-I)

Select
     Same as the SELECT button, will open a requester to indicate the path. (short-cut RAmiga-E)

About
     Some information on the author and on the program.

Quit
     Guess... (short-cut RAmiga-Q)

Settings Menu
-------------

Search mode
     By this mutual exclude submenu you can establish the searching mode of the program.

     Only files
          to specify that you want to search only files;

     Only dirs
          to specify that you want to search only dirs;

     Both
          to specify that you want to search both files and dirs;

               note: Only one of the three menu items above can be specified!

     Only root
          to specify that you want to search only in the directory specified in the Search path gadget;

     All recursively
          to specify that you want to search the file in all the subdirectories of the one specified in the Search path gadget;

               note: Only one of the two menu items above can be specified!

Configure #n...
     (Where n is a number from 1 to 4)

     Opens a window with three string-gadgets: the first (Command name) contains the text that will be displayed in one of the four custom buttons in the main window, the second is the program name to run, to which CERCA passes a file name selected from the list (for example if your command is c:Delete, the resulting command will be c:Delete FILE_SELECTED_IN_THE_LISTVIEW). The last one contains the parameters for the console window.

     Note: The parameters of a console window are

     CON:LeftEdge/TopEdge/Width/Height/Name/AUTO/CLOSE/WAIT/

     WINDOW 0XADDR/ SCREEN NAME, etc

     where the last five optional keywords means:

     AUTO
          don't open CON: window until/unless input or output occurs;

     CLOSE
          put a close gadget om the CON: window;

     WAIT
          hold off close until user clicks Close or types CTRL-\;

     WINDOW
          Use specified window (may be on a custom screen);

     SCREEN
          Open on specified public screen;

          The additional CON: keywords BACKDROP, NODRAG, NOBORDER, NOSIZE, SIMPLE, and SMART, allow control of other attributes of a CON: window.

     Example: "CON:0/0/640/256/My console/AUTO/CLOSE/WAIT".

     If the Run Asynch. gadget is checked you establish that your command will be run in asynchronous mode so you can quit CERCA even if your program is running and you can continue working with it! :-).

     If the Open Console gadget is checked you establish to open an I/O console (read above) for your application.

     The Select gadget helps you to find your program by a file requester and will place the command in the Function gadget. Click Ok to confirm your settings or Cancel to forget them. (short-cut RAmiga-N, with N from 1 to 4)

Open Settings...
     Will load a configuration previously saved with Save Settings or Save Settings As....

Save Settings
     Will save actual string-gadgets' and buttons' content, search mode configuration  and actual window's position and dimension in the file Cerca.config in the envarc: directory.

Save Settings As...
     Same as the above menu, but here you can select another name and dir for the configuration file.

Appendices
**********

Pattern matching under 2.0
==========================

The dos.library v37 (or greater) contains new functions to parse an argument string and to evaluate it. By default search patterns are ? # % ' , and  after installing StarBurst (or equivalent) you find added *. There are some operators which can be used to bind two or more patterns (a multi-pattern): they are ~ | ( ).

There are some examples:

Pattern
     Meaning

?
     Matches any single character

#<C>
     Matches the <C> item occurring zero or more times

%
     Like a null string (same as  giving a "" file name as parameter to a command)

#? or *
     Matches any string

'
     Remove the effect of the pattern character

Operator
     Logical Meaning

|
     or

( )
     and

~
     not

Examples:

Delete #?
     Will delete all the contents of the actual path

Delete #?.info
     Will delete any file ending with the string .info and starting with any combination of any lenght of characters

Delete ~(#?.info)
     Will delete any file which doesn't end with .info

Dir *.pic
     Displays all the files ending with .pic (same as #?.pic)

Dir (*.pic|*.iff)
     Displays all the files ending with .pic or .iff

CD Sheet'#
     If it exists, the system will assume it as actual directory Sheet#

Dir CG*
     Displays all the files starting with CG

Dir CG*fonts
     Displays all the files starting with CG and ending with fonts

For more information about the argument read the manual Using The System Software chapter AmigaDos References, (c) 1990/1991 by Commodore Amiga Inc.

Recognized file types
=====================

CERCA can recognize a lot of file types (listed below):

  * Workbench icon file

  * ASCII text file

  * 'C' source code file

  * 'C' header file

  * Assembly language source code file

  * Assembly language include file

  * Modula-2/Oberon source code file

  * ARexx script file

  * Basic source code

  * AmigaGuide© document file

  * TeX document file

  * Metafont font file

  * Generic font file

  * Packed TeX font file

  * TeX device independent output file

  * PasTeX font library file

  * Manx 3.x object code file

  * Manx 5.x object code file

  * Manx 3.x library file

  * Manx 5.x library file

  * AmigaDOS object code file

  * AmigaDOS object code library file

  * AmigaDOS executable file

  * System library file

  * System device file

  * AmigaDOS filing system handler file

  * AmigaDOS handler file

  * GIF image file

  * Degas image file

  * MacPaint image file

  * SuperPaint image file

  * Macintosh PICT image file

  * Sun raster image file

  * Postscript file

  * PCX image file

  * TIFF image file

  * Windows bitmap image file

  * JFIF image file

  * IFF-ILBM image file

  * IFF-ANIM animation file

  * IFF-8SVX sound file

  * IFF-SMUS score file

  * IFF-FTXT text file

  * IFF-PREF preferences file

  * IFF-TERM term configuration file

  * IFF file

  * AmigaVision flow file

  * Imploder data output file

  * PowerPacker data output file

  * LhPak self extracting archive

  * LhASFX self extracting archive

  * Arc archive file

  * ARJ archive file

  * Compress output file

  * CPIO archive file

  * Freeze output file

  * MacCompress archive file

  * Compact archive file

  * Diamond archive file

  * LhArc archive file

  * LHA archive file

  * Zoo archive file

  * PKZip archive file

  * Stuff It! archive file

  * Pack It! archive file

  * DMS disk archive file

  * Warp disk archive file

  * Zoom disk archive file

  * SPARC object code

  * SPARC executable

  * MS-DOS executable

  * Atari-ST/TT executable

  * Macintosh executable

I think they should be enough ;-) !!!

To Do
=====

Here are some plans for future expansion of CERCA. Comments and additions are welcome.

  * Becoming a commodity: resident, little, with a key pop-up.

  * Configurable list of most used patterns.

  * Possibility to iconify the program.

  * Multiple dir/volume search.

  * Localization.

  * Arexx port to communicate with other applications.

... to be continued ...

Known Bugs
==========

The actual version (37.75) was tested very hardly with Enforcer and Mungwall for a long time. If you find a bug, please contact me.

History
=======

  * CERCA V1.0 (37.69)  :  First release.

  * CERCA V1.1 (37.75)  :  Now, the configuration file is saved in envarc:Cerca.config instead of S:Cerca.config. Note that the old configuration file is still good.

     Fixed a bug when opens a window with small fonts (like topaz 8-9). Now works with all fonts.

     Fixed a bug when loads a configuration more 'large' then the actual selected. Now the window will modify their dimensions.

     Now AmigaGuide© is not necessary to run the program. However, if you have the library, you must now set the environment variable AmigaGuide/Path to search in the directory where Cerca.guide is placed. Open a shell and type SetEnv AmigaGuide/Path "S: Sys:My_Docs".

     Now the menus are compatible with the NewLookMenus of OS 3.0 (black pen on white background).

     Now Cerca's error messages appear on the workbench window.

Greetings
=========

Finally, I want to thank

  * Finardi Dario for suggestions, first & hard testing and part of the manual.

  * Barthel Olaf (the author of 'Term') for the base utility of the file type identification.

  * Vigna Sebastiano for suggestions and beta testing.

  * Puerari Monia for the revision of this English manual.

  * Reinhard Spisser for converting the documentation in TeXinfo format.

  * Di Giuseppe Fabrizio for the beautiful icon.

  * The beta testers: Attias Roberto, Gentile Giovanni, Lodi Fabrizio, Ruocco Sergio, Santagostino Carlo, Silvera Paolo, Zandonadi Marco.

The Documentation
=================

The documentation files for CERCA are given in four different formats:

Cerca.doc
     The documentation for CERCA in ASCII;

Cerca.guide
     The documentation for CERCA in AmigaGuide® hypertext format;

Cerca.dvi
     The documentation for CERCA in TeX's device-independent format;

Cerca.texinfo
     The documentation for CERCA in TeXinfo format; using makeinfo you can produce the .doc and .guide files.

Program and distribution notes
==============================

CERCA is © 1992 Carlo Todeschini and it's freely distributable as long as all of its files are included in their original form without additions, deletions, or modifications of any kind, and only a nominal fee is charged for its distribution.

CERCA is a DonationWare program. If you like and so use CERCA, make a donation to a public institution or foundation like Fight Against Cancer, WWF, Amnesty International, UNICEF etc...and write me to tell that you like my work.

This software is provided ``AS IS'' without warranty of any kind, either expressed or implied. By using CERCA, you accept either the whole risk or the quality and performance of the program.

How to reach the author
=======================

If you have some additional ideas and/or bug reports, feel free to send a letter (e-mail preferred) or to give me a call (you're advised: letters or e-mail costs less :-)).

You can reach me via

      Internet: todeschi@pippo.sm.dsi.unimi.it

          Mail: Carlo Todeschini
                via Martiri della Liberta' 25
                I-26030 Malagnino (CR)

         Phone: +39-(0)372-58171