.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "CHRONICLE 1" .TH CHRONICLE 1 "2021-01-05" "perl v5.32.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" chronicle \- A simple blog compiler. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& 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\*(Aqs 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\*(Aqt create an archive page. \& \-\-no\-cache Don\*(Aqt use the optional memcached features, even if available. \& \-\-no\-calendar Don\*(Aqt use the optional calendar upon the index. \& \-\-no\-comments Don\*(Aqt allow comments to be posted. \& \-\-no\-sitemap Don\*(Aqt generate a sitemap. \& \-\-no\-tags Don\*(Aqt produce any tag pages. \& \-\-no\-xrefs Don\*(Aqt 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. .Ve .SH "ABOUT" .IX Header "ABOUT" .Vb 3 \& 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. .Ve .SH "BLOG FORMAT" .IX Header "BLOG FORMAT" .Vb 2 \& The format of the text files we process is critical to the output \& pages. Each entry should look something like this: .Ve .PP .Vb 3 \& 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. .Ve .PP .Vb 2 \& 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. .Ve .ie n .IP "Title: Describes the title of the post. If not present the filename of the entry is used instead. ""Subject:"" may also be used." 8 .el .IP "Title: Describes the title of the post. If not present the filename of the entry is used instead. ``Subject:'' may also be used." 8 .IX Item "Title: Describes the title of the post. If not present the filename of the entry is used instead. Subject: may also be used." .PD 0 .IP "Subject: This is a synonym for 'Title:'." 8 .IX Item "Subject: This is a synonym for 'Title:'." .IP "Date: The date the post was written. If not present the creation time of the file is used instead." 8 .IX Item "Date: The date the post was written. If not present the creation time of the file is used instead." .IP "Publish: This header is removed from all entries, and is used by the chronicle-spooler script." 8 .IX Item "Publish: This header is removed from all entries, and is used by the chronicle-spooler script." .IP "Tags: Any tags which should be associated with the entry, separated by commas." 8 .IX Item "Tags: Any tags which should be associated with the entry, separated by commas." .PD .PP .Vb 2 \& 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 \& 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. .Ve .SH "CONFIGURATION" .IX Header "CONFIGURATION" .Vb 4 \& 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: .Ve .PP .Vb 1 \& input = /home/me/blog \& \& output = /var/www/blog \& \& format = markdown .Ve .PP .Vb 1 \& Keys which are unknown are ignored. .Ve .SH "OPTIONAL CACHING" .IX Header "OPTIONAL CACHING" .Vb 2 \& 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: .Ve .PP .Vb 2 \& apt\-get update \& apt\-get install memcached libcache\-memcached\-perl .Ve .PP .Vb 2 \& You may disable this caching behaviour with \-\-no\-cache, and see the \& effect with \-\-verbose. .Ve .SH "OPTIONAL CALENDAR" .IX Header "OPTIONAL CALENDAR" .Vb 2 \& If the \*(AqHTML::CalendarMonthSimple\*(Aq 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 \*(Aq\-\-no\-calendar\*(Aq. .Ve .SH "OPTIONAL COMMENTING" .IX Header "OPTIONAL COMMENTING" .Vb 2 \& 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: .Ve .IP "Install the \s-1CGI\s0 script and edit the path at the start." 8 .IX Item "Install the CGI script and edit the path at the start." .PD 0 .IP "Copy the output comments to your local blog source." 8 .IX Item "Copy the output comments to your local blog source." .IP "Run this script again with \-\-comments=./path/to/comments" 8 .IX Item "Run this script again with --comments=./path/to/comments" .PD .PP .Vb 3 \& This should include the comments in the static output. More \& explicit instructions are provided within the file \*(AqCOMMENTS\*(Aq \& included within the distribution. .Ve .SH "AUTHOR" .IX Header "AUTHOR" .Vb 3 \& Steve \& \-\- \& http://www.steve.org.uk/ .Ve .SH "LICENSE" .IX Header "LICENSE" Copyright (c) 2007\-2010 by Steve Kemp. All rights reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The \s-1LICENSE\s0 file contains the full text of the license.