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 54016b2a2d Got name wrong. 16 years ago
Display Fixed a minor bug with Markup spitting error messages for undefined image alt text. 16 years ago
lib Cleaning up lib/ 16 years ago
wala Tagging a version at October 4, 2007. 16 years ago
Display.pm Tagging a version at October 4, 2007. 16 years ago
Display.pod Updated documentation slightly. 16 years ago
MethodSpit.pm Tagging a version at October 4, 2007. 16 years ago
README Updated README. 16 years ago
conf.pl Tagging a version at October 4, 2007. 16 years ago
display.fcgi Tagging a version at October 4, 2007. 16 years ago
display.pl Tagging a version at October 4, 2007. 16 years ago
footer Tagging a version at October 4, 2007. 16 years ago
footer_basic Restructuring... 17 years ago
header Tagging a version at October 4, 2007. 16 years ago
header_basic Restructuring... 17 years ago
htaccess Display::Image::gallery is functional, just. 16 years ago
p1k3.css Tagged prior to building an OO interface. 16 years ago
test.pl Some tests. 16 years ago
testgal.pl Some tests. 16 years ago
validate.pl Tagging a version at October 4, 2007. 16 years ago

README

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

SYNOPSIS
#!/usr/bin/perl

use Display;
my $d = Display->new(
root_dir => 'archives',
url_root => '/display.pl?',
# etc.
);
print $d->handle(@ARGV);

DESCRIPTION
Display started life as a simple script to concatenate fragments of
handwritten HTML by date. It has since haphazardly accumulated several
of the usual weblog features (comments, lightweight markup, feed
generation, embedded Perl, poetry tools, image galleries, and
ill-advised dependencies), but the basic idea hasn't changed much.

The module will work with FastCGI, if called from the appropriate
wrapper script. If you use CGI::Fast, you can pass query objects
directly to "handle()".

By default, entries are stored in a simple directory tree under
"root_dir".

Like:

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

It is possible (although not yet as flexible as it ought to be) to
redefine the directory layout. More about this after a bit.

An entry may be either a plain text file, or a directory containing
several files. If it's a directory, a file named "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. Links to certain other filetypes will
be displayed as well.

Directories may be nested to an arbitrary depth, although it's probably
not a good idea to go very deep with the current display logic.

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
2001/1/1/whatever/index.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 HTML-like 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 the hash underlying the
Display object, for the moment:

<perl>$self->title("About Ralph, My Dog"); return '';</perl>

<p>The title is <em>${title}</em>.</p>

This will change.

Embedded code and variables are 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
plus -- 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.

ARCHIVE LAYOUT
default values
entry_map(\%map)
Takes a hashref which will dispatch entries matching various regexen
to the appropriate output methods. The default looks something like
this:

nnnn/[nn/nn/]doc_name - a document within a day.
nnnn/nn/nn - a specific day.
nnnn/nn - a month.
nnnn - a year.
doc_name - a document in the root directory.

You can re-map things to an arbitrary archive layout.

Since the entry map is a hash, and handle() simply loops over its
keys, there is no guaranteed precedence of patterns. Be extremely
careful that no entry will match more than one pattern, or you will
wind up with unexpected behavior. A good way to ensure that this
does not happen is to use patterns like:

qr(
^ # start of string
[0-9/]{4}/ # year
[0-9]{1,2}/ # month
[0-9]{1,2] # day
$ # end of string
)x

...always marking the start and end of the string explicitly.

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

new()
configure(param => 'value')
Set specified parameters.

walaconf(%options)
Set parameters for Wala.pm.

display($entry1, $entry2, ...)
Return a string containing the given entries, which can be in the
form of CGI query objects or date/entry strings. If no parameters
are given, default to default_entry().

display() expands aliases ("new" and "all") and CGI query objects as
necessary, collects input from handle($entry), and wraps the whole
thing in header and footer files.

handle($entry)
Return the text of an individual entry.

expand_query
Expands a CGI query object (for example, one passed in from
CGI::Fast) to an appropriate list of parameters.

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

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

If a year file is text, returns that instead.

month_before
Return the month before the given month in the archive.

Very naive; there has got to be a smarter way.

dir_list($dir, $sort_order, $pattern)
Return a $sort_order sorted list of files matching regex $pattern in
a directory.

Calls $sort_order, which can be one of:

alpha - alphabetical
reverse_alpha - alphabetical, reversed
high_to_low - numeric, high to low
low_to_high - numeric, low to high

year($year)
List out the updates for a year.

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

entry($entry)
Returns the contents of a given entry. Calls dir_list and
icon_markup. Recursively calls itself.

entry_wrapped
Wraps entry() in entry_markup.

entry_stamped
Wraps entry() + a datestamp in entry_markup()

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

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 from the keys to
$self.

month_name
Turn numeric dates into English.

root_locations($file)
* Given a file/entry, return the appropriate concatenations with
root_dir and url_root.

local_path
Return an absolute path for a given file. Called by root_locations.

Arguably this is stupid and inefficient.

feed_print
Return an Atom feed of entries for a month. Defaults to the most
recent month in the archive.

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

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.