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