home *** CD-ROM | disk | FTP | other *** search
/ Dream 52 / Amiga_Dream_52.iso / Linux / Magazine / wwwoffle-2.1.tar.gz / wwwoffle-2.1 / UPGRADE < prev    next >
Text File  |  1997-12-19  |  5KB  |  122 lines
  1.           WWWOFFLE - World Wide Web Offline Explorer - Version 2.0
  2.           ========================================================
  3.  
  4. WHAT?
  5. -----
  6.  
  7. The format of the cache that wwwoffle uses to store the web pages has changed in
  8. version 2.x compared to the previous versions.  If you have used wwwoffle
  9. version 1.x then you *MUST* upgrade the existing cache before you can use the
  10. new version of the program.
  11.  
  12.  
  13. HOW?
  14. ----
  15.  
  16.          *** READ ALL THIS SECTION BEFORE DOING ANYTHING ELSE ***
  17.  
  18.  
  19. When you compile wwwoffle there is another program called 'upgrade-cache' that
  20. is also compiled.  You need to run this program to convert the cache from the
  21. old format to the new one.
  22.  
  23.  
  24. There are a number of options that you can take for this upgrade route, the
  25. following applies to all of them.
  26.  
  27. In each of the options the basics are that you must run upgrade-cache and it
  28. takes an argument of the name of the cache directory that is used (usually
  29. /var/spool/wwwoffle).  When the program runs it prints out informational and
  30. warning messages, these may be useful.
  31.  
  32.  
  33. Option 1 - Be reckless
  34.  
  35. Run 'upgrade-cache /var/spool/wwwoffle', watch the messages go flashing by and
  36. hope that it works.
  37.  
  38. Option 2 - Be brave
  39.  
  40. With sh/bash run 'upgrade-cache /var/spool/wwwoffle > upgrade.log 2>&1'
  41. or with csh/tcsh run 'upgrade-cache /var/spool/wwwoffle >& upgrade.log'
  42. read the messages and check the warnings.
  43.  
  44. Option 3 - Be safe
  45.  
  46. Backup the cache first then follow option 2.
  47. With GNU tar I suggest that you use the --atime-preserve option so that the
  48. access times of the files in the cache are not modified by performing the
  49. backup.  The index and purge options in wwwoffle use these so it is important.
  50.  
  51.  
  52. When it finishes, the multiple host named directories in /var/spool/wwwoffle are
  53. gone, moved into a new sub-directory called http.  The outgoing directory and
  54. this http directory are the only directories that should be left.
  55.  
  56. If there is a warning message then you should decide what needs doing.  It could
  57. be any of the following reasons:
  58.  
  59. That upgrade-cache was run by a user without write permissions.
  60. That one or more files were changed while the program was running.
  61. That there is a spare file in one of the host directories that needs deleting.
  62. That there is a symbolic link that does not point anywhere.
  63.  
  64.  
  65. If the upgrade-cache program crashes then that is a bug - tell me.
  66.  
  67. If you are left with many files or directories and the warnings are unclear then
  68. this may be a bug - tell me.
  69.  
  70. If there are only a small number of spare files or directories, then just delete
  71. them, you probably won't notice that they are missing.
  72.  
  73.  
  74. WHY?
  75. ----
  76.  
  77. The existing scheme for naming of the files in the cache had some problemsm, the
  78. new one is better.
  79.  
  80. 0) It was designed for my personal use which did not involve many web-pages
  81.    stored and did not visit any pages with unusual names,
  82.    You could say that the hacks that I implemented to get it working as I wrote
  83.    it were not well enough thought out.  But at the time I wrote it I wanted to
  84.    get it working as soon as possible and did not write it with the future
  85.    growth in mind.  The scheme as implemented has not caused any problems for me
  86.    personally.
  87.  
  88. 1) It was possible for a web-page that has several possible arguments to be
  89.    stored incorrectly.
  90.    This is because for each page that has arguments a hash value is computed
  91.    from the arguments to provide a unique filename.  The reason for this failing
  92.    is that I used a hash function that I made up on the spot, giving a 32-bit
  93.    hashed value.  This seemed to be sufficient for 4 billion sub-pages with the
  94.    same path name for each host and path combination.  As it turned out the hash
  95.    function was not strong enough and the number of possibilities was much
  96.    smaller.
  97.  
  98. 2) There was no provision for any protocol other than http.
  99.    Very quickly the idea of doing ftp as well came to my mind, but could not be
  100.    implemented easily or cleanly with the current system.
  101.  
  102. 3) The outgoing directory was inefficient for large numbers of files.
  103.    An increasing sequence of numbers was used resulting in slow access, this was
  104.    fixed in version 1.2x but there could still be many requests for the same URL
  105.    in the directory.  Now a unique name based on a hash is used so that only one
  106.    request for each page is stored.
  107.  
  108. 4) Bad characters and url-encoded URLs caused problems.
  109.    Some URLs that had funny characters including URL-encoded sequences caused
  110.    problems.  The URL http://www.foo.com/~bar and http://www.foo.com/%7Ebar are
  111.    the same URL but could be stored in different files.
  112.  
  113. 5) It is now a neater design with no special cases.
  114.    Previously only files with arguments needed hashing, now all of them use a
  115.    hash, this simplifies the logic.  The format of the outgoing directory is the
  116.    same as the other directories.
  117.  
  118. 6) There are more possibilities for future expansion.
  119.    It is now possible to consider adding more files to the cache to store extra
  120.    information about a URL, for example a password.  It is obvious now that this
  121.    would be another file with the same hash value but a different prefix.
  122.