home *** CD-ROM | disk | FTP | other *** search
/ Kosovo Orphans' Appeal Charity CD / KosovoOrphansAppeal.iso / internet / software / _validator / _help < prev    next >
Encoding:
Text File  |  1998-09-05  |  10.3 KB  |  245 lines
  1.                .--------------.
  2.                ª  !Validator  ª  vsns 0.25  23Aug97
  3.                '--------------'    to 0.34  15Sep98
  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 seven 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.  Finally, save ÉChoicesæ back whence it came!
  105.  
  106.  
  107.  Running
  108.  =======
  109.  Double-click on the É!Validatoræ application icon to start the program
  110.  and install its icon on the icon-bar.
  111.  
  112.  To actually validate a file or directory of files:  either
  113.  
  114.  (a) drag the file or directory icon on to the icon-bar !Validator icon,
  115.      which will bring up the öoptionsò window;  or
  116.  
  117.  (b) click (select) on the icon-bar !Validator icon, which will also
  118.      bring up much the same öoptionsò window, except that the topmost
  119.      display of source path is a writeable icon:  this will initially
  120.      show the default source as set up in the ÉChoicesæ file, but it
  121.      can be edited to any other path you like.
  122.  
  123.  (c) click ADJUST on the icon-bar !Validator icon, which will bring up
  124.      an öoptionsò window for the immediately-previous source specified
  125.      (if any);  this is to enable you to re-analyse the last data set.
  126.      (Useful immediately after editing errors on a page, to re-check)
  127.  
  128.  öValidator optionsò window
  129.  --------------------------
  130.  There are 8 option buttons to muck about with;  the first 7 will be
  131.  pre-loaded according to the defaults in the ÉChoicesæ file.  They are:
  132.  
  133.    [ ] No markup inside anchors
  134.    [ ] Quotes " must be "
  135.    [ ] Ampersand must be &
  136.    [ ] Disallow named tbs entities
  137.    [ ] Check all &entity; names
  138.    [ ] Disallow nested <FONT>
  139.    [ ] Only allow Strict HTML 2.0
  140. and
  141.    [ ] Print results
  142.  
  143.  If you change any of these and want to re-use them on later occasions,
  144.  click the [Save options] button and it will re-write the ÉChoicesæ file
  145.  (note: this includes any default source path string,
  146.  but does *not* include the öPrint resultsò option).
  147.  
  148.  If/when youære happy with your selection, click on the [Analyse] button
  149.  (if you got the options window by clicking on - instead of dragging to -
  150.  the icon-bar, and youæve edited the source path, pressing [Return] has
  151.  the same result).
  152.  This will replace that window by the öReportò window.
  153.  
  154.  Output results (ÉReportLogæ file, and printout if selected)
  155.  ==============  ----------------
  156.  Assuming it was given a directory to process, it will go through every
  157.  file in turn (and recurse into any sub-directories), ignoring any files
  158.  which are not HTML, and analysing all that are.
  159.  If there are no errors at all, you will just get one line per file,
  160.  with the leaf-name of the file, its size in bytes, followed by öOK Çò.
  161.  
  162.  If there are any errors, each will be shown by it reproducing the ölineò
  163.  in which it thinks the error occurs, preceded by what it thinks is its
  164.  öline numberò;  followed by a pointer (character count along the line)
  165.  of where it actually found the error, and a description of the error.
  166.  Of course, part of the mistake could have occurred in the previous line,
  167.  in which case you wonæt see it!
  168.  
  169.  Some mismatch/nesting errors can have a öripple onò effect, and throw up
  170.  a sequence of spurious errors later on.  If this appears to be happening,
  171.  try correcting the first (few) recognisable mistake(s) only, and then
  172.  re-running !Validator (adjust-click on the icon-bar icon) to see if the
  173.  follow-on error-messages disappear.
  174.  
  175.  Output results (öreport windowò on screen)
  176.  --------------  ---------------
  177.  Three lines of information are displayed as files are processed:
  178.    The öFilingSystemPath.LeafNameò of the file currently being checked;
  179.    (As much as possible of) the ölineò in which an error has been found;
  180.    The error message itself.
  181.  Running totals of numbers of files and errors are also displayed.
  182.  
  183.  When finished, the full report will be in the text-file ÉReportLogæ
  184.  inside the application;  the window has three buttons to allow you to:
  185.    Close the window [Cancel],
  186.    Save that file elsewhere,
  187.    View that file (in !Edit or your default text editor).
  188.  
  189.  Limitations
  190.  ===========
  191.  Because it does not have a definitive list of permissible HTML-tags
  192.  (unless you've selected strictHTML2), it will cheerfully pass  the
  193.  likes of  <THING>Hello</THING>, but will flag a mismatch message for
  194.  <thing>Hello</thong>.
  195.  Also, apart from looking for HREF=/NAME= inside <A> and SRC inside <IMG>,
  196.  it does not yet check for any other attributes inside a tag.
  197.  
  198.  It does not correctly process a öselectionò of files dragged to its icon
  199.  but just analyses the last one in the selection  (if anyone knows how to
  200.  get round this, I'd be grateful if they'd let me know).
  201.  
  202.  The "Report: Save" option is actually implemented by a "*Copy", and
  203.  therefore can only save into a Filer Window, but not into another
  204.  application.
  205.  
  206.  Maximum file size
  207.  -----------------
  208.  As supplied, the program has an arbitrary limit of 96Kbytes as the
  209.  largest HTML-file that it will load and process.
  210.  
  211.  If you need to increase this, you certainly may (up to 576K) by
  212.  editing the ömaxSize%ò entry in ÉChoicesæ;  but please note that
  213.  if the increase is more than just a few K, it will also be necesssary
  214.  to increase the space allotted by öWimpSlotò in the É!Runæ file by
  215.  the same amount.
  216.  
  217.  --------------------------------------------------
  218.  
  219.  Acknowledgements
  220.  ================
  221.  My thanks are due to:
  222.  
  223.  Bob Charlton <charlton@argonet.co.uk> for chivvying me into converting
  224.  the basic program into a öproperò wimp-compliant multi-tasking one,
  225.  and for doing some brutal beta-testing ;-)
  226.  
  227.  Richard Wilson <rwilson@argonet.co.uk> for offers of help and suggestions
  228.  on the layout of the report window;
  229.  
  230.  Rosemary Miskin <miskin@argonet.co.uk> for help and advice in creating
  231.  the öcorrectò button icons and patiently answering a string of damfool
  232.  wimp-programming questions from yours truly!
  233.  
  234.  --------------------------------------------------
  235.  
  236.  Warranties:  NONE
  237.  
  238.  DISCLAIMER:  Use only as directed.   Extremely dangerous to fish.
  239.  Intentional misuse by deliberately concentrating contents can be fatal.
  240.  
  241.  John Alldred ZFC:B, 20Aug97
  242.  email  john@protovale.co.uk
  243.  http://www.argonet.co.uk/users/protovale/john.html
  244.  http://www.protovale.co.uk/john/
  245.