home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / w3grab15.zip / wwwgrab2.eng < prev    next >
Text File  |  1997-12-16  |  44KB  |  1,160 lines
  1.  
  2.                          Welcome to WWWGrab/2 v1.5
  3.                          -------------------------
  4.  
  5. <Czech>
  6. ¼esk∞ návod je v souboru WWWGrab2.CZE.
  7. </Czech>
  8.  
  9. <Spanish>
  10. La versión en castellano es WWWGrab.SPA
  11. </Spanish>
  12.  
  13. <French>
  14. La documentation en français est dans le fichier WWWGRAB.FRA.
  15. </French>
  16.  
  17.  
  18. Table of Contents
  19. -----------------
  20. Introduction
  21. Requirements
  22. Copyright and Disclaimer
  23. Starting WWWGrab/2
  24. Regular Expressions
  25. Using `@' Files
  26. Macros
  27. Configuration File Format
  28. Command List - Detailed Reference
  29. Command List - Quick Reference
  30. Quick Reference Chart
  31. Predefined Variables
  32. Examples
  33. Credits
  34.  
  35.  
  36. Introduction
  37. ------------
  38. WWWGrab/2 is a utility for making a copy of a remote web site (or part of
  39. a site).  WWWGrab/2 makes a local copy, on your hard disk (or a network
  40. drive), of a remote WWW server's files, including HTML files, images, and
  41. more.
  42.  
  43. You need WWWGrab/2 if:
  44.  
  45.   * You are a web site administrator and need to mirror your site on
  46.     different machines.  You can configure WWWGrab/2 to run periodically
  47.     (by using a "cron"-type utility) and automatically keep your site
  48.     mirrored.
  49.   * You are having trouble getting a reliable or speedy connection to a
  50.     web site.  Let WWWGrab/2 spend the time downloading the pages - you
  51.     can look at them later.
  52.   * You are working on your own web page and want to see the HTML code to
  53.     someone else's page to see how they did it.
  54.   * You want to have a local copy of a web site for quick, easy reference.
  55.   * You want to make a copy of a web page or site because it may
  56.     disappear.
  57.   * You have a slow connection to the Internet, or simply don't like the
  58.     "World Wide Wait".
  59.   * You pay for Internet access by the minute.
  60.   * You frequently reference a Web site, but don't want to have to go
  61.     online every time you need to look at it.
  62.  
  63.  
  64. WWWGrab/2 offers many features that make it a very powerful and flexible
  65. tool for mirroring a web site, including:
  66.  
  67.   * Nearly 50 commands and options which provide maximum control and
  68.     flexibility over the program's operation.  (However, only a handful
  69.     are required in most cases.)
  70.   * Easy-to-use configuration files to let you control every option and
  71.     command in detail.  Configuration files may be nested, allowing common
  72.     commands and options to be automatically included, and you can have
  73.     separate configuration files for a single web site.
  74.   * U*IX-like regular expression strings for maximum flexibility and
  75.     control over filenames.
  76.   * A web site may be checked for modifications if it has been previously
  77.     mirrored.
  78.   * External programs can be run for every successfully downloaded file,
  79.     allowing unlimited customized actions.
  80.   * Logging of files successfully downloaded.
  81.  
  82.  
  83. Requirements
  84. ------------
  85. WWWGrab/2's requirements are simple and few:
  86.  
  87.      * OS/2 Version 2.11 or greater. Merlin or OS/2 Warp Connect suggested
  88.        for best performance.
  89.      * One  of the following TCP/IP  packages for OS/2 (listed in order of
  90.        preference):
  91.          * IBM TCP/IP included in OS/2 Warp Merlin.
  92.          * IBM TCP/IP 3.0 included in OS/2 Warp Connect.
  93.          * IBM TCP/IP 2.0 Base Kit with CSD64092 or greater applied.
  94.          * The Internet Access Kit from OS/2 Warp's Bonus pack.
  95.  
  96.      * A  disk  with  long  filename  support  (HPFS, ext2fs, etc.) is not
  97.        required but is strongly recommended!
  98.      * Approximately 100K for program files and documentation.
  99.      * Sufficient disk space for your mirroring.  Depending on how you use
  100.        WWWGrab/2, this may be as little as a few kilobytes or megabytes.
  101.  
  102.  
  103. Disclaimer etc.
  104. ---------------
  105.  
  106.                  This program is COPYRIGHTED by J. Rubes.
  107.  
  108.      WWWGrab/2  is  a  shareware product. It is distributed through public
  109. access  channels  so  that  prospective  buyers  have  the  opportunity to
  110. evaluate the product before making a decision to buy.
  111.  
  112.      WWWGrab/2  may  be  used  only  for  legal purposes. CHECK if you are
  113. allowed to mirror a site before doing so.
  114.  
  115.                             USE AT YOUR OWN RISK
  116.  
  117.      This  program  is  provided  AS IS without any warranty, expressed or
  118. implied,  including  but  not limited to fitness for a particular use. The
  119. user  is responsible for the results of correct or incorrect usage of this
  120. software. WWWGrab/2 may not be used to provide commercial services without
  121. written permission of the author.
  122.  
  123.  
  124. Starting WWWGrab/2
  125. ------------------
  126.      To  start  WWWGrab/2  simply  type  the  following at an OS/2 command
  127. prompt:
  128.  
  129.   WWWGRAB <config_file> [-i] [-c0|-c1]
  130.  
  131.      <config_file> is the configuration file to use. The configuration
  132. file is a plain ASCII  text file with commands and options that control
  133. WWWGrab/2's behavior. Its  format, and the commands and options available,
  134. are  described  below.  The  easiest way to create your first
  135. configuration file is to copy an existing demonstration file and change it
  136. to suit your needs.
  137.  
  138.      -i tells WWWGrab/2 to not load the default configuration file.
  139. Normally, the default configuration file (named "DEFAULT.W3D"), is
  140. processed when WWWGrab/2 is executed.  This file should contain commands
  141. and options that never change.  However, you can prevent WWWGrab/2 from
  142. processing the default configuration file by using the -i switch.  (See
  143. the Quick Reference Chart to see which commands and options may be used in
  144. DEFAULT.W3D.)
  145.  
  146.      -c0 or -c1 write a list of URLs modified since the site was last
  147. mirrored to the file W3GRAB.CHG:
  148.  
  149.    c0 - check sites without  the HEAD command.  This method is slower, but
  150.         safer.
  151.    c1 - check sites using the HEAD command.  This is faster, but less
  152.         safe, because some simple WWW servers don't accept the HEAD
  153.         command from a client, and return a error code. (Apache, CERN, ICS,
  154.         and Netscape behave correctly).
  155.  
  156.      Note that in order to use -c0 or -c1 the site must have previously
  157. been mirrored.
  158.  
  159.      WWWGrab/2  may  be called from command and REXX files and from
  160. Program objects on the OS/2 desktop.
  161.  
  162.  
  163. Regular expressions
  164. -------------------
  165.      WWWGrab/2  uses  U*IX-like  regular  expressions in some
  166. commands. This allows complex specifications such as
  167. http://www.foo.*/*/index.htm* or   c??. This allows   considerably wider
  168. flexibility  in  URL  specification,  or  in extension specification,  or
  169. any other circumstance in which this type of pattern matching is wanted.
  170.  
  171. In the specified pattern string:
  172.      `*' matches any sequence of zero or more characters.
  173.      `?' matches any single character.
  174.      `\' suppresses the syntactic significance of a special character.
  175.      [SET] matches any character in the specified set.
  176.      [!SET] or [^SET] matches any character NOT in the specified set.
  177.  
  178.      A  set  is  composed  of individual characters  or  character ranges.
  179. A range is two characters separated by a hypen (0-9 or A-Z, for example).
  180. Numerals, letters (uppercase and lowercase), and the underscore (`_') are
  181. the minimal  set  of  characters  supported in patterns.  Nearly all
  182. operating systems support additional (8-bit) characters.
  183.  
  184.      The `escape character' (`\') is used to  suppress the syntactic
  185. significance of the characters `[]*?!^-\', so that such a character may be
  186. matched. For example, the pattern string `file\*' matches the string
  187. `file*', not the string beginning with `file\' and followed by zero or
  188. more characters; the pattern string `file\[*' matches the string `file['
  189. followed by zero or more additional characters.
  190.  
  191.      See the Quick Reference Chart to see which commands support regular
  192. expressions.
  193.  
  194.      Examples:
  195.         file*
  196.           Match any string beginning with the letters `file', such as
  197.           `file', `filestar', `file100'.
  198.         ??file
  199.           Match any six-character string ending in `file', such as
  200.           `00file', `dofile', etc.
  201.         file[abc]*
  202.           Match any string beginning with the letters `file', followed by
  203.           `a', `b', or `c', followed by zero or more characters, such as
  204.           `filea', `filea100', `fileabcd'.
  205.         file[0-9]\-?
  206.           Match any string beginning with the letters `file', followed by
  207.           a numeral 0-9, followed by a hypen `-', followed by any
  208.           character, such as `file3-a', `file0-0', etc.
  209.  
  210.  
  211. Using `@' Files
  212. ---------------
  213.      You  are likely to use the same commands and options for multiple web
  214. sites.  These can be stored in the default configuration file if they
  215. never change, but include files (`@' files) provide greater flexibility,
  216. letting you store options and commands common to only some sites.  Include
  217. files are referenced by the main configuration file (specified on the
  218. command line).
  219.  
  220. For example, if you often use the MASK command, you may store it in the
  221. DEFAULT.W3G file and it will be applied to all configuration files.  But
  222. if you want to use two different MASKs for different sites, you must use
  223. an include file.  To do this, you must create two include files, and then
  224. reference the correct include file in each configuration file.
  225.  
  226. Make one file called (for example) MASKS1 with the following text.  This
  227. will be the first include file:
  228.  
  229. *.HTML
  230. *.HTM
  231. *.?.JPEG
  232. *.0?.GIF
  233.  
  234. Then create the second include file named (for example) MASKS2 with this
  235. text:
  236.  
  237. *.SHTML
  238. *.SHTM
  239. *.JPEG
  240. *.GIF
  241. *.WAV
  242.  
  243. Note that the include file must contain only one parameter per line.
  244.  
  245. Finally, reference the appropriate include file from the configuration
  246. file.  For example, to use MASKS1 add the following line to the
  247. configuration file:
  248.  
  249. MASK @MASKS1 ; use contents of the MASKS1 file
  250.  
  251. When WWWGrab/2 reads the configuration file, it will read the parameters
  252. for the MASK command from the MASKS1 file.  NOTE: Don't forget the `@'
  253. sign in front of the filename!
  254.  
  255. You may use multiple include files with the same command, as long as the
  256. command may be used more than once.  For example, to reference both MASKS1
  257. and MASKS2 add the two lines below to the configuration file:
  258.  
  259. MASK @MASKS1  ; use contents of the MASKS1 file
  260. MASK @MASKS2  ; and add contents of the MASK2 file
  261.  
  262.      If  you  had  used  just MASK @MASKS2, then only *.SHTML, *.SHTM,
  263. *JPEG, *.GIF, and *.WAV files would be mirrored.
  264.  
  265. See the Quick Reference Chart to see which commands support include files.
  266.  
  267.  
  268. Macros
  269. ------
  270. WWWGrab/2 allows you to define and then use simple text-replacement macros
  271. similar to the facilities provided by makefiles.  The syntax is:
  272.  
  273.  #define <var> [value]
  274.  
  275. The <var> is the variable to be defined, and [value] is its optional
  276. value.
  277.  
  278. Examples:
  279.  #define NOBIN
  280.  Creates a variable called NOBIN, with no value
  281.  
  282.  #define USERPATH c:\jirir
  283.  Creates a variable called USERPATH and assigns it the value c:\jirir
  284.  
  285. There are two ways to use a variable.  The first way is as simple text
  286. expansion.  For example, given the above definition of USERPATH, the
  287. following two lines are identical:
  288.  
  289.  LOCALPATH $(USERPATH)\mirrors
  290.  LOCALPATH c:\jirir\mirrors
  291.  
  292. You should consider using a variable in this fashion whenever you need to
  293. change the same text in different places repeatedly.  Create a variable
  294. near the top of the .INI file, and reference it instead of the actual
  295. text; then, when the text needs to be changed it only has to be done once.
  296.  
  297. The second way to use variables is within a conditional expression.  A
  298. conditional expression can change which statements in the .INI file will
  299. be read.  The syntax is:
  300.  
  301. #ifdef <var>     - OR -
  302. #ifndef <var>
  303. ...
  304. #else
  305. ...
  306. #endif
  307.  
  308. If the given variable is defined (it does not need to have a value), the
  309. lines below the #ifdef (IF DEFined) are read.  If the variable is not
  310. defined, the lines below the #else are read.  The #endif denotes the end
  311. of the conditional.  #ifndef (IF Not DEFined) reverses the logic, reading
  312. the statements belows the #ifndef if the variable is not defined and the
  313. statements below the #else if it is defined.  Examples:
  314.  
  315. #ifdef __OS2__
  316. LOCALPATH c:\wwwgrab2\mirrors
  317. #else
  318. #ifdef __UNIX__
  319. LOCALPATH /home/w3g/mirrors
  320. #else
  321. LOCALPATH c:\wwwgrab95\mirrors
  322. #endif
  323. #endif
  324.  
  325. This will set the LOCALPATH based on which operating system the user is
  326. using.  (The OS2 and UNIX variables are predefined.)
  327.  
  328. Conditionals may be nested to eight levels.
  329.  
  330. For a list of predefined variables, see the Predefined Variables section.
  331.  
  332.  
  333. Configuration File Format
  334. -------------------------
  335. All commands and options in the configuration file have the same format:
  336.  
  337. <command> [parameters]
  338.  
  339. There may be spaces before the command, and there must be at least one
  340. space after the command if there are any parameters supplied.
  341.  
  342. Single line comments are preceded by a semi-colon (`;'). Text following
  343. the semi-colon is ignored until the next line is reached.  Examples:
  344.  
  345. URL http://www.foo.com/bar      ; This is a comment
  346. ; This is also a comment.
  347.  
  348. All URLs must be in the full http format.  Always use
  349. `http://www.foo.com', not `foo', `foo.com', or `www.foo.com'.  You may
  350. use IP addresses and port numbers, e.g. `http://127.0.0.1/localhost/' or
  351. `http://www.foo.com:8080/misc'.
  352.  
  353.  
  354. Command List - Detailed Reference
  355. ---------------------------------
  356. Following is a detailed reference to each of the commands and options
  357. which control WWWGrab/2's behavior.
  358.  
  359.  
  360. ADD <path>
  361.      Add  the  specified path to the list of requested URL's. This command
  362.      can  be  used  more  than  once,  and always applies to the first URL
  363.      command.
  364.  
  365.      Example:
  366.        URL http://www.xxx.yyy/path1/index.html
  367.        URL http://foobar.com/
  368.        ADD /path2/pic/index.html
  369.          Mirrors: http://www.xxx.yyy/path1/index.html      AND
  370.                   http://www.xxx.yyy/path2/pic/index.html  AND
  371.                   http://foobar.com/
  372.  
  373.  
  374. ALL
  375.      Normally,  if WWWGrab/2 sees that a file already exists, it will send
  376.      a  conditional  GET to the remote server. The file is only downloaded
  377.      again  if  the version on the server is newer than the local file. If
  378.      you  want  to update all the files regardless of their date and local
  379.      existence, you should use the ALL option.
  380.  
  381.  
  382. ALLOW <URL-in-http-form>
  383.      Explicitly  specifies  that  a  subtree  is retrievable. This command
  384.      can be used more than once and may use regular expressions.
  385.  
  386.      Example:
  387.        ALLOW http://www.xxx.yyy/allow/this/path/
  388.  
  389.  
  390. CHAM <number>
  391.      Some  servers  (esp.  Netscape)  try to recognize the client name. If
  392.      they  don't  know  the client name, they don't send any data. You may
  393.      use  this  option to "mask" the client name (like CHAMeleon). Numbers
  394.      are:
  395.           0 - WWWGrab        (default)
  396.           1 - Mozilla        Netscape Browser
  397.           2 - WebExplorer    IBM WebExplorer/2
  398.           3 - WebCrawler     WebCrawler robot
  399.           4 - InfoSeek       InfoSeek robot
  400.           5 - Harvest        a web robot
  401.           6 - Mosaic         NCSA Mosaic
  402.           7 - Lynx           Lynx, text browser
  403.           8 - PRODIGY-WB     Prodigy browser
  404.           9 - Internet       Microsoft's web browser
  405.  
  406.  
  407.     Example:
  408.       CHAM 2
  409.         Sends the server the WebExplorer client name.
  410.  
  411.  
  412. CHANGESITE <num sites>
  413.      Normally,  if WWWGrab/2 finds a link to another WWW server in an html
  414.      file,  the  link is ignored. If you want to allow WWWGrab/2 to follow
  415.      links  to  another server, use the CHANGESITE command. The default is
  416.      0,  which  means  don't change sites. BE CAREFUL what you enter here!
  417.      You may start mirroring the entire WWW!
  418.  
  419.      Example:
  420.        CHANGESITE 2
  421.  
  422.  
  423. CLIENT
  424.      When the CLIENT option is used, WWWGrab/2 turns all links to relative
  425.      links.  <a href="/www/files/foo.html"> becomes <a href=foo.html"> for
  426.      example.  Use  this  option  if  you want to be able to browse a site
  427.      locally.  (Note that server-side-includes, CGI programs, and Java
  428.      programs will not work when a site is browsed locally as these
  429.      features require an HTTP server.)
  430.  
  431.  
  432. DEFAULTNAME <name>
  433.      Sometimes links point to a directory instead of a file. In this case,
  434.      if  the  filename  is  not  known  the  DefaultName  is used for that
  435.      directory. The default value for DefaultName is "index.html".
  436.  
  437.      Example:
  438.      DEFAULTNAME Welcome.html
  439.  
  440.  
  441. DENY  <URL-in-http-form>
  442.      The  URL  provided,  as  well  as  all  subtrees  of the URL, are not
  443.      processed.  Many times specific directory subtrees are not desirable.
  444.      You  can  deny retrieval of these URL's using this setting. It can be
  445.      used more than once, and regular expressions can be used too.
  446.  
  447.      Example:
  448.        DENY http://www.xxx.yyy/deny/this/path/
  449.        Do not download any files from the /deny/this/path/ tree.
  450.  
  451.      If      you     do     not     include     the     trailing     slash
  452.      (http://www.xxx.yyy/deny/this/path) then all subdirectories beginning
  453.      with   "path"   are   not   processed.  This  includes  "paths.html",
  454.      "path1/news", etc.
  455.  
  456.  
  457. DO <DEF | HTML | IMG | SND> <NOTHING | command>
  458.      This  command allows you execute a command for every
  459.      successfully downloaded file. You may specify different commands for
  460.      different file types.  If no command is associated with a particular
  461.      type, the default (DEF) command is executed.  You may use the
  462.      following options in the command:
  463.          %d depth
  464.          %h host (www server)
  465.          %l local full filename
  466.          %p parent URL (where this link came from)
  467.          %r remote file (URL without host)
  468.          %t file timestamp in RFC 822 format
  469.          %u URL
  470.          %% % (percent sign)
  471.  
  472.      NOTE: Use of the '%' options is discouraged in favor of the
  473.      predefined variables.  For more information, see the Macros and
  474.      Predefined Variables sections.
  475.  
  476.      If  you don't want to execute any command for specified type, but you
  477.      want to execute the DEF command, then specify NOTHING as the command.
  478.      Types are:
  479.            HTML - file defined with the text/html content
  480.            IMG  - file defined with the image/*   content
  481.            SND  - file defined with the audio/*   content
  482.            DEF  - any other file
  483.  
  484.  
  485.      Programs  that are spawned operate concurrently with WWWGrab/2 and
  486.      may  OVERLOAD  your  system. Spawned applications include those begun
  487.      with "start".
  488.  
  489.      Example:
  490.        DO HTML start /b html2txt %l
  491.        ; spawn html2txt on the background for each html file
  492.        DO SND play file=%l
  493.        ; plays grabbed sound files
  494.        DO IMG NOTHING
  495.        ; does nothing for image files
  496.        DO DEF echo %u >>other.files
  497.        ; logs other grabbed files
  498.  
  499.  
  500. EXCL <www-server>
  501.      This  command  defines  a  WWW server to exclude from mirroring. This
  502.      command  is  usable  together  with the CHANGESITE command. It can be
  503.      used more than once.
  504.  
  505.      Example:
  506.        EXCL www.yyy.zzz
  507.        EXCL microsoft.is.lame.org      BTW: try this URL :-)
  508.  
  509.  
  510. EXTENSIONS <list of extensions>
  511.      The  EXTENSIONS  command  defines  a  list  of  file extension search
  512.      strings  which  are  to  be downloaded. Extensions are seperated by a
  513.      space.  If  you  don't  specify  any extension, then HTM, HTML, SHTM,
  514.      SHTML,  JPG, GIF, WAV, AU, CLASS, and JAVA are automatically defined.
  515.      You  may  alternatively  use the ':' char as a 'NOT' operator to list
  516.      extensions  which  you  wish to ignore. Be careful what you put here!
  517.      Including  EXE  or  ZIP  extensions could use vast quantities of disk
  518.      space  if you start mirroring a large site such as hobbes or sunsite!
  519.      You may use regular expressions in this command (see above), and this
  520.      command may be used more than once.
  521.  
  522.      Example:
  523.        EXTENSIONS ZIP C
  524.        Use ZIP and C extensions
  525.  
  526.        EXTENSIONS ZIP JAVA :C??
  527.        Use ZIP and JAVA, but C++, C--, C00...
  528.  
  529.  
  530. FAT
  531.      This option turns on FAT compatibility. In this mode WWWGrab/2 stores
  532.      all  mirrored  files in a single directory using the FAT 8.3 filename
  533.      format.  It  automaticaly  fixes  links.  This option is automaticaly
  534.      turned on if the local path (LOCALPATH) is located on a FAT partition
  535.      or on a partition without long filename support.
  536.  
  537.  
  538. FIXSL
  539.      Sometimes  authors of web pages do not add a trailing slash to links.
  540.      You may use the FIXSL option to fixing their "slash-forgetting".
  541.  
  542.  
  543. HUP <mins>
  544.      The HUP command allows you to restrict how long WWWGrab/2 will work,
  545.      in minutes.  When the time limit is reached, WWWGrab/2 will exit.  If
  546.      a file is being transferred, WWWGrab/2 will exit after it finishes
  547.      transferring the file.
  548.  
  549.      Example:
  550.       HUP 90
  551.       WWWGrab/2 will work for 90 minutes and then stop.
  552.  
  553.  
  554. HUPF <filename>
  555.      This command tells WWWGrab/2 to create the specified file when it
  556.      exits to the operating system.
  557.  
  558.      Example:
  559.       HUPF c:\work\wwwhup.
  560.       WWWGrab/2 will create the file c:\work\wwwhup when it exits.
  561.  
  562.  
  563. I401
  564.      If  WWWGrab/2  sends  a  conditional GET to a protected page, and the
  565.      page  isn't  modified, some servers return a 401 status code. You may
  566.      use I401 to override this response and download the file.
  567.  
  568.  
  569. INCLUDE <file>
  570.      This  commmand  allows you to include another configuration file into
  571.      the configuration file currently being processed. Nesting is allowed,
  572.      to  a maximum depth of 4 levels. This command is useful for including
  573.      commands which are used in multiple configuration files. See also '@'
  574.      files.
  575.  
  576.      Example:
  577.        INCLUDE realms.inc
  578.        INCL    urls.inc
  579.  
  580.  
  581. IRO
  582.      Some web sites have a file that tells webcrawlers and other automated
  583.      programs such as WWWGrab/2 which files they may download.  Normally,
  584.      WWWGrab/2 will look for this file and obey the restrictions in it.
  585.      If you wish to ignore this file, use the IRO (Ignore RObot file)
  586.      option. WWWGrab/2 will then download all files (subject to
  587.      restrictions from other commands and options).
  588.  
  589.  
  590. ISO9660
  591.      This option forces WWWGrab/2 to save all files using the ISO9660
  592.      file naming system, a popular format for CD-ROMs.  The ISO9660 format
  593.      allows only uppercase letters, digits, and the underscore character
  594.      in filenames.
  595.  
  596.  
  597. LOCALPATH <path>
  598.      WWWGrab/2  must  have  a  place to store the files it downloads. This
  599.      command  tells  WWWGrab/2  the path on your local machine under which
  600.      the URL will be mirrored.
  601.  
  602.      Example:
  603.        LOCALPATH F:\GRAB\IBM\
  604.        Stores files mirrored under the F:\GRAB\IBM\ directory.
  605.  
  606.  
  607. LOG <log-file> <log-string>
  608.      This  commands  logs  all  successfully  mirrored files to the file
  609.      <log-file> in the format described in <log-string>. In the log-string
  610.      you may use these special characters:
  611.          %d depth
  612.          %h host (www server)
  613.          %l local full filename
  614.          %p parent URL (where this link came from)
  615.          %r remote file (URL without host)
  616.          %t file timestamp in RFC 822 format
  617.          %u URL
  618.          %% % (percent sign)
  619.          \n new line
  620.          \t tab
  621.          \\ \ (backslash)
  622.  
  623.   Note:  The LOG command doesn't automatically append the CRLF at the end
  624.          of each string.
  625.  
  626.   Example:
  627.     LOG foo.log URL %u is stored in %l\n
  628.     Will produce:
  629.       URL http://www/index.html is stored in \grab\www\index.html
  630.       URL http://www/foo/foo.gif is stored in \grab\www\foo\foo.gif
  631.       ...
  632.  
  633.  
  634. MAP
  635.      This  option  turns  on  creating  of  a map file. This file is named
  636.      w3gmap.htm.  The map file contain a map of the mirrored site. You may
  637.      use it later for to manually.
  638.  
  639.  
  640. MASK <file mask>
  641.      Use  this  command  if  you want to mirror only specified files. This
  642.      command  overrides  EXTENSIONS. You MUST explicitly define every file
  643.      mask if using this command, including the defaults in EXTENSIONS such
  644.      as HTML, etc.! This command can be used more than once. The file mask
  645.      can  have  wildcard  characters  (special  characters  for  character
  646.      substitution). See the part named "regular expressions".
  647.  
  648.      Example:
  649.        MASK *.jpg
  650.          Will mirror all files with the .jpg extension
  651.  
  652.        MASK ?a*.html
  653.          Will mirror all files beginning with any character,
  654.          followed by 'a', having any number of characters following,
  655.          and ending with .html, such as zaphod.html, 0a.html, etc.
  656.  
  657.        MASK *.jpg s?n.htm* do*s.large.i*x *.*.html.c*
  658.          Will mirror one.jpg, two.jpg, sin.htm, son.htm, sun.html,
  659.          dogs.large.idx, doorways.large.index, index.short.html.cz852,
  660.          index.of.html.cz.html, try.decode.html.c, etc...
  661.  
  662.  
  663.        MASK *.jp*g chapter[0-4].htm*
  664.          Will mirror any jpg or jpeg file, and chapter0.htm, chapter1.htm,
  665.          chapter0.html, chapter1.html, chapter2.htm, chapter3.html, but
  666.          not chapter5.html.
  667.  
  668.  
  669. MAXDEEP <levels>
  670.      MaxDeep  defines  how  many  subdirectory  levels deep WWWGrab/2 will
  671.      mirror.  Pages  which  are  lower than <levels> subdirectories in the
  672.      tree are ignored.
  673.  
  674.      Example:
  675.        MAXDEEP 5
  676.        Will get http://www.foo.com/1/2/3/4/5/file.html but not
  677.        http://www.foo.com/1/2/3/4/5/6/file.html
  678.  
  679.      NOTE: The shareware version of WWWGrab/2 is limited to 5 levels.
  680.  
  681.  
  682. MAXDL <limit>
  683.      This defines the maximum number of kilobytes WWWGrab/2 will download.
  684.      When  WWWGrab/2  is about to download a file, it checks the filesize.
  685.      If downloading the file would exceed the limit specified in MAXDL,
  686.      WWWGrab/2 will ignore the file.
  687.  
  688.      Example:
  689.        MAXDL 3
  690.          Download up to 3KB.
  691.  
  692.  
  693. MAXFSIZE <file-size-in-kb>
  694.      You  may  use  this  command to set the largest allowable filesize to
  695.      mirror, in kilobytes. Files larger than the size set by MAXFSIZE will
  696.      be  ignored.  This  command  does  not  work with servers which don't
  697.      return the content length.
  698.  
  699.      Example:
  700.        MAXFSIZE 100
  701.         Will not mirror files larger than 100kb.
  702.  
  703.  
  704. MAXTRIES <num>
  705.      MaxTries  tells WWWGrab/2 how many times it should try to get a file.
  706.      WWWGrab/2  tries  to grab all the files sequentially. If a file isn't
  707.      successfully  retrieved on the first attempt, it is ignored until the
  708.      complete list has been processed. Then WWWGrab/2 retries files missed
  709.      on  the  first  attempt. This process is repeated until all the files
  710.      are retrieved or MAXTRIES attempts have been made.
  711.  
  712.      Example:
  713.        MAXTRIES 3
  714.  
  715.  
  716. METAFILE <filename>
  717.      This command specifies the file WWWGrab/2 uses for saving information
  718.      about  mirrored  files.  The  default  filename is META.DAT, which is
  719.      stored in the LOCALPATH\%host% directory.
  720.  
  721.      Example:
  722.        META data.met
  723.  
  724.  
  725. NICE [delay]
  726.      This command defines the adjustable delay in seconds between links so
  727.      you  don't hog all the resources of the system you're mirroring from.
  728.      If  you  use  this  command  without a value, WWWGrab/2 will delay 10
  729.      seconds  before  requesting  the  next  file.  Warning: WWWGrab/2 can
  730.      generate  requests  too  fast  for  some  servers.  Setting  the NICE
  731.      parameter  too  low may generate too many requests for the server and
  732.      crash  the  server. This is not nice :-). A low NICE setting is known
  733.      to kill the following types of servers:
  734.  
  735.           All WWW servers that run under Microsoft Windows(TM)
  736.           Old generation (HTML/1.0) CERN servers on all platforms
  737.  
  738.      Low  NICE  values  may also generate large amounts of network traffic
  739.      and  hog  network  resources.  For  safety,  you  should set the NICE
  740.      value  to  at  least  five seconds. The longer, the better. Remember,
  741.      this  program  is automated and can easily run for hours with no user
  742.      interaction.
  743.  
  744.      Example:
  745.        NICE 5
  746.  
  747.      NOTE:  If  you  try to set a NICE value of 0 (zero), the value
  748.             will be automatically changed to five seconds.
  749.  
  750.  
  751. NOAPPLET, NOIMG, NOOTH, NOSND, NOVID
  752.      Each mirrored file has a "Content-type:" field in the header which
  753.      describes what type of file it is (application, image, sound, text,
  754.      video, or other).  These options allow you to tell WWWGrab/2 which
  755.      types of files you do not want to mirror.  The commands and content
  756.      types are:
  757.  
  758.      NOAPPLET
  759.       Ignore application files.
  760.  
  761.      NOIMG
  762.       Ignore image files.
  763.  
  764.      NOOTH
  765.       Ignore files of type "other" (e.g. not application, image, sound,
  766.       text, or video).
  767.  
  768.      NOSND
  769.       Ignore audio (sound) files.
  770.  
  771.      NOVID
  772.       Ignore video files.
  773.  
  774.  
  775. OHTML
  776.      This option combines NOIMG, NOSND, NOOTH, NOVID and NOAPPLET.
  777.  
  778.  
  779. PPORT <proxy port>
  780.      This  command specifies the proxy port. The default value is 80. This
  781.      command is ignored if no proxy is specified with the PROXY command.
  782.  
  783.      Example:
  784.        PPORT 8080
  785.  
  786.  
  787. PROXY <hostname>
  788.      Use this command if you access the Internet via a Proxy server/cache.
  789.      The <hostname> may be the full hostname (i.e. proxy.foo.com) or an IP
  790.      address.  If  you're  uncertain  about  this,  counsult  your  system
  791.      administrator or internet service provider.
  792.  
  793.      Examples:
  794.        PROXY www.proxy.server
  795.  
  796.        PROXY 123.456.789.10
  797.  
  798.  
  799. PROXYAUTH <base64>
  800.      Use the PROXYAUTH command if you access the Internet through a
  801.      secured proxy server.
  802.  
  803.      Example:
  804.        PROXY     secured.proxy.net
  805.        PROXYAUTH LTot
  806.  
  807.  
  808. REALM <host> <"Realm Name"> <encoded username and password>
  809.      Defines   a   secured   host,   a  realmname  and  a  base64  encoded
  810.      username+password. REALM can be used more than once. The realmname is
  811.      CaSe  SeNsItIvE!  If  you  don't know the realmname you may insert an
  812.      empty   string  (i.e.  ""),  or  examine  WWWGRAB.LOG.  The  host  is
  813.      basic-auth  secured  host.  It may be in IP format (1.22.33.44) or in
  814.      the  standard  "domain" format (www.foo.com). Realms are generated by
  815.      the  makeauth program. You may use the INCLUDE command to include its
  816.      output into the configuration file.
  817.  
  818.      Example:
  819.        REALM www.secured.host "This is ReaLmName" LTot
  820.  
  821.  
  822. REMOVE
  823.      This  option  informs  WWWGrab/2  to  remove unused links from a HTML
  824.      file. Links are not deleted, but only commented out.
  825.  
  826.  
  827. REPL <path>
  828.      Specifies a path which replaces the LOCALPATH in a link. For example,
  829.      if    you    specify   "REPL   /mirrors"   and   the   LOCALPATH   is
  830.      F:\OS2Httpd\HTML\GRAB\,  for  a  link in the grabbed HTML document to
  831.      "<A  HREF="/some/pages/index.html"> link </a>", the replaced filename
  832.      is   "F:\OS2Httpd\HTML\GRAB\www.foo.com\some\pages\index.html".   The
  833.      link in the document will be changed to:
  834.      "/mirrors/www.foo.com/some/pages/index.html"
  835.  
  836.      Example:
  837.        REPL /mirrors
  838.  
  839.  
  840. SITELIST <hostname>
  841.      Normally,  if  WWWGrab/2  finds a link to another web site in an html
  842.      file,  the  link  is  ignored.  You  can  use the SITELIST command to
  843.      specify  allowed  hosts.  You  may  use  the  ':'  character as a NOT
  844.      operator. This command can be used more than once.
  845.  
  846.      Example:
  847.        SITELIST www.xxx.yyy
  848.          Allow connections to site www.xxx.yyy.
  849.  
  850.        SITELIST :www.xxx.yyy
  851.          All websites except www.xxx.yyy.
  852.  
  853.      NOTE: This command overrides the CHANGESITE command!
  854.  
  855.  
  856. SWSLASH
  857.      This option turns left slashes to right slashes i.e. from '/' to '\'.
  858.      It's useful for "older|dumber" browsers.
  859.  
  860.  
  861. TIMC <sec>
  862.      The TIMC command tells WWWGrab/2 what the server timeout value is.
  863.      If  WWWGrab/2  didn't  get  a  response from server in time less than
  864.      timeout,  then  close  the connection to server. This value should be
  865.      less  than or equal to TIMP and greater than 10. The default value is
  866.      60  seconds.  Do not use this command if you don't understand what it
  867.      does!
  868.  
  869.      Example:
  870.        TIMC 100
  871.  
  872.  
  873. TIMP <sec>
  874.      The TIMP command tells WWWGrab/2 what the timeout is for packets. The
  875.      connection  is closed after timeout. The default value is 60 seconds.
  876.      The  value  should  be  grater than 10. Don't use this command if you
  877.      don't understand what it does!
  878.  
  879.      Example:
  880.        TIMP 120
  881.  
  882.  
  883. TOP <URL-in-http-form>
  884.      Defines  the  TOP  of  the  path.  WWWGrab/2  will  ignore  files  in
  885.      directories  higher  than  this path. In other words, the path of the
  886.      file  must  start  with this string. You may use regular expressions.
  887.      This command can be used more than once.
  888.  
  889.  
  890.      Example:
  891.        TOP http://www.foo.com/path/xxxx/
  892.          Ignore files above /path/xxxx/, i.e. DON'T mirror /path/some.file
  893.        TOP http://www.*.net/java/
  894.  
  895.  
  896. URL <url-in-the-http-form>
  897.      This  command tells WWWGrab/2 a site you wish to mirror. The complete
  898.      URL  of  the  site is required! The URL command can be used more than
  899.      once  to  mirror  multiple  sites or multiple directories on the same
  900.      site. This is a basic command :-)
  901.  
  902.      Example:
  903.        URL http://www.geocities.com/SiliconValley/Heights/7262/index.html
  904.  
  905.  
  906.  
  907. Command List - Quick Reference
  908. ------------------------------
  909. Following is a quick reference to the nearly 50 commands and options which
  910. control WWWGrab/2's behavior.
  911.  
  912. ADD <path>            Add specified path to the list of requested URLs.
  913. ALL                   Update all files regardless of date (get all files).
  914. ALLOW <URL>           Explicitly specify a subtree to be retrievable.
  915. CHAM <number>         Fake a client name (chameleon).
  916. CHANGESITE <num>      Follow <num> links to other servers.
  917. CLIENT                Change links to be relative, for local browsing.
  918. DEFAULTNAME <name>    Set default HTML filename for directories.
  919. DENY <URL>            Prevent processing of <URL> tree.
  920. DO <option> <cmd>     Execute <cmd> on DEF|HTML|IMG|SND file.
  921. EXCL <server>         Exclude WWW server from mirroring.
  922. EXTENSIONS <list>     Allowable file extensions to download.
  923. FAT                   Enable FAT filesystem compatibility.
  924. FIXSL                 Add trailing slash to links which do not have one.
  925. HUP <min>             Restrict how long WWWGrab/2 will work.
  926. HUPF <file>           Create the specified file when WWWGrab/2 exits.
  927. I401                  Override I401 error and enable download of file.
  928. IRO                   Ignore the robots file.
  929. ISO9660               Enable ISO 9660 filesystem compatibility (CD FS).
  930. INCLUDE <file>        Insert another configuration file at this point.
  931. LOCALPATH <path>      Local path to store mirrored files.
  932. LOG <file> <string>   Log to <file> using <string>.
  933. MAP                   Create HTML map of mirrored site.
  934. MASK <mask>           Explicitly set allowable file extensions.
  935. MAXDEEP <levels>      How many subdirectory levels to mirror.
  936. MAXDL <limit>         Maximum kilobytes to download.
  937. MAXFL <size>          Maximum filesize to download.
  938. MAXTRIES <num>        Maximum number of tries to get file.
  939. METAFILE <file>       Specify metafile filename.
  940. NICE <seconds>        Delay for <seconds> after each get.
  941. NOAPPLET              Do not download applets.
  942. NOIMG                 Do not download images.
  943. NOOTH                 Do not download "other" files.
  944. NOSND                 Do not download audio files.
  945. NOVID                 Do not download video files.
  946. OHTML                 Combine NOIMG, NOSND, NOOTH, NOVID and NOAPPLET.
  947. PPORT <port>          Specify proxy port.
  948. PROXY <hostname>      Specify proxy host.
  949. PROXYAUTH <base64>    Specify proxy authorization.
  950. REALM <h> <rlm> <pw>  Define secure host, realm, and username/password.
  951. REMOVE                Remove unused links from HTML files.
  952. REPL <path>           Replace local path in a link.
  953. SITELIST <host>       Allow connections to <host>.
  954. SWSLASH               Convert forward slashes to backslashes.
  955. TIMC <sec>            Server timeout value.
  956. TIMP <sec>            Server timeout value for packets.
  957. TOP <URL>             Defines top of path (don't dl files above this).
  958. URL <URL>             URL of site to mirror.
  959.  
  960.  
  961. Quick Reference Chart of Commands and Options
  962. ---------------------------------------------
  963.  
  964. COMMAND       SHORTCUT  '@'    DEFCFG  OVERRIDES  DEFVAL   REX  REG  MULT
  965. --------------------------------------------------------------------------
  966. ADD                     YES    NO                          NO   NO   YES
  967. ALL                     NO     NO                          NO   NO   NO
  968. ALLOW                   YES    NO                          YES  YES  YES
  969. CHAM                    NO     YES                0        NO   NO   NO
  970. CHANGESITE    CHSIT     NO     NO                 0        NO   YES  NO
  971. CLIENT                  NO     YES                         NO   NO   NO
  972. DEFAULTNAME   DEF       NO     YES                [3]      NO   YES  NO
  973. DENY                    YES    NO                          YES  YES  YES
  974. DO                      NO     YES                         NO   YES  NO
  975. EXCL                    YES    NO                          YES  NO   YES
  976. EXTENSIONS    EXT       YES    YES                [1]      YES  YES  YES
  977. FAT                     NO     YES                         NO   NO   NO
  978. FIXSL                   NO     YES                         NO   NO   NO
  979. HUP                     NO     YES                         NO   NO   NO
  980. HUPF                    NO     YES                         NO   NO   NO
  981. I401                    NO     YES                         NO   NO   NO
  982. INCLUDE       INCL      NO     NO                          NO   NO   YES
  983. IRO                     NO     YES                         NO   YES  NO
  984. ISO9660                 NO     YES                         NO   NO   NO
  985. LOCALPATH     LOP       NO     YES                [0]      NO   NO   NO
  986. LOG                     NO     YES                         NO   YES  NO
  987. MAP                     NO     YES                         NO   NO   NO
  988. MASK                    YES    YES     EXTENSIONS          YES  YES  YES
  989. MAXDEEP       MDP       NO     YES                1        NO   [2]  NO
  990. MAXDL                   NO     YES                         NO   NO   NO
  991. MAXFL                   NO     YES                         NO   NO   NO
  992. MAXTRIES      MTR       NO     YES                         NO   NO   NO
  993. METAFILE      META      NO     NO                          NO   NO   NO
  994. NICE                    NO     YES                10       NO   NO   NO
  995. NOAPPLET      NOAP      NO     YES                         NO   NO   NO
  996. NOIMG                   NO     YES                         NO   NO   NO
  997. NOOTH                   NO     YES                         NO   NO   NO
  998. NOSND                   NO     YES                         NO   NO   NO
  999. NOVID                   NO     YES                         NO   NO   NO
  1000. OHTML                   NO     YES     [4]                 NO   NO   NO
  1001. PPORT                   NO     YES                80       NO   NO   NO
  1002. PROXY                   NO     YES                         NO   NO   NO
  1003. PROXYAUTH               NO     YES                         NO   NO   NO
  1004. REALM                   NO     NO                          NO   YES  YES
  1005. REMOVE                  NO     YES                         NO   YES  NO
  1006. REPL                    NO     YES                         NO   YES  NO
  1007. SITELIST      SLIST     YES    NO      CHANGESITE          NO   YES  YES
  1008. SWSLASH                 NO     YES                         NO   NO   NO
  1009. TIMC                    NO     YES                60       NO   NO   NO
  1010. TIMP                    NO     YES                60       NO   NO   NO
  1011. TOP                     NO     NO                          YES  NO   YES
  1012. URL                     YES    NO                          NO   NO   YES
  1013.  
  1014.  
  1015. [0] - \WWWGrab\Grab
  1016. [1] - HTM, HTML, SHTM, SHTML, JPG, GIF, WAV, AU, CLASS, and JAVA.
  1017. [2] - The shareware version of WWWGrab/2 is limited to five levels.
  1018. [3] - The default value for the shareware version is "index.html".
  1019. [4] - Combines NOIMG, NOSND, NOOTH, NOVID and NOAPPLET.
  1020.  
  1021.  
  1022. REX  - Regular expressions
  1023. REG  - Registered version only
  1024. MULT - Command can be used more than once
  1025.  
  1026. Predefined Variables
  1027. --------------------
  1028. WWWGrab/2 predefines several variables.  Depending on which operating
  1029. system is in use, one of the following is set:
  1030. __OS2__
  1031. __NT__
  1032. __UNIX__
  1033.  
  1034. The OS variable is set to one of the following values, based on the
  1035. current operating system in use:
  1036.  
  1037. OS/2
  1038. Windows NT|95
  1039. Linux
  1040.  
  1041. SEM     Semicolon (;)
  1042. VER     WWWGrab/2 version
  1043. UHTP    "URL http://"
  1044. LHOST   Local machine name
  1045.  
  1046. URL     Mirrored URL            (%u)
  1047. LFILE   Local file              (%l)
  1048. TIME    File timestamp          (%t)
  1049. HOST    Remote host             (%h)
  1050. DEPTH   Actual nest level       (%d)
  1051. PARENT  Parent of actual URL    (%p)
  1052. RFILE   Remote filename         (%r)
  1053.  
  1054. Please note that use of the '%' commands is discouraged in favor of the
  1055. newer variables.
  1056.  
  1057.  
  1058. Examples
  1059. --------
  1060. Basic authorization example:
  1061.      URL http://www.sec1.host/secured/pages/index.html
  1062.      LOCALPATH \MyGrab\Secured
  1063.      MAXDEEP 5
  1064.      MAXTRIES 3
  1065.      REALM www.sec1.host "Realm 1" WAEFfgSDRGwer==
  1066.      REALM www.sec1.host "Realm 2" WQREGFbsdgiwheg
  1067.  
  1068.  
  1069. The default configuration file example:
  1070.  
  1071. ;; Definition of common extensions
  1072. ;
  1073. EXTENSIONS HTML HTM SHTML SHTM
  1074. EXTENSIONS JPG JPEG GIF XBM
  1075. EXTENSIONS WAV VOC AU
  1076. EXTENSIONS JAVA CLASS
  1077.  
  1078. ;
  1079. ;; The default value for the MAXDEEP command
  1080. ;
  1081. MAXDEEP 5
  1082.  
  1083. ;
  1084. ;; The default value for the NICE command
  1085. ;
  1086. NICE 3
  1087.  
  1088.  
  1089. Credits
  1090. -------
  1091.      I  want  to  express  my thanks to all who have tested WWWGrab/2 on a
  1092. voluntary  basis and reported errors and gave constructive suggestions for
  1093. improvement.  Without  their  help  WWWGrab/2  would  not  have  been this
  1094. successful.
  1095.  
  1096. Special thanks go out to:
  1097.  
  1098.    * Tom Wheeler
  1099.    * Andreas Krattenmacher
  1100.    * Mike Nice
  1101.    * Stanislav Koci (St/\n)
  1102.    * Jochen Riemer
  1103.    * Fernando Cassia
  1104.    * Vincent Bernat
  1105.  
  1106. A special, *BIG* thanks goes to Tom Wheeler for checking the documentation.
  1107.  
  1108. Spanish language translation by Fernando Cassia (fcassia@theoffice.net).
  1109. http://ourworld.compuserve.com/homepages/fcassia/sos2.htm
  1110.  
  1111. French language translation by Vincent Bernat (bernat@mail.dotcom.fr).
  1112. http://w.home.ml.org ou http://www.mygale.org/07/www/
  1113.  
  1114.  
  1115.      Thanks  also  to  HELLOWEEN, GAMMA RAY, Michael Kiske, MANOWAR, Alice
  1116. Cooper,  GREEN  DAY, and all the other great musicians who provide me with
  1117. music to listen to while I am programming.
  1118.  
  1119.  
  1120. ---------------------------------------------------------------------------
  1121.  
  1122. If you like this program, please:
  1123.      Send  me  $15.00,  the  normal  user  fee for WWWGrab/2. You may send
  1124.      more :-)
  1125.  
  1126.      This  registration  fee is for INDIVIDUALS. A negotiated site licence
  1127. is   required  for  businesses,  governments  and  other  institutions  if
  1128. WWWGrab/2  is  to  be used on more than one computer at that site. Contact
  1129. the author for details on site license discounts.
  1130.  
  1131.  
  1132.      Upon   registration   you  will  receive  (via  email)  a  registered
  1133. personalized   copy   of  the  most  recent  version  of  WWWGrab/2.  This
  1134. registration makes all subsequent versions available free of charge.
  1135.  
  1136.      See the REGISTER.ENG file for registration information.
  1137.  
  1138. If you don't like this program:
  1139.      Please tell me why not, then delete it.
  1140.  
  1141. ---------------------------------------------------------------------------
  1142.  
  1143. Remember that software of this kind lives or dies by the response it gets.
  1144.  
  1145. You may get the most recent version of the WWWGrab/2 at:
  1146. http://wwwgrab.home.ml.org                       or:
  1147. http://www.geocities.com/SiliconValley/Heights/7262/
  1148.  
  1149.  
  1150. You may send comments, suggestions, bugs, etc. to:
  1151. email (listed in order of preference):
  1152.   jirkar@writeme.com
  1153.   jirkar@hotmail.com
  1154.   Jiri_Rubes@slad.fido.cz
  1155.  
  1156. FidoNet:
  1157.   Jiri Rubes 2:421/37
  1158.  
  1159.  
  1160.