wrt/README

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

DESCRIPTION
    display started life as a way to concatenate fragments of handwritten
    HTML by date. While the script has since haphazardly accumulated several
    of the usual weblog features (comments, lightweight markup, feed
    generation, embedded Perl, poetry tools, stupid dependencies), it hasn't
    changed much in six years. The current version is intended to support
    FastCGI via CGI::Fast, if available, and otherwise operate as a
    traditional CGI or commandline utility. It may have some distance to go
    towards this goal.

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

    dir_list()
        Return a $sort_order sorted list of files matching $pattern in a
        directory. Called by year_print(), month_print(), and entry_print().

        calls $sort_order, which can be one of

         alpha - alphabetical 
         reverse_alpha - alphabetical, reversed (might not work yet)
         high_to_low - numeric, high to low
         low_to_high - numeric, low to high

    year_print()
        List out the updates for a year. Calls dir_list(), entry_print().

    month_print()
        Prints the entries in a given month (nnnn/nn). Calls dir_list(),
        datestamp().

    entry_print()
        Prints the contents of a given entry. Calls datestamp,
        fragment_print, 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

        Called by entry_print, 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. Called by entry_print.

    fragment_print()
        Print a text fragment - a header, footer, update, etc. Called by
        main routines, used to print headers and footers. Calls
        fragment_slurp to get the fragment it's supposed to print. Returns 1
        on successful completion, 0 otherwise.

    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. Called by entry_print, at least

    line_parse()
        Performs substitutions on lines called by fragment_slurp, at least.
        Calls image_markup, Text::Textile, Wala::wiki_page_to_html,
        eval_perl. Returns string.

        Parses some special markup, specifically:

            <perl>embedded perl</perl>
            ${variable} interpolation from %DISPLAY_CONF
            <textile></textile> - Text::Textile to HTML
            <wala></wala> - Wala::wikify();
            <image>filename.ext</image>
            <freeverse></freeverse>
            <retcon></retcon>
            <list></list>

    eval_perl()
        Evaluate embedded Perl, replacing blocks enclosed with <perl> tags
        with whatever they return (well, evaluated in a scalar context).

    image markup()
        Parse out an image tag and return the appropriate html. Calls
        image_size. Called by line_parse.

    month_name()
        Turn numeric dates into English.

    feed_print()
        Dump out an Atom feed of entries for a month.

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

    entry_markup()
        Return text wrapped in the appropriate markup for an entry. Just a
        wrapper around div() at the moment.

    div()
        Return text wrapped in a div of the specified class.

    a() Returns an HTML link. Called all over the place.

    ornament()
        Returns a type ornament.

    image_size()
        Returns (width, height) of a variety of image files. Called by
        icon_markup and line_parse. Uses Image::Size if available, otherwise
        uses a couple of built-in routines munged together from pngsize and
        jpegsize in wwwis, by Alex Knowles and Andrew Tong.

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.