TEMPLATE FILE SYNTAX

NAME

funroll::Page - A fuss(1) Module that creates the source for your slide show.

DESCRIPTION

This module takes a TEMPLATE FILE, and substitutes in your filenames / captions (which you specified in the fuss(1)/CONFIG FILE). It understands basic loops and flow control statements (so you can design tables etc). If the limited syntax doesn't meet your needs, it has the option to filter the processed template through your favourite text processor (php, perl, etc).

OPTIONS

output_dir: The directory your output files go into. Generally, when filenames are prefixed with a ``-'', they will go in this directory. The directory name should end with a ``/''.
shared_outdir: The directory your shared files should go into. Shared files prefixed with a ``+'' will go in here. The directory name should end with a ``/''.
cwd: The current directory. Files prefixed with ``./'' will go in here. The directory name should end with a ``/''.
base_dir: The base directory of the program. Input files prefixed with ``='' will be looked for in here. The directory name should end with a ``/''.
templates_dir: The base directory for templates. Template files prefixed with a ``+'' will be looked for in here. The directory name should end with a ``/''.
shared_indir: The base directory for shared input files. Sources of shared files prefixed with a ``+'' will be looked for in here. The directory name should end with a ``/''.
template_file: Name of the template file. This file is processed by this module and transformed into the html / php / etc source for your slide show. See the section on TEMPLATE FILES.
pagename: Expression that returns the name of the current page. The current page number can be found in the token &pageno;. If this evaluates to ``'' then the page is written to the STDOUT.
filter: Program to filter your output through. %f (or %s) denote the filename. For instance, setting this option to ``php %f'' will filter your page through php.
copy_shared: If this option is defined, shared files will be copied to the correct location.
statements: You can change the syntax of the template file by changing this (and a few other undocumented options). These are a bunch of perl regexps which tell this module the syntax of the statements (loop control / conditionals / etc). If you don't like the default syntax, read the source to figure out the exact details on these regexps. Then change them to your taste :)

TOKENS

Tokens are used in the template file. An expression of the form &token; in the template file is replaced with the value of the token (unless it's overridden by a shared file). See the section on TEMPLATE FILE for the exact syntax.

The tokens depend highly on the template file. If you're using a theme, then you should also see the theme documentation for a list of tokens. The following tokens however are universal to all template files.

firstpage: Expression that evaluates to the first page number. For each number between the firstpage and lastpage, fuss will process the template file and produce an output (controlled by the option pagename).
lastpage: Expression that evaluates to the last page number.
pageno: This token SHOULD NOT be set. This evaluates to the page number of the current page. You can use this freely in the template file, or in the pagename option.

SHARED FILES

Shared files are typically icons or style sheets (but can be anything). If the option copy_shared is set, these are copied. Shared files can be accessed as tokens in the TEMPLATE FILE.

Any shared file has the following attributes:

nocopy: If this attribute is set, this file is not copied.
src: This contains the source location of the file. If unset the value from the name attribute, prefixed with a `+' is used.
dest: This contains the destination location of the shared file. If unset the value from the name attribute, prefixed with a `+' is used.

TEMPLATE FILE

The ``Template file'' is a ``template'' for your slide show source. filenames / tokens are substituted as instructed into the template file, and the output is written into one or more files.

TEMPLATE FILE SYNTAX

Any statement not understood is echoed verbatim into the output. If a semicolen occers at a word boundary, it can be omited EXCEPT when it directly follows an & (like marking the end of an expression in &if ... &;). I.e. &else Hello world is OK, but &elseHello world is not.

Most statements (not tokens / list refferences) will 'gobble' spaces (and tabs) before them, and all consecuitive newlines after them. An &space; (or &sp for short) can be used to stop a statement from gobbling spaces (e.g. &space&if will not gobble spaces before, and &endif&space will not gobble spaces after). An &\ anywhere will gobble all spaces and newlines spaces after it. This functionality is provided mainly so that you can indent your HTML code as you normally would, and indent fuss statements like preprocesser directives, and the resulting HTML code will be `properly' indented.

&tokname;

This evaluates to the value of the shared file or token named tokname (if one exists). If not, this is untouched. If a shared file named tokname exists, then the value of the ``name'' attribute of the shared file is used. If not, and a token named tokname is defined, then the value of that token is used.

&name{attr}

If a shared file named name is defined, and has the attribute attr defined, this evaluates to the value of the attribute attr of the shared file name. Otherwise, if the shared file name is defined, but does not have the attribute attr defined, this evaluates to the empty string. If a shared file named name is not defined, this expression is untouched.

&pagename{expr}

Evaluates to the name of the page numbered expr as specified by the pagename option. expr is evaluated as a perl(1) expression.

&literal{stuff}

Evaluates to &stuff. (To be used to just incase you think using &stuff will confuse fuss.)

&?tokname;

Evaluates to 1 if a shared file named tokname or a token named tokname is defined. Evaluates to 0 otherwise.

&name[expr]{attr}

If a list named name exists, then if it has item expr which has attribute attr then the expression evaluates to this value. If the list name exists, but does not have item expr or the exprth item doesn't have the attribute attr, then the expression evaluates to the empty string. If the list name does not exist, this expression is untouched.

&#name;

If a list named name exists, then evaluates to the number of the items in the list name. If not evaluates to 0.

&?#name;

Evaluates to 1 if a list named name exists and 0 otherwise.

&for id, start, end, step &;

...

&endfor;

Equivalent to:

    for( id=start; id<end; id+=step) {
        ...
    }

In the body of the loop the the value of the loop index can be accessed as a token named id.

&eval expr &;

This evaluates to the value of expr evaluated as a perl(1) expression.

if expr &;

...

elsif expr &;

...

else

...

endif;

The usual if / elsif ladder. The elsif and else blocks are optional, and there can be more than one elsif blocks. The expr (after token substitution) is evaluated as a perl(1) expression. See perlop(1) for a list of operators / syntax etc.

&include filename&;

Just like #include ``filename'' in C. If filename does not begin with '.', '/', '+' or '=', it is looked for in the directory of the current file being processed.

LICENCE

This program, and all files distributed with it are protected under the GNU General Programers Licence version 2 or later. See the file Licence for details.

AUTHOR

Gautam Iyer <gi1242@users.sourceforge.net>.