home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / cheklink.zip / cheklink.doc < prev    next >
Text File  |  1998-05-15  |  42KB  |  1,037 lines
  1. 15 May 1998: The CheckLink addon for SRE-http, Version 1.02
  2.  
  3. Contact: Daniel Hellerstein (danielh@econ.ag.gov)
  4.  
  5.  
  6.          CheckLink: Create, display,traverse,and index a web-tree
  7.  
  8. Abstract:  CheckLink is a multi-threaded, socket aware utility used to
  9.            create, verify, traverse, and index a web-tree; where 
  10.            "web-tree" is defined as all URL's (in-line images, anchors, 
  11.            etc.) that are referenced in a root HTML document, and in all 
  12.            documents reachable from this root. CheckLink can be run as an
  13.            SRE-http addon, or from an OS/2 command prompt.
  14.            
  15.  
  16.                                 -------------------
  17.  
  18. Contents:
  19.  
  20. 1.     Introduction
  21. 1.a.       Web Tree? Does that make sense?
  22. II.    Installation
  23. II.a.      Using CheckLink without SRE-http.
  24. III.   CheckLink parameters.
  25. III.a.     A Note on How CHEKLINK displays results
  26. III.b.     CHEKLINK, CHEKLNK2, and CHEKINDX  parameters
  27. IV.    CheckLink Request Options
  28. IV.a.     CHEKLINK options.
  29. IV.b.     CHEKLNK2 options
  30. IV.c.     CHEKINDX 
  31. IV.c.ii.    CHEKINDX options.
  32. IV.c.iii.   CHEKINDX edit mode
  33. V.    Notes
  34. VI. Disclaimer
  35.  
  36.                                 -------------------
  37. I. Introduction
  38.  
  39. CheckLink is a robot that is used to create, verify, traverse and index 
  40. a web-tree. In other words, CheckLink will find and variously display all 
  41. the URLS (such as anchors and in-line images) that appear in a set of HTML 
  42. documents. In particular, CheckLink will:
  43.   
  44.   ... given a "starter-URL"  provided by a client:
  45.  
  46.   a) use TCP/IP socket calls to obtain the contents of the html document 
  47.      (that this "starter-URL" points to)
  48.   b) find URLs referred to by this document (i.e. <A Href=.. elements contained)
  49.      within the document)
  50.   c) verify the "existence" of all of these URLs
  51.   d) recursively check each URL that maps to an html document
  52.         The recursive part simply means "go back to step a" for each 
  53.         and every "on-site" text/html document pointed to by a URL in this
  54.         starter-URL (etc.).
  55.  
  56. The net effect is that a "web-tree" is mapped, with the root of the 
  57. web-tree being the starter-URL selected by the client, and with 
  58. each element of the web-tree being a unique URL.  Typically, the bulk
  59. of these URLs lie on a single site; though off-site URLs can be checked 
  60. to see if the resources they point to are still available.
  61.  
  62. CheckLink will maintain information on all links "contained
  63. in", or that "point to", the resources represented by the URLs that comprise
  64. the web-tree.  With this information in hand, CheckLink makes it easy to 
  65. traverse a web-tree, such traversal being a handy way to ascertain the
  66. devious ways the web-site (or the portion of the web-site spanned by
  67. the web-tree) is interconnected.
  68.  
  69. CheckLink is best run as an "addon" for the SRE-http web server
  70. (http://rpbcam.econ.ag.gov/srehttp). In particular, version 1.2M (or
  71. above) of SRE-http is required.  However, you can select any
  72. "starter-URL" desired -- it need NOT be on the site hosting CheckLink.  
  73.  
  74. For those lacking SRE-http, you can use the components of CheckLink as a 
  75. standalone program running from an OS/2 prompt, and as a CGI-BIN script.
  76. Although it's a cleaner product when run under SRE-http, the functionality
  77. is basically the same.
  78.  
  79. Lastly, CheckLink is mult-threaded. In addition to adding
  80. speed to web-traversals, the multi-threaded nature protects CheckLink against 
  81. recalcitrant servers; servers that might stop or otherwise hang-up a 
  82. single threaded link checker.
  83.  
  84.                                 -------------------
  85.  
  86. 1.a.  Web Tree? Does that make sense? 
  87.  
  88.     Perhaps the use of the term "web-tree" is misleading -- it's more of a 
  89.     web-network, web-graph, or (dare we say it?) a web-web.  The point
  90.     is that a tree implies a bottom-to-top branching structure, with a 
  91.     clearly defined set of precedences. In contrast, a web site is defined
  92.     by a network of links, with each node connecting to a wide variety
  93.     of other nodes. Although most web-sites do have some sort of hierarchy
  94.     (i.e.; there is usually one or several "home pages"), this is usually
  95.     loosely defined, with lots of cross-cutting links.
  96.  
  97.     Nevertheless, for reasons of brevity we will use the term "web-tree"    
  98.     in this documentation to refer to "the network of resources, as refered
  99.     to by URLs, that may be reached from a single starting point". Although
  100.     this single-starting point (the "starter-URL") is really just a point of
  101.     entry, one usually chooses a "starter-URL" that is somehow more
  102.     fundamental -- say, a home page.  Hence, this "starter-URL" is often
  103.     refered to as the "root of the web-tree".
  104.  
  105.                                 -------------------
  106.  
  107. II. Installation
  108.  
  109. CheckLink consist of 3 seperate program files, and one sample HTML FORM
  110. (and this documentation). The 3 files are:
  111.    CHEKLINK.CMD --- creates the web-tree, and displays basic information on
  112.                     the web tree
  113.    CHEKLNK2.CMD --- examine and traverse a web-tree
  114.    CHEKINDX.CMD --- create a hierarchical index of a web-tree.
  115.    CHEKLINK.HTM --- an HTML document with several forms for invoking the
  116.                     above programs.
  117.  
  118. Assuming that you have SRE-http installed as your web-server,
  119. installation of these components of CheckLink is straightforward:
  120.  
  121.   i) UNZIP CHEKLINK.ZIP to an empty temporary directory.
  122.  
  123.  ii) Copy CHEKLINK.CMD, CHEKLNK2.CMD, and CHEKINDX.CMD to your SRE-http
  124.      "ADDON" directory (i.e.; D:\GOSERVE\ADDON)
  125.  
  126. iii) Copy CHEKLINK.HTM to your GoServe data directory, or someother
  127.      WWW accessible location (i.e.; D:\WWW)
  128.  
  129.   iv) Optional: Change parameters in CHEKLINK.CMD and CHEKLNK2.CMD.
  130.  
  131. The easiest way to use CheckLink is by pointing your browser at /CHEKLINK.HTM.
  132. CheckLink works with all browsers that understand tables, but the results 
  133. look best with browsers that understand either multi-part documents or 
  134. client pull (such as NetScape 2.01. and above).  
  135.  
  136.                                 -------------------
  137.  
  138. II.a. Using CheckLink without SRE-http.
  139.  
  140. If you are not an SRE-http user, you can run CheckLink as a standalone
  141. program -- just copy CHEKLINK.CMD to an appropriate directory (say,
  142. D:\INTERNET\CHEKLINK). When you are ready to run CheckLink, just CD to 
  143. this directory, run CHEKLINK from an OS/2 command prompt, and follow
  144. the directions.
  145.  
  146. For example:
  147.      D:>cd \internet\cheklink
  148.      D:\INTERNET\CHEKLINK>cheklink
  149.  
  150. When run in standalone mode, the i/o interface is primitive, and the 
  151. final output is HTML code -- it is  meant to be viewed with a browser.
  152. Otherwise, the results are the same as when run as an SRE-http
  153. addon (it might even be a touch faster).
  154.  
  155.  IMPORTANT NOTE: To use CheckLink as a standalone program, you MUST have
  156.                  REXXLIB.DLL.  REXXLIB is $25 shareware (obtainable from
  157.                  http://www.quercus-sys.com/rexxlib.htm).  It's a good 
  158.                  bargain, but if this expenditure is problemmatic, please 
  159.                  contact danielh@econ.ag.gov for alternatives.
  160.  
  161. If you want to use CheckLink to "examine and traverse the web-tree",
  162. or to "create an index of the web-tree", you should copy the 
  163. CHEKLNK2.CMD and CHEKINDX.CMD files to your CGI-BIN scripts
  164. directory.  The output from CHEKLINK will contain CGI-BIN
  165. calls to CHEKLNK2.  Thus ...
  166.  
  167.     To use CheckLink in a non-SRE-http environment, you will
  168.         a) Run CHEKLINK.CMD, from an OS/2 command prompt, to generate the
  169.            index of a web-tree, and to produce several tables of results.
  170.         b) Run CHEKLNK2.CMD and CHEKINDX.CMD as CGI-BIN scripts
  171.         c) Optionally, make a few small CGI-BIN modifications to 
  172.            CHEKLINK.HTM (see CHEKLINK.HTM for the details)
  173.  
  174.                                 -------------------
  175.  
  176. III. CheckLink parameters.
  177.  
  178. Regardless of how you run CheckLink, you may wish to first adjust
  179. several performance-tuning and display-customization parameters.
  180. Most of these appear at the top of the CHEKLINK.CMD, and there are a
  181. few in CHEKLNK2.CMD and CHEKINDX.CMD -- you should modify these files with
  182. your favorite text editor. 
  183.  
  184. Note that to use any of the 3 CheckLink programs you do NOT need to set 
  185. these parameters -- the default values work reasonably well. 
  186.  
  187.    However, if you intend to make more then occasional use of CheckLink,
  188.    we recommend setting the LINKFILE_DIR parameter in  CHEKLINK.CMD, 
  189.    CHEKLNK2.CMD, and CHEKINDX.CMD.
  190.  
  191.                                 -------------------
  192.  
  193. III.a.  A Note on How CHEKLINK displays results
  194.  
  195. Before further discussion, a note on how CHEKLINK displays results
  196. (when run as an SRE-http addon) is germane:
  197.  
  198.    CHEKLINK can return results either in one long document, as a
  199.    "two part" document, or in two seperate documents. 
  200.  
  201.    In a "two part" document:
  202.         The first part contains status information, and is sent to the
  203.         client in pieces. 
  204.         The second part contains the results tables.  
  205.  
  206.    In a "long document" these parts are concatenated -- the final
  207.    output contains both "status" and "results" information (and will
  208.    be a bit more cluttered as a result)
  209.  
  210.    Since CHEKLINK can take several minutes to process a thousand or so 
  211.    links, the production of "status" information is crucial. In fact, this
  212.    status information is "sent in pieces" -- with some sort of output
  213.    being sent to the client every few seconds. Not only does this help
  214.    keep the client from giving up, it also prevents  "server inactive" 
  215.    timeouts.
  216.  
  217.    In fact, it's this "may take several minutes to finish" aspect of 
  218.    CHEKLINK that makes it very difficult to distribute a pure CGI-BIN
  219.    version of CHEKLINK -- most CGI-BIN implementations do NOT allow
  220.    for "sending results as they become avaialble", and one can not
  221.    count on lengthy (i.e.; more then a few minutes) inactive-timeouts. 
  222.  
  223.    Although two-part documents are the more elegant solution, with
  224.    certain browsers some very annoying "over refresh" behavior occurs
  225.    (i.e; every time you "back up" to the results, CHEKLINK is reinvoked).
  226.  
  227.    As a work around, the "two document" strategy can be used, which will
  228.    result in almost the same display as a two-part document (client pull
  229.    is used to automatically replace the "status" document with the 
  230.    "results" document). The drawback is the requirement for semi-permanent
  231.    storage of the results file on your server's disk -- you may need to 
  232.    monitor disk space if you allow CHEKLINK to be extensively used in 
  233.    two-document mode.
  234.  
  235.                                 -------------------
  236.  
  237. III.b.  CHEKLINK, CHEKLNK2, and CHEKINDX  parameters:
  238.  
  239.  
  240. BACK_1 : <BODY> modifiers.
  241. BACK_2
  242.  
  243.   BACK_1 and BACK_2 are used to set a BGCOLOR (or BACKGROUND) for the
  244.   "two parts" of CheckLink's output.  Note that if you are using CheckLink
  245.   in single-part mode (i.e.; if you are using an older web browser, or
  246.   if you set the multi_use option to 0) BACK_2 is ignored.
  247.  
  248.   Examples:
  249.      back_1='bgcolor="#668a78"'
  250.      back_2='bgcolor="#8888dd" background="CL.GIF' 
  251.  
  252.   Note: BACK_1 (BACK_2) is ignored if INTRO_1A (INTRO_1B) is set to a non-null
  253.         value.
  254.  
  255.  
  256. CHEKLINK_HTM : URL pointing to CHEKLINK.HTM
  257.  
  258.    CHEKLINK_HTM should contain a URL (usually, a relative URL) that
  259.    points to the CHEKLINK.HTM file shipped with CheckLink. This variable
  260.    is used to add a "generate another web-tree" option to the output file.
  261.    Thus, neglecting to properly set CHEKLINK_HTM will have few deleterious
  262.    effects.
  263.  
  264.    Example: CHEKLINK_HTM = '/CHEKLINK.HTM'
  265.  
  266. CHECK_ROBOT : Suppress checking ROBOTS.TXT.
  267.   If check_robot=1, then check the starter-URL site for a /robots.txt file, 
  268.   and use it to control extent of search.  
  269.  
  270.   Proper net'iquette dicates that when checking a stranger's site,
  271.   make sure you have set check_robot=1.
  272.  
  273.   Note: the contents of a ROBOTS.TXT file are added to the a special
  274.         "site-specific" EXCLUSION_LIST -- it only effects URLs on the
  275.         starter-URL site.
  276.  
  277.   Example: check_robot=1
  278.  
  279.  
  280. DOUBLE_CHECK:
  281.  
  282.    Since servers can be momentarily busy, it's often wise to "double check"
  283.    busy servers.  To do this, set  DOUBLE_CHECK=1
  284.    To NOT double check, set DOUBLE_CHECK=0.
  285.  
  286.    This double checking will only look at servers that were "not available".
  287.    It will be done after all links have been examined (thus giving the "not
  288.    available" server a chance to become available. Lastly, GET queries
  289.    are used (instead of HEAD queries).
  290.  
  291. GET_QUERY:
  292.    As part of mapping a web-tree, CheckLink will query servers for basic
  293.    information on URLs.  These queries are best done with HEAD
  294.    requests. 
  295.  
  296.    Unfortunately, there are a number of older servers that
  297.    do not properly respond to HEAD requests.If you find that CheckLink
  298.    is identifiying many URLs as unavailable (even though your browser
  299.    can get to them readily), it may be due to their host server's failure 
  300.    to recognize these HEAD requests.
  301.  
  302.    As a work around, you can use short GET requests instead of
  303.    HEAD requests.  This method is engaged by setting:
  304.         get_query=1.
  305.  
  306.    Example: get_query=0
  307.  
  308.    Note: This get_query=1 method is not highly recommended -- it's slower,
  309.          and somewhat "ruder" (connections are purposely broken, which
  310.          tends to add garbage to the visited server's log file).
  311.          Instead, we recommend setting DOUBLE_CHECK=1
  312.  
  313. LINKFILE_DIR: directory to store "linkage" files in.
  314.  
  315.    Linkage files contain "link" information on all the URLs discovered during
  316.    CheckLink's recursive mapping of a "web tree".  In particular, the LINKFILE
  317.    option (see section IV) specifies a filename, which will then
  318.    be stored in the LINKFILE_DIR.
  319.  
  320.    By default, LINKFILE_DIR will be your OS/2 TEMP drive.
  321.  
  322.    Example: LINKFILE_DIR='D:\GOSERVE\CHKLNKS'
  323.  
  324.    Note: in addition to storing LINKFILEs, the LINKFILE_DIR is also used
  325.          to store "RESULTS" files.
  326.  
  327. MAXATONCE: maximum number of "query" threads 
  328.  
  329.   Specifies the maximum number of threads to use when checking for the
  330.   existence (and mimetype) of a link (using HEAD requests).  
  331.   Increasing this number may speed up throughput, but it may subject the
  332.   target server(s) to  excessive loads.
  333.       
  334.   Example: maxatonce=6       
  335.  
  336. MAXATONCE_GET: maximum number of "read" threads.
  337.  
  338.   Specifies the maximum number of threads to use when retrieving the
  339.   contents of a URL (using GET requests).  Increasing this number may 
  340.   speed up throughput, but it may subject the target server(s) to  excessive 
  341.   loads.
  342.  
  343.   Example:  maxatonce_get=2   
  344.  
  345. MAXAGE: Kill a query if it's old
  346.  
  347.   Specifies number of seconds to wait on a query (a HEAD request). 
  348.   You may need to increase this time span if sites are far away or otherwise
  349.   slow. However, increasing MAXAGE will increase the time that
  350.   CheckLink waits on "hung" sites.
  351.  
  352.   Example:maxage=30       
  353.  
  354.  
  355. MAXAGE2: Kill a read if it's old
  356.  
  357.   Specifies number of seconds to wait on a read (a GET request). 
  358.   You may need to increase this time span if sites are far away or otherwise
  359.   slow. However, increasing MAXAGE will increase the time that
  360.   CheckLink waits on "hung" sites.
  361.  
  362.   Example:maxage2=60     
  363.  
  364.  
  365. ROW_COLOR1   : Used to set the <TR> in the results tables
  366. ROW_COLOR2
  367. ROW_COLOR1A
  368. ROW_COLOR2A
  369.     
  370.   ROW_COLOR1 and ROW_COLOR2 set the odd and even rows (respectively)
  371.   of tables used to display the results of checking IMG links.
  372.  
  373.   ROW_COLOR1A and ROW_COLOR2A set the odd and even rows (respectively)
  374.   of tables used to display the results of checking Anchor links.
  375.  
  376.   Examples:
  377.  
  378.    row_color1='bgcolor="#bbcc66"'   
  379.    row_color2='bgcolor="#aaccdd"'   
  380.  
  381.    row_color1a='bgcolor="#bbaa44"'  
  382.    row_color2a='bgcolor="#aaccdd"'  
  383.  
  384. TD_INDENT: Used to Indent a Type=2 (table) index
  385.   This string is used to indent each row of an "index table".
  386.   You can try using characters (i.e.; ___ ), none-breaking spaces (i.e.;  )
  387.   or empty columns (i.e.; <TD> </TD> )
  388.  
  389.   Example:
  390.         td_indent='<td bgcolor="#789966"> <font color="#789966">__</font></td>'
  391.  
  392.   Special Feature:
  393.      If you have a 1_PIXEL.GIF in the /IMGS/ directory of your web tree, you
  394.      can set td_indent equal to an integer value, which will cause the following
  395.      to be used:
  396.          <td> <IMG SRC="/IMGS/1_PIXEL.GIF" width=45> </td>
  397.      where  45 is any number equal to td_indent * indent_levels.
  398.      The above example would be used if
  399.           > td_indent=15,
  400.           > a given line is being displayed at a third level indentation
  401.      Since td_indent*3 == 15*3 == 45; a 45 pixel "blank" spacer-image will
  402.      be drawn 
  403.      NOte: 1_PIXEL.GIF should be a GIF file consisting of 1 transparent pixel.
  404.      
  405.       
  406. TD_TITLE: : Modifies "title" field of a table index.
  407.   TD_TITLE is used in the <TD  field of a "table": index.
  408.  
  409.   Example:
  410.      td_title='valign="TOP" bgcolor="#a2a9a9" '
  411.  
  412. TD_DESCRIP
  413.   TD_DESCRIP is used when writing descriptions.
  414.  
  415.   Example:
  416.     td_descrip='valign="TOP"'
  417.  
  418. TR_MOD1 and TR_MOD2: Modifies rows of a table index
  419.    TR_MOD1 and TR_MOD2 modify <TR elements of a table index. TR_MOD1 is used
  420.    on odd rows, TR_MOD2 is used on even rows. Note that if TD_TITLE and TD_DESCRIP
  421.    are used, TR_MODn may not have much impact.
  422.  
  423.   tr_mod1=' Bgcolor="#449922"'
  424.   tr_mod2=''
  425.  
  426.  
  427. USER_INTRO1A  : Files containing "header" information.
  428. USER_INTRO1B
  429.  
  430.   Fully qualified file names containing "header" information, for each part.
  431.   If ='', then a generic header is used 
  432.   If specified, the file MUST contain at least:
  433.        <HTML><HEAD>.... </HEAD> <BODY ...> <h1>... </h1> 
  434.   Note: use of user_intro1a (user_intro1b) means that back_1 (back_2) are 
  435.   NOT used. 
  436.  
  437.   Examples:
  438.     user_intro1a=''
  439.     user_intro1b='D:\GOSERVE\CHEK1.HDR'
  440.  
  441.                                 -------------------
  442.  
  443. IV. CheckLink Request Options
  444.  
  445. Request options are specified when one of the CheckLink programs
  446. is requested; say, when you use CHEKLINK as the ACTION in an HTML FORM. 
  447. The following briefly describe these options.  
  448.  
  449. For further details, we recommend perusing CHEKLINK.HTM.
  450.  
  451.                                 -------------------
  452.  
  453. IV.a. CHEKLINK options.
  454.  
  455.  
  456. The only required option is URL (defaults will be used for the other options
  457. when they are not specified). 
  458.  
  459. Options:
  460.  
  461.  BASEONLY :  
  462.         BASEONLY=0 : Read url's relative to the root of the request
  463.         BASEONLY=1 : Read url's relative to the base of the request
  464.  
  465.        Example: if URL=/dogs/foo.htm; then
  466.          baseonly=0 : /cats/bar.htm would be "recursively" read
  467.          baseonly=1 : /cats/bar.htm would NOT "recursively" read
  468.  
  469.  
  470.  DESCRIP:
  471.         Create & save descriptions for "on-site" (and "in directory", 
  472.         if BASEONLY=1) documnents.
  473.          DESCRIP=0   -- do not create descriptions
  474.          DESCRIP=1   -- create descriptions for text/html documents
  475.          DESCRIP=2   -- create descriptions for text/html and text/plain 
  476.                         documents
  477.  
  478.          DESCRIP=1 is fairly costless (it uses information that's already 
  479.          been read).  DESCRIP=2 requires reading additional files.
  480.  
  481.          A maximum of 300 characters is retained (this can be modified
  482.          by changing the DSCMAX parameter in CHEKLINK.CMD).
  483.  
  484.  
  485.  EXCLUSION_LIST: 
  486.         Space delimited list of selector to NOT query or read.
  487.                 *'s can be used as wildcards.
  488.         Example:!*  *?* *MAPIMAGE/* CGI-*' 
  489.                 (this is also the default)
  490.  
  491.  LINKFILE :  Name of a file to store "linkage" information. 
  492.  
  493.         Linkage information pertains to each and every URL in the web-tree.
  494.         Each of these URLs will be associated with a list of web-tree
  495.         residing, text/html, URLs that contain links pointing to this URL.
  496.         In addition, each text/html URL (in the web tree) is associated with
  497.         a list of all it's links (that point both on and off site) 
  498.         
  499.         The LINKFILE is used to store these lists.  More importantly,
  500.         CHEKLNK2.CMD uses the LINKFILE to "examine and traverse" the
  501.         web tree.
  502.  
  503.         Notes:
  504.           * The LINKFILE should be a file name, without path or extension
  505.             information. A default extension of .STM is used, and 
  506.             the file is written to the LINKFILE_DIR directory.
  507.           * If you do not want to retain this information, set LINKFILE=0
  508.           * If you set LINKFILE (to a non-0 value), the output from
  509.             CHEKLINK will contain links (one for each URL) to CHEKLNK2.
  510.  
  511.  
  512.  NAME: A descriptive name
  513.         You can enter a descriptive name for this "web-tree" -- it will be 
  514.         displayed at various points.  If you do not specify a name, a default 
  515.         name will be constructed from the URL option (see below).
  516.  
  517.         Example:  name=A+Sample+web_tree
  518.                        (note the URL encoding of spaces as + characters)
  519.  
  520.  OUTTYPE:
  521.     A space delimited list of tables to produce.  
  522.  
  523.     The following values can be used in any combinaton:
  524.       OK ) Display succesfully found links
  525.   NOSITE ) Display links to unreachable sites
  526.    NOURL ) Display links missing resources>
  527.  OFFSITE ) Display links to off-site URLs
  528. EXCLUDED ) Display links to excluded URLs (as specified in the EXCLUSION_LIST)
  529.      ALL ) Display all links
  530.  
  531.   Examples: OUTTYPE='ALL'
  532.             OUTTYPE='OK NOURL '
  533.  
  534.  
  535.  RESULTS : A file containing the results of a prior call to CheckLink
  536.           (primarily for internal use by CheckLink).
  537.         
  538.         Due to inappropriate refreshing by certain browsers, CheckLink
  539.         can be instructed to save it's results tables to a file (see
  540.         description of use_multi).  RESULTS points to one of these
  541.         files -- when included, CheckLink will just return the RESULTS
  542.         file.
  543.  
  544.         Example: results="CHKS0001.HTM"
  545.         
  546.         Note that these "results" files are stored in the LINKFILE_DIR 
  547.         directory.
  548.  
  549.  
  550.  
  551.  SITEONLY:
  552.        SITEONLY=0 : Query all url's
  553.        SITEONLY=1 : Query url's on starter-URL's "own site"
  554.  
  555.  
  556.  URL:  URL=fully qualified, or relative, URL
  557.       This is the "starter-URL"
  558.  
  559.       Example: url="/samples/guide.htm"  
  560.  
  561.  
  562.  USE_MULTI: 
  563.     USE_MULTI=0 : Return results in one long documemt
  564.     USE_MULTI=1 : Return results in two-part document; with the second
  565.                   part replacing (overwriting) the first.
  566.     USE_MULTI=2 : Return results in two seperate documents, the second
  567.                   one being stored on the server's disk.
  568.  
  569.         Note that if an older browser (that does not support
  570.         connection:maintain) is used, then USE_MULTI is set to 2.
  571.         
  572.         The primary reason for USE_MULTI=2 is to work around the "over-
  573.         refreshing" bugs of certain browsers.
  574.  
  575.         Note that when USE_MULTI=2 is used, the RESULTS option is
  576.         used internally by CHEKLINK to provide a link to the second
  577.         document. This document, which will be assigned random name,
  578.         will be stored on the LINKFILE_DIR directory.
  579.  
  580.                                 -------------------
  581.  
  582. IV.b. CHEKLNK2 options
  583.  
  584. CHEKLNK2 is used to examine and traverse a web tree. Typically, you would not
  585. code a requeset to CHEKLNK2 -- you'ld use links to CHEKLNK2 in the table
  586. produced by CHEKLINK. In addition, CHEKLNK2 includes numerous links 
  587. back into CHEKLNK2, links that utilize the options listed below.
  588.  
  589.    That is, CHEKLNK2 is somewhat of a self-contained program.
  590.    It is NOT expected that expected that CHEKLNK2 will be explicitily used
  591.    by most authors.
  592.         
  593.            Therefore -- the following description will be rudimentary.
  594.        
  595. Note that CHEKLNK2 can be called as an SRE-http addon, or as a CGI-BIN 
  596. script (but not as a standalone program).
  597.  
  598. Options:
  599.  
  600.  LINKFILE -- Same definition as above -- the linkage file (relative to the
  601.              LINKFILE_DIR directory) that was created by a request to CHEKLINK.
  602.  
  603.  ENTRYNUM -- pointer to an entry in the LINKFILE -- his entry corresponds to a
  604.              unique URL; CHEKLNK2 will display links to and from this 
  605.              unique URL.
  606.  
  607.              Example:entrynum=12
  608.               
  609.              If entrynum=0, an alphabetized index of all text/html documents 
  610.              (in the web-tree) will be displayed.
  611.               
  612.  ISIMG    -- Select between image & anchors linkss. Setting isimg=1 means to
  613.              use "image" links; otherwise, use "anchor" links.  Note that
  614.              the the combination of ENTRYNUM and ISIMG dictate which URL will
  615.              be examined.
  616.  
  617.               Example: entrynum=15&isimg=1
  618.  
  619.  VIA     -- Information on what location in the web-tree (which URL) was
  620.              being examined prior to jumping here.
  621.  
  622.  LIST     -- Enable "traverse web tree mode".  LIST can take the following 
  623.              values:
  624.  
  625.            LIST=0  (the default (used if LIST is not specified).
  626.                Display a "synopsis" of the URL. This synopsis includes 
  627.                basic information (such as the size and mime type), 
  628.                and a list of URLs (in the web tree) that refer to
  629.                  text/html documents that contain links to this URL (the 
  630.                  entrynum URL). In addition, if this (the entrynum) URL
  631.                  is a text/html document, a table of all links (images and
  632.                  anchors) will be displayed
  633.      
  634.            LIST=1 
  635.                  Display an (alphabetized) list of links to all text/html
  636.                  documents pointed to by links in the "entrynum URL" (more
  637.                  precisely, by the text/html document pointed to by the
  638.                  entrynum URL).
  639.  
  640.            LIST=2
  641.                  Similar to LIST=1, but display text/html documents that
  642.                  point TO the "entrynum URL" (LIST=2 is the reverse
  643.                  of LIST=1)
  644.              
  645.            LIST=3
  646.                   Display an alphabetized table of ALL urls contained in 
  647.                   web-tree.  In contrast, using LIST=0 and ENTRYNUM=0 will
  648.                   generate a list of "on-site, text/html documents".
  649.  
  650.           Example: LIST=1&entrynum=5
  651.      
  652.                      
  653.  MIME   --   A space delimited list of mimetypes, possibly containing 
  654.              wildcards.        
  655.  
  656.              MIME is only used when LIST=3.  When you specify MIME, then
  657.              only URLs with a mimetype matching (one of) the elements of
  658.              the MIME value will be used.
  659.                    
  660.              Examples: LIST=3&MIME=text/plain
  661.                        LIST=3&MIME=image/*   
  662.                        LIST=3&MIME=application/pdf+application/x-pdf
  663.                                    (note use of + as a url encoded space)
  664.  
  665.  
  666. Special Note: 
  667.   If you include an * in the LINKFILE value, CHEKLNK2 will 
  668.   produce a short list of currently available linkage files, and let you 
  669.   choose one to examine. The choice uses normal file matching rules.
  670.   For example  /CHEKLNK2?linkfile='CHK*' may yield CHK01, CHKNOW, and CHK_C.
  671.  
  672.                                 -------------------
  673.  
  674. IV.c. CHEKINDX 
  675.  
  676. CHEKINDX is used to create a hierarchical index of your web-tree. By 
  677. hierarchical index, we mean the sort of index we are all familiar with
  678. -- a highly indented list, with more "subsidiary" resources on more indented
  679. lines.  Basically, the notion is to use CHEKINDX to create a "web index" that
  680. you can post on your site (usually with suitable prettifications).
  681. Note that CHEKINDX uses nested "unordered lists" (<UL> constructs) to display 
  682. the hierarchical index; hence the output should be viewable by all browsers.
  683.  
  684. As noted in section 1a, the web-tree is something of a misnomer; and
  685. construction of such a "hierarchical index" is not a cut and dried 
  686. affair. That is, given the mutiplicity of cross-cutting links, there is
  687. no single hierarchical representation of these "web-trees".
  688.  
  689. Therefore, CHEKINDX uses a simple heuristic: given a specified "root-url" 
  690. (which may, or may not, be the starter-URL), CHEKINDX will determine the
  691. position in the hierarchy as a function of distance to the root-url.
  692. Basically, the following rules are used:
  693.  
  694. Level 1 (starting closest to the left margin):
  695.     The root-url. There is only one "level 1" row (it's the top row).
  696.  
  697. Level 2: (second closest to the left margin):
  698.     All URLs contained in the "root-URL" (that is, contained in the text/html
  699.     document pointed to by the "root-URL".
  700.  
  701. Level 3:
  702.     All URLs contained in a level 2 URL.  
  703.  
  704. Level 4, 5, etc are defined similarly.  Note that level 3 lists appear directly
  705. after the appropriate level 2 URL, and so forth. 
  706.  
  707.                    Root-URL
  708.                       2A
  709.                       2B
  710.                          3B.i
  711. For example:             3B.ii
  712.                          3B.iii
  713.                       2C
  714.                          3C.i
  715.                          3C.ii
  716.                             4.C.ii.x
  717.                             4.C.ii.xx
  718.                          3.C.iii
  719.  
  720. The above heuristic contains a key rule:
  721.  *  Once listed, a URL can never appear in a "higher level". That is,
  722.     3C.i can NOT list 2A.  
  723.  
  724. This rule can be applied at various levels of stringency.  For example, you 
  725. could allow "ties" to displayed multiple times, or you could only allow 
  726. "one listing" per URL.
  727.  
  728. Controlling this stringency, as well as otherwise influencing the scope of the
  729. listing, in controlled by the CHEKINDX options.
  730.  
  731.                                 -------------------
  732.  
  733. IV.c.ii.  CHEKINDX options.
  734.  
  735. Options:
  736.  
  737.  
  738.  CLEANUP :  Used to remove "earlier, higher level references"
  739.           
  740.      CLEANUP=1 signals CHEKINDX to remove "higher level" references
  741.      that preceded lower level references. In the examples used
  742.      above, setting MULTI=1 would cause the earlier "level 5"
  743.      reference to be removed from the index.
  744.  
  745.      CLEANUP has no effect when used with MULTI=0.
  746.      When used with MULTI=1, then only the first (of several
  747.      possible ties) is displayed. That is, MULTI=1 and CLEANUP=1
  748.      invokes a "use first occurence of lowest level" rule.
  749.  
  750.      When used with MULTI=2, all ties are displayed -- "use all
  751.      occurences of the best level".
  752.  
  753.      Note that CLEANUP requires an extra iteration, hence
  754.      requires more processing time.
  755.  
  756.      Example: CLEANUP=1
  757.  
  758.      By default, CLEANUP=0      (cleanup is not attempted).
  759.  
  760.   DESCRIP: Write descriptions (if available)
  761.         DESCRIP=1  : Write descriptions (under the title-link), if available       
  762.         DESCRIP=0  : Do notwrite descriptions)
  763.  
  764.  
  765.  DROP: Space delimited list of (possibly wildcarded) selectors to drop
  766.  
  767.     URL's with a selector portion that matches one of the
  768.     items in DROP will not be displayed in the index.
  769.     However, links within "dropped" selectors may be displayed!
  770.     Thus, you should coordinate DROP with EXCLUDE.
  771.  
  772.     Examples: DROP=*SAMPLES/*FILELIST.HTM   
  773.               DROP=*/IND*.HTM+*/MAP*.HTM
  774.                          (note use of + as a URL-encoded space)
  775.  
  776.     By default, DROP=''  (nothing is dropped)                
  777.  
  778.  
  779.  
  780.  
  781.  EXCLUDE:  Space delimited list of (possibly wildcarded) selectors to 
  782.       "not expand".
  783.  
  784.     URL's with a selector portion that matches one of the
  785.     items in EXCLUDE will be included in the index, but will
  786.     not be "expanded".  That is, the "links" associated with
  787.     an EXCLUDEd selector are not used.  Contrast this with DROP,
  788.     which drops display of the selector, but (possibly) retains
  789.     URL's with links that appear within the document the selector refers to.
  790.  
  791.     Examples: EXCLUDE=FILELIST.HTM   
  792.                 EXCLUDE=*/SITEMAP.HTM+*/INDICE.HTM
  793.                          (note use of + as a URL-encoded space)
  794.  
  795.     The primary use of EXCLUDE is to prevent some other "file listing"
  796.     from being placed at a low level and "capturing" the bulk of
  797.     the URLs. Such an occurence may distort the true relationship
  798.     between URLs.
  799.           
  800.     By default, EXCLUDE=''  (nothing is excluded)                
  801.  
  802.  
  803.  HEADER: Optional header to display at top of index.
  804.         If not specified, the servername will be displayed.
  805.         
  806.         Example: Header='This+is+OUR+Site'
  807.  
  808.  
  809.  LINKFILE:  As defined above (filename only, no path).
  810.     LINKFILE is the only required parameter (note that the
  811.     LINKFILE=* shortcut is NOT supported by CHEKINDX).
  812.  
  813.  
  814.  MIME: Space delimited list of mimetypes (possibly wildcarded)
  815.     URLs to include in the index. 
  816.  
  817.     More precisely: The mimetype of the resource (that is pointed
  818.     to by URLs in the web-tree) is compared to the list of
  819.     mimetypes in the MIME option. If no match occurs, the 
  820.     URL is NOT included in the index.
  821.  
  822.  
  823.     Examples:  MIME=text/*
  824.                MIME=image/jpeg+image/gif
  825.                     (note use of + for URL-encoding)
  826.                MIME=application/pdf
  827.  
  828.     By default, MIME=text/html.
  829.  
  830.  
  831.  MULTI:  Used to control the "stringency" of display.
  832.  
  833.    As mentioned above, it is likely that URLs will be referred
  834.    to by several other "URLs" (that is, by html documents pointed
  835.    to by several other URLs).  To prevent infinite recursion,
  836.    the basic rule is to:
  837.       "never include a URL if it's already been included at a lower level"  
  838.  
  839.     MULTI controls the other cases:
  840.        
  841.        MULTI=0  -- only one reference to a URL per index. Thus,
  842.                    if the first reference is at "level 5", and
  843.                    a "level 3" reference is found later, the
  844.                    "level 3" reference will NOT be displayed.
  845.  
  846.                    Note that "level 2" references are ALWAYS
  847.                    displayed -- they are checked first.
  848.  
  849.        MULTI=1 -- if latter references are strictly lower, then
  850.                   also display them. Thus, the level 3 reference
  851.                   mentioned above would be displayed (along with               
  852.                   the level 5 reference).
  853.  
  854.        MULTI=2  -- Similar to MULTI=1, but ties are also displayed
  855.                    (thus, a second level 5 reference would be
  856.                     displayed if MULTI=2, but not if MULTI=1)
  857.        
  858.     Example: MULTI=2
  859.        
  860.     By default, MULTI=0
  861.  
  862.  
  863.  
  864.  PIX. :  Stem variable pointing to mime-type specific imags.
  865.  
  866.    PIX. is a stem variable that points to small
  867.    .GIF icons that will be displayed next to the title
  868.    (or selector) of each entry in the index.  
  869.    The syntax is:
  870.         PIX.0=number of entries
  871.         PIX.n="mime/type  selector
  872.             where
  873.                n: 1.. pix.0
  874.                mime/type can include * as a wildcard
  875.                selector is a selector
  876.         PIX.!INCLUDE=text to include in IMG element
  877.  
  878.         For example:
  879.            pix.0=3
  880.            pix.1='text/plain  /imgs/text.gif '
  881.            pix.2='image/* /imgs/image.gif '
  882.            pix.3='text/html '
  883.                pix.!include=' height=18 width=18 ALT="*" align="center" '
  884.  
  885.         Note that when there is no "selector", no icon is 
  886.         drawn. Also, the first (of several possible) matches is used.
  887.  
  888.  
  889.  
  890.  SITEONLY: Only include URLs on the "starter-URL's" site.
  891.   
  892.     If SITEONLY=1, then URLs that point off-site will
  893.     not be included in the index. 
  894.     If SITEONLY=0, then all URLs may be included in the index.
  895.        
  896.     Note that "off-site" URLs will NEVER reference other links --
  897.     for purposes of the web-tree, they are all "leafs".
  898.  
  899.     By default SITEONLY=1  (off-site URLs are excluded)
  900.  
  901.  TYPE: Display type
  902.      
  903.     There are three types of display:
  904.        TYPE=1  : Use an Unordered List (<UL>)
  905.        TYPE=2  : Use a table (<TABLE>)
  906.        TYPE=3  : Return an "editable" document. You can use this to delete,
  907.                  change or move various records and fields (see section 
  908.                  IV.c.iii for details).
  909.                  
  910.     Note: if you select TYPE=2, you might want to play with the varions TABLE_, TR_
  911.           and TD_ parameters in CHEKINDX.CMD.
  912.  
  913.  
  914.  URL: The "root-URL".  
  915.     Actually, it's the "root selector" -- you don't need to specify the
  916.     http://a.b.c/ portion.   CHEKINDX will use this "root-URL" as
  917.     the "level 1" of the hierarchical index.  
  918.    
  919.         Example:  URL=/samples/index.htm
  920.  
  921.     By default, the "starter-URL" of the LINKFILE is used.
  922.         
  923.  
  924.                                 -------------------
  925.  
  926. IV.c.iii.  CHEKINDX edit mode.
  927.  
  928. In many cases, the hierarchical index created the CheckLink can use
  929. editing.  You may want to remove uninteresting links, change the
  930. indentation levels, modify uniformative descriptions, or even move
  931. index entries around.  To facilitate such actions, you can invoke
  932. the "edit" mode of CHEKINDX (see the description of the TYPE option above).
  933.  
  934. In "edit" mode, an HTML form listing each entry, along with several options
  935. per entry, will be listed. With this form you can:
  936.   * Remove entries
  937.   * Move entries
  938.   * Change an entries indentation level
  939.   * Modify the "title" of the entry
  940.   * Modify the "description" of the entry.
  941.  
  942. After making these changes, you can then create a <UL> or <TABLE> index;
  943. or, you can re-edit the index (and make additional changes).
  944.  
  945. Notes:
  946.    * These edits do NOT effect the "link file" (from which the index is first
  947.      generated). 
  948.    * Edit mode is NOT available when CHEKINDX is run as a cgi-bin script.  It 
  949.      is only available if you are running this CheckLink package as an SRE-http
  950.      addon.
  951.    * You can re-edit several times, until you like what you see; and then you
  952.      can finalize the index as a <UL> or a TABLE.  
  953.    * After finalizing, you should save the index to an HTML document (you might
  954.      then further modify it with your favorite text editor).
  955.    * A <UL> version of the index (reflecting current changes) is written on the 
  956.      bottom portion of the customization page.
  957.  
  958.                                 -------------------
  959.  
  960. V. Notes:
  961.  
  962.    *  CHEKLINK looks for a few kinds of "image" links, and several kinds 
  963.       of "anchor" links:
  964.         Image Links:
  965.                 <IMG src="xxx">
  966.                 <BODY background="XXX">
  967.         Anchor Links
  968.                 <A Href="XXX">
  969.                 <AREA Href="xxx">
  970.                 <FRAME src="XXX">
  971.                 <EMBED src="XXX">
  972.                 <LINK href="xxx">
  973.                 <APPLET code="xxx" codebase="http://x.x.x/yy" >
  974.                 <OBJECT codebase="xxx">
  975.                 
  976.         Note that tags in comments (between <!-- --> are NOT processed.
  977.  
  978.         Note that if there is some tag I've left out, please contact me
  979.         (danielh@econ.ag.gov) if inclusion of such a capability would
  980.         greatly enhance CheckLink!
  981.  
  982.         ? The major difference between IMG and ANCHOR links is that IMG links are
  983.           never "read" (they are only queried).  Should APPLET or OBJECT be
  984.           treated as images?
  985.  
  986.   *   A possibility (given enough interest): A graphical web-mapper component
  987.       for CheckLink.
  988.  
  989.   *   To display some of the run-time status information, you'll need 
  990.       PMPRINTF.EXE  (http://www2.hursley.ibm.com/goserve).
  991.  
  992.   *   Sample speeds of CHEKLINK (on a Pentium 100 over a 16/4M Token Ring
  993.       LAN based Intranet, with a T1 line to the outside world): 
  994.          1 GETs per second (of html/text URLs, average size  of 20k).  
  995.          8 HEADs per second (requests for basic information)
  996.  
  997.   
  998.                                 -------------------
  999.  
  1000. VI. Disclaimer
  1001.  
  1002.   Copyright 1997,1998 by Daniel Hellerstein. 
  1003.  
  1004.   Permission to use this program for any purpose is hereby granted 
  1005.   without fee, provided that the author's name not be used in
  1006.   advertising or publicity pertaining to distribution of the software 
  1007.   without specific written prior permision.
  1008.  
  1009.   This includes the right to subset and reuse the code, with proper attribution; 
  1010.   and with the following understanding:.
  1011.  
  1012.      We, the authors of CheckLink and any potentially affiliated institutions,
  1013.      disclaim any and all liability for damages due to the use, misuse, or
  1014.      failure of the product or subsets of the product.
  1015.  
  1016.   Furthermore you may also charge a reasonable re-distribution fee for
  1017.   CheckLink; with the understanding that this does not remove the
  1018.   work from the public domain and that the above proviso remains in effect.
  1019.  
  1020.     THIS SOFTWARE PACKAGE IS PROVIDED "AS IS" WITHOUT EXPRESS
  1021.     OR IMPLIED WARRANTY.
  1022.     THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE PACKAGE,
  1023.     INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.
  1024.     IN NO  EVENT SHALL THE AUTHOR (Daniel Hellerstein) OR ANY PERSON OR
  1025.     INSTITUTION ASSOCIATED WITH THIS PRODUCT BE LIABLE FOR ANY
  1026.     SPECIAL,INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
  1027.     RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
  1028.     OF CONTRACT,NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
  1029.     IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE PACKAGE.
  1030.  
  1031.  
  1032.    SRE-http was developed on the personal time of Daniel Hellerstein,
  1033.    and is not supported, approved, or in any way an official product
  1034.    of my employer (USDA/ERS).
  1035.  
  1036.  
  1037.