--funroll-slideshow Code

215 lines (124 with data), 9.6 kB

=head1 NAME

fuss - An extensible customisable program to create HTML slideshows.

=head1 SYNOPSIS

B<fuss> I<filename> 

=head1 DESCRIPTION

B<fuss> (short for B<--funroll-slideshow>) is a highly customisable program designed to create slide shows. Anyone who's tried to write an HTML slide show from scratch knows how tedius the task can be (especially if one has a large collection of images). B<fuss> simplifies matters as follows. 

=over

=item 1.  

You write a L</CONFIG FILE> for B<fuss>, with the list of images, captions or whatever else you choose to include. 

=item 2.  

You write one or more "Templates" for your slide show in any markup language. (You can just use the default Theme [see L</THEMES>] if you like).


=back

That's it. B<fuss> does the rest. B<fuss> has a collection of L</MODULES> (which in reality are just Perl Modules) which are executed from the L</CONFIG FILE>. The module funroll::Page(1) substitutes the filenames / captions specified in the config file, and generates a html file (generally your slideshow or index files). It understands basic loop control and flow statements, so you can control the output to your taste. It also provides the option to filter the output through a preprocesser (like B<php> for instance).

The module funroll::Resize(1) resizes and or rotates your images, and the module funroll::Directory(1) can be used to recurse folders. See the section on L</MODULES> for a complete list and description. See also the section on L</THEMES>, which are a collection of config files, templates, stylesheets and icons designed to create a complete slideshow.

Finally, if you're interested in extending B<fuss> you should read the source :). I've not got around to documenting the interface yet, but will soon. If you write a perl module which might be usefull to others then send it to me for inclusion with B<fuss>.

=head1 CONFIG FILE

B<fuss> begins by reading the config file specified on the command line, and exits after processing it. A L</CONFIG FILE> is used to define tokens (like a title), options, lists (like a list of images), shared files (like icons or stylesheets) and to execute actions (L</MODULES>) like creating HTML sources for your slide show, or resizing images.

=head2 CONFIG FILE SYNTAX

Blank lines, and lines beginning with a # are treated as comments (and ignored). Leading spaces are ignored, so indent as you like. Lines ending with a "\" are treated as continuing onto the next line.

=over

=item B<option> [B<default>] I<name> = I<value>

Sets the option I<name> to I<value>. I<value> is treated as a literal string, so please don't quote it (unless you want the quotes to be part of I<value>). Options are used differently by each module, so see the section on L</MODULES> for a list of options and descriptions.

If the keyword B<default> is present, then the value of I<name> is set only if it has not previously been set or unset. If I<value> is B<undef> then the option I<name> is undefined, and it's existence forgotten. You can use this to unset an option.

=item B<token> [B<default>] I<name> = I<value>

Behaves exactly like the B<option> command, except it sets a "token" instead. Tokens are used differently by each module, so see the section on L</MODULES> for details.

=item B<shared> [B<default>] I<filename> [I<prop1>=I<val1>] [I<prop2>=I<val2>] [...]

=item B<shared_file> [B<default>] I<filename> [I<prop1>=I<val1>] [I<prop2>=I<val2>] [...]

Defines a shared file I<filename>. If specified, each shared file has the attributes I<attr1>, I<attr2>, ... associated to it (with values I<val1>, I<val2>, ...). If a B<name> attribute is not specified, then it is defined by default, and has the value I<filename>. If the keyword B<default> is present, then attributes are set only if they are not previously defined (or undefined). 

A shared file is exactly what the name suggests. For instance, a stylesheet or icon could be a shared file. Each module has a different action for shared files, so see the section on L</MODULES> for an explanation of what the module does to shared files, and a list of attributes. In general, shared files will either be ignored, or copied to the appropriate shared directory.

=item B<list> I<listname> B<fields>=(I<field1> [,I<field2>...]) {

=over

=item I<value1> [: I<value2> [:...]]

=back

=item }        

=item Z<>

Defines a list called I<listname>. Each line between the braces "{" and "}" is an item in this list. Each item in this list has fields (or attributes) named I<field1>, I<field2>... with values I<value1>, I<value2>... . If a value contains a ":", then precede it with a backslash.

Each module handles lists differently. Different templates, modules or themes might require specially named lists. See the section on L</MODULES> and L</THEMES>.

=item B<local> I<ENDWORD> 

=over

=item I<line1>

=item I<[line2]>

=item I<[...]> 

=back

=item I<ENDWORD>

The lines I<line1>, I<line2>, ... are processed as a L</CONFIG FILE>. When a line containing the identifier I<ENDWORD> alone is found, all operations done in I<line1>, I<line2>, ... are forgotten, and processing of the config file resumes as it were before it encountered the B<local> statement. 

=item B<include> I<filename>

Reads the config file I<filename>, and then continues with the current file (just like B<#include> in C).  B<fuss> first searches for I<filename> as follows:

=over

=item 1.

If I<filename> begins with "B<=>", then fuss looks for the file in fuss's base directory (the directory containing the base executable, with all symlinks resolved).

=item 2.

The filename "B<+filename>" is equivalent to "B<=include/filename>".

=item 3.

If the file beginns with either a "B<.>" or a "B</>", then the file treated as relative to the current directory, or an absolute path (respectively).

=item 4.

Otherwise B<fuss> looks for I<filename> in the same directory as the config file currently bieng processed.

=back

=item B<do> I<filename>

Equivalent to:

    local EOF
	include filename
    EOF

=item B<funroll> I<ModName>

This passes all the lists, options, tokens, and shared files to the module I<ModName>. Each module does something different. See the section on L</MODULES> for a list of modules, and a description of what they do.

=back

=head1 MODULES

B<fuss> has a collection of Modules, each of which serve a specific purpose. Modules are executed from the L</CONFIG FILE> using the L<"funroll"|/item funroll ModName> command. Each module has it's own man page. The modules currently shipped with B<fuss> are:

=over

=item funroll::Page(1)

Creates the source (HTML / PHP / etc) for your slide show.

=item funroll::Resize(1)

Resizes and or rotates your images.

=item funroll::Directory(1)

Recurses directories.

=back

=head1 THEMES

In reality a "Theme" is nothing but a collection of L</CONFIG FILE>S and "Templates", which create a complete slide show. Using themes is easy. First create a L</CONFIG FILE> and define your images, captions, titles, descriptions and other options. At the end of your config file, just call the theme file with L<"do +Theme.fuss"|/item do filename>. That's it.

Currently there is only one theme fussTheme::Simple(1). Hopefully someone (you) will write more :). If you do, and you think it looks good, send it to me for inclusion with fuss.

See the man page funroll::Simple(1) for a description and list of options of the "Simple" theme.

=head1 EXAMPLES

The following config file recurses the current directory and creates a slide show:

    # When hosting your pictures online, upload both the following
    # directories to your webserver.
    option output_dir     = /tmp/upload/pictures/
    option shared_outdir  = /tmp/upload/shared/

    # When hosting your pictures online, change the token below to
    # point to the location of the shared_outdir above. If left
    # unchanged, the html files generated will be suitable for
    # viewing only on your local computer.
    token  shared_prefix  = /tmp/upload/shared/

    # Set the title subtitle and contat info as desired. (HTML can
    # be used here).
    token  title          = My Fantastic Pictures
    token  subtitle       = June 11<sup>th</sup>, 2004
    token  contact_info   = Deeds Drumhill &lt;\
	<a href="mailto:deeds@zartop.com">deeds@zartop.com</a>&gt;

    # Create the slideshow
    funroll Directory

The following config file creates a slide show with captions for specified files.

    option output_dir     = /tmp/upload/pictures/

    # If you'd like shared files from all slideshows you create to go
    # in the same directory, then uncomment the following lines.
    # Before hosting your files online, be sure to change the token
    # shared_prefix to point to the location of your shared files
    #
    # option shared_outdir  = /tmp/upload/shared
    # token  shared_prefix  = /tmp/upload/shared

    # Set the title subtitle and contat info as desired.
    # (HTML can be used here).
    token  title          = My Fantastic Pictures
    token  subtitle       = June 11<sup>th</sup>, 2004
    token  contact_info   = Deeds Drumhill &lt;\
	<a href="mailto:deeds@zartop.com">deeds@zartop.com</a>&gt;

    # Define captions for your images
    list	files fields=(filename, caption) {
	image1.jpg	: Caption for image1.jpg
	image2.jpg	: Caption for image2.jpg
	image3.jpg	: Caption for image3.jpg
	image4.jpg	: Caption for image4.jpg
    }

    # Specify the directory containing your images.
    option image_indir    = ./

    # Create the slideshow
    do +Simple/Create.fuss