CHRONICLE(1)

📦 version 4.6, in debian bookworm, ubuntu jammy, ubuntu noble

💖 CHRONICLE(1) 💖

okay so bestie, welcome to the chronicle manual page — it's a User Contributed Perl doc, and it's literally your new fave thing. let's get into it 🦋

✨ NAME ✨

chronicle — a simple blog compiler. that's it, that's the whole vibe. no cap. 💅

🌸 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.

and now the option-by-option rundown, because you deserve the full tour 🎀

🗂️ Path Options

  • --comments — point this at the optional comments directory, if you have one.
  • --config — hand it a configuration file to read.
  • --input — tell it which input directory to use.
  • --output — tell it which directory to write the output to.
  • --theme-dir — the path to your theme templates.
  • --theme — which theme to use.
  • --pattern — the pattern of files it should work with.
  • --url-prefix — the prefix for the live blog.
  • --sitemap-prefix — the prefix for the site map.

📝 Blog Entry Options

  • --format — the format of your entries: HTML, textile, or markdown.

🚀 Pre & Post-Build Commands

  • --pre-build — a command to run before the blog gets built.
  • --post-build — a command to run 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 — the maximum age of posts that will accept comments.
  • --date-archive-path — include the date in the archive.
  • --force — force the copying of static files from the blog theme.
  • --lang — 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 they're 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 👑

okay so, the whole tea: Chronicle is a simple tool that converts a collection of text files — all chillin' in a single directory — into a blog made of static HTML files. iconic behaviour honestly. 🫶

it supports only the bare minimum of features required to be useful:

  • Tagging support. ✨
  • RSS support. ✨
  • Archive support. ✨

and the obvious deficiencies (not me listing the red flags):

  • Lack of support for instant commenting. 😭
  • Lack of pingback/trackback support. 😭

having said all that — it is a robust, stable, and useful system. periodt. 💅

🦋 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. no skipping this one bestie, it's giving mandatory.

so in this example we can see the entry itself has been prefaced with a small header. an entry header 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 --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 --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 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 --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. (they're just there for the vibes, apparently. 🙈)

⚡ OPTIONAL CACHING ⚡

to speed the rebuilding of a large blog, the compiler may use a local Memcached daemon, if installed and available. lowkey a glow-up for big blogs. 💅

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. main character energy fr fr. ✨

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:

  1. Install the CGI script and edit the path at the start.
  2. Copy the output comments to your local blog source.
  3. 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.

and that's the whole page bestie!! 💖 this one's perl v5.32.0, dated 2021-01-05 — so go forth, compile that blog, and slay. 🌈👑✨

📦 where this page comes from