brennen
/
wrt

NAME    Display - module to display fragments of text on the web and elsewhere
SYNOPSIS        #!/usr/bin/perl
        use Display qw(%WalaConf %DISPLAY_CONF &handle);
        do 'conf.pl' if -e 'conf.pl'; # grab config
        $WalaConf{'ShowSearchlinks'} = 0;
        print 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, ill-advised dependencies), but    the basic idea hasn't changed much.
    The module will 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        Expands a CGI query (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        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_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, 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_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 (for now) from        %DISPLAY_CONF values.
    month_name        Turn numeric dates into English.
    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.