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.
118 lines
3.6 KiB
118 lines
3.6 KiB
=pod
|
|
|
|
=head1 NAME
|
|
|
|
Display - module to display fragments of text on the web and elsewhere
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
#!/usr/bin/perl
|
|
|
|
use Display;
|
|
my $d = Display->new(
|
|
root_dir => 'archives',
|
|
url_root => '/display.pl?',
|
|
# etc.
|
|
);
|
|
print $d->handle(@ARGV);
|
|
|
|
=head1 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
|
|
C<handle()>.
|
|
|
|
By default, entries are stored in a simple directory tree under C<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.
|
|
|
|
=head2 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.
|
|
|
|
B<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.
|
|
|
|
B<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 F<header> and F<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.)
|
|
|
|
B<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>
|
|
|
|
B<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.
|
|
|
|
=cut
|
|
|