=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