               .--------------.
                 !Validator    vsns 0.35 25Nov98
               '--------------'    to 0.37d 08Feb99
 Validates either single HTML files, or a directory
 containing  HTML files (in which case it will
 recurse through subdirectories).  The source can
 either be dragged to the icon-bar icon, or else
 the source pathname can be typed in explicitly.
 The checks made are for mismatched or badly-nested
 tags, quote-marks, and angle-brackets;  but apart
 from a few exceptions, attributes are not checked.
 Default settings are in a Choices text-file.
 Just double-click on the !Validator icon to run
 and install --  but read the instructions below!
                 -------------------------------

 !Validator instructions
 ==========-------------

 Introduction
 ============
 This is a fairly simple-minded parser/validator for HTML-code;
 it is intended to pick up the more common errors of mismatched,
 wrongly-paired or wrongly-nested angle-brackets, quote-marks and tags.
 It does NOT investigate attributes within tags nor validity of URLs.

 Because there is no one true standard for HTML (apart from the rather
 restricted W3C HTML 2.0), it is not feasible for it to decide whether
 all the tags in the code are legal or not;  but it does look out for
 the deprecated ones.

 To minimise button-input each time it is run, there are a number of
 default options which can be set up by editing a Choices file
 within the application.  This allows you to pre-configure any
 information which rarely changes.

 There is no actual need to access the Choices file directly, as
 all the options (except maximum file size) can be set via the program;
 however, a full description (which can be skipped) is given below.

 Options set-up
 ==============

 Some default values for options are pre-defined, even before youve
 started to re-define any, so you dont HAVE to worry about them.
 They can be altered during run-time, and saved from there.

 The only one that cant be accessed/altered except by file-editing
 is MaxSize%, which limits the largest file it will process.

 You can also access (and edit) them directly, as described below:

 Load the options into !Edit (or your text editor of choice) by
 Shift-double-clicking on the !Validator application icon to open it,
 then double-clicking on the Choices Text icon.
 You will see what looks like a BASIC program, assigning values to
 nine different variables. 
 Leave the variable name to the left of the = symbol well alone; 
 and just edit the values to its right as required.

 defaultPath$ should be set to either the full path-name of a single
 HTML file;  or else to the full path of a directory containing some
 HTML files (all of which will be checked, as will any files within
 sub-directories).
 The two most useful settings for this variable are either:
 the path-name of the directory containing the local copy of your site;
 or else "RAM::RamDisc0.$", the RAM filing system, into which you can
 drag any file(s) you want to check.
 Note that this default can always be over-ridden at run-time.

 maxSize% is used to set the amount of memory allocated for loading
 a file in to;  a sensible value for this can allow the program to
 refuse to accept a multi-meg movie-file with the wrong file-type!

 The next nine options variables are merely set to TRUE or FALSE:

 pedantic% checks the recommendation that the text between <A> and
 </A> anchor tags contains no further markup except for <IMG> elements
 (though it does allow Bold and Italic).  Failure to comply with this
 recommendation is not strictly an error, but may help to show up a
 bad construction in the vicinity.

 quoteEntity% requires all quote marks (") in the text to be represented
 by the entity &quot; and only permits ordinary quote marks within tags
 (where they are used to enclose URLs etc).

 ampersand% similarly requires the & character to be represented by the
 entity &amp; (again, except within URLs).

 noEntityNames% requires all named entities such as &Ntilde; to be
 replaced by the numeric entity &#209; (in this example).

 entityCheck% performs a more thorough check that all &whatever; 
 entity names are valid in the ISO-8859-1 and ISO 8879:1986 sets.
 (This option will be deemed to be also required if you have selected
 noEntityNames above).

 noNestedFont% requires that each <FONT> must be followed by a
 closing </FONT> before the next opening <FONT>.

 strictHTML2% checks for strict compliance with W3C HTML 2.0;  if you
 have this on (TRUE), it will outlaw things like <CENTER> and <FONT>!

 verbose% gives full reporting;  if FALSE, it suppresses mere comments
 and listing of error-free pages.

 skipJS% suppresses error-reports which would otherwise appear from
 JavaScript within comment tags.

 throwback% pre-selects the Throwback option;  this only works if
 you have the DDEUtils module.

 loadDDEUtils% allows the DDEUtils module (needed for Throwback) to
 be loaded if available, and is assumed to be TRUE if omitted;
 setting it to FALSE will prevent it being RMLOADed.

 Finally, save Choices back whence it came!


 Running
 =======
 Double-click on the !Validator application icon to start the program
 and install its icon on the icon-bar.

 To actually validate a file or directory of files:  either

 (a) drag the file or directory icon on to the icon-bar !Validator icon,
     which will bring up the options window;  or

 (b) click (select) on the icon-bar !Validator icon, which will also
     bring up much the same options window, except that the topmost
     display of source path is a writeable icon:  this will initially
     show the default source as set up in the Choices file, but it
     can be edited to any other path you like.

 (c) click ADJUST on the icon-bar !Validator icon, which will bring up
     an options window for the immediately-previous source specified
     (if any);  this is to enable you to re-analyse the last data set.
     (Useful immediately after editing errors on a page, to re-check)

 Validator options window
 --------------------------
 There are 11 option buttons to muck about with;  the first 10 will be
 pre-loaded according to the defaults in the Choices file.  They are:

   [ ] No markup inside anchors
   [ ] Quotes " must be &quot;
   [ ] Ampersand must be &amp;
   [ ] Disallow named tbs entities
   [ ] Check all &entity; names
   [ ] Disallow nested <FONT>
   [ ] Only allow Strict HTML 2.0
   [ ] Verbose reporting
   [ ] Skip over (Java)Script
   [ ] Generate throwbacks       (greyed-out if you haven't got DDEUtils)
and
   [ ] Print results

 If you change any of these and want to re-use them on later occasions,
 click the [Save options] button and it will re-write the Choices file
 (note: this includes any default source path string,
 but does *not* include the Print results option).

 If/when youre happy with your selection, click on the [Analyse] button
 (if you got the options window by clicking on - instead of dragging to -
 the icon-bar, and youve edited the source path, pressing [Return] has
 the same result).
 This will replace that window by the Report window.

 Output results (ReportLog file, and printout if selected)
 ==============  ----------------
 Assuming it was given a directory to process, it will go through every
 file in turn (and recurse into any sub-directories), ignoring any files
 which are not HTML, and analysing all that are.
 If there are no errors at all, you will just get one line per file,
 with the leaf-name of the file, its size in bytes, followed by OK 
 (unless Verbose was un-ticked, in which case you get nothing).

 If there are any errors, each will be shown by it reproducing the line
 in which it thinks the error occurs, preceded by what it thinks is its
 line number;  followed by a pointer (character count along the line)
 of where it actually found the error, and a description of the error.
 Of course, part of the mistake could have occurred in the previous line,
 in which case you wont see it!

 Some mismatch/nesting errors can have a ripple on effect, and throw up
 a sequence of spurious errors later on.  If this appears to be happening,
 try correcting the first (few) recognisable mistake(s) only, and then
 re-running !Validator (adjust-click on the icon-bar icon) to see if the
 follow-on error-messages disappear.

 Output results (report window on screen)
 --------------  ---------------
 Three lines of information are displayed as files are processed:
   The FilingSystemPath.LeafName of the file currently being checked;
   (As much as possible of) the line in which an error has been found;
   The error message itself.
 Running totals of numbers of files and errors are also displayed.

 When finished, the full report will be in the text-file ReportLog
 inside the application;  the window has three buttons to allow you to:
   Close the window [Cancel],
   Save that file elsewhere,
   View that file (in !Edit or your default text editor).

 Limitations
 ===========
 Because it does not have a definitive list of permissible HTML-tags
 (unless you've selected strictHTML2), it will cheerfully pass  the
 likes of  <THING>Hello</THING>, but will flag a mismatch message for
 <thing>Hello</thong>.
 Also, apart from looking for HREF=/NAME= inside <A>, and SRC= and ALT=
 inside <IMG>, it does not yet check for any other attributes inside a tag.

 It does not correctly process a selection of files dragged to its icon
 but just analyses the last one in the selection  (if anyone knows how to
 get round this, I'd be grateful if they'd let me know).

 The "Report: Save" option is actually implemented by a "*Copy", and
 therefore can only save into a Filer Window, but not into another
 application.

 Maximum file size
 -----------------
 As supplied, the program has an arbitrary limit of 96Kbytes as the
 largest HTML-file that it will load and process.

 If you need to increase this, you certainly may (up to 576K) by
 editing the maxSize% entry in Choices;  but please note that
 if the increase is more than just a few K, it will also be necesssary
 to increase the space allotted by WimpSlot in the !Run file by
 the same amount.

 --------------------------------------------------

 Acknowledgements
 ================
 My thanks are due to:

 Bob Charlton <charlton@argonet.co.uk> for chivvying me into converting
 the basic program into a proper wimp-compliant multi-tasking one,
 and for doing some brutal beta-testing ;-)

 Richard Wilson <rwilson@argonet.co.uk> for offers of help and suggestions
 on the layout of the report window;

 Rosemary Miskin <miskin@argonet.co.uk> for help and advice in creating
 the correct button icons and patiently answering a string of damfool
 wimp-programming questions from yours truly!

 Robert Munro <rjm@cryogen.com> for adding to the pressure to be able to
 skip over JavaScript;  and more importantly, for suggesting and helping
 with the implementation of Throwbacks.

 --------------------------------------------------

 Warranties:  NONE

 DISCLAIMER:  Use only as directed.   Extremely dangerous to fish.
 Intentional misuse by deliberately concentrating contents can be fatal.

 John Alldred ZFC:B, 27Dec98
 email  john@protovale.co.uk
 http://www.argonet.co.uk/users/protovale/john.html
 http://www.protovale.co.uk/john/
