% Theme -- a tool to apply a consistant look to webpages
% Jessica L. Parsons <orc@pell.portland.or.us>
%

#Theme#

**Theme** is a simple tool that wraps a template around a webpage
to easily set up a consistant appearance for all the pages in a website.
It can be run as a cgi script with **`ScriptAlias`** or it can be run
from the command line as a (sort of regular) program.

##Description

When started, it looks for the file `page.them` in the current
directory, then in each of the parent directories up to the document
root.  If it doesn't find one, it fails, but if it finds one, it copies
it out, doing various substitutions on it as it goes.  If theme encounters
a `<?theme`&nbsp;_command_`?>` html command, it substitutes

=`body`=
    The webpage that you're trying to view
=`cwd`=
    The current directory (for example, if you're looking at
    </~orc/Code/ragbin/theme/index.html>,
    `<?theme`&nbsp;`cwd?>` is `/~orc/Code/theme`.)
=`root`=
    The path to the directory where `page.theme` was found.
    If you're looking at
    </~orc/Code/ragbin/theme/index.text>,
    and the theme is at `/~orc`,
    `<?theme`&nbsp;`root?>` is `../../`.
=`title`=
    The title for the page (as set in the page itself, see below)
    bracketed by `<title>` and `</title>`.
=`meta`=
    `<meta `...`/ >` tags for the page.
=`$`_name_=
    The contents of the variable _name_.  In most cases,
    `<?theme`&nbsp;_command_`?>` is the same as `<?theme`&nbsp;`$`_command_`?>`,
    with the notable exception of `<?theme`&nbsp;`title?>`, which adds
    `<title>` and `</title>` to the output while
    `<theme $title>` does not.

##Contents of the webpage
You can set various things in the webpage itself, by defining them
at the top of the page before any of the content.   When `theme`
runs, it picks any variables (set by `set`&nbsp;_name_`:=`_rest of line_)
out of the file and saves the rest of the file for inclusion in
`page.theme`.  You can also set some of the variables by an obsolete
method of _name_`:`_rest of line_

=`sccs`=
    same as **`set sccs`**
=`title`=
    same as **`set title`**
=`meta`=
    same as **`set meta`** **[except](class:caps)** that multiple
`meta:` lines will concatenate into one big meta variable.

##Restrictions

 1. Currently, theme only works on user pages.   If the page you
    give it doesn't start with a `/~`_user_, theme will cheerfully
    spit out an error page and quit.
 2. Theme doesn't play well with other cgi scripts.  If you have dynamic
    content, you can't use theme in a **`ScriptAlias`**, but must
    run it from the command line.

##Building theme

Theme uses my [configuration system](/~orc/Code/configure),
which is sort of like the FSF's system (except that you run
`configure.sh` instead of `configure`).  The `--help`
option tells you all the settings you can change.  There are two
custom settings that are important to properly set;

1.  **`--with-user-dir`** sets the directory under `/~`_user_ which
    contains their html files.  This is normally `htdocs`, but can
    be set to anything (including `.`, which makes all of that
    users files accessable to `theme` and the rest of the world .)
2.  **`--with-pages`** changes the types of files that `theme` will
    process.  If this is not set, `theme` will only process files
    that have a `.html` or `.htm` extension.   Provide a colon-separated
    list of extensions to change this.

##Source Code
=[version 0.01](theme-0.01.tar.gz)=
    This is the first public release.  Note the complete lack of
    documentation, readmes, or anything other than the configure
    scripts and source files.