home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / srev13g.zip / DIR.DOC < prev    next >
Text File  |  1999-06-26  |  15KB  |  326 lines
  1. 15 Apr 1998
  2.             !DIR: SRE-http's built-in directory display facility
  3.  
  4. I. Introduction 
  5.  
  6. !DIR is SRE-http's built in directory display facility.
  7. It has a number of display options, and can even automatically generate 
  8. "descriptions" of text documents.
  9.  
  10. !DIR is invoked in one of two ways:
  11.  i) By explicitily calling it with a selector of !DIR.
  12.     Example:  /!DIR?dir1
  13. ii) By the !CREATE option of AUTO_NAME; which instructs
  14.     SRE-http to generate a directory listing "when there is no INDEX file".
  15.     Example: /dir1/    (assuming there is no "directory specific index file"
  16.                         in the DIR1 subdirectory)
  17.  
  18. Notes:
  19.  
  20.  * To improve performance, !DIR will "cache" directory listings;
  21.    which it will use (after checking for changes).
  22.  * For those interested in a more configurable directory display procedure,
  23.    we recommend SRE-http's GETAFILE addon.
  24.  
  25.                 --------------------------
  26.  
  27. II. Options
  28.  
  29. By default, !DIR displays a "sorted by name" directory listing with a
  30. descriptive icon, a filename (that links to the file), the creation date,
  31. and the size.  The link is a standard selector, and (when selected)
  32. will be processed by SRE-http using the standard rules (for example, 
  33. it will be subject to selector-specific access controls).
  34.  
  35.  
  36. You can change these  display options modifying several SRE-http parameters:
  37.    DIR_EXCLUSION and DIR_OPTIONS.  
  38. You can also suppress display of selected directory (trees) by setting:
  39.   DIR_ACCESS and DIR_ACCESS_PRIVS
  40. (all four of these parameters are in INITFILT.80, and can be modified
  41. with the intermediate configurator).
  42.  
  43. When yous use a !DIR selector, you can also include a list of options 
  44. in the selector (after a ?) --they will override the options specified
  45. in the DIR_OPTIONS parameter.
  46.  
  47. II.1. Descriptions of the DIR_ parameters:
  48.  
  49.   1) DIR_EXCLUSION: a space delimited  list of 'files and subdirectories'
  50.                     to exclude. Note that the * wildcard can be used.
  51.       Example: dir_exclusion='HTACCESS.  DESCRIBE.TXT /PRIVATE  *.CNT '
  52.  
  53.       Files and subdirectories listed in DIR_EXCLUSION will not be
  54.       displayed by !DIR.  However, the appearance of a directory
  55.       in DIR_EXCLUSION does NOT suppress display of the entire directory
  56.       (should it be the target of it's own !DIR). 
  57.           For example,
  58.              if DIR_EXCLUSION='PRIVATE '
  59.              if D:\WWW is the default data directory, and it has
  60.                 D:\WWW\JOE, D:\WWW\JOE\PRIVAVE. D:\WWW\PETER,
  61.                 and D:\WWW\PETER\PRIVATE subdirectories,
  62.              then 
  63.                * a !DIR?JOE request will list all files and directories
  64.                  under d:\WWW\JOE, EXCCEPT for the PRIVATE directory.
  65.                * a !DIR?PETER request will list all files and directories
  66.                  under D:\WWW\PETER, EXCEPT for the PRIVATE directory.
  67.                * a !DIR?JOE/PRIVATE will list the contents of
  68.                  D:\WWW\JOE\PRIVATE
  69.  
  70.           Thus, a well-informed client can view the contents of 
  71.           an "excluded" directory (but will still be subject to 
  72.           access controls if she tries to download anything from it).
  73.  
  74.           * If you want to suppress "viewing the contents of"
  75.             D:WWW\JOE\PRIVATE (or D:\WWW\PETER\PRIVATE), use the
  76.             DIR_ACCESS options.
  77.  
  78.           
  79.   2) DIR_ACCESS and DIR_ACCESS_PRIVS
  80.      For extra security, you can use DIR_ACCESS to suppress display of 
  81.      selected directories. DIR_ACCESS should contain a space delimited list
  82.      of "selectors" that !DIR will limit access to.
  83.   
  84.    More precisely, each item in DIR_ACCESS is compared against the 
  85.    requested directory; and if any of them match (possibly using wildcards)
  86.    then the client must have one of the privileges listed in DIR_ACCESS_PRIVS
  87.    (or must be a SUPERUSER). If the client does not have one of these
  88.    privileges, !DIR will not display the directory.
  89.  
  90.         Example: DIR_ACCESS=' SYSTEM    */PRIVATE '
  91.                    Note that !DIR?JOE/PRIVATE would match */PRIVATE.
  92.                  DIR_ACCESS_PRIVS='SUPERUSER DIRPRIVS '
  93.  
  94.     For a further description, see INITFILT.DOC.
  95.  
  96.     Note: DIR_ACCESS and DIR_ACCESS_PRIVS are also used by the GETAFILE addon.
  97.  
  98.  
  99.   3)DIR_OPTIONS: A space delimited list  of display options, including:
  100.   
  101.     AUTO_DESCRIBE == Try to create descriptions. This is done by extracting
  102.                      <TITLE> and <META NAME="DESCRIPTION" Content="xx">
  103.                      headers from HTML files,  the -z comments or
  104.                      FILE_ID.DIZ files from .ZIP files, and the beginning of
  105.                      plain text files.
  106.  
  107.     DESCRIBE=filename.ext == Use one line descriptions that are contained
  108.                              in filename.ext. If just a DESCRIBE is included,
  109.                              the filename.ext is assumed to be DESCRIBE.TXT
  110.                              (see below for more details)
  111.  
  112.     DESC_LEN=nnn == Maximum characters to display in the description (ignored
  113.                     if neither DESCRIBE or AUTO_DESCRIBE options are included)
  114.  
  115.     DATEFMT=x == The date format used; where x is one of B C D E M N O S U W.
  116.              Where, given a date of 27 Aug 1988
  117.                 B:    725975
  118.                 D:    240
  119.                 E:    27/08/88
  120.                 L:    27 August 1988
  121.                 M:    August
  122.                 N:    27 Aug 1988
  123.                 O:    88/08/27
  124.                 S:    19880827
  125.                 U:    08/27/88
  126.                 W:    Saturday
  127.  
  128.            Note that if "x" is not one of these, N is used.
  129.  
  130.  
  131.     HEADERFILE=filename.ext == A file to use as a "header".  If no
  132.                                filename.ext is given, then DIR.HDR
  133.                                is looked for. See below for details.
  134.     FOOTERILE=filename.ext == A file to use as a "footer".  If no
  135.                                filename.ext is given, then DIR.FTR
  136.                                is looked for. See below for details.
  137.  
  138.     MULTI_SEND  == If the client's browser supports "Connection:Keep-Alive"
  139.                    (i.e.; NetScape 1.3), and the directory contains more then
  140.                    20 files, and AUTO_DESCRIBE will be attempted ..
  141.                    then MULTI_SEND instructs  !DIR to display
  142.                    "status" messages as the files are processed. These
  143.                    status messages (written after every 15 files) are
  144.                    sequentially displayed; and after all files have been
  145.                    processed, they will be overwritten by the directory
  146.                    listing.
  147.                    Note that older browsers (such as IBM's WebEx) do not 
  148.                    support "Connection:Keep-Alive"; !DIR will detect this 
  149.                    and not attempt to send status messages to such browsers.
  150.  
  151.     NOCACHE == If =1, Do NOT use the !DIR cache (force re-creation of the
  152.                directory listing)
  153.  
  154.     NOSIZE ==  If =1, Suppress display of size.
  155.     NOTIME ==  If =1, Suppress display of creation time
  156.     NODATE ==  If =1, Suppress display of creation time and date
  157.     NOICON ==  If =1, Suppress icon display
  158.     NOSORT ==  If =1, Suppress sort-by-name
  159.     NODIR  ==  If =1, Suppress subdirectory display (display files only)
  160.     NO_RECURSE_DIR == Do NOT Use DIR on subsequent directories.                 
  161.                     When NO_RECURSE_DIR=0, clicking on a directory
  162.                     link will yield a new !DIR style listing (using
  163.                     the current options). When NO_RECURSE_DIR=1,
  164.                     clicking on a directory link is treated as a
  165.                     standard request -- SRE-http will try to find
  166.                     a "directory specific" default file, and if
  167.                     it can't it might "automatically create a 
  168.                     directory listing"
  169.  
  170.     PATTERN==  Include only files that match this (possibly wildcard 
  171.                 containing) pattern.  You can have many PATTERN= elements.
  172.                     Example: PATTERN=*.HTM+PATTERN=*.DOC
  173.  
  174.  
  175.     PREFIX ==  Add a "special directive" before each element in the
  176.                list of file links.  Typically, this would be "SENDAS_CHECK_TYPE";
  177.                or one of the other "mime type modifiers".  Note that if your
  178.                forget to start the PREFIX with a !, one will be added.
  179.                    Example: PREFIX=!SENDAS_CHECK_TYPE
  180.  
  181.     SHOWPARENT ==  Allow client to go up to parent. This CAN be used with
  182.                    the NODIR option.
  183.     SIZEFMT=aaaaa == The size format: aaaaa=ABBREV means 13K,
  184.                                       aaaaa=0 means 13,012
  185.  
  186.     TABLE  == use an HTML TABLE to display (otherwise, use <PRE> formatting)
  187.     TABLE_BORDER=nnn  == Size of border (if table used). If nnn=0, then no
  188.                          border is shown.
  189.     TARGET=href_target == the "target window" -- if non-zero, documents will 
  190.                           displayed in a second window 
  191.     TIMEFMT=nn ==  The time format: nn=24 means use 13:01, nn=0 means  1:01p
  192.  
  193.  
  194.   Examples:
  195.      DIR_OPTIONS='notime describe no_recurse_dir datefmt=u nocache '
  196.      DIR_OPTIONS='showparent table auto_describe desc_len=300 multi_send '
  197.  
  198.  
  199. II.2. Specifying options in the selector.
  200.  
  201.   When invoking !DIR with a selector, you can append options
  202.   after the directory name (the directory name MUST immediately follow
  203.   the ?.  Seperate each option with a space (or a + if you are hand
  204.   coding a URL), and NOT with a &. The options are the same as above.
  205.  
  206.        For example:  /DIR?dir1+nosize+auto_describe
  207.  
  208.   Each of these options can be specified as is, or as option=0,
  209.   which "turns them off".  This =0 form is useful if you wish
  210.   to override a "parameter" settting with "request selector" option.
  211.   Alternatively, option=1 "turns them on" (note that turning on a
  212.   NOxxx option may mean suppressing a piece of the file info display).
  213.  
  214. II.3 Notes on the DESCRIBE option:
  215.  
  216.   * The description file (say, DESCRIBE.TXT) is assumed to be in the
  217.     "own directory". Thus, seperate directories must have their "own"
  218.     description file.
  219.  
  220.   * The DESCRIBE option expects a  "filename.ext" after an
  221.     = sign. If you leave this off, DESCRIBE.TXT is used (if available).
  222.     For example: !DIR?dir2+describe
  223.                 means "use the DESCRIBE.TXT file in the DIR2 subdirectory".
  224.  
  225.   * The description file (i.e.; DESCRIBE.TXT) file should be organized as
  226.       FILE1.xxx a description
  227.       file2.yyy  another description
  228.       /subdir1      a subdirectory description
  229.  
  230.   * Note that descriptions start with a file name (or a directory name,
  231.     which must be preceded by a /) followed by the description
  232.     (seperated from the filename by at least one space). These refer to
  233.     subdirectories of the request directory (for example, 
  234.     if D:\WWW is the default data directory, and !DIR?DIR2 is used,
  235.      the /SUBDIR1 refers to d:\www\dir2\subdir1)
  236.  
  237.   * The description must be on one (arbitrarily long) line. However, it will
  238.     be formatted to fit in the (possibly multi-line) display area.
  239.     This is in contrast with several SRE-http addons, which permit
  240.     multi-line descriptions.
  241.  
  242.   * When used with AUTO_DESCRIBE, if an explicit description is found
  243.     in the description file, it is always used. That is, AUTO_DESCRIBE
  244.     only applies to files that do NOT have an entry in the description file
  245.     (assuming the DESCRIBE option is used).
  246.  
  247.   * If you want to suppress all descriptions (!DIR is much faster when you
  248.     don't display descriptions), set AUTO_DESCRIBE=0 and DESCRIBE=0.
  249.  
  250.  
  251. II.4. Notes on the HEADERFILE and FOOTERFILE options.
  252.  
  253.   * The header-file and footer-file is assumed to be in the "own" directory.
  254.   * If a HEADERFILE is specified, and exists, the default
  255.     header is NOT written.
  256.     THUS.... If a HEADERFILE is specified, it MUST contain a <BODY>
  257.              element. In all likelihood, that's why you'ld use it
  258.              (so that you could specify a <BODY BACKGROUND=xxx.gif> element)!
  259.   * The HEADERFILE option expects a  "filename.ext" after an
  260.     = sign. If you leave this off, DIR.HDR is used (if available).
  261.     Similarly, if no file exists after the FOOTERFILE, a DIR.FTR file
  262.     is used (if available).
  263.  
  264.  
  265. II.5. Note on PATTERN= and DIR_EXCLUSION
  266.  
  267.    * DIR_EXCLUSION is a "can not match list".  PATTERN= entries, after
  268.      concatenation (nb: you can have multiple PATTERN= entries in your
  269.      option list) form a "must match list".  You can have both -- in
  270.      which case the file MUST match a PATTERN=, and must NOT match
  271.      a DIR_EXCLUSION element.
  272.   *  When invoking !DIR as a selector:
  273.          To override a PATTERN=xx.xx  that you've included in the DIR_OPTIONS;
  274.          just include a PATTERN=* option in the selector.
  275.          For example: /!DIR?PICTURES+PATTERN=*.JPG+PATTERN=INDEX.HTML
  276.  
  277.   * Reminder: DIR_EXCLUSION and PATTERN refers to files (and subdirectories) 
  278.               in a requested directory. DIR_ACCESS and DIR_ACCESS_PRIVS
  279.               refers to the requested directory itself. Thus, in order
  280.               for DIR_EXCLUSION and PATTERN to come into play, DIR_ACCESS
  281.               must first be satisfied.
  282.  
  283.                    --------------------------
  284.  
  285. III. Notes on caching
  286.  
  287.   * Caching is meant to be used in conjunction with the AUTO_DESCRIBE
  288.     and DESCRIBE=filename option. If you are not including descriptions,
  289.     then caching will probably not help a lot.
  290.  
  291.  *  A fairly simple caching algorithim is used, which will limit
  292.     the cache's usefulness if !DIR is used extensively.
  293.     If you intend to use !DIR extensively, you should consider
  294.     using the BBS addon.
  295.  
  296.   * Caching uses files that are stored in the TEMPDATA_DIR directory
  297.     (typically, \GOSERVE\TEMP).  A _DIR.IDX file is used as a reference
  298.     index, and _nnnnn.DSH files are used as "directory cache" files.
  299.  
  300.   * SRE-http will check the file-stamps of all files and subdirectories
  301.     in the requested directory.  In addition, it will check the
  302.     dir_option and dir_exclusion parameters.  If any of these have
  303.     changed, the cache entry will not be used.
  304.     Note: actually, a CRC of this information is used; thus, on very rare
  305.           occasions SRE-http will NOT detect a change.
  306.  
  307.   * The DIR_CACHE_DURATION and DIR_CACHE_SIZE variables (set in INIT_STA.80)
  308.     are used to set the size and lifespan of entries in the directory
  309.     cache.  The default values are 3 days and 1Megabyte.
  310.     Note that about once a day, !DIR will (when invoked) clean up
  311.     the directory cache (say, get rid of entries that have somehow
  312.     become orphaned).
  313.  
  314.   * To suppress, on a request specific basis, SRE-http's use of this
  315.     cache; just include a NOCACHE option in the request selector (using the
  316.     !DIR?dirname+NOCACHE syntax). To permanently suppress  it,
  317.     set DIR_CACHE_SIZE=0
  318.  
  319.    * Cache entries are identified by both fully qualified directory,
  320.      and by the "option list and exclusion" lists.
  321.      Thus, multiple views of the same directory may be cached.
  322.  
  323.                 --------------------------
  324.  
  325. :End of DIR.DOC.
  326.