Almost-minimal filesystem based blog.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

398 lines
13 KiB

17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
17 years ago
  1. NAME
  2. Display - module to display fragments of text on the web and elsewhere
  3. SYNOPSIS
  4. #!/usr/bin/perl
  5. use Display;
  6. my $d = Display->new(
  7. root_dir => 'archives',
  8. url_root => '/display.pl?',
  9. # etc.
  10. );
  11. print $d->handle(@ARGV);
  12. DESCRIPTION
  13. Display started life as a simple script to concatenate fragments of
  14. handwritten HTML by date. It has since haphazardly accumulated several
  15. of the usual weblog features (comments, lightweight markup, feed
  16. generation, embedded Perl, poetry tools, image galleries, and
  17. ill-advised dependencies), but the basic idea hasn't changed much.
  18. The module will work with FastCGI, if called from the appropriate
  19. wrapper script. If you use CGI::Fast, you can pass query objects
  20. directly to "handle()".
  21. By default, entries are stored in a simple directory tree under
  22. "root_dir".
  23. Like:
  24. archives/2001/1/1
  25. archives/2001/1/1/sub_entry
  26. It is possible (although not yet as flexible as it ought to be) to
  27. redefine the directory layout. More about this after a bit.
  28. An entry may be either a plain text file, or a directory containing
  29. several files. If it's a directory, a file named "index" will be treated
  30. as the text of the entry, and all other lower-case filenames without
  31. extensions will be treated as sub-entries or documents within that
  32. entry, and displayed accordingly. Links to certain other filetypes will
  33. be displayed as well.
  34. Directories may be nested to an arbitrary depth, although it's probably
  35. not a good idea to go very deep with the current display logic.
  36. A PNG or JPEG file with a name like
  37. 2001/1/1.icon.png
  38. 2001/1/1/index.icon.png
  39. 2001/1/1/whatever.icon.png
  40. 2001/1/1/whatever/index.icon.png
  41. will be treated as an icon for the appropriate entry file.
  42. MARKUP
  43. Entries may consist of hand-written HTML (to be passed along without
  44. further interpretation), a supported form of lightweight markup, or some
  45. combination thereof. Actually, an entry may consist of any darn thing
  46. you please, as long as Perl will agree that it is text, but presumably
  47. you're going to be feeding this to a browser.
  48. Special markup is indicated by a variety of HTML-like container tags.
  49. Embedded Perl - evaluated and replaced by whatever value you return
  50. (evaluated in a scalar context):
  51. <perl>my $dog = "Ralph."; return $dog;</perl>
  52. This code is evaluated before any other processing is done, so you can
  53. return any other markup understood by the script and have it handled
  54. appropriately.
  55. Interpolated variables - actually keys to the hash underlying the
  56. Display object, for the moment:
  57. <perl>$self->title("About Ralph, My Dog"); return '';</perl>
  58. <p>The title is <em>${title}</em>.</p>
  59. This will change.
  60. Embedded code and variables are intended for use in header and footer
  61. files, where it's handy to drop in titles or conditionalize aspects of a
  62. layout. You want to be careful with this sort of thing - it's useful in
  63. small doses, but it's also a maintainability nightmare waiting to
  64. happen. (WordPress, I am looking at you.)
  65. Several forms of lightweight markup:
  66. <wala>Wala::Markup, via Wala.pm - very basic wiki syntax</wala>
  67. <textile>Dean Allen's Textile, via Brad Choate's
  68. Text::Textile.</textile>
  69. <freeverse>An easy way to
  70. get properly broken lines
  71. plus -- en and em dashes ---
  72. for poetry and such.</freeverse>
  73. And a couple of shortcuts:
  74. <image>filename.ext
  75. alt text, if any</image>
  76. <list>
  77. one list item
  78. another list item
  79. </list>
  80. As it stands, freeverse, image, and list are not particularly robust.
  81. NAME
  82. Display - module to display fragments of text on the web and elsewhere
  83. SYNOPSIS
  84. #!/usr/bin/perl
  85. use Display;
  86. my $d = Display->new(
  87. root_dir => 'archives',
  88. url_root => '/display.pl?',
  89. # etc.
  90. );
  91. print $d->handle(@ARGV);
  92. DESCRIPTION
  93. Display started life as a simple script to concatenate fragments of
  94. handwritten HTML by date. It has since haphazardly accumulated several
  95. of the usual weblog features (comments, lightweight markup, feed
  96. generation, embedded Perl, poetry tools, image galleries, and
  97. ill-advised dependencies), but the basic idea hasn't changed much.
  98. The module will work with FastCGI, if called from the appropriate
  99. wrapper script. If you use CGI::Fast, you can pass query objects
  100. directly to "handle()".
  101. By default, entries are stored in a simple directory tree under
  102. "root_dir".
  103. Like:
  104. archives/2001/1/1
  105. archives/2001/1/1/sub_entry
  106. It is possible (although not yet as flexible as it ought to be) to
  107. redefine the directory layout. More about this after a bit.
  108. An entry may be either a plain text file, or a directory containing
  109. several files. If it's a directory, a file named "index" will be treated
  110. as the text of the entry, and all other lower-case filenames without
  111. extensions will be treated as sub-entries or documents within that
  112. entry, and displayed accordingly. Links to certain other filetypes will
  113. be displayed as well.
  114. Directories may be nested to an arbitrary depth, although it's probably
  115. not a good idea to go very deep with the current display logic.
  116. A PNG or JPEG file with a name like
  117. 2001/1/1.icon.png
  118. 2001/1/1/index.icon.png
  119. 2001/1/1/whatever.icon.png
  120. 2001/1/1/whatever/index.icon.png
  121. will be treated as an icon for the appropriate entry file.
  122. MARKUP
  123. Entries may consist of hand-written HTML (to be passed along without
  124. further interpretation), a supported form of lightweight markup, or some
  125. combination thereof. Actually, an entry may consist of any darn thing
  126. you please, as long as Perl will agree that it is text, but presumably
  127. you're going to be feeding this to a browser.
  128. Special markup is indicated by a variety of HTML-like container tags.
  129. Embedded Perl - evaluated and replaced by whatever value you return
  130. (evaluated in a scalar context):
  131. <perl>my $dog = "Ralph."; return $dog;</perl>
  132. This code is evaluated before any other processing is done, so you can
  133. return any other markup understood by the script and have it handled
  134. appropriately.
  135. Interpolated variables - actually keys to the hash underlying the
  136. Display object, for the moment:
  137. <perl>$self->title("About Ralph, My Dog"); return '';</perl>
  138. <p>The title is <em>${title}</em>.</p>
  139. This will change.
  140. Embedded code and variables are intended for use in header and footer
  141. files, where it's handy to drop in titles or conditionalize aspects of a
  142. layout. You want to be careful with this sort of thing - it's useful in
  143. small doses, but it's also a maintainability nightmare waiting to
  144. happen. (WordPress, I am looking at you.)
  145. Several forms of lightweight markup:
  146. <wala>Wala::Markup, via Wala.pm - very basic wiki syntax</wala>
  147. <textile>Dean Allen's Textile, via Brad Choate's
  148. Text::Textile.</textile>
  149. <freeverse>An easy way to
  150. get properly broken lines
  151. plus -- en and em dashes ---
  152. for poetry and such.</freeverse>
  153. And a couple of shortcuts:
  154. <image>filename.ext
  155. alt text, if any</image>
  156. <list>
  157. one list item
  158. another list item
  159. </list>
  160. As it stands, freeverse, image, and list are not particularly robust.
  161. CONFIGURATION
  162. options
  163. See conf.pl for a sample configuration.
  164. entry_map(\%map)
  165. Takes a hashref which will dispatch entries matching various regexen
  166. to the appropriate output methods. The default looks something like
  167. this:
  168. nnnn/[nn/nn/]doc_name - a document within a day.
  169. nnnn/nn/nn - a specific day.
  170. nnnn/nn - a month.
  171. nnnn - a year.
  172. doc_name - a document in the root directory.
  173. You can re-map things to an arbitrary archive layout.
  174. Since the entry map is a hash, and handle() simply loops over its
  175. keys, there is no guaranteed precedence of patterns. Be extremely
  176. careful that no entry will match more than one pattern, or you will
  177. wind up with unexpected behavior. A good way to ensure that this
  178. does not happen is to use patterns like:
  179. qr(
  180. ^ # start of string
  181. [0-9/]{4}/ # year
  182. [0-9]{1,2}/ # month
  183. [0-9]{1,2] # day
  184. $ # end of string
  185. )x
  186. ...always marking the start and end of the string explicitly.
  187. METHODS
  188. For no bigger than this thing is, it gets a little convoluted.
  189. new(%params)
  190. Get a new Display object with the specified parameters set.
  191. configure(param => 'value')
  192. Set specified parameters.
  193. walaconf(%options)
  194. Set parameters for Wala.pm.
  195. display($entry1, $entry2, ...)
  196. Return a string containing the given entries, which can be in the
  197. form of CGI query objects or date/entry strings. If no parameters
  198. are given, default to default_entry().
  199. display() expands aliases ("new" and "all") and CGI query objects as
  200. necessary, collects input from handle($entry), and wraps the whole
  201. thing in header and footer files.
  202. handle($entry)
  203. Return the text of an individual entry.
  204. expand_query
  205. Expands a CGI query object (for example, one passed in from
  206. CGI::Fast) to an appropriate list of parameters.
  207. expand_option
  208. Expands/converts 'all' and 'new' to appropriate values.
  209. recent_month
  210. Tries to find the most recent month in the archive.
  211. If a year file is text, returns that instead.
  212. month_before
  213. Return the month before the given month in the archive.
  214. Very naive; there has got to be a smarter way.
  215. dir_list($dir, $sort_order, $pattern)
  216. Return a $sort_order sorted list of files matching regex $pattern in
  217. a directory.
  218. Calls $sort_order, which can be one of:
  219. alpha - alphabetical
  220. reverse_alpha - alphabetical, reversed
  221. high_to_low - numeric, high to low
  222. low_to_high - numeric, low to high
  223. year($year)
  224. List out the updates for a year.
  225. month($month)
  226. Prints the entries in a given month (nnnn/nn).
  227. entry($entry)
  228. Returns the contents of a given entry. Calls dir_list and
  229. icon_markup. Recursively calls itself.
  230. entry_wrapped
  231. Wraps entry() in entry_markup.
  232. entry_stamped
  233. Wraps entry() + a datestamp in entry_markup()
  234. icon_markup
  235. Check if an icon exists for a given entry if so, return markup to
  236. include it. Icons are PNG or JPEG image files following a specific
  237. naming convention:
  238. index.icon.[png|jp(e)g] for directories
  239. [filename].icon.[png|jp(e)g] for flat text files
  240. Calls image_size, uses filename to determine type.
  241. datestamp
  242. Returns a nice html datestamp for a given entry, including a
  243. wikilink for discussion and suchlike.
  244. fragment_slurp
  245. Read a text fragment, call line_parse to take care of funky markup
  246. and interpreting embedded code, and then return it as a string.
  247. Takes one parameter, the name of the file, and returns '' if it's
  248. not an extant text file.
  249. This might be the place to implement an in-memory cache for FastCGI
  250. or mod_perl environments. The trick is that the line_parse() results
  251. for certain files shouldn't be cached because they contain embedded
  252. code.
  253. eval_perl
  254. Evaluate embedded Perl in a string, replacing blocks enclosed with
  255. <perl> tags with whatever they return (well, evaluated in a scalar
  256. context). Modifies a string in-place, so be careful.
  257. Also handles simple ${variables}, replacing them from the keys to
  258. $self.
  259. month_name
  260. Turn numeric dates into English.
  261. root_locations($file)
  262. Given a file/entry, return the appropriate concatenations with
  263. root_dir and url_root.
  264. local_path
  265. Return an absolute path for a given file. Called by root_locations.
  266. Arguably this is stupid and inefficient.
  267. feed_print
  268. Return an Atom feed of entries for a month. Defaults to the most
  269. recent month in the archive.
  270. Called from handle(), requires XML::Atom::SimpleFeed.
  271. SEE ALSO
  272. walawiki.org, Blosxom, rassmalog, Text::Textile, XML::Atom::SimpleFeed,
  273. Image::Size, CGI::Fast.
  274. AUTHOR
  275. Copyright 2001-2007 Brennen Bearnes
  276. Image sizing code (in image_size) derived from wwwis, by Alex Knowles
  277. and Andrew Tong.
  278. display.pl is free software; you can redistribute it and/or modify
  279. it under the terms of the GNU General Public License as published by
  280. the Free Software Foundation; either version 2 of the License, or
  281. (at your option) any later version.
  282. This program is distributed in the hope that it will be useful,
  283. but WITHOUT ANY WARRANTY; without even the implied warranty of
  284. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  285. GNU General Public License for more details.