WebChange for RISC OS

from Soft Rock Software

User Guide

The Main Functions

General overview

WebChange 2's main functions are accessible from the main window, some by making selections in the window, which are acted upon when the 'Process' button is clicked, and some are accessed by clicking <MENU> in that window, and choosing the 'Processes' submenu, which are acted upon immediately.

All of these functions, and others besides, are also available to the script language, which is dealt with in a later section.

In this section, the functions which are actioned when 'Process' is clicked are dealt with first, followed by the instant action functions and, finally, a mention of the statistics function.

The main window
The main window

[Main Contents]

Search and replace

First of all, a word of warning about the search and replace facility: it can, particularly if using wildcards, be very dangerous; it is all too easy to enter a search string which will wipe out large amounts of your HTML. For this reason, it is highly recommended that you always take backups of your site before using this feature.

There are four icons in the main window which deal with the search and replace facility; two writable icons, and two arrows.

In the first writable icon, labelled 'Replace:', you enter the text that is to be replaced.

If wildcards are enabled (see general choices), you can use an asterisk (*) to represent anything so, for example, 'Web*2' would find 'WebChange 2' or 'Web 2' or any other sequence which starts with 'Web' and ends with '2'.

Wildcards should not be entered as the first or last character of the 'Replace:' string.

If case sensitivity is disabled (see general choices), 'Web' would match 'WEB', 'Web' and 'web' along with any other permutations of upper and lower case letters.

In the second writable icon, labelled 'With:', you enter the replacement text (or you can leave this blank to delete any instances of the text in the first icon - a confirmation prompt will appear when you actually click 'Process').

Up to four matched wildcards matched can be inserted, by including *1 to *4 in the replacement text - *1 will insert whatever text was matched by the first * in the text to find, *2 will insert whatever was matched by the second, and so on. To include an actual asterisk (*) use **

The case (capitalisation) as entered will be used when replacing text - so if you want 'ABCD' to be used, you must enter 'ABCD' and not 'abcd' etc.

The two arrows to the right of these icons can be used to copy the text from one into the other.

You can include carriage returns and linefeeds in both fields, using |J for linefeeds, and |M for carriage returns.

You can also drag a file (or directory) over each of the two writable icons, and the full path of that file is inserted. (This could be useful with certain script based processes).

[Main Contents]

Tag case changing

If the 'Tag case' option is selected, when 'Process' is clicked WebChange will run through the site directory changing the capitalisation of all HTML tags to that specified in the general choices window.

A typical use of this function would be, for example, for when you are taking over the maintenance of a site from someone else, and you want to change the style used to your own; some people prefer to use lower case HTML tags, others upper case. You might also have copied some example HTML that someone else has provided into one or more of your own pages.

The program adopts a fairly simple approach to doing this, so the results can be affected by poor/invalid HTML - though in trials it does seem to have proven fairly robust. To avoid any silly mistakes, however, you might want to check the validity of your HTML using something like John Alldred's validator, to be found hereabouts, before using this function.

[Main Contents]

ALT text checking/inserting

With this option selected, when 'Process' is clicked WebChange will search through your HTML looking for IMG tags in order to check that they include an ALT="" attribute.

If there is no ALT text, one will be inserted in accordance with what you have set in the general choices window.

On its own, the function is somewhat limited, since it can't look at the image and come up with a suitable description of it! The best it can do is extract the leafname from the SRC="" attribute and use that as ALT text, which is hardly the ideal ALT text, which should be meaningful.

However, use of leafnames could be followed by a series of searches/replaces, with which you could replace 'mycar.jpeg' with 'a picture of my car', and 'mydog.jpeg' with 'a picture of my dog'.

[Main Contents]

Including standard files

This option is one of three which provides pseudo-SSI facilities. SSI stands for 'server side includes' and at its simplest, as its name suggests, refers to having the (web) server include something in your HTML when the visitor downloads it.

WebChange's facilities are referred to as 'pseudo-SSI facilities' because it attempts to provide some of the benefits of server side includes, but obviously can't do so as server side includes, since it isn't a web server; with WebChange the facility must be used prior to uploading the site.

The 'FileIncludes' option provides the facility to load and insert one file into another. This allows you to (for example) define a standard page header for your site, or a standard footer, or a standard button bar.

When processing your site directory, WebChange will look out for special tags which tell it to perform this file inclusion. When found, it looks at what's between the tags and compares it with the file specified - if the comparison matches, the file is not included, but if it fails, the file is loaded and inserted; thus pages which 'include' the file only change if the file changes.

This means that, once defined, you only need to make a change to the included file for that change to be reflected throughout the site.

The special tags to use for this are:

<!-- FileInclude:"filespec" -->
and <!-- /FileInclude -->

'filespec' should be a relative reference, pointing to the file which is to be inserted.

A limitation of this version is that WebChange doesn't parse links within the inserted file, to update them so that links to different directory levels continue to work. This means you need to have such files set up for each directory level - a shortcoming which is hoped to be addressed shortly.

[Main Contents]

Including file sizes

'FileSizes' is the second of WebChange's pseudo-SSI functions, this one being to read the sizes of specified files and include that in the HTML. The most obvious use for this function is on 'download' pages, to warn visitors of the size of files they may wish to download.

By getting WebChange to include the file size(s), rather than doing so yourself, you can have WebChange update the size(s) whenever the referenced file or files are updated. Whenever the relevant tags are encountered, the program establishes the size of the specified file and compares it with what's already contained between the tags, only changing it if the match fails.

The special tags to use for this are:

<!-- FileSize:"filespec" -->
and <!-- /FileSize -->

'filespec' should be a relative reference, pointing to the file whose size is to be inserted.

[Main Contents]

Including file datestamps

This is the third and final of the pseudo-SSI functions, enabled by selecting 'FileUpdates' in the main window.

Using this function, you can have WebChange read the datestamps of specified files, and have them inserted in your HTML - the most obvious use being to say when any given page was last updated. With WebChange inserting the dates, you don't have to remember to manually change any/all such dates; just run WebChange before any uploads, with this option selected.

The tags used by this function are similar to the two above, but also provide some additional options for the 'filespec'. The tags are:

<!-- FileUpdate:"filespec" -->
and <!-- /FileUpdate -->

'filespec' should be a relative reference, pointing to the file whose datestamp is to be inserted. You can also use 'ThisFile' as the filespec, which is self referential - the datestamp of the file containing the tags is inserted.

Furthermore, you can specify a directory in the filespec - and use 'ThisDir' to represent the directory containing the file. When a directory is specified, WebChange checks the dates of all the files in the directory (and subdirectories), and it is the most recent date which is used.

The datestamp inclusion function actually performs two passes, so that in some cases dates are updated, and then updated again. This attempts to prevent situations where a file is being updated simply because it was updated the last time.

It may be possible that due to particularly complicated cross referencing, a two pass system isn't enough. If this occurs, just run the process a second time - and let me know so I can increase (or make configurable) the number of passes.

You will also notice in the main window a large square icon containing the words 'Run Script' - this is the 'target' icon for running your own scripts; you can drag them to here or to the icon bar icon. Scripts are dealt with later in this guide.

Also, in the bottom left of the window is a button labelled 'Search Only' - this button will run the search and replace program, but only using the text to find; no replacement will be carried out. The results of doing this are stored in a text file, which contains details of where the text has been found in your site directory, in the format:

Filepath (From, To)
This text file is Filer_Run when the search is complete.

[Main Contents]

Changing filename case

This function is the first of the immediate ones, which are all accessed from the main window menu, processes submenu, this one being 'Filename Case'.

The menu item leads to a submenu on which you will find 'Upper', 'Lower' and 'Proper' - the three types of capitalisation you may wish to change all your filenames to.

Clicking on 'Upper' results in WebChange renaming all the files in your site directory so that they are all in upper case, clicking on 'Lower' causes it to rename all the files so that they are lowercase, and clicking on 'Proper' causes them to be changed to proper case, which means that they all have an upper case first letter, and the rest are lower case.

Note that this only changes the case of the actual filenames stored on disk; it has no effect on the capitalisation of links within your HTML.

[Main Contents]

Changing extension lengths

The next item on the processes submenu is for changing the extension length of files on disk. It leaves to a further submenu containing three items - 'Long', 'Short' and 'None'.

Clicking 'Long' causes WebChange to look at all the files in your site directory and rename them, if necessary, so that their extension is a longer one - eg /html instead of /htm, or /jpeg instead if /jpg. Clicking 'Short' makes the extensions of the shorter form, such as /jpg instead of /jpeg, etc. Clicking 'None' causes WebChange to remove all of the extensions.

Note that this only changes the extensions of the actual files on disk; it has no effect on the extensions used in links in your html.

Note that when changing extension lengths, WebChange attempts to decide the extension from the filetype, but it only 'knows' about a small number of filetypes.

[Main Contents]

Setting filetypes

The next item on the processes submenu is 'Set Filetypes', clicking which causes WebChange to attempt to set the RISC OS filetype for all the files in your site directory according to their file extensions - eg if a file has the extension /html WebChange will set its filetype to be &FAF.

Note that, as with the extension length changing process above, the filetype setting routine only knows about a small number of file extensions and their matching types.

[Main Contents]

Changing newline types

Newlines is the next item on the processes submenu, and this leads to a submenu containing four entries, LF, CR, LF/CR and CR/LF. CR means carriage return, and LF means linefeed.

Clicking on each of these causes WebChange to work through all the text and html files in your site directory, changing all the newlines to the type shown on the clicked menu item.

This can be useful if, for example, transferring a copy of your site onto a DOS format disk for modification on a Windows machine - the normal newline sequence on such machines is CR/LF, whereas RISC OS usually uses just LF; you could change all the newlines to be CR/LF before you copy onto the DOS disk and, later, after moving the modified site back onto your RISC OS machine, you can convert them back to just linefeeds.

[Main Contents]

Saving a validation file

If you click on 'Validation File' in the Processes submenu, a save dialogue box will appear. Using this you can specify a filename and drag the icon to a suitable location in order to save a HTML file, which will contain a link for each page in your site directory.

These links are created from the information entered in the Validation Choices window, so provided the information there is set up correctly, each link should be usable to check the validity of each page in your site.

This works by creating a link to a validator, and appending the URL of your site and the relative path to the page as the main parameter - the address of the page to check. For example, if you enter 'http://www.softrock.co.uk/' as the site URL in that window, and 'http://validator.w3.org/check?uri=' as the link prefix, the generated link will start with:


The leafnames of every page in the top level of the site directory would be added to that and, finally, the link suffix if any is set. So for the 'index.html' file the end result is the link:


...which is actually asking validator.w3.org to check http://www.softrock.co.uk/index.html to see if it is valid.

Preparing this page of links so that once your site is uploaded you can just click on each to submit each page to the validator reduces your online time compared with the slower and more tedious approach of visiting validator.w3.org and entering the address of each page in turn in the form.

[Main Contents]

Saving an index file

Clicking on the 'Indexing File' entry on the Processes submenu leads to another save dialogue, this time to save a HTML file containing an index of key words and terms found in your site - much like an index found at the back of a text book. This is not to be confused with the 'index.html' file, which is commonly used as the default page returned by web servers when opening directories, and so this function should not be used to generate such a file.

The indexing system seeks out any of three tag types, according to how you've set things up in the indexing choices window:

Anchor name tags take the form <A NAME="label">word/phrase</A> and when WebChange indexes these (assuming the relevant option is selected in the window mentioned above), the word/phrase between the opening and closing tag is what is indexed, and the link is to the label.

Index tags take the form <!-- Index -->word/phrase<!-- /Index --> and, again, when WebChange indexes these the word/phrase between the tags is inserted in the index, but this time the link is just to the page containing the phrase.

Meta keyword tags take the form <META NAME="keywords" CONTENT="comma delimited list"> and when indexing with this option selected, WebChange includes each word in the comma delimited list into the index, with a link to the page.

As a general rule, and particularly if you tend to include the same keywords in META tags across a number of pages and/or include lots of 'variations on a theme' in your META keywords for the benefit of search engines, it's probably better to exclude these from any index generated by WebChange, and just stick with anchor and index tags, otherwise your index file could finish up being extremely big and pretty much unusable.

[Main Contents]

Saving a file list file

The final item on the Processes submenu, File List, opens a save dialogue from which you can save a HTML file containing a link to every file in your site directory.

[Main Contents]


Statistics window
The statistics window

If you click the 'Stats' item on the main window menu, WebChange will analyse your site directory and open a window revealing various size and quantity statistics about it.

Main contents