view release on metacpan or  search on metacpan

lib/App/Followme/Guide.pm  view on Meta::CPAN

package App::Followme::Guide;

use 5.008005;
use strict;
use warnings;
use integer;

use base qw(Pod::Text);

#----------------------------------------------------------------------
# Create a new object to display the pod in this document

sub new {
    my ($pkg) = @_;

    my $self = Pod::Text->new();
    return bless($self, $pkg);
}

#----------------------------------------------------------------------
# Print the pod from this file into a string

sub print {
    my ($self) = @_;

    my $result;
    $self->output_string(\$result);
    $self->parse_file(__FILE__);
    
    return $result;
}

1;

=pod

=encoding utf-8

=head1 NAME

App::Followme::Guide - How to install, configure, and run followme

=head1 SYNOPSIS

    followme [directory]

=head1 DESCRIPTION

Updates a static website after changes. Constant portions of each page are
updated to match, text files are converted to html, indexes are created
for files in the archive, and changed files are uploaded to the remote server.

The followme script is run on the directory or file passed as its argument. If
no argument is given, it is run on the current directory.

If a file is passed, the script is run on the directory the file is in. In
addition, the script is run in quick mode, meaning that only the directory
the file is in is checked for changes. Otherwise, not only that directory, but
all directories below it are checked.

=head1 CHANGES

This version is version two of followme. In the past the code constructed a hash 
and passed it to the template, which used the values in the hash to produce the 
web page. In version two the code passes an object to the template, which calls 
the build method for each variable in the template, passing the name of the 
variable and a filename to retrieve it from as arguments. The module then 
returns the value, which is used to fill in the template. The major user visible 
change is that the template syntax has changed, the new syntax is a subset of the 
previous syntax. Please see L<App::Followme::Template> for a description of the 
template syntax. 

The second change is that the configuration parameters of some of the modules 
has changed. The new configuration parameters are described in each module. 
The motivation for the change is that placing the variable building in a separate 
class allows more than one type of file to be handled by modules placed in the 
configurarion file. Each class handles a type of file and the name of the class 
which builds the variables is a configuration parameter. 

The third change is that the configuration file format has changed
to use a subset of yaml instead of . The new configuration file format is decribed 
below. The biggest change is to how modules are assigned to run_before and
run_after. Previously this is how the configuration file would look:

    author = Your Name
    run_before = App::Followme::FormatPage
    run_before = App::Followme::ConvertPage
    run_after = App::Followme::CreateSitemap 

This is how the same lines in the configuration file look now:

    author: Your Name
    run_before:
        - App::Followme::FormatPage
        - App::Followme::ConvertPage
    run_after:
        - App::Followme::CreateSitemap 

=head1 INSTALLATION

First, install the L<App::Followme> module from CPAN. It will copy the
followme script to /usr/local/bin, so it will be on your search path.

    sudo cpanm App::Followme

Then create a folder to contain the new website. Run followme with the
init option in that directory

    mkdir website
    cd website
    followme --init

lib/App/Followme/Guide.pm  view on Meta::CPAN

    <!-- section name in folder_name -->
    <!-- endsection name -->

where folder_name is the the folder the content is kept constant across. The
folder name is not a full path, it is the last folder in the path.

=item L<App::Followme::ConvertPage>

This module changes text files to html files. By default the text files are
in Markdown format, though other converters can be used. Markdown format is 
described at:

    http://daringfireball.net/projects/markdown/

It builds several variables and substitutes them into the page template. The
most significant variable is body, which is the contents of the text file
after it has been converted to html. The title is built from the title of
the file if one is put at the top of the file. If the file has no
title, it is built from the file name, replacing dashes with blanks and
capitalizing each word, The url and absolute_url are built from the html file
name. To change the look of the html page, edit the page template. Only blocks
inside the section comments will be in the resulting page, editing the text
outside it will have no effect on the resulting page. A complete listing of the
variables is given in the variables section.

=item L<App::Followme::CreateIndex>

This module builds an index for a directory containing links to all the files
with the specified extension contained in it. The same variables mentioned above
are calculated for each file, with the exception of body. Comments that look like

    <!-- for @files -->
    <!-- endfor -->

indicate the section of the template that is repeated for each file contained
in the index.

=item L<App::Followme::CreateGallery>

Create a photo gallery for images in a directory. Each image must have a 
thumbnail image whose name has the suffix "-thumb". The suffix name is a 
configuration parameter. The code is very similar to 
L<App::Followme::CreateIndex>, but the template is more complex, so it is a 
separate module.

=item L<App::Followme::CreateRss>

This module creates an rss file from the metadata of the most recently updated 
files in a directory. It is a companion to App::Followme::CreateIndex and should
be used if you also want an rss file.

=item L<App::Followme::CreateSitemap>

This module creates a sitemap file, which is a text file containing the url of
every page on the site, one per line. It is also intended as a simple example of
how to write a module that can be run by followme.

=item L<App::Followme::UploadSite>

This module uploads changed files to a remote site. The default method to do the
uploads is local copy, but that can be changed by changing the parameter upload_pkg.
This package computes a checksum for every file in the site. If the checksum has
changed since the last time it was run, the file is uploaded to the remote site.
If there is a checksum, but no local file, the file is deleted from the remote
site. If followme is run in quick mode, only files whose modification date is
later then the last time it was run are checked.

=back

=head1 RUNNING

The followme script is run on the directory or file passed as its argument. If
no argument is given, it is run on the current directory. If a file is passed,
the script is run on the directory the file is in and followme is run in
quick mode. Quick mode is an implicit promise that only the named file has
been changed since last time. Each module can make of this assumption what it
will, but it is supposed to shorten the list of files examined.

Followme looks for its configuration files in all the directories above the
directory it is run from and runs all the modules it finds in them. But they are
are only run on the folder it is run from and subfolders of it. Followme only
looks at the folder it is run from to determine if other files in the folder
need to be updated. So after changing a file, followme should be run from the
directory containing the file.
Templates support the basic control structures in Perl: "for" loops and
"if-else" blocks. Creating output is a two step process. First you generate a
subroutine from one or more templates, then you call the subroutine with your
data to generate the output.

The template format is line oriented. Commands are enclosed in html comments
(<!-- -->). A command may be preceded by white space. If a command is a block
command, it is terminated by the word "end" followed by the command name. For
example, the "for" command is terminated by an "endfor" command and the "if"
command by an "endif" command.

All lines may contain variables. As in Perl, variables are a sigil character
('$' or '@') followed by one or more word characters. For example, C<$name> or
C<@names>. To indicate a literal character instead of a variable, precede the
sigil with a backslash. When you run the subroutine that this module generates,
you pass it a metadata object. The subroutine replaces variables in the template
with the value in the field built by the metadata object.

If the first non-white characters on a line are the command start string, the
line is interpreted as a command. The command name continues up to the first
white space character. The text following the initial span of white space is the
command argument. The argument continues up to the command end string.

Variables in the template have the same format as ordinary Perl variables,
a string of word characters starting with a sigil character. for example,

    $body @files

are examples of variables. Array variable names (variable names starting with 
a C<@>) may have a suffix that indicates how the array is sorted. You can add
a suffix to a scalar variable (variable names strting with a C<$>) but it
will have no effect. The format for the name is:

    @data_field[_by_$sort_field][_reversed]

the brackets are not part of the variable name. They are there to indicate that 
these sections are optional. Two examples of variables with sort suffixes are

    @files_by_size