README

   1 Server Side Includes Compiler
   2 =============================
   3
   4 This is ssic, a Server Side Includes Compiler.
   5
   6 ssic processes HTML documents with SSI directives formatted as SGML comments.
   7 It can be used to process documents without an HTTP server for local browsing or
   8 to generate static HTML documents to be efficiently served by an HTTP server.
   9 Documents could even be preprocessed, e.g. by a Markdown processor, before being
  10 parsed with ssic.
  11
  12 The set of commands, tags, and variables supported by ssic is mostly a superset
  13 of those supported by the old NCSA HTTPd and a subset of those supported by
  14 Apache HTTPd's `mod_include`:
  15
  16     http://web.archive.org/web/19971210170837/http://hoohoo.ncsa.uiuc.edu/docs/tutorials/includes.html
  17     http://httpd.apache.org/docs/current/mod/mod_include.html
  18
  19 ssic uses the `CGI::SSI` Perl module for directive processing.
  20
  21 SSI Commands
  22 ------------
  23
  24 SSI directives are formatted as follows:
  25
  26     <!--#command tag1="value1" tag2="value2" -->
  27
  28 Most commands take only one tag.
  29
  30 The following commands are supported:
  31
  32   * `config` controls various aspects of processing.  There are three valid
  33     tags:
  34     - `errmsg` controls the message that is substituted into the document when
  35       an error occurs.
  36     - `timefmt` is a format string used by `strftime` that controls the format
  37       of dates.
  38     - `sizefmt` controls the units of file sizes.  Valid values are `bytes` for
  39       sizes in bytes and `abbrev` for sizes in kibibytes or mebibytes.
  40   * `set` sets the value of a variable.  Two tags are accepted: `var` and
  41     `value`.
  42   * `echo` prints the value of an include variable (see below) or environment
  43     variable.  The only valid tag is `var`.
  44   * `printenv` prints a list of all environment variables and their values.
  45   * `include` processes and inserts the text of a document into the current
  46     document.  There are two valid tags:
  47     - `file` gives a pathname relative to the current directory.
  48     - `virtual` gives a pathname, beginning with `/`, relative to the document
  49       root.
  50   * `exec` executes a shell command.  The only valid tag is `cmd`.
  51   * `flastmod` prints the modification date of a specified file.  Valid tags are
  52     the same as for the `include` command.
  53   * `fsize` prints the size of a specified file.  Valid tags are the same as for
  54     the `include` command.
  55
  56 Include Variables
  57 -----------------
  58
  59 The following variables are set:
  60
  61   * `DATE_GMT` is the current date in UTC.
  62   * `DATE_LOCAL` is the current date in the local timezone.
  63   * `DOCUMENT_NAME` is the current filename.
  64   * `DOCUMENT_ROOT` is the document root, in which files specified with the
  65     `virtual` tag are found.
  66   * `DOCUMENT_URI` is the current filename.
  67   * `LAST_MODIFIED` is the modification date of the current document.
  68
  69
  70 Copyright Information
  71 =====================
  72
  73 Copyright (C) 2013  Patrick "P. J." McDermott
  74
  75 Copying and distribution of this file, with or without modification,
  76 are permitted in any medium without royalty provided the copyright
  77 notice and this notice are preserved.  This file is offered as-is,
  78 without any warranty.