CHRONICLE(1)						User Contributed Perl Documentation					      CHRONICLE(1)

NAME

       chronicle - A simple blog compiler.

SYNOPSIS

	 chronicle [options]

	 Path Options:

	  --comments	   Specify the path to the optional comments directory.
	  --config	   Specify a configuration file to read.
	  --input	   Specify the input directory to use.
	  --output	   Specify the directory to write output to.
	  --theme-dir	   Specify the path to the theme templates.
	  --theme	   Specify the theme to use.
	  --pattern	   Specify the pattern of files to work with.
	  --url-prefix	   Specify the prefix to the live blog.
	  --sitemap-prefix Specify the prefix for the site map.

	 Blog Entry Options:

	  --format	Specify the format of your entries, HTML/textile/markdown.

	 Pre & Post-Build Commands:

	  --pre-build	 Specify a command to execute prior to building the blog.
	  --post-build	 Specify a command to execute once the blog has been built.
	  --pre-filter	 A command to filter each blog entry before HTML conversion.
	  --post-filter  A command to filter each blog entry after HTML conversion.

	 Sorting Options:

	  --recent-dates-first	Show recent entries first in the archive view.
	  --recent-tags-first	Show recent entries first in the tag view.

	 Counting Options:

	  --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
	  --comment-days Specify the number maximum age of posts to accept comments.
	  --date-archive-path  Include the date in the archive.
	  --force	 Force the copying of static files from the blog theme.
	  --lang	 Specify the language to use for formatting dates.
	  --lower-case	 Lower-case all filenames which are output.
	  --no-archive	 Don't create an archive page.
	  --no-cache	 Don't use the optional memcached features, even if available.
	  --no-calendar  Don't use the optional calendar upon the index.
	  --no-comments  Don't allow comments to be posted.
	  --no-sitemap	 Don't generate a sitemap.
	  --no-tags	 Don't produce any tag pages.
	  --no-xrefs	 Don't produce any cross references.

	 Help Options:

	  --help	Show the help information for this script.
	  --manual	Read the manual for this script.
	  --verbose	Show useful debugging information.
	  --version	Show the version number and exit.

ABOUT

	 Chronicle is a simple tool to convert a collection of text files,
	located within a single directory, into a blog consisting of static
	HTML files.

	 It supports only the bare minimum of features which are required
	to be useful:

	  * Tagging support.

	  * RSS support.

	  * Archive support.

	 The obvious deficiencies are:

	  * Lack of support for instant commenting.

	  * Lack of pingback/trackback support.

	 Having said that it is a robust, stable, and useful system.

BLOG FORMAT

	 The format of the text files we process is critical to the output
	pages.	Each entry should look something like this:

	   Title:  This is the title of the blog post
	   Date:  2nd March 2007
	   Tags: one, two, three, long tag

	   The text of your entry goes here.

	 NOTE: The header MUST be separated from the body of the entry by at least a
	single empty line.

	 In this example we can see that the entry itself has been prefaced
	with a small header.  An entry header is contains three optional lines,
	if these are not present then there are sensible defaults as described
	below.

	  The formatting of the output dates may be changed via the use of the
	B<--lang> command line option (or the matching "lang=french" option in the
	configuration file), but the date of the entry itself should be specified in
	English.

       Title: Describes the title of the post.	If not present the filename of the entry is used instead.  "Subject:" may also be used.
       Subject: This is a synonym for 'Title:'.
       Date: The date the post was written.  If not present the creation time of the file is used instead.
       Publish: This header is removed from all entries, and is used by the chronicle-spooler script.
       Tags: Any tags which should be associated with the entry, separated by commas.

	 The format of the entry is assumed to be HTML, however there is support
	for writing your entries in both textile and markdown formats.

	 The format of entries is specified via the B<--format> argument, or
	via a "format: foo" setting in your chroniclerc file.

	 The format of entries is assumed to be global; that is all your entries
	will be assumed to be in the same format.  However you can add a
	"format: foo" pseudo header to specific entries if you wish to write
	specific entries in a different format.

	 To allow flexibility in the handling of entries each blog entry will
	be passed through the filter script B<chronicle-entry-filter>
	which allows you to modify this handling in a single location. This
	script allows entries to be updated via filters both before and after
	the conversion to HTML.  For further details please see the manpage for
	that script.

CONFIGURATION

	 The configuration of the software is minimal, and generally performed
	via the command line arguments.  However it is possible to save settings
	either in the file global /etc/chroniclerc or the per-user ~/.chroniclerc
	file.

	 If you wish you may pass the name of another configuration file to
	the script with the B<--config> flag.  This will be read after the
	previous two files, and may override any settings which are present.

	 The configuration file contains lines like these:

	  input  = /home/me/blog

	  output = /var/www/blog

	  format = markdown

	 Keys which are unknown are ignored.

OPTIONAL CACHING

	 To speed the rebuilding of a large blog the compiler may use a local
	Memcached daemon, if installed and available.

	 To install this, under a Debian GNU/Linux system please run:

	   apt-get update
	   apt-get install memcached libcache-memcached-perl

	 You may disable this caching behaviour with --no-cache, and see the
	effect with --verbose.

OPTIONAL CALENDAR

	 If the 'HTML::CalendarMonthSimple' module is available each blog will
	contain a simple month-view of the current month upon the index.

	 To disable this invoke the program with '--no-calendar'.

OPTIONAL COMMENTING

	 Included with the chronicle code you should find the file
	cgi-bin/comments.cgi.

	 This file is designed to write submitted comments to the local
	filesystem of your web-server.	If you install that, and edit the
	path at the start of the script you should be able to include
	comments in your blog.

	 In short there are three things you need to do:

       Install the CGI script and edit the path at the start.
       Copy the output comments to your local blog source.
       Run this script again with --comments=./path/to/comments

	 This should include the comments in the static output.  More
	explicit instructions are provided within the file 'COMMENTS'
	included within the distribution.

AUTHOR

	Steve
	--
	http://www.steve.org.uk/

LICENSE

       Copyright (c) 2007-2010 by Steve Kemp.  All rights reserved.

       This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  The LICENSE file contains the
       full text of the license.

perl v5.12.3							    2011-05-15							      CHRONICLE(1)