README: New file.

[ssic.git] / README

diff --git a/README b/README
new file mode 100644 (file)
index 0000000..0bc7d2a
--- /dev/null
+++ b/README
@@ -0,0 +1,78 @@
+Server Side Includes Compiler
+=============================
+
+This is ssic, a Server Side Includes Compiler.
+
+ssic processes HTML documents with SSI directives formatted as SGML comments.
+It can be used to process documents without an HTTP server for local browsing or
+to generate static HTML documents to be efficiently served by an HTTP server.
+Documents could even be preprocessed, e.g. by a Markdown processor, before being
+parsed with ssic.
+
+The set of commands, tags, and variables supported by ssic is mostly a superset
+of those supported by the old NCSA HTTPd and a subset of those supported by
+Apache HTTPd's `mod_include`:
+
+    http://web.archive.org/web/19971210170837/http://hoohoo.ncsa.uiuc.edu/docs/tutorials/includes.html
+    http://httpd.apache.org/docs/current/mod/mod_include.html
+
+ssic uses the `CGI::SSI` Perl module for directive processing.
+
+SSI Commands
+------------
+
+SSI directives are formatted as follows:
+
+    <!--#command tag1="value1" tag2="value2" -->
+
+Most commands take only one tag.
+
+The following commands are supported:
+
+  * `config` controls various aspects of processing.  There are three valid
+    tags:
+    - `errmsg` controls the message that is substituted into the document when
+      an error occurs.
+    - `timefmt` is a format string used by `strftime` that controls the format
+      of dates.
+    - `sizefmt` controls the units of file sizes.  Valid values are `bytes` for
+      sizes in bytes and `abbrev` for sizes in kibibytes or mebibytes.
+  * `set` sets the value of a variable.  Two tags are accepted: `var` and
+    `value`.
+  * `echo` prints the value of an include variable (see below) or environment
+    variable.  The only valid tag is `var`.
+  * `printenv` prints a list of all environment variables and their values.
+  * `include` processes and inserts the text of a document into the current
+    document.  There are two valid tags:
+    - `file` gives a pathname relative to the current directory.
+    - `virtual` gives a pathname, beginning with `/`, relative to the document
+      root.
+  * `exec` executes a shell command.  The only valid tag is `cmd`.
+  * `flastmod` prints the modification date of a specified file.  Valid tags are
+    the same as for the `include` command.
+  * `fsize` prints the size of a specified file.  Valid tags are the same as for
+    the `include` command.
+
+Include Variables
+-----------------
+
+The following variables are set:
+
+  * `DATE_GMT` is the current date in UTC.
+  * `DATE_LOCAL` is the current date in the local timezone.
+  * `DOCUMENT_NAME` is the current filename.
+  * `DOCUMENT_ROOT` is the document root, in which files specified with the
+    `virtual` tag are found.
+  * `DOCUMENT_URI` is the current filename.
+  * `LAST_MODIFIED` is the modification date of the current document.
+
+
+Copyright Information
+=====================
+
+Copyright (C) 2013  Patrick "P. J." McDermott
+
+Copying and distribution of this file, with or without modification,
+are permitted in any medium without royalty provided the copyright
+notice and this notice are preserved.  This file is offered as-is,
+without any warranty.