System Variables
================

This chapter lists all variables interpreted or produced by FileWiki.
Note that these variables are in capital letters, in order to
distinguish them from the user-defined variables.


Configuration Variables
-----------------------

The variables described here directly affect the FileWiki behaviour.


### BASEDIR

Mandatory. Points to the top-level directory of the website. This must
be set as function parameter to the FileWiki calls.


### OUTPUT_DIR

Target (output) directory of the website. Mandatory for the
`FileWiki::create()` function. Absolute as well as relative paths are
allowed.

NOTE: The given directory as well as all subdirectories will be
created on the fly, without checking or user inerraction. Make sure to
provide a reasonable value here.

Example:

    OUTPUT_DIR=/tmp/filewiki/${BUILD_TIME}


### PLUGINS

Mandatory. Defines a list of plugins to be enabled. There are three
types of plugins:

  * Page handler: Create a web page (e.g. Markdown, Copy,
    GenericPageHandler), or more generically spoken: Generates a
    target by transforming a source file. Only one page handler is
    allowed per source file. If no page handler plugin is enabled, the
    source file will not be processed.

  * Vars provider: Provide extra variables (e.g. Git, EXIF). Multiple
    vars provider are allowed.

  * Resource creator: Creates additional resources for a page
    (e.g. ImageMagick, ExtCmd). Multiple resiource creators are
    allowed.

Refer to FileWiki::Plugin::* modules documentation for further
information about each plugin.

Example:

    PLUGINS=Markdown,Copy

This enables the Markdown and Copy plugin.


### PLUGIN_&lt;plugin&gt;_MATCH

Defines a match on file names for a plugin. The given plugin will be
enabled if the file matches the expression.

Example:

    PLUGINS=Markdown,Copy
    PLUGIN_MARKDOWN_MATCH=\.txt$
    PLUGIN_COPY_MATCH=\.(ico|png)$

This enables the "Markdown" plugin for all files ending with ".txt",
and the "Copy" plugin for all files ending in ".ico" or ".png".


### PLUGIN_GROUP_&lt;group&gt;_MATCH

Defines a match on file names for a plugin group. The plugins in the
given group will be enabled if the file matches the expression.

Example:

    PLUGINS=EXIF<IMAGE>, ImageMagick<IMAGE>(THUMB), GenericPageHandler<IMAGE>
    PLUGIN_GROUP_IMAGE_MATCH=\.(jpg|png)$

This assigns the EXIF (vars provider), ImageMagick (resource creator)
and GenericPageHandler (page handler) plugins to the IMAGE group. All
files ending in ".jpg" or ".png" will be processed by the plugins in
the IMAGE group.


### TEMPLATE

Mandatory. Template to be parsed for the page. Relative to
`TT_INCLUDE_PATH`.


### TT_*

Set configuration options for [Template Toolkit]. See
[Template::Manual::Config] for a complete list of options.

Make sure the `INCLUDE_PATH` points to your template directory.

For the FileWiki apache handler to work correctly, you also need to
set `ABSOLUTE=1`.

Example:

    TT_INCLUDE_PATH=${BASEDIR}/template
    TT_ABSOLUTE=1


  [template toolkit]: http://template-toolkit.org/index.html
  [Template::Manual::Config]: http://search.cpan.org/~abw/Template-Toolkit/lib/Template/Manual/Config.pod


### CMD_*

Command being executed by `FileWiki::command($command)` function.

Example:

    CMD_INSTALL=rsync -rvz --delete -e "ssh -l webmaster" ${OUTPUT_DIR}/ www.example.org:/var/www/htdocs

This installs the page to the host www.example.org when typing:

    filewiki -c install example.org


### URI_PREFIX

Prefix for the URI's generated by FileWiki. Useful if the website
generated is in a subdirectory within some other site.


### URI_DIR

Set the root URI to a new value. This will make the source directory
(as well as all including files and folders recursively) appear under
a new root URI.

NOTE: Set this in `dir.vars`. You will get unexpected result when set
in `tree.vars`!


### URI_TRANSFORM_LC

If set, convert all URI's to lowercase.


### TARGET_MTIME

Format: "YYYY-MM-DD hh:mm:ss" or unix timestamp

If set, affects modification date for the target (output) file of a
page.

This is particulary useful if you use rsync -t for installing the
site, and you don't want a page's mtime to change on every install.


### TIME_FORMAT

Defines how time is formatted in the system. They correspond to the C
library routines "strftime" and "ctime".  Defaults to "%C".

Example:

    TIME_FORMAT=%B %e, %Y

Result: "January  1, 2011"


### SKIP

If set in `dir.vars` or `tree.vars`, files as well as subdirectories
will not be processed.  If set in `page.vars`, the page will not be
processed.


### SKIP_PREVNEXT

If set, the page will be excluded from the `PAGE_PREV` / `PAGE_NEXT`
list (see below).


### INDEX

Specifies the order of the page within the current directory. Defaults
to the source file name.

Important when creating menues using the `PageTree()` or `PageList()`
functions in the templates.

Note that the index is being sorted lexically (NOT numerically): This
means for example that "10" is considered smaller than "2". You should
use "02" here.


### MAKE_INDEX_PAGE

Marks the page as `INDEX_PAGE` for the directory. This is mainly
used by the menu.


### REF

Comma separated list of references to the page URI. Used by the HTML
converter (Markdown or Textile) to create links from a reference.

Only useful in `page.vars`.


### SORT_KEY

Key to use for sorting pages within a directory. Defaults to "INDEX".


### SORT_STRATEGY

Strategy to use for sorting pages within a directory. Supported values
are:

  * `sortkey-only`: sort by SORT_KEY (default).
  * `dir-first`: sort by SORT_KEY, but put directories in front.
  * `dir-last`: sort by SORT_KEY, but push directories to back.
  * `none`: do not sort (useful when using INCLUDE).


### SORT_ORDER

Order to use for sorting pages within a directory. Supported values
are:

  * `asc`: sort ascending (default).
  * `desc`: sort descending.


### INCLUDE_VARS

Include variables from a given vars file. Note that no checking on
circular including is performed. Make sure that you don't include vars
files which include the currently parsed file again!


### INCLUDE

Include files/directories. Multiple includes are separated by a colon,
or by using array variables. Optionally, you can specify a prefix from
where to read additional tree-, page- and file-vars in square
brackets.

Example (include files):

    INCLUDE=/my/include/file[myprefix]:/my/other/file

This includes the file specified. The vars for the included file will
be read from `myprefix.vars` in the current directory.


Example (include file and assign plugin):

    INCLUDE=/my/special/script.js > JavaScript

This includes the file specified, and sets `PLUGINS=JavaScript` in
page vars.


Example (include directories):

    INCLUDE=/my/include/directory[myprefix]:/my/other/include_dir

This includes the directories specified. The vars for the included
directory will be read from `myprefix.tree.vars` and
`myprefix.dir.vars` in the current directory. The vars from
subdirectories will be read from `myprefix_subdir.tree.vars` and
`myprefix_subdir.dir.vars`. The vars from a file `myfile.txt` within
the directory will be read from `myprefix_myfile.txt.vars`.

Example (use array variable):

    +INCLUDE=/my/include/directory[myprefix]
    +INCLUDE=/my/other/include_dir

Same as above, using array variable notation.


### EXCLUDE

Exclude files/directories on matching pattern. Multiple excludes are
separated by a colon, or by using array variables. The match is done
against the full path starting at `BASEDIR`.

Examples:

    EXCLUDE=/test.txt$
    EXCLUDE=private:\.bak$

The first example excludes any file or directory named "test.txt". The
second example excludes any file or directory containing the word
"private" (e.g. "somedir/private" or "my_privateer.txt"), and any file
or directory ending with ".bak".


### RESOURCES_FORCE_REBUILD

If set, force a rebuild of all resources (i.e. all files generated by
resource creator plugins), even if the resource files already exist.


### SRC_REGEXP

Modify source file data before it is processed by plugins. Use with
care!

The only supported regexp modifier is 'g'. Note that filewiki always
adds the 'm' and 'ee' modifiers.

Example (fix links in Markdown source):

    SRC_REGEXP=s/\(doc\/([a-zA-Z0-9_]+).md\)/\(\L$1\E.html\)/g


Preset Variables
----------------

The variables described here are set by FileWiki, and can be used in
the templates.

### NAME

The name of the page (or directory respectively). This is taken from
the filename. Changing this variable directly affects the `URI`
variable (or `URI_DIR` for directories).


### ENV

System environmnent (reference to Perl %ENV).


### MTIME

Modification date, taken from the source file modification date, and
formatted using the `TIME_FORMAT` variable.


### BUILD_DATE

Date of the generation of a page. This is set to the systems current
date upon page generation, and formatted using the `TIME_FORMAT`
variable.


### PAGE_PREV

Points to the previous page in current directory. Not set if current
page is first page.


### PAGE_NEXT

Points to the next page in current directory. Not set if current page
is last page.


### DIR

Container for the `dir.vars`. Makes the `dir.vars` accessible from the
page.

Template Example:

    [% DIR.my_var %]

Returns the variable `my_var` from `dir.vars`.


Transformation Variables
------------------------

### EVAL

`EVAL` variables must be declared as arrays (using the '+' modifier).

Expression of form `[!]KEY: EXPR`. Sets $_ to the value of `KEY`, and
assigns the value of $_ to variable `KEY` after evaluating
`EXPR`.

The transformation happens after "variable late expansion", or, if the
`!` modifier is set, before any variables are read from disk. Using
the `!` modifier makes only sense if you wish to transform system
variable presets at an early state (e.g. `NAME` or `URI_DIR`).

Note that `EXPR` is evaluated using the perl `eval` statement, which
means that you can do very nasty stuff with this!

Examples:

    +EVAL  !NAME: s/^\d+-//
    +EVAL  NAME: WARN "EVAL: malformed NAME=$_" if($_ =~ /^[^A-Za-z]/)
    +EVAL  title: s/_/ /g

The first line removes leading digits from variable NAME, affecting
the resulting URI of all pages down the tree. The second line prints a
warning if NAME does not start with a letter. The third line replaces
all underscores with whitespace on variable `title`.

Invasive Examples:

    +EVAL  NAME: print "I'm a dirty hacker! " while 1
    +EVAL  passwd: $_ = `cat /etc/passwd`

These examples show why you should not let FileWiki process variables
from unknown sources.
