                     =====================================
                     ===== HELP manual for SiteMatch =====
                     =====  Dave Edwards  1999-2004 =====
                     ==== Developed by Richard Porter ====
                     ===== Version 2.47  August 2020 =====
                     =====================================

What is SiteMatch?
------------------

SiteMatch is a utility which makes maintenance of your web site easier by
keeping track of a local copy of your web site held on your hard drive. It
detects any additions, changes and deletions to objects (files and directories)
on your local sites and enables you to upload those changes to your web server.

After the changes have been uploaded, you can save the state of the local site
ready for the next changes. It keeps keep your local website and the remote
sites synchronised with the minimum amount of effort and FTP traffic.

Note that SiteMatch does not scan the remote web site - it keeps track of what
has changed by storing a copy of the site information inside the application
directory on your hard drive.

SiteMatch can create a script for use of sFTP (version 0.46), FTPc (version
1.23 or later) or psftp to update your site, which can be passed to your FTP
client immediately or at a later time. It can also use file sharing, LanMan98,
maintain a copy on your local filing system or copy all the new and changed
files to a new directory which can, for example, be on a memory card or USB
flash drive.

As well as updating web sites, SiteMatch can be used to create incremental
backups of a particular directory and upload them to a server or save them on
removable media. It can also provide a listing of your site as a text file.

Licence details and Disclaimer
------------------------------

This program is freeware. It may be distributed provided it is unaltered in
any way and no charge is made. However it would be better to pass on the web
page URL so that new users can get the latest version.

This software is supplied 'as is' neither I nor Dave Edwards will be held
responsible for any loss financial or otherwise through the use of this
program. Use it at your own risk. If you encounter any problems or bugs
please let me know and they will be fixed.
                                                             Richard Porter
Overview
--------

The first thing you have to do is to tell SiteMatch about the sites you wish
it to monitor and upload. It needs to know the root directory on your hard
drive and a name. If you want SiteMatch to upload your site you need to enter
the FTP address, login details and remote directory.

After adding a new site you can click the Compare button which will cause
SiteMatch to carry out a recursive scan of the local site and create a list
of all the files and subdirectories along with the file type and the date
and time they were last modified. The first time you do this all the objects
will show up as "new".

If you wish to upload the site in its entirety you can click the Upload
button at this point, or you can click Reset which will create a file
listing the current state of all the objects on the site. This file is used
next time round to detect what changes have been made.

Next time you click on Compare, SiteMatch will tell you what objects have
been created, deleted, modified or left unchanged since you last did a Reset.
Optionally you can save a list list all the objects on the site for any of
these categories (new, modified, unchanged and deleted).

Note that SiteMatch does not alter your local site in any way. Also be
aware that it doesn't read any information back from your web server so
it won't know about any changes that you make by other means.

Because of the amount of memory required by SiteMatch to run, you can
configure the maximum number of sites and the maximum size of any one
site that it can handle by setting the values of max_files and max|_sites
in the config file. As supplied the values are 1,000 and 20 respectively.
If the configured site size is exceeded the program will terminate with an
error message and you will need to increase the limit before continuing.
You may also need to increase the WimpSlot size.

As mentioned above, SiteMatch detects which objects are unchanged or have
been modified, added or deleted since the last reset. You can choose which
of these four categories you wish to display in the main window for further
inspection - or none if you so desire.

Regardless of which files you choose to display, SiteMatch will compare the
whole site, and also display the number of files found in each category in
the boxes next to the selection tick boxes.

You can play about with SiteMatch locally without doing any harm, but it is
important that once you start to use SiteMatch to maintain your remote site
you should continue to use it. If you start to upload files manually then
SiteMatch will get out of sync with your remote site.

Although SiteMatch has been designed specifically for updating web sites,
it could be used as a backup application using FTP or file sharing to a
remote server, but it will not preserve earlier versions of files unless
you move or rename them yourself. However if you use the facility to save
files locally you can rename the target directory to contain the date if
you wish to do so.

Installation
------------

If you have an earlier version of SiteMatch you should get all your sites
up-to-date vefore you upgrade. You would be well advised to make a backup
copy of your existing version.

Drag SiteMatch application from the archive into a suitable directory on
your hard disc. The Internet directory would be a good choice!

Please read the ReadMe file in the download archive for more imformation
on upgrading from earlier versions.

You may need to edit the max_files and max_sites values in the config file
if the defaults are inappropriate. You can do this via the Config...
option on the icon bar menu before adding or comparing any sites that
might exceed the supplied values.

You may also need to alter the WimpSlot value in the WimpSlot file. You
can also do this using the Config... option as long as the application
loads in the first place.

To run SiteMatch double click on the application or run it from a suitable
launcher such as !MenuBar from APDL. This will add an icon to the icon bar
and open the main window.

Interactive Help
----------------

SiteMatch can provide interactive help text for icons and menu options.
This is displayed when you are running an application like !Help (in Apps).

If you do not require interactive help you can enable it by changing line
2 of the !RunImage file from
LIBRARY "<SiteMatch$Dir>.HelpLib"
to
LIBRARY "<SiteMatch$Dir>.NoHelpLib"

This will save about 10k bytes of runtime memory requirement.


The Icon Bar Icon
-----------------

If the main window is closed you can open it again in the same state by
clicking Select or Adjust on the icon.

- Icon Bar Menu
  -------------

-- Info
   ----

This displays the current version number and other information about the
program. You can click on the "Web" button to open the software download
page in order to check on the latest updates.

-- Choices...
   ----------

This opens the Choices window which is described below.

-- Config...
   ---------

The Sitematch Configuration window allows you to view and change the maximum
number of sites and the maximum number of objects per site that SiteMatch can
handle. You can also alter the WimpSlot size for the task. The changes do not
take effect until the next time you run SiteMatch.

You may not change the maximum number of sites to a value less than the number
of sites currently configured.

The WimpSlot value may be suffixed by "k" or "M" for kilobytes or megabytes,
but will be displayed in kilobytes and should be a multiple of 4k. Decimal
fractions are not allowed.

After saving the changes SiteMatch will ask you whether you wish to quit now.
Click OK to quit and re-run the task with the new configuration, or click
Cancel to continue. If you click Cancel the new configuration will take effect
next time SiteMatch is run.

Use this facility with care. For safety you should make a backup copy of the
<SiteMatch$Dir>.!Run file or keep the download archive in case anything goes
wrong. You should make any changes necessary before adding a new site or
doing a Compare on any site that would exceed the existing limits.

A warning message is output if the WimpSlot size may be too low for the
task to run at all. You should click Cancel to enter a higher figure or
OK and hope for the best. If the program crashes immediately you will need to
edit the WimpSlot file yourself.

-- Help
   ----

The Help option opens this file in your chosen editor.

-- Quit
   ----

This option terminates the program.

Choices Window
--------------

- Display
  -------

The tickboxes in this section set the default values for the display flags.
The flags determine which categories of objects are displayed in the main
window and are included in a text file. The display of excluded objects can
be overridden on the Edit site window.

This Unix tickbox sets the default pathname display format for the main window
and saved text files. If it is ticked the directory delimiter is a slash and
the full stop can be used in filenames, otherwise the normal RISC OS format is
used. The format can be toggled as required on the main menu or by using a
keyboard shortcut (see below), and for text files on the Save text window.

- Save text
  ---------

This section sets the default values used when saving a text file. They can be
overridden by the Save text window.

The header, if included, contains the site name, local path and the date and
time of the last update.

Tab, Comma and Return select the separator used between the items shown for
each object. Each object starts on a new line.

Hex and Text determine how the file type is displayed: either as a three
digit hexadecimal number or as an ASCII name if available.

- Auto compare
  ------------

These tickboxes determine whether the local site is automatically scanned and
compared with its previous state when the site is selected, before it is
uploaded and after it has been reset. In the last two cases clicking Adjust
reverses the action of the auto compare flag.

- Suppress reset warning
  ----------------------

If this tickbox is unticked a warning and confirmation box will be displayed
when you perform a Reset. Tick the box to suppress this warning.

- Exclude dir excludes contents
  -----------------------------

If this tickbox is ticked then if you toggle the exclude status for a
directory, the same resulting state will be applied to all the new, changed
and deleted objects inside that directory. Also if you 'include' an unchanged
directory all unchanged objects within that directory will be included. You
can change this option as required and close the "Choices..." window without
saving the choices.

- Save, Cancel
  ------------

Save saves the choices are saved to the Choices:SiteMatch directory in the
!Boot sequence. If this directory does not exist it will be created.

If you click on Cancel the choices are not saved but the icon states will be
observed. Closing the window has the same effect.

Main Window
-----------

- Select Site
  -----------

When you first run the program or select a new site you will see the message
"Site not compared. 'Upload' will Compare first.". Selecting a site merely
gets the site details ready for further operations.

After selecting a site you will see the date and time of the last Reset (or
when the site was added if no Reset has been performed) and the full pathname
of the local directory. When the program is run you will see the first site
in the list, or "(none)" if no sites have been added.

You can double-click Select on the pathname to open the site root directory,
or Adjust to open its parent directory.

- Next/Scan
  ---------

Clicking Select on "Next/Scan" will select the next site in the site list,
looping round from the last to the first site.

Clicking Adjust on "Next/Scan" will compare all the sites in turn, starting
with the next site in the list, until a site with changes on it is found or
all sites have been scanned.

This icon is disabled if there are fewer than two sites.

- Compare
  -------

Clicking on "Compare" will scan your local site and produce a list of new,
modified, deleted and unchanged objects since your last Reset (see below),
depending on which display flags are set. By default the unchanged objects
are not listed.

If no objects are selected for the display categories you have enabled -
if, for example, your site is fully up to date - you will see a message
"No local files have been selected.". This message is preceded by a
green tick icon if no changes have been found, or by an orange cross icon
if changes have been found but are not shown because of the display flags.

If the root directory for the local site is empty you will see a red "E"
icon and the message "The directory is empty.".

Pressing Escape during a compare will terminate the compare and return the
site to the uncompared state. You'll see the message "Comparison terminated"
in place of the normal "Site not compared..." message.

You can continue to make as many changes to the local site as you wish and
every time that you click on Compare, a new comparison will be made, based 
always on the last time that you did a Reset.

You can double click Select on any object other than a deleted object to run
it in any application that will accept it, or double-click Adjust to open
the enclosing directory.

The icon is disabled if no sites have been added.

- Upload
  ------

This function prepares an FTP script to delete any objects marked as deleted
and upload all new and modified objects to the remote site, regardless of
which display flags are enabled.

The reason for doing the deletes first is that if you rename an object by only
changing the case of one or more letters SiteMatch will note a deletion and a
new object (and in the case of a directory for all its contents). If the server
is not case sensitive then the old object must be deleted before the new one is
uploaded. Also if you are close to your web space limit, deleting objects first
will make room for the new ones. Deletes are done in reverse order so that
the contents of directories are deleted before the directories themselves.

This is not the best strategy for maintaining the integrity of the site
during an upload, so you may wish to carry out your amendments in stages:

1. Create any new objects that you require.
2. Modify existing pages to link in new objects and unlink obsolete ones.
3. Finally, delete the obsolete objects.

You would execute a Compare, Upload and Reset after each stage.

In the following cases a fresh scan of the site will be executed before the
upload is done (note that this will clear any excludes other than permanent
excludes):

a) the site has been reset or or has not yet been compared;
b) there are no changes to upload;
c) you click Select and have set auto-compare for upload in Choices...;
d) you click Adjust and have not set auto-compare for upload in Choices...

In all other case any changes you have made since the last Compare will not be
noticed until you do another Compare. The changes will not be forgotten by
doing a Reset.

You need to watch the FTP window or check the log to determine the success
of the upload. SiteMatch does not read back the results from the FTP client.

- Reset
  -----

This function writes out a file to the Sites directory within the application
containing a listing of all the objects in the local site as seen at the last
Compare. Any subsequent changes will not be recorded. The files are named
as the number of the site within the sites list, starting at 1.

Before a site file is written the existing file is renamed as a backup file
be appending the letters "bu" to the filename (e.g. file "1" is renamed to
"1bu"). Any previous backup file is deleted. This will enable you to recover
should you accidentally perform an unintended Reset.

Optionally, a dialogue box will pop up asking you to confirm that you wish
to proceed with the Reset. This can be disabled in the icon bar Choices...
window.

If you click Select on the Reset button and have set auto-compare for Reset
SiteMatch will rescan the local site and perform a new compare after doing
the Reset. This will show any changes made since the last Compare and
any objects which were excluded. If no changes have been made you will see
the message "No local files match the display criteria".

If you click Select on the button and have not set auto-compare then SiteMatch
will perform a new compare without rescanning the local site. The result will
be similar to that described above but no new changes will be picked up.

If you click Adjust on the button this reverses the effect of the auto compare
flag.

The icon is disabled if you have not done a Compare on the currently selected
site, or if no sites have been added.

- Display flags
  -------------

The display that you get will depend on which of the five display categories
you have enabled: New, Deleted, Modified, Unchanged and Excluded. You will see
the total number of objects for each of these categories whether you select
them for display or not.

Note that an excluded object is also counted in its normal categories, and
is only displayed if both the Excluded display flag and the display flag for
the object's normal category are ticked.

The default display settings are Unchanged off and the rest on.

The display flags do control what is included when you create a listing
of the local site using the Save option on the menu (see below). They do
not affect what is uploaded.

If you click Select on a display flag the main window is refreshed accordingly.
If you click Adjust on a display flag the window is not changed.
In the case of Excluded clicking either button refreshes the main window.

- Main Menu Options
  -----------------

-- Save text file
   --------------

This opens a save dialogue which will allow you to save a text file
listing the objects corresponding the the enabled display flags. You can
change the display flags for this purpose without doing a new Compare.

Optionally, a header including the site name, path name and date last reset
can be written to the file.

You can choose to have the file type as three hexadecimal digits or converted
to a text name where possible. If no textual name is available you will get
the hex code preceded by an ampersand.

You can choose to have RISC OS or Unix style pathnames. Unix style converts
directory delimiters to slashes and slashes in filenames to dots.

The file contains the pathname, file type, date and time stamp and comparison
result (New, Modified, Deleted or Unchanged) for each object, separated by a
tab, comma or return. A new line is also outout after each object.6

-- Save changed files
   ------------------

This opens a save dialogue which allows you to save new and changed files,
including the relevant directory structure, to a new location. Optionally
a list of deleted objects may also be produced. The facility is intended for
users who wish to transfer updated files on removable media such as USB
flash memory, diskettes or cartridge drives.

There is little point in using this option if the target site is mounted
on the same computer since the filer with the 'newer' option set will do
the same thing more easily (though without the 'exclude' facility). It
can usefully be used to create incremental backups of the source directory.

By default, the new root directory name is the same as the local site
directory name. Excluded objects will not be copied. New empty directories
will be created but existing directories will not be created unless they
contain at least one file or one new directory which needs to be copied.

If a list of deleted objects is required it will written to a file in the
same parent directory or device as the target root directory, and with the
same name suffixed by "_deleted".

-- Indented list
   -------------

This allows you to toggle between an indented (tabbed) display showing the
depth of each object within the directory structure, and a plain unindented
display. The option is ticked when the indented display style is selected.

When indented style is selected all directories are displayed regardless of
the display flags.

This function can also be achieved by pressing the Tab key when focus is
on the main window. The default is plain.

-- Exclude '<object name>'
   -----------------------

This option allows you to toggle the exclude status of an object. If an
object is excluded it will be ignored during a following Upload or Reset.
The object is marked with a red "X>" icon in the left margin when it is
excluded and the menu option is ticked if you click Menu on than object.

All the exclude flags are cleared following an Upload or Reset or Compare
except for those set as a result of exclude strings in the site profile
(which can be edited in the "Edit this site..." window).

If the object is a directory and if the "Exclude dir excludes contents"
option is set in Choices... then if you exclude or unexclude a directory
the action affects all new, modified and deleted objects inside that
directory.

The option is disabled unless you are pointing to a new, modified or
deleted object.

-- Exclude from here
   -----------------

This option excludes changed objects from the selected file to the end of
the site. This enables you to do a partial Reset if your connection goes
down during a large upload. Examine the FTP log to find out the last
successfully uploaded or deleted file.

Because the deletes are always done first when you do an upload, the
behaviour of this function is different depending on whether you have
the cursor on a deleted object or a new or modified object.

If the pointer is on a new or modified object then that object and all
subsequent new and modified objects are excluded.

If the pointer is on a deleted object you get a choose dialogue asking you
to confirm that you wish to exclude that object, all subsequent deleted
objects and all new and modified objects. Click OK to proceed, or Cancel.

The option is disabled unless you are pointing to a new, modified or
deleted object.

-- Include '<object name>'
   ---------------------

This option marks an unchanged file (not a directory) as modified, which
will force it to be included in a following Upload or Save. All forced
includes are lost if you do a compare or reset. You cannot toggle the include
status, but you can exclude an included object.

If the object is a directory and if the "Exclude dir excludes contents"
option is set in Choices... then if you include a directory all the unchanged
objects inside that directory are also included.

This option is disabled unless you are pointing to an unchanged file.

-- Include after
   -------------

This option marks all unchanged objects with a timestamp later than the
selected object (which can be a delete) to changed. There is no special
processing for directories. See the previous option for other details.

This is intended to get you out of trouble if things have gone wrong at
the server (e.g. you exceeded your disc quota and didn't realise) and you
want to upload all files changed after a certain point in time. Be aware
that deletes lost by doing a reset can't be repeated.

This option is disabled unless you are pointing to an object in the main
window.

-- FTP
   ---

This leads to a submenu which offers the following options:

Upload now    - creates an FTP script and submits it to the FTP client.
                If psftp is selected an obey file to run it is created.
Script only   - creates an FTP script but does not submit it,
Submit script - submits the last created script to the selected FTP client.
                The script does not need to be for the curently selected
                site but the correct client must be selected.
Edit script   - opens the script file in an editor so that you can view,
                amend and/or save it somewhere else.

The last three options are enabled for FTPc(s) and sFTP clients only.

-- Add new site...
   ---------------

Use this menu option on the main window to open a blank Edit site window.
You must at least give your site a name and enter the full path of the local
root directory. You can do the latter simply by dragging the directory onto
the down arrow icon.

If you wish to upload your site automatically you must enter the FTP host
address and login details. You can also enter the path to the root directory
where your html files are stored if the host address doesn't take you there
directly (typically 'public_html' on Apache servers). Do not enter "ftp://".

You can, if you wish, override the passive mode setting in FTPc by entering
either "-passive" or "-passive off" (not the quotes) in the flags field.
This is useful if you have some sites that require passive mode and others
that don't. For secure mode FTPc please select the "FTPcs" client option (see
below) rather than relying on the "-secure n" flag.

You can enter up to ten strings, separated by commas, in the "Exclude in
update" box. Objects in the local site for which the pathname contains any
of the strings entered in this box will be excluded from the upload or reset.
Do not put the strings in quotes.

You can set the 'hide excludes' default status to hide or show excluded items.
This status can be toggled using the "Excluded" display flag (see above).

The radio buttons on the right allow you to select the FTP client to be used.
The default client is FTPc. The FTPcs button selects secure mode in FTPc.

The client button labelled "FS" selects the File System or File Sharing option.
This enables a directory icon which you can drag to the destination location
which could be on your local computer, on your LAN or on a mass storage device
such as a memory card or USB flash drive. The destination may not be the same
as or inside the root directory of your site. By default the leaf name of the
destination will be that of the root directory.

You can also enter a 'chmod' value to set the access permissions for perl
scripts. This must be three octal digits and is normally "755". Leave the
files blank to disable this option. This applies to FTP clients only.

To save the site details click on the "Save" button. This does not scan the
local site but it creates a stub site file. When you do a Compare you will
see all the objects marked as "new". This enables you to upload the site in
its entirety or perform a Reset if the site already exists on the remote
server.

The maximum number of sites you can have is set by the max_sites value in
Choices:config file. The default is 20 sites.

The maximum number of objects in a site is set by max_files value in the
Choices:config file. The default is 1,000 objects.

If you get 'No Room' or 'Out of memory' errors you should increase the
WimpSlot value in the config file. See the Config... option on the icon bar
menu.

CAUTION: When you select Add new site... or select any site from the site
menu, you will lose any unsaved changes you may have set for the current
site (even if you reselect the same site). If you decide not to go ahead
with adding a new site you should use the Cancel button to restore the
current site in the uncompared state.


-- Edit this site...
   -----------------

This option opens the Edit site window for the currently selected site. You
can alter any of the details shown and click on Save to update the site list
file which contains the site profiles. You can also click on Set to use the
currently shown data without saving them to the site list file. Revert will
reset the data to the values previously saved in the site list.

Take care if you change the local root directory. If you do so other than
just to rename or move the directory you must do a Compare before uploading,
otherwise you might try to upload files which are no longer accessible.

The option is disabled if no sites have been added.

-- Remove this site
   ----------------

This option opens a choose dialogue asking you to confirm that you wish to
remove the currently selected site. If you click on OK all the details of
the site are deleted from SiteMatch. The site list is updated if there is
at least one site remaining, otherwise it is deleted.

The option is disabled if no sites have been added.

-- Site statistics
   ---------------

This option opens the site statistics window showing the total size, number
of directories and number of files both on disc and in the upload.

This option is disabled if you haven't done a Compare on the currently
selected site or if no sites have been added.

The statistics window is closed if you select another site or perform a
Reset or another Compare.

- Keyboard Shortcuts
  ------------------

Pressing Tab toggles the display between indented and plain format.

Pressing Slash (/) toggles the Unix style display option which swaps dots
and slashes in the path name (the directory delimiter becomes a slash).
Note that exclude strings are always matched against the RISC OS path.


Support
-------

Up-to-date versions of this software, and details of any issues currently under
investigation can be obtained from the following web site or by clicking the
web button on the info window of the program.

http://www.richardporter.me.uk/riscos/sitematch/

Please send any feedback to me, Richard Porter rich@richardporter.me.uk

Acknowledgements
----------------
Special thanks to:

Dave Edwards for dreaming the whole thing up in the first place, and producing
a well-structured program which made further development a pleasure.

Andrew Ayre who wrote the original  Dr.Wimp without which this program would 
probably not have been written.

The late Ray Favre for maintaining and regularly updating this invaluable 
programming aid. His support will be sorely missed.

Colin Granville author of FTPc for his assistance in getting SiteMatch to 
work with his excellent ftp client.

Martin Avison for the ArmSort module which has greatly simplified the program
logic. The ArmSort application can be found at www.avisoft.force9.co.uk

Tim Powys-Lybbe and Frank de Bruin for testing version 2 on Iyonix and
providing fixes and suggestions.

Theo Markettos for his port of the SSH (Secure Shell) software including psftp
and the CryptRandom module. See www.chiark.greenend.org.uk/~theom/riscos/crypto/

Bryan Hogan for providing and testing the changes needed to support psftp.

Martin Bazley for the WimpScrap change and multi-user testing (hopefully).

Steve Fryatt for suggesting and helping with the FTPc secure mode enhancement.

Also my grateful thanks to those who have emailed me or Dave with thanks and
suggestions, and those who have looked through the code and suggested bug
fixes and improvements.