home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / programs / comms_networking / htmlscan / !HTMLScan / !ReadMe < prev    next >
Encoding:
Text File  |  1998-06-08  |  11.8 KB  |  249 lines
  1.  
  2.                          !HTMLScan's ReadMe file
  3.                          ~~~~~~~~~~~~~~~~~~~~~~~
  4. This program was originally designed to add "height=" and "width=" tags to
  5. HTML files by reading the information from the headers of the relevant image
  6. files.
  7.  
  8. This is desirable as it enables intelligently designed browsers to render the
  9. entire file's text before trying to load the images.  If the images cause
  10. difficulties for any reason, then it is still possible to navigate the page. 
  11. If the browser multitasks properly, then it should be possible to follow
  12. links while the graphics are being redrawn.  If a graphic fails to load
  13. because of local resource problems this should not interfere with the
  14. rendering of most of the page.
  15.  
  16. An analysis of the web sites of many companies seems to reveal that they are
  17. in dire need of a tool very much like this one.
  18.  
  19. While the file is being scanned, various syntactical checks are also
  20. performed.  These are not exhaustive by any means, but are usually
  21. sufficient to catch many common mistakes.  The following tags are checked
  22. for to make sure that they have matching partners at appropriate points in
  23. the file:
  24.  
  25. <H1 - H6>, <HTML>, <HEAD>, <BODY>, <TITLE>, <ADDRESS>, <TEXTAREA>, <TABLE>,
  26. <FORM>, <QUOTE>, <KBD>, <UL>, <OL>, <A>, <B>, <I>, <EM>, <OL>, <KBD>,
  27. <CODE>, <TT>, <SUB>, <SUP>, <STRIKE>, <RIGHT>, <LEFT>, <FONT>, <DFN>,
  28. <BLOCKQUOTE>, <PRE>, <CITE>, <CENTER>, <QUOTE> and <STRONG>.
  29.  
  30. <P> tags are also counted and a report is made if they are used unusually.
  31. <META> tags are checked to see if they are located in the header.
  32.  
  33. Quotes are matched within tags and tags without open or close markers are
  34. noted.  Within <img> tags, the existence of a "src=" is checked, along with
  35. the presence of "alt=" and of course, "width=" and "height=".
  36.  
  37. If "width=" or "height=" are missing or do not match with the values found in
  38. the header of the relevant GIF or JPEG files, these tags are added (if the
  39. "Make Changes" option is ticked) and or old values can be overwritten with
  40. the new (if the "Overwrite" option is ticked).
  41.  
  42. HREF parameters in anchor files may optionally be parsed, and checks made
  43. to ensure that the files being referred to actually exist.  The existence
  44. of appropriate markers within the files (when these are referred to) is not
  45. currently checked.
  46.  
  47. If "Remove spaces" (Crunch SP) or "Remove carriage returns" (Crunch CR) are
  48. selected then unpreformatted text has duplicate strings of the relevant
  49. characters are deleted from the file.  This may squeeze a few bytes from the
  50. file so it can travel down the wires a little quicker.
  51.  
  52. If "Don't check legality" is not selected then ampersands, quotes, less-than
  53. and greater than symbols and top-bit-set characters will be queried.
  54.  
  55. If "Don't check entities" is not selected then anything between a "&" symbol
  56. and a ";" which is non-numerical will be parsed and checked against an
  57. internal list of entities.
  58.  
  59. Groups of HTML files may be dragged to the icon bar icon and processed
  60. simultaneously.
  61.  
  62. The front end of the program relies on the existence of Acorn's "FrontEnd"
  63. module which is part of the DDE.  It was once on an "Archimedes World" cover
  64. disc, but it is recognised that many people will not have access to it from
  65. that source.
  66.  
  67. The program may be used from the command line.  It is in the "Library"
  68. directory and is called "HTMLScan".  When run with no parameters it prints
  69. its command-line syntax.
  70.  
  71. HTMLScan should work from within archives, or from non-writable media,
  72. though you will not be able to save any options you select.
  73.  
  74. Problems and wishes
  75. ~~~~~~~~~~~~~~~~~~~
  76. Not all GIF files store their width and height in the same manner.  The
  77. "Warning: Unusual GIF format" messages that you will sometimes encounter
  78. should be nothing to worry about.  The program has not failed yet with a
  79. 'weird' GIF, but I am not absolutely positive I have understood the GIF
  80. specification correctly, so please advise me if there are problems.  GIFs
  81. containing multiple images of differing sizes may cause confusion.  If you
  82. do not like the "Unusual GIF format" warnings appearing, then you can try
  83. loading the relevant GIFs into a bitmap editor and then saving them. 
  84. !WebGif2 always produces files which !HTMLScan does not give warnings about.
  85.  
  86. The program works with all the JFIF style of JPEG file that it has been
  87. tried with.  Colour and greyscale JPEGs are supported, though note that
  88. progressive JPEGs are not handled.  Once again, the exact specification has
  89. been guessed at to some extent, so there may be files that do not work.
  90.  
  91. Sprites and PNGs and other graphics formats apart from JPEGs and GIFs are
  92. not dealt with.
  93.  
  94. More (and more useful) checking could usefully be implemented.  Checking the
  95. links within files exist when "href=" has an associated marker point would
  96. be a useful start.  The messages given could sometimes be made more helpful.
  97. Some messages do not give any indication about where in the file the problem
  98. is most likely to lie.
  99.  
  100. Tags are treated as though they are heirarchical, but this is not necessarily
  101. the case and "Some <b>bold, <cite>bold cited,</b> cited and </cite> back to
  102. normal" is certainly unambiguous, though not all browsers can cope with it,
  103. and I do not think it is supported by any standard document, HTMLScan
  104. should probably not query it in the way it currently does.
  105.  
  106. Add an option to insert the entity which needs to be inserted automatically.
  107. Now that the Zap HTML mode does this adding it to HTMLScan seems quite
  108. unimportant.
  109.  
  110. HTMLScan continues gaily parsing through HTML comments as though they are
  111. not present.  This is a known bug, and will hopefully be addressed.
  112.  
  113. History
  114. ~~~~~~~
  115. 1.20 - Released 08-Jun-98:
  116.      * Added support for HTML-4 entities.
  117.      * HTMLScan now works properly if no task is registered for throwback.
  118.  
  119. 1.19 - Released 23-Jun-97:
  120.      * Modification to hopefully allow a larger range of JPEG files to be
  121.        processed by HTMLScan.  It has not been tested with progressive JPEGs
  122.        yet to see if processing of these is successful.
  123.      * Stopped stupidly adding unnecessary carriage returns when inserting
  124.        image dimensions.
  125.  
  126. 1.18 - Released 03-Apr-97:
  127.      * Removed bug which caused unnecessary warnings if an anchor tag
  128.        contained both "href=" and "name=" attributes.
  129.  
  130. 1.17 - Released 05-Feb-97:
  131.      * Fixed bug which involved pages whose local references started with
  132.        the "/" character.
  133.  
  134. 1.16 - Released 23-Jan-97:
  135.      * Added knowledge about mailto: and gopher: directives, so these are
  136.        no longer flagged as warnings (as long as they are in lower case).
  137.      * References to things in directories with "cgi-bin" in their paths
  138.        are treated less severely.
  139.      * References to directories are now treated more sensibly.  However
  140.        errors involving the directory not being present are more likely
  141.        to cause HTMLScan internal problems.
  142.      * Made entity checking case sensitive and removed an illegal entity or
  143.        three.
  144.  
  145. 1.15 - Released 14-Dec-96:
  146.      * Throwback implemented.
  147.  
  148. 1.14 - Released 25-Nov-96.
  149.      * Fixed problems with the <a name="name"> construct which has no </a>
  150.        ending tag.  !HTMLScan now knows this.
  151.  
  152. 1.13 - Released 21-Nov-96:
  153.      * Characters such as ", &, >, and < now have their entity equivalent
  154.        indicated by !HTMLScan when they are found.
  155.  
  156. 1.12 - Released 20-Nov-96:
  157.      * Added a huge list of entities and options for !HTMLScan to
  158.        check all the entities in the document for ones that are not known to
  159.        it.
  160.      * Characters such as ", &, >, and < are now queried as they would
  161.        be better expressed as entities.
  162.      * Problems with the <FORM> tag resolved.
  163.  
  164. 1.11 - Released 13-Nov-96:
  165.      * Incorrect command-line options in "Desc" file changed.
  166.      * Problems with the <QUOTE> tag resolved.
  167.  
  168. 1.10 - Released 10-Nov-96:
  169.      * !HTMLScan now copes with files whose paths are not in quotation
  170.        marks provided the path name stays in the restricted case available
  171.        when quotes are not used, i.e. 0-9, A-Z, a-z, '.' and '/'.
  172.      * A dump at the end of the scan of any unmatched tags is now made.
  173.        This should make the task of tracking down unclosed tags easier.
  174.      * More checking is now performed on <CENTER> and <QUOTE> tags.
  175.  
  176. 1.09 - Released 08-Nov-96:
  177.      * Added the extended command line functionality provided by Acorn's
  178.        "DDEUtils" module to the program.
  179.      * Changed the internal format of the storage of tags internally to
  180.        make it easier to add new tags.  This should make tracing backwards
  181.        through the tag-stack to find a tag matching a missing one easier to
  182.        implement.
  183.      * Added dozens of new tags found during my research for ZapHoTMeaL.
  184.      * <META> and <TITLE> tags are now only allowed in the header.
  185.      * <TT> tag added to list queried if strict checking is enabled.
  186.  
  187. 1.08 - Released 20-Oct-96:
  188.      * Added ability to follow "HRef="s in anchor tags.
  189.      * Added switch to control the above feature off.
  190.      * Added checking to "Background=" parameters of <BODY> tags.
  191.      * Added switches to control the reporting of non-local "HRef="s,
  192.        "Src="s and "Background="s.
  193.      * Strict checking now includes warnings about missing "alt=" parameters
  194.        in image tags, and missing "Text=", "BGColor=", "Link=", "VLink=" and
  195.        "ALink=" parameters in <BODY> tags which use background images.
  196.      * Added switch to make "Be very strict" mode optional.
  197.      * Cured bug causing occasional failure to find 'Src=' files if dozens
  198.        of them had already failed to be located.
  199.      * Tidied up a number of the reported messages.
  200.      * More options have been changed to their opposites.  Sorry if this
  201.        causes angst amongst users who are using batchfiles.  Once more, this
  202.        makes the command-line syntax more sensible.
  203.      * <HTML>, <BODY> and <TITLE> now all need to be missing for a fatal
  204.        error to be generated.  This is now trying to be especially kind to
  205.        errant files with poor headers.
  206.  
  207. 1.07 - Released 13-Oct-96:
  208.      * Queried <I> and <B> tags as some people have requested a strict mode
  209.        where these tags are faulted as being too specific in their nature,
  210.        with <EM> and <STRONG> tags being recommended in preference.
  211.      * "-v" [verbose] option changed to its opposite "-q" [quiet] partly to
  212.        benefit command-line users, and partly in order to reduce the length
  213.        of the command-line call which can cause problems if both your !Scrap
  214.        directory and !HTMLScan are buried deep in the directory structure.
  215.        Those who are upgrading are advised to delete their !Choices file
  216.        because of this change.
  217.      * Added start up message to tell people that the program is alive and
  218.        well.
  219.      * Added "Processing" file line to output so when processing multiple
  220.        files, accessing the command line is not needed when trying to find
  221.        out which output window relates to which file.
  222.      * <BODY> and <HTML> now both need to be missing for a fatal error to
  223.        be generated.  This is now in line with the specification for HTML.
  224.      * "Mismatched tags at end of file" warning replaced by a more specific
  225.        message with the number of tags involved listed.
  226.        
  227. 1.06 - Released 06-Oct-96:
  228.      * Corrected problems with some GIFs giving 'Unable to locate expected
  229.        comma in GIF file' errors.
  230.        
  231. 1.02 - Released 14-Sep-96:
  232.      * Corrected messages to remain agnostic with respect to differing <P>
  233.        conventions.
  234.      * Corrected bug associated with images higher in the directory tree
  235.        than the source HTML file (i.e. paths with "../" structures).
  236.      * Template file made more conventional by filling its buttons.
  237.  
  238. 1.01 - Released 04-Sep-96:
  239.      * Added support for <CENTER>, <P> and <STRONG> tags.
  240.      * Used "Squeeze" instead of proprietary compression because of
  241.        the possibility of StrongARM related problems.
  242.  
  243. 1.00 - Released 01-Aug-96:
  244.      * First version.
  245.  
  246. Enjoy
  247. __________ 
  248.  |im |yler  The Mandala Centre - tt@cryogen.com - http://www.mandala.co.uk
  249.