NEWS: Release ssic 1.0.0.

[ssic.git] / README

diff --git a/README b/README
index 0bc7d2a0124369cff4d9685ecfe7b2e1fb1f859d..679265e6720cfe5243c3797ae700fc503b342d02 100644 (file)
--- a/README
+++ b/README
@@ -3,18 +3,19 @@ Server Side Includes Compiler
 
 This is ssic, a 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.
+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`:
+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://web.archive.org/web/19971210170837/http://hoohoo.ncsa.uiuc.edu/docs/tutorials/includes.html

-    http://httpd.apache.org/docs/current/mod/mod_include.html
+    http://httpd.apache.org/docs/2.2/mod/mod_include.html

 
 ssic uses the `CGI::SSI` Perl module for directive processing.
 
 
 ssic uses the `CGI::SSI` Perl module for directive processing.
 


@@ -29,43 +30,92 @@ Most commands take only one tag.
 
 The following commands are supported:
 
 
 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:
+  * `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.
     - `file` gives a pathname relative to the current directory.

-    - `virtual` gives a pathname, beginning with `/`, relative to the document
-      root.
+    - `virtual` gives a pathname, beginning with `/`, relative to the
+      document root.

   * `exec` executes a shell command.  The only valid tag is `cmd`.
   * `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.
+  * `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:
 
 
 Include Variables
 -----------------
 
 The following variables are set:
 

+  * `__SSIC__` indicates that the Server Side Includes Compiler is being
+    used to process the document's SSI directives.

   * `DATE_GMT` is the current date in UTC.
   * `DATE_LOCAL` is the current date in the local timezone.
   * `DOCUMENT_NAME` is the current filename.
   * `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_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.
 
   * `DOCUMENT_URI` is the current filename.
   * `LAST_MODIFIED` is the modification date of the current document.
 

+Flow Control Commands
+---------------------
+
+The flow control commands are:
+
+    <!--#if expr="test_expression" -->
+    <!--#elif expr="test_expression" -->
+    <!--#else -->
+    <!--#endif -->
+
+If `test_expression` evaluates to false, processing of basic commands is
+suspended until the next `elif`, `else`, or `endif` is encountered.  If
+`test_expression` evaluates to true, processing of basic commands is
+suspended between any following `elif` or `else` commands and the next
+`endif` command.
+
+`test_expression` is a Perl expression, which is passed to Perl's
+`eval()` function.  Variables may be expanded but should be quoted.
+
+The following example will output "foo is bar" if the variable `foo` is
+set to the value "bar":
+
+    <!--#if expr="'$foo' eq 'bar'" -->
+            foo is bar
+    <!--#endif -->
+
+The following example checks the SSI interpreter and uses the correct
+expression syntax for either ssic or `mod_include` from Apache HTTPd 2.2
+or earlier:
+
+    <!--#if expr="'$__SSIC__' eq '__SSIC__'" -->
+        <!-- Apache HTTPd 2.2 mod_include -->
+        <!--#if expr="$foo = 'bar'" -->
+            foo is bar
+        <!--#endif -->
+    <!--#else -->
+        <!-- Server Side Includes Compiler -->
+        <!--#if expr="'$foo' eq 'bar'" -->
+            foo is bar
+        <!--#endif -->
+    <!--#endif -->
+
+This is the recommended way to check the value of the variable
+`__SSIC__`.
+

 
 Copyright Information
 =====================
 
 Copyright Information
 =====================