chronicle1

Usage

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.