home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / programs / comms_networking / validator / !Validator / !Help < prev    next >
Encoding:
Text File  |  1999-02-08  |  11.2 KB  |  266 lines
  1.                .--------------.
  2.                ¦  !Validator  ¦  vsns 0.35ß 25Nov98
  3.                '--------------'    to 0.37d 08Feb99
  4.  Validates either single HTML files, or a directory
  5.  containing  HTML files (in which case it will
  6.  recurse through subdirectories).  The source can
  7.  either be dragged to the icon-bar icon, or else
  8.  the source pathname can be typed in explicitly.
  9.  The checks made are for mismatched or badly-nested
  10.  tags, quote-marks, and angle-brackets;  but apart
  11.  from a few exceptions, attributes are not checked.
  12.  Default settings are in a ‘Choices’ text-file.
  13.  Just double-click on the !Validator icon to run
  14.  and install --  but read the instructions below!
  15.                  -------------------------------
  16.  
  17.  !Validator instructions
  18.  ==========-------------
  19.  
  20.  Introduction
  21.  ============
  22.  This is a fairly simple-minded parser/validator for HTML-code;
  23.  it is intended to pick up the more common errors of mismatched,
  24.  wrongly-paired or wrongly-nested angle-brackets, quote-marks and tags.
  25.  It does NOT investigate attributes within tags nor validity of URLs.
  26.  
  27.  Because there is no one true standard for HTML (apart from the rather
  28.  restricted W3C HTML 2.0), it is not feasible for it to decide whether
  29.  all the tags in the code are “legal” or not;  but it does look out for
  30.  the “deprecated” ones.
  31.  
  32.  To minimise button-input each time it is run, there are a number of
  33.  “default options” which can be set up by editing a ‘Choices’ file
  34.  within the application.  This allows you to “pre-configure” any
  35.  information which rarely changes.
  36.  
  37.  There is no actual need to access the ‘Choices’ file directly, as
  38.  all the options (except maximum file size) can be set via the program;
  39.  however, a full description (which can be skipped) is given below.
  40.  
  41.  Options set-up
  42.  ==============
  43.  
  44.  Some “default” values for options are pre-defined, even before you’ve
  45.  started to re-define any, so you don’t HAVE to worry about them.
  46.  They can be altered during run-time, and saved from there.
  47.  
  48.  The only one that can’t be accessed/altered except by file-editing
  49.  is “MaxSize%”, which limits the largest file it will process.
  50.  
  51.  You can also access (and edit) them directly, as described below:
  52.  
  53.  Load the options into !Edit (or your text editor of choice) by
  54.  Shift-double-clicking on the ‘!Validator’ application icon to open it,
  55.  then double-clicking on the ‘Choices’ Text icon.
  56.  You will see what looks like a BASIC program, assigning values to
  57.  nine different variables. 
  58.  Leave the “variable name” to the left of the “=” symbol well alone; 
  59.  and just edit the values to its right as required.
  60.  
  61.  “defaultPath$” should be set to either the full path-name of a single
  62.  HTML file;  or else to the full path of a directory containing some
  63.  HTML files (all of which will be checked, as will any files within
  64.  sub-directories).
  65.  The two most useful settings for this variable are either:
  66.  the path-name of the directory containing the local copy of your site;
  67.  or else "RAM::RamDisc0.$", the RAM filing system, into which you can
  68.  drag any file(s) you want to check.
  69.  Note that this default can always be over-ridden at run-time.
  70.  
  71.  “maxSize%” is used to set the amount of memory allocated for loading
  72.  a file in to;  a sensible value for this can allow the program to
  73.  refuse to accept a multi-meg movie-file with the wrong file-type!
  74.  
  75.  The next nine options variables are merely set to TRUE or FALSE:
  76.  
  77.  “pedantic%” checks the recommendation that the text between <A> and
  78.  </A> anchor tags contains no further markup except for <IMG> elements
  79.  (though it does allow Bold and Italic).  Failure to comply with this
  80.  recommendation is not strictly an error, but may help to show up a
  81.  bad construction in the vicinity.
  82.  
  83.  “quoteEntity%” requires all quote marks (") in the text to be represented
  84.  by the entity ‘"’ and only permits ordinary quote marks within tags
  85.  (where they are used to enclose URLs etc).
  86.  
  87.  “ampersand%” similarly requires the & character to be represented by the
  88.  entity ‘&’ (again, except within URLs).
  89.  
  90.  “noEntityNames%” requires all named entities such as Ñ to be
  91.  replaced by the numeric entity Ñ (in this example).
  92.  
  93.  “entityCheck%” performs a more thorough check that all ‘&whatever;’ 
  94.  entity names are valid in the ISO-8859-1 and ISO 8879:1986 sets.
  95.  (This option will be deemed to be also required if you have selected
  96.  noEntityNames above).
  97.  
  98.  “noNestedFont%” requires that each <FONT> must be followed by a
  99.  closing </FONT> before the next opening <FONT>.
  100.  
  101.  “strictHTML2%” checks for strict compliance with W3C HTML 2.0;  if you
  102.  have this on (TRUE), it will outlaw things like <CENTER> and <FONT>!
  103.  
  104.  “verbose%” gives full reporting;  if FALSE, it suppresses mere comments
  105.  and listing of error-free pages.
  106.  
  107.  “skipJS%” suppresses error-reports which would otherwise appear from
  108.  JavaScript within comment tags.
  109.  
  110.  “throwback%” pre-selects the Throwback option;  this only works if
  111.  you have the DDEUtils module.
  112.  
  113.  “loadDDEUtils%” allows the DDEUtils module (needed for “Throwback”) to
  114.  be loaded if available, and is assumed to be TRUE if omitted;
  115.  setting it to FALSE will prevent it being RMLOADed.
  116.  
  117.  Finally, save ‘Choices’ back whence it came!
  118.  
  119.  
  120.  Running
  121.  =======
  122.  Double-click on the ‘!Validator’ application icon to start the program
  123.  and install its icon on the icon-bar.
  124.  
  125.  To actually validate a file or directory of files:  either
  126.  
  127.  (a) drag the file or directory icon on to the icon-bar !Validator icon,
  128.      which will bring up the “options” window;  or
  129.  
  130.  (b) click (select) on the icon-bar !Validator icon, which will also
  131.      bring up much the same “options” window, except that the topmost
  132.      display of source path is a writeable icon:  this will initially
  133.      show the default source as set up in the ‘Choices’ file, but it
  134.      can be edited to any other path you like.
  135.  
  136.  (c) click ADJUST on the icon-bar !Validator icon, which will bring up
  137.      an “options” window for the immediately-previous source specified
  138.      (if any);  this is to enable you to re-analyse the last data set.
  139.      (Useful immediately after editing errors on a page, to re-check)
  140.  
  141.  “Validator options” window
  142.  --------------------------
  143.  There are 11 option buttons to muck about with;  the first 10 will be
  144.  pre-loaded according to the defaults in the ‘Choices’ file.  They are:
  145.  
  146.    [ ] No markup inside anchors
  147.    [ ] Quotes " must be "
  148.    [ ] Ampersand must be &
  149.    [ ] Disallow named tbs entities
  150.    [ ] Check all &entity; names
  151.    [ ] Disallow nested <FONT>
  152.    [ ] Only allow Strict HTML 2.0
  153.    [ ] Verbose reporting
  154.    [ ] Skip over (Java)Script
  155.    [ ] Generate throwbacks       (greyed-out if you haven't got DDEUtils)
  156. and
  157.    [ ] Print results
  158.  
  159.  If you change any of these and want to re-use them on later occasions,
  160.  click the [Save options] button and it will re-write the ‘Choices’ file
  161.  (note: this includes any default source path string,
  162.  but does *not* include the “Print results” option).
  163.  
  164.  If/when you’re happy with your selection, click on the [Analyse] button
  165.  (if you got the options window by clicking on - instead of dragging to -
  166.  the icon-bar, and you’ve edited the source path, pressing [Return] has
  167.  the same result).
  168.  This will replace that window by the “Report” window.
  169.  
  170.  Output results (‘ReportLog’ file, and printout if selected)
  171.  ==============  ----------------
  172.  Assuming it was given a directory to process, it will go through every
  173.  file in turn (and recurse into any sub-directories), ignoring any files
  174.  which are not HTML, and analysing all that are.
  175.  If there are no errors at all, you will just get one line per file,
  176.  with the leaf-name of the file, its size in bytes, followed by “OK €”
  177.  (unless “Verbose” was un-ticked, in which case you get nothing).
  178.  
  179.  If there are any errors, each will be shown by it reproducing the “line”
  180.  in which it thinks the error occurs, preceded by what it thinks is its
  181.  “line number”;  followed by a pointer (character count along the line)
  182.  of where it actually found the error, and a description of the error.
  183.  Of course, part of the mistake could have occurred in the previous line,
  184.  in which case you won’t see it!
  185.  
  186.  Some mismatch/nesting errors can have a “ripple on” effect, and throw up
  187.  a sequence of spurious errors later on.  If this appears to be happening,
  188.  try correcting the first (few) recognisable mistake(s) only, and then
  189.  re-running !Validator (adjust-click on the icon-bar icon) to see if the
  190.  follow-on error-messages disappear.
  191.  
  192.  Output results (“report window” on screen)
  193.  --------------  ---------------
  194.  Three lines of information are displayed as files are processed:
  195.    The “FilingSystemPath.LeafName” of the file currently being checked;
  196.    (As much as possible of) the “line” in which an error has been found;
  197.    The error message itself.
  198.  Running totals of numbers of files and errors are also displayed.
  199.  
  200.  When finished, the full report will be in the text-file ‘ReportLog’
  201.  inside the application;  the window has three buttons to allow you to:
  202.    Close the window [Cancel],
  203.    Save that file elsewhere,
  204.    View that file (in !Edit or your default text editor).
  205.  
  206.  Limitations
  207.  ===========
  208.  Because it does not have a definitive list of permissible HTML-tags
  209.  (unless you've selected strictHTML2), it will cheerfully pass  the
  210.  likes of  <THING>Hello</THING>, but will flag a mismatch message for
  211.  <thing>Hello</thong>.
  212.  Also, apart from looking for HREF=/NAME= inside <A>, and SRC= and ALT=
  213.  inside <IMG>, it does not yet check for any other attributes inside a tag.
  214.  
  215.  It does not correctly process a “selection” of files dragged to its icon
  216.  but just analyses the last one in the selection  (if anyone knows how to
  217.  get round this, I'd be grateful if they'd let me know).
  218.  
  219.  The "Report: Save" option is actually implemented by a "*Copy", and
  220.  therefore can only save into a Filer Window, but not into another
  221.  application.
  222.  
  223.  Maximum file size
  224.  -----------------
  225.  As supplied, the program has an arbitrary limit of 96Kbytes as the
  226.  largest HTML-file that it will load and process.
  227.  
  228.  If you need to increase this, you certainly may (up to 576K) by
  229.  editing the “maxSize%” entry in ‘Choices’;  but please note that
  230.  if the increase is more than just a few K, it will also be necesssary
  231.  to increase the space allotted by “WimpSlot” in the ‘!Run’ file by
  232.  the same amount.
  233.  
  234.  --------------------------------------------------
  235.  
  236.  Acknowledgements
  237.  ================
  238.  My thanks are due to:
  239.  
  240.  Bob Charlton <charlton@argonet.co.uk> for chivvying me into converting
  241.  the basic program into a “proper” wimp-compliant multi-tasking one,
  242.  and for doing some brutal beta-testing ;-)
  243.  
  244.  Richard Wilson <rwilson@argonet.co.uk> for offers of help and suggestions
  245.  on the layout of the report window;
  246.  
  247.  Rosemary Miskin <miskin@argonet.co.uk> for help and advice in creating
  248.  the “correct” button icons and patiently answering a string of damfool
  249.  wimp-programming questions from yours truly!
  250.  
  251.  Robert Munro <rjm@cryogen.com> for adding to the pressure to be able to
  252.  skip over JavaScript;  and more importantly, for suggesting and helping
  253.  with the implementation of Throwbacks.
  254.  
  255.  --------------------------------------------------
  256.  
  257.  Warranties:  NONE
  258.  
  259.  DISCLAIMER:  Use only as directed.   Extremely dangerous to fish.
  260.  Intentional misuse by deliberately concentrating contents can be fatal.
  261.  
  262.  John Alldred ZFC:B, 27Dec98
  263.  email  john@protovale.co.uk
  264.  http://www.argonet.co.uk/users/protovale/john.html
  265.  http://www.protovale.co.uk/john/
  266.