|
|
- NAME
- Display - module to display fragments of text on the web and elsewhere
-
- DESCRIPTION
- Display started life as a simple script to concatenate fragments of
- handwritten HTML by date. While it's since haphazardly accumulated
- several of the usual weblog features (comments, lightweight markup, feed
- generation, embedded Perl, poetry tools, stupid dependencies), the
- present module hasn't changed much in six years.
-
- This version should 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
- Returns parameters if it's given a CGI object.
-
- expand_option
- Expands/converts 'all' and 'new' to appropriate values.
-
- recent_month
- Tries to find the most recent month in the archive.
-
- Could cause problems if a year is a text file rather than a
- directory.
-
- dir_list
- Return a $sort_order sorted list of files matching $pattern in a
- directory.
-
- 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.
-
- month_print
- Prints the entries in a given month (nnnn/nn).
-
- 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
-
- 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_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.
-
- 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.
-
- 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();
- <freeverse></freeverse>
- <retcon></retcon>
- <list></list>
-
- <image>filename.ext
- optional alt tag</image>
-
- textile_process
- Inline replace <textile> markup in a string.
-
- Trying to implement some caching here, though it's questionable
- whether this makes any sense.
-
- 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.
-
- image markup
- Parse out an image tag and return the appropriate html.
-
- month_name
- Turn numeric dates into English.
-
- feed_print
- Dump out an Atom feed of entries for a month.
-
- Called from handle(), 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.
-
- 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.
-
|