# WASD Hypertext Services - Environment Overview

## 3 - Directory Listing

> 3.1 - Controlling Access To A Directory
> 3.2 - "Hidden" Files
> 3.3 - Server Directives
> 3.3.1 - Layout
> 3.3.2 - Readme Files
> 3.3.3 - Listing Delimiters
> 3.3.4 - Suppressing Directories
> 3.3.5 - Listing Refresh and Expiry
> 3.3.6 - Scripting From Directory Listings
> 3.3.7 - Auto-Scripting
> 3.3.8 - Specifying Content-Type
> 3.4 - Directory Tree

[next] [previous] [contents] [full-page]

A directory listing is sometimes refered to as a document Index, and is generally titled "Index of ...".

Unless disabled by the server's configuration, a directory listing is recognised by the server whenever a wildcard is present in a specification and there is no query string directing another activity (e.g. a document search). Compliant with other hypertext implementations, a directory listing is also generated if a URL specifies a directory only and that directory contains no home page.

All specifications must be made using URL-style paths. See 2.3 - Document Specification.

The directory listing is designed to look very much like the basic layout of other servers, except that all directories are grouped at the top. In the opinion of the author, this looks and functions better than when interspersed with the files, as is otherwise common. The default listing provides:

  iconic indication of the data type
  file name
  last revison date/time
  size
  description

The description can be either be just that, a description of the role of that type of file under VMS, or if presented within quotes, an HTML document's own internal description taken from the "<TITLE></TITLE>" element.

Note that directory listings only processes the physical file system. This may or may not correspond to the hypertext environment's virtual mappings.

The following link illustrates the directory listing format: *.*

###
VMS-ish Format

The default listing has a generic WWW look about it, however it can be made to look a little more like the format of the VMS "DIRECTORY" command. In this mode the directories are presented as VMS subdirectories, the version number is shown, if a version wildcard was included in the specification then all matching versions are shown, the size is presented in used and allocated blocks, and automatic script activation is disabled. The VMS-style format is enabled by providing an explicit or wildcard version number with the specification, as in the following example: *.*;

###
Listing Icons

By default (and generally) WASD installations are configured to return a binary file (usually triggering a browser "save-as" dialog) for unknown content-types. For such files and for non-text files in general, a directory listing icon becomes a link to a plain-text version of the file (regardless of it's actual content). So for files containing such plain-text (often readme files with "interesting" file names) this becomes a convenient way of access the content.

###
3.1 - Controlling Access To A Directory

The following files (empty, or not), when within a specific directory regulate access to that directory, and the listing of any parent directory or subdirectories.

- .WWW_HIDDEN - Renders the directory completely invisible to the directory listing mechanism. Files within the directory may still be accessed if specified explicitly but the directory content itself cannot be listed by any means.

- .WWW_NOWILD - Renders the directory incapable of being listed using "*.*" characters at the end of the path, even if allowed by the server. This is a little different to .WWW_HIDDEN, which hides the directory completely. The no-wild still allows a directory without a home page to list as a directory, it does however prevent the forced listing using the "*.*" syntax.

- .WWW_NOP - Any parent directory is not listed.

- .WWW_NOS - Any subdirectories are not listed.

- .WWW_NOPS - Any parent directory or subdirectories are not listed.

###
3.2 - "Hidden" Files

Any file name beginning with a period is hidden from the directory listing mechanism (i.e. in VMS parlance it has only a type/suffix/extension). If specifically accessed they will be retrieved however. Hence the following files would not appear in a directory listing:

  .WWW_NOPS
  .CANT_BE_SEEN
  .HIDDEN_FROM_VIEW
  .;1

###
3.3 - Server Directives

The WASD server behaviour can be modified using server directives. For directory listings this involves the inclusion of a query string beginning with "?httpd=index". The server detects this query string and processes it internally, changing the default action of directory listings.

Multiple directives can be combined by concatenating them with intervening ampersands, as per normal URL syntax.

      ?httpd=index&autoscript=no
      ?httpd=index&readme=no
      ?httpd=index&type=text/plain
      ?httpd=index&layout=format
      ?httpd=index&script=script-name
      ?httpd=index&script=script-name&readme=no
      ?httpd=index&delimit=none&readme=no&nos=yes

###
3.3.1 - Layout

Allows specification of the directory listing layout from the URL, overriding the server default. The layout directive is a short, case-insensitive string that specifies the included fields, relative placement and optionally the width of the fields in a directory listing. Each field is controlled by a single letter (one with colon-separated parameter) and optional leading decimal number specifying its width. When a width is not specified an appropriate default applies. An underscore is used to indicate a single space and is used to separate the fields (two consecutive works well).

  C - creation date
  D - description (often best specified last)

    D:L - for files, make a link out of the description text

  I - icon (takes no field-width attribute)

    L - link (highlighted anchor using the name of the file)
    L:F - file-system name (for ODS-5 displays spaces, etc.)
    L:N - name-only, do not display the extension
    L:U - force name to upper-case

  N - name (no link, why bother? who knows!)
  O - owner (can be disabled)
  R - revision date
  S - size

    S:B - in bytes (comma-formatted)
    S:D - decimal kilos (see below)
    S:F - kilo and mega are displayed to one decimal place
    S:K - in kilo-bytes (and fractions thereof)
    S:M - in mega-bytes (and fractions thereof)

  U - upper-case file and directory names (must be the first character)

The default layout is:

      I__L__R__S__D

The following provide other examples:

      ?httpd=index&layout=UI__L__R__S__D
      ?httpd=index&layout=I__L__R__S:b__D
      ?httpd=index&layout=I__L__R__S__D
      ?httpd=index&layout=I__15L__S__D
      ?httpd=index&layout=15L__9R__S
      ?httpd=index&layout=15N_9C_9R_S

The size of files is displayed by default as 1024 byte kilos. When using the "S:k", "S:m" and "S:f" size modifiers the size is displayed as 1000 byte kilos. If it is prefered to have the default display in 1000 byte kilos then set the directory listing layout using:

      ?httpd=index&layout=I__L__R__S:d__D

If unsure of the kilo value being used check the "<META>" information in the directory listing.

The following links illustrate this functionality by listing this document's directory in a default and then three other formats.

Default.
Only an icon and link.
Icon, link and size (in VMS-style format).
Name, day created and day revised.
Name (in upper-case), day created and day revised.
Description (fixed width) as a link, size in bytes, and day revised.

###
3.3.2 - Readme Files

When a directory listing is generated any "README.", "README.TXT" or "README.HTML" file (or others as configured for the particular server) in the directory will have its contents displayed immediately below the title of the page. This allows additional information on the directory's contents, function, etc., to be presented. This can be suppressed by appending the following query-string to the directory specification, as in the accompanying example:

      ?httpd=index&readme=no

      <A HREF="*.*?httpd=index&readme=no">*.* (no <I>readme</I>s)</A>

Read-me files can be SSI documents if configured by the server administrator. General SSI guidelines apply to these, see 4 - Server Side Includes (SSI)

###
3.3.3 - Listing Delimiters

A directory listing is normally delimited by a header, comprising an "Index of", column headings and horizontal line, and a footer, comprising a horizintal line. This default behaviour may be modified using the "delimit=" directive.

- header - a header comprising a horizontal rule and column heading is generated

- footer - a footer comprising a horizontal rule is generated

- none - no header or footer is generated

- both - both header and footer is generated (default)

      ?httpd=index&delimit=none

      ?httpd=index&delimit=top

###
3.3.4 - Suppressing Directories

Parent and subdirectories may be suppressed in a listing using the "nop", "nops" and "nos" directives. These parallel the purpose of the directory listing control files described in 3.1 - Controlling Access To A Directory, and if set to true suppress the listing of the corresponding directories.

- nop - any parent directory is not listed

- nops - any subdirectories are not listed

- nos - any parent directory or subdirectories are not listed

      ?httpd=index&nop=yes

      ?httpd=index&nops=yes

      ?httpd=index&nos=yes

###
3.3.5 - Listing Refresh and Expiry

Directory listings and trees may be pre-expired. That is, the listing is reloaded each time the page is referenced. This is convenient in some environments where directory contents change frequently, but adds considerable over-head and so is often disabled by default. Individual directory listings may have either default behaviour over-ridden using syntax similar to the following examples:

      /dir1/dir2/*.*?httpd=index?expired=yes
      /dir1/dir2/*.*?httpd=index?expired=no
      /tree/dir1/dir2/?httpd=index?expired=yes
      /tree/dir1/dir2/?httpd=index?expired=no

###
3.3.6 - Scripting From Directory Listings

When a directory listing is requested a script name can be specified to be used as a prefix to all of the file links in the listing. When the client selects a file link the script specified is implicitly activated.

      ?httpd=index&script=script_name

      <A HREF="*.*?httpd=index&script=print">print *.*</A>

The following link illustrates this facility by specifying the (print) script. When a link is selected the print script presents a form to allow the file to be printed:

print *.*

###
3.3.7 - Auto-Scripting

The server's auto-scripting facility (see description of [AddType] configuration directive in the Technical Overview) can be suppressed by appending the following query-string to the directory specification, as in the accompanying example:

      ?httpd=index&autoscript=no

      <A HREF="*.*?httpd=index&autoscript=no">get me *.*</A>

This implies that any file accessed from the listing will be transfered without any data conversion possible due to script activation. The browser must then process the document in some fashion (often by activating a save as dialog).

###
3.3.8 - Specifying Content-Type

When accessing files it is possible to explicitly specify the identifying content-type to be returned to the browser in the HTTP response header. Of course this does not change the actual content of the file, just the header content-type! This is primarily provided to allow access to plain-text documents that have obscure, non"-standard" or non-configured file extensions. See 2.2 - Explicitly Specifying Content-Type.

It could also be used for other purposes, "forcing" the browser to accept a particular file as a particular content-type. This can be useful if the extension is not configured (as mentioned above) or in the case where the file contains data of a known content-type but with an extension conflicting with an already configured extension specifying data of a different content-type.

It is posssible to "force" the content-type for all files in a particular directory. Enter the path to the directory and then add

      ?httpd=index&type=text/plain

(or what-ever type is desired). Links to files in the listing will contain the appropriate "?httpd=content&type=..." appended as a query string.

This is an example:

      *.*

      *.*?httpd=index&type=text/plain

###
3.4 - Directory Tree

The "Tree" internal script allows a directory tree to be generated. This script is supplied with a directory name from which it displays all subdirectories in a hierarchical layout, showing subordinancies. Selecting any one of the subdirectories displayed generates a directory listing (see 3 - Directory Listing).

Appending a file specification (with or without wildcards) to the directory name results in the any directory listing displaying only files matching the specification. To display all files a "*.*" should always be appended.

Note that this script only processes the physical file system. This may or may not correspond to the hypertext environment's virtual mappings.

To enable the VMS-style directory listing format, or to use any of the directory server directives, append one, or a combination of, the following query strings to the directory specification:

      ?httpd=index&autoscript=no
      ?httpd=index&readme=no
      ?httpd=index&script=script-name
      ?httpd=index&script=script-name&readme=no

The following links provide online demonstrations:

/ht_root/ tree
/ht_root/ (VMS-ish) tree

Note that this activity is I/O intensive, and can take a considerable period if the tree is extensive.

> NOTE

> The "tree" internal script supercededs the "Dtree" external script which has been retired.

[next] [previous] [contents] [full-page]