|
|
- NAME
- Display - module to display fragments of text on the web and elsewhere
-
- SYNOPSIS
- #!/usr/bin/perl
-
- use Display;
- my $d = Display->new(
- root_dir => 'archives',
- url_root => '/display.pl?',
- # etc.
- );
- print $d->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, 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 "handle()".
-
- By default, entries are stored in a simple directory tree under
- "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.
-
- 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.
-
- 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 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 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
- plus -- 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.
-
- NAME
- Display - module to display fragments of text on the web and elsewhere
-
- SYNOPSIS
- #!/usr/bin/perl
-
- use Display;
- my $d = Display->new(
- root_dir => 'archives',
- url_root => '/display.pl?',
- # etc.
- );
- print $d->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, 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 "handle()".
-
- By default, entries are stored in a simple directory tree under
- "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.
-
- 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.
-
- 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 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 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
- plus -- 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.
-
- CONFIGURATION
- options
- See conf.pl for a sample configuration.
-
- entry_map(\%map)
- Takes a hashref which will dispatch entries matching various regexen
- to the appropriate output methods. The default looks something like
- this:
-
- nnnn/[nn/nn/]doc_name - a document within a day.
- nnnn/nn/nn - a specific day.
- nnnn/nn - a month.
- nnnn - a year.
- doc_name - a document in the root directory.
-
- You can re-map things to an arbitrary archive layout.
-
- Since the entry map is a hash, and handle() simply loops over its
- keys, there is no guaranteed precedence of patterns. Be extremely
- careful that no entry will match more than one pattern, or you will
- wind up with unexpected behavior. A good way to ensure that this
- does not happen is to use patterns like:
-
- qr(
- ^ # start of string
- [0-9/]{4}/ # year
- [0-9]{1,2}/ # month
- [0-9]{1,2] # day
- $ # end of string
- )x
-
- ...always marking the start and end of the string explicitly.
-
- METHODS
- For no bigger than this thing is, it gets a little convoluted.
-
- new(%params)
- Get a new Display object with the specified parameters set.
-
- configure(param => 'value')
- Set specified parameters.
-
- walaconf(%options)
- Set parameters for Wala.pm.
-
- display($entry1, $entry2, ...)
- Return a string containing the given entries, which can be in the
- form of CGI query objects or date/entry strings. If no parameters
- are given, default to default_entry().
-
- display() expands aliases ("new" and "all") and CGI query objects as
- necessary, collects input from handle($entry), and wraps the whole
- thing in header and footer files.
-
- handle($entry)
- Return the text of an individual entry.
-
- expand_query
- Expands a CGI query object (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($dir, $sort_order, $pattern)
- 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($year)
- List out the updates for a year.
-
- month($month)
- Prints the entries in a given month (nnnn/nn).
-
- entry($entry)
- Returns the contents of a given entry. Calls dir_list and
- icon_markup. Recursively calls itself.
-
- entry_wrapped
- Wraps entry() in entry_markup.
-
- entry_stamped
- Wraps entry() + a datestamp in entry_markup()
-
- 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 from the keys to
- $self.
-
- month_name
- Turn numeric dates into English.
-
- root_locations($file)
- Given a file/entry, return the appropriate concatenations with
- root_dir and url_root.
-
- local_path
- Return an absolute path for a given file. Called by root_locations.
-
- Arguably this is stupid and inefficient.
-
- 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.
-
|