|
|
- =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
-
|