StaticPress

Version alpha 1

== Getting Started ====================

First step is to add the spm directory to the PATH variable (or remember it and
always run the full path). All commands are accessed by running "spm.py".

To get started, open the directory you want to be the parent of the new website
and run:

$ spm.py init MyExampleSite

This will create a skeleton website in a new folder called MyExampleSite (note
that this directory must not exist beforehand).

Initially this will only contain folders, and a basic config file called
"default.conf". Something like:

-MyExampleSite
\- config
 \- default.conf
\- logs
\- tags
\- tmp
\- www
\- cache



== Directory Structure ================

Folder   | Description
---------+-----------------------------
         |
config   | Contains configuration files. Currently only one is used, though
         | more will be added soon when multiple contexts are added.
         |
---------+-----------------------------
         |
         | Will contain logs from commands, in the format "command##.log". All
         | commands are logged, and the ## is a number that is incremented to
         | give it a new file name. For example, running:
logs     | 
         | > spm.py gen
         | 
         | Will generate a log file "gen0.log", which will list every single
         | file processed, the action that was attempted, and the result.
         |
---------+-----------------------------
         |
tags     | Contains tag replacement files. See Tag Replacement for details.
         |
---------+-----------------------------
         |
tmp      | Temporary directory. Should not be touched.
         |
---------+-----------------------------
         | 
www      | The directory for the site as edited by the user. This is where all
         | the web pages are before being processed.
         | 
---------+-----------------------------
         | 
         | This is the output directory. It contains the files after being
cache    | processed. Any changes here will be overwritten as soon as the next
         | round of processing is executed.
         |
---------'-----------------------------



== Tag Replacements ===================

spm can do a number of different types of tag replacement:

  * Custom tag, of the format <prefix:suffix /> which can be replaced by HTML
      snippets, or used to run python files.
  * Generic tag, where an already existing html tag can be replaced completely
      by a snippet, or attributes can be modified
  * Code tags, which follow the normal code tag <? ... ?> format, and are
      executed as python code.



== Custom Tag Replacements ============

Custom tags are stored in the tags directory, under "prefix/suffix.ext".

These files can be either html files, or python scripts. If they are html files
then any time that the tag is encountered, it is replaced by the contents of
the file.

If they are python code files, then they must contain a method called handler
that accepts a dictionary of attributes for the tag, such as:


> def handler(attrs):
>     return """ Some new html code """


The tag is replaced completely by the return value from the function, so it is
important that function does return a value.



== Generic Tag Replacements ===========

These are used for every html tag, and must be python code files. There are 2
variations, which cannot be used togethor. The first is like the custom tag
handler, but ignores the return value, instead using the user changes to the
attributes dictionary.


> def handler(attrs):
>     pass # Make changes to attrs here


The second is a replacement handler. This can be used to completely change the
output of the tag, in a similar way to the custom tag handler.


> def repl_handler(attrs):
>     return """ Some new html code """


The latter is not advised. It is better to create a custom tag to avoid
problems later.



== Processing =========================

Files are modified in the www folder, then the following command is used to
"compile" the results to the final site:

$ spm.py gen

This performs all the translations available, and so will modify any html,
.redirect or .meta files it finds. Any other files are copied straight into the
cache folder.

For each file, the following will be printed to the console (and a similar, but
csv version, is logged):


> index.html ...(translate) -> success


Where "index.html" is the file (using the path from the base), "translate" is
the action performed, and "success" is the result. The result can be "nochange"
to show that the file was not modified by the processing.

== Other Commands =====================

Try:

> spm.py help

For a list of commands available.