view release on metacpan or  search on metacpan

bin/chronicle  view on Meta::CPAN

chronicle - A static blog-compiler.

=cut

=head1 SYNOPSIS

  chronicle [options]


  Path Options:

   --comments       Specify the path to the optional comments directory.
   --config         Specify a configuration file to read.
   --database       Specify the path to the SQLite database to create/use.
   --input          Specify the input directory to use.
   --output         Specify the directory to write output to.
   --pattern        Specify the pattern of files to work with.
   --theme          Specify the theme to use.
   --theme-dir      Specify the path to the theme templates.
   --url-prefix     Specify the prefix to the generated blog.
   --template-engine Specify the template system to use
                    (HTMLTemplate (default), Xslate or XslateTT)

  Counting Options:

   --comment-days=N    The maximum age a post may allow comments.
   --entry-count=N     Number of posts to show on the index.
   --rss-count=N       Number of posts to include on the RSS index feed.

  Optional Features:

   --author        Specify the author's email address.
   --blog-subtitle Set the title of the blog.
   --blog-title    Set the title of the blog.
   --force         Always regenerate pages.
   --lower-case    Write only lower-case post-files.
   --unicode=<yes|no|mac>
                   Allow non-ASCII characters in file names. Default is
                   `no'. Use `mac' if serving files off an HFS+ volume.

  Help Options:

   --help         Show the help information for this script.
   --list-plugins List the available plugins.
   --list-themes  List the available themes.
   --manual       Read the manual for this script.
   --verbose      Show useful debugging information.
   --version      Show the version number and exit.

=cut

=head1 ABOUT

Chronicle is a blog-compiler which will convert a directory full of
plain-text blog-posts into a fully-featured HTML website containing
posts, tags, and archives.

All blog-posts from a given input directory are parsed into a SQLite
database which is then used to generate the output pages.

The SQLite database is assumed to persist, such that it will be updated
if new posts are written, or previous posts are updated.  However if
it is removed it will be recreated when needed.

=cut

=head1 DATABASE STRUCTURE

When C<chronicle> is first executed it will create an SQLite database
if it is not already present.  The database will contain two tables,
one for the posts, and one to store the tags associated with the posts,
if you choose to use tags in your entries.

The blog-entry table contains the following columns:

=over 8

=item mtime

The C<mtime> of the input file.

=item date

The date-header as self-reported in the blog-post.

=item body

The body of the blog-post itself.

=item title

The title of the blog-post itself.

=back

If you wish to add extra tables via a local plugin you're welcome to do so.

=cut

=head1 EXTENDING WITH PLUGINS

The main driver, chronicle, is responsible for only a few small jobs:

=over 8

=item Finding Blog Posts.

By default C<data/*.txt> are read, but you may adjust the input directory via the C<--input> command-line flag.  The pattern may be set with C<--pattern>.

B<NOTE> The pattern is applied recursively, if you wish to create sub-directories with your posts inside them for organizational purposes.

=item Inserting them into the SQLite database.

The header is read to look for things such as the post-date, the subject,
and the tags.  The body is imported literally, unless expanded and reformatted
via a plugin.

=item Executing plugins

Each registered plugin will be invoked in turn, allowing the various
output parts to be generated.