Almost-minimal filesystem based blog.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
Brennen Bearnes 17beaef40c Tagged a version in expectation of some drastic changes. 16 years ago
lib Restructuring... 17 years ago
Display.pm A little, largely unneeded, tuning. 16 years ago
README Numerous small changes to line_parse, etc. Some formatting tweaks. 16 years ago
conf.pl Restructuring... 17 years ago
display.fcgi Minor changes to wrapper scripts, Display::handle now returns text instead 16 years ago
display.pl Minor changes to wrapper scripts, Display::handle now returns text instead 16 years ago
footer Restructuring... 17 years ago
footer_basic Restructuring... 17 years ago
header Numerous small changes to line_parse, etc. Some formatting tweaks. 16 years ago
header_basic Restructuring... 17 years ago
htaccess Restructuring... 17 years ago
p1k3.css Restructuring... 17 years ago
test.pl A little, largely unneeded, tuning. 16 years ago

README

NAME
Display - module to display fragments of text on the web and elsewhere

DESCRIPTION
Display started life as a simple script to concatenate fragments of
handwritten HTML by date. While it's since haphazardly accumulated
several of the usual weblog features (comments, lightweight markup, feed
generation, embedded Perl, poetry tools, stupid dependencies), the
present module hasn't changed much in six years.

This version should work with FastCGI, via CGI::Fast, if called from the
appropriate wrapper script.

Entries are stored in a simple directory tree under
$DISPLAY_CONF{ROOT_DIR}.

Like:

archives/2001/1/1
archives/2001/1/1/sub_entry

An entry may be either a plain text file, or a directory containing
several such files + whatever else you'd like to store. If it's a
directory, the file called "index" will be treated as the text of the
entry, and all other lower case filenames without extensions will be
treated as sub-entries or documents within that entry, and displayed
accordingly.

Directories may be nested to an arbitrary depth, though I don't promise
that this won't break on you.

A PNG or JPEG file with a name like

2001/1/1.icon.png
2001/1/1/index.icon.png
2001/1/1/whatever.icon.png

will be treated as an icon for the appropriate entry file.

MARKUP
Entries may consist of hand-written HTML (to be passed along without
further interpretation), a supported form of lightweight markup, or some
combination thereof. Actually, an entry may consist of any darn thing
you please, as long as Perl will agree that it is text, but presumably
you're going to be feeding this to a browser.

Special markup is indicated by a variety of XML-style container tags.

Embedded Perl - evaluated and replaced by whatever value you return
(evaluated in a scalar context):

<perl>my $dog = "Ralph."; return $dog;</perl>

This code is evaluated before any other processing is done, so you can
return any other markup understood by the script and have it handled
appropriately.

Interpolated variables - actually keys to %TEMPLATE, for the moment:

<perl>$TEMPLATE{dog} = "Ralph"; return '';</perl>
<p>My dog is named ${dog}.</p>

Embedded code and variables are mostly intended for use in header and
footer files, where it's handy to drop in titles or conditionalize
aspects of a layout. You want to be careful with this sort of thing -
it's useful in small doses, but it's also a maintainability nightmare
waiting to happen. (WordPress, I am looking at you.)

Several forms of lightweight markup:

<wala>Wala::Markup, via Wala.pm - very basic wiki syntax</wala>

<textile>Dean Allen's Textile, via Brad Choate's
Text::Textile.</textile>

<freeverse>An easy way to
get properly broken lines
-- en and em dashes ---
for poetry and such.</freeverse>

And a couple of shortcuts:

<image>filename.ext
alt text, if any</image>

<list>
one list item

another list item
</list>

As it stands, freeverse, image, and list are not particularly robust.

SUBROUTINES
For no bigger than this thing is, it gets a little convoluted.

handle
Handle a given request, either in the form of a CGI query object or
a date/entry string.

output
Returns appropriate output for a given option.

expand_query
Returns parameters if it's given a CGI object.

expand_option
Expands/converts 'all' and 'new' to appropriate values.

recent_month
Tries to find the most recent month in the archive.

Could cause problems if a year is a text file rather than a
directory.

dir_list
Return a $sort_order sorted list of files matching $pattern in a
directory.

calls $sort_order, which can be one of

alpha - alphabetical
reverse_alpha - alphabetical, reversed (might not work yet)
high_to_low - numeric, high to low
low_to_high - numeric, low to high

year_print
List out the updates for a year.

month_print
Prints the entries in a given month (nnnn/nn).

entry_print
Prints the contents of a given entry. Calls datestamp,
fragment_print, dir_list, and icon_markup. Recursively calls itself.

icon_markup
Check if an icon exists for a given entry if so, return markup to
include it. Icons are PNG or JPEG image files following a specific
naming convention:

index.icon.[png|jp(e)g] for directories
[filename].icon.[png|jp(e)g] for flat text files

Calls image_size, uses filename to determine type.

datestamp
Returns a nice html datestamp for a given entry, including a
wikilink for discussion and suchlike.

fragment_print
Print a text fragment - a header, footer, update, etc. Called by
main routines, used to print headers and footers. Calls
fragment_slurp to get the fragment it's supposed to print. Returns 1
on successful completion, 0 otherwise.

fragment_slurp
Read a text fragment, call line_parse to take care of funky markup
and interpreting embedded code, and then return it as a string.
Takes one parameter, the name of the file, and returns '' if it's
not an extant text file.

This might be the place to implement an in-memory cache for FastCGI
or mod_perl environments. The trick is that the line_parse() results
for certain files shouldn't be cached because they contain embedded
code.

line_parse
Performs substitutions on lines called by fragment_slurp, at least.
Calls image_markup, Text::Textile, Wala::wiki_page_to_html,
eval_perl. Returns string.

Parses some special markup, specifically:

<perl>embedded perl</perl>
${variable} interpolation from %DISPLAY_CONF
<textile></textile> - Text::Textile to HTML
<wala></wala> - Wala::wikify();
<freeverse></freeverse>
<retcon></retcon>
<list></list>

<image>filename.ext
optional alt tag</image>

textile_process
Inline replace <textile> markup in a string.

Trying to implement some caching here, though it's questionable
whether this makes any sense.

eval_perl
Evaluate embedded Perl in a string, replacing blocks enclosed with
<perl> tags with whatever they return (well, evaluated in a scalar
context). Modifies a string in-place, so be careful.

Also handles simple ${variables}, replacing them (for now) from
%DISPLAY_CONF.

image markup
Parse out an image tag and return the appropriate html.

month_name
Turn numeric dates into English.

feed_print
Dump out an Atom feed of entries for a month.

Called from handle(), requires XML::Atom::SimpleFeed.

entry_markup
Return text wrapped in the appropriate markup for an entry. Just a
wrapper around div() at the moment.

div Return text wrapped in a div of the specified class.

a Returns an HTML link.

ornament
Returns a type ornament.

image_size
Returns (width, height) of a variety of image files. Called by
icon_markup and line_parse. Uses Image::Size if available, otherwise
uses a couple of built-in routines munged together from pngsize and
jpegsize in wwwis, by Alex Knowles and Andrew Tong.

SEE ALSO
walawiki.org, Blosxom, rassmalog, Text::Textile, XML::Atom::SimpleFeed,
Image::Size, CGI::Fast.

AUTHOR
Copyright 2001-2007 Brennen Bearnes

Image sizing code (in image_size) derived from wwwis, by Alex Knowles
and Andrew Tong.

display.pl is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.