The dynamically-generated homepage and commenting system uses four files of perl and three directories in which assorted text files are kept. There is one ancillary script which just fires up $VISUAL on the entry for today, for a specified date, or for a specified number of days in the past.
All dates used by the system are in the form YYYY-MM-DD. There are occasional attempts to fix up dates that are received in the form YY-MM-DD or YY-DD-MM, but in general, if you manually feed the system a date in the wrong format, it will mock you either behind your back or to your face.
By default, the text files are in the directories "journal/entries", "journal/comments", and "journal/templates" under the main directory.
Entries are named by their corresponding date, and have no particular internal structure. They are interpolated as-is into HTML output, so can (and probably should) contain HTML formatting, hyperlinks, etc.
Comments are named by the date of the entry they go with, plus a number which is taken to indicate sequence: higher-numbered comments show later on the page than lower-numbered ones. Comments created by the system are numbered by their time() value and the processID of the script run that created them, but any number works, if you want to create a comment by hand for some reason.
The first three lines of a comment should be, in no particular order:
Anything after these lines is interpolated into HTML output just like the contents of an entry file.
Template files are HTML files (and need to follow all the rules for such, like having <head></head> and <body></body> sections. They may also have pseudotags of the form <%variable_name%>, which will be replaced by the variable of that name in the script that reads and writes the template. Template files can have any name, but always have the extension ".tmplt" (8.3 weenies can bite me).
The variables produced by index.cgi are JOURNAL (the entire text of journal entries and comment headers requested for display) and NAV (a nav bar with links back to the script for each month that contains entries.
The more verbose comment.cgi produces HIDDEN (hidden data that needs to be passed from one invocation of the script to another), DATE (the date/name of the entry under consideration), TEXT (the text of the entry and all existing comments on it), MESSAGE (stuff the user needs to be notified of, like error conditions), FROM_BOX (a text input field to get the commentor's name), SUBJECT_BOX (a text input field to get the subject line), BODY_BOX (a textarea to get the body of the comment), and SUBMIT_BUTTON (the submit button for the form).
There are currently three templates: current.tmplt, which has my main site title and nav bar and whatnot; archive.tmplt, which just has a bit of framing HTML and uses <%NAV%> for its navbar; and comment_form.tmplt, which is just what it says.
Onward, to the actual scripts! By default, the two .cgi scripts should be in the main directory, and the two fun.pl files should be in the directory "lib" under that.
This is the script that shows entries. Normally called via GET, it accepts the parameters:
When called, index.cgi sucks in the specified template and sploots it out, interpolating <%variable_name%> tags as described above. In particular, <%JOURNAL%> is replaced by all the journal entries from bdate to edate with their comment headers (or full comments, if you didn't believe me). The comment headers will be links to comment.cgi with appropriate parameters. (Each link is given a bogus parameter which is just a really cheesy checksum of the info in the header of the comment, so that browsers can tell which ones you've visited; if there are unvisited links after the last visited one, they're probably new comments.)
The only parameter you should be passing manually to comment.cgi is "entry", the date of the entry you want to comment on. The script also uses "last_page", "from", "subject", "body", "from_err", "subject_err", "body_err", "message", and "page" but should generate those automatically as needed.
When first invoked (usually by a link in index.cgi output), comment.cgi sploots out comment_form.tmplt, showing the specified entry, all existing comments on that entry, and a form where you can input a new comment. No attempt at strong authentication, or even weak authentication, is made: the From field is just a text entry box.
When you fill out the form and bang on the SUBMIT button, the values you entered are passed to a new invocation of the script, which checks them for okayness ("from" and "subject" must not be blank, "body" must be either blank or more than five characters) and then either pops up the form with messages describing your inadequacy in detail, or writes a comment file (with a name based on the current time() and process ID) into the comments directory and pops back to the page you were on before you came to the first invocation of comment.cgi (technically, the HTTP_REFERER that comment.cgi got then).
This just contains some functions used by both CGIs, like finding all entries between two dates, finding all comments for an entry, converting raw entry or comment files to nice HTML, etc.
Contains generically useful CGI functions, like reading in form data and removing the %-escaping, creating various types of form input fields based on perl lists, etc.
The journal script takes some number of arguments, tries to interpret each one as a date, and fires up your $VISUAL on each journal entry in turn.
Valid arguments are:
If you give journal no arguments at all, it takes that to mean the current day.
No web-based or other remote administration tools are provided; filesystem access with useful permissions is assumed.
Since entries and comments are plain text files, you can (in fact, must) edit them with vi or your favorite editor if you want to change them, and delete them with rm if your want to get rid of them. Editing comments without permission of the commentor is considered poor form; deleting comments may or may not be ethically defensible depending on the details of the situation.
Comments have unhelpful filenames, but you can always use grep.
The scripts should be fairly portable. You'll need to edit the entry, comment, and template directory settings at the top of journalfun.pl, and the entry_dir setting at the top of journal to be valid directories to which you have write access and all. You may also need to modify the require("") calls at the tops of the CGI scripts.
You'll definitely want to edit the .tmplt files; you can do anything you want with the HTML, but don't take out or modify the <%variable_name%> pseudotags unless you're sure you know what you're doing.
The complete list of files you need to start with is:
Entry and comment files will be produced as needed; you just need someplace to put them.
This file was last modified at 1529 on 11Oct01 by trip@idiom.com.