From 50e96cad8ffcfc0b4e91f589affdbdcd68fc91c8 Mon Sep 17 00:00:00 2001 From: Alex Schroeder Date: Tue, 11 Nov 2008 04:50:46 +0000 Subject: [PATCH] * modules/poetry.pl ($PoetryIsHandlingXMLStyleMarkup): New option. ($PoetryIsHandlingCreoleStyleMarkup): New option. (PoetryRule): Utilized new options, so as to permit several markup styles, and simplified implementation, according to recent refactoring in "wiki.pl". (CloseHtmlEnvironmentsPoetry): New function, permitting block-level elements (e.g., lists, tables) within poems. --- ChangeLog | 10 +++ modules/poetry.pl | 161 ++++++++++++++++++++++++++++++++++------------ 2 files changed, 129 insertions(+), 42 deletions(-) diff --git a/ChangeLog b/ChangeLog index 2f90fc0e..ec5e2bc1 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,13 @@ +2008-11-12 Brian Curry + + * modules/poetry.pl ($PoetryIsHandlingXMLStyleMarkup): New option. + ($PoetryIsHandlingCreoleStyleMarkup): New option. + (PoetryRule): Utilized new options, so as to permit several markup + styles, and simplified implementation, according to recent + refactoring in "wiki.pl". + (CloseHtmlEnvironmentsPoetry): New function, permitting block-level + elements (e.g., lists, tables) within poems. + 2008-11-11 Brian Curry * modules/creole.pl (CreoleRule): Corrected a horrific link-caching diff --git a/modules/poetry.pl b/modules/poetry.pl index 118585f0..1b6e5cdd 100755 --- a/modules/poetry.pl +++ b/modules/poetry.pl @@ -7,9 +7,9 @@ poetry - An Oddmuse module for adding poetry to Oddmuse pages. =head1 SYNOPSIS -Poetry - particularly, rhymically loose "free verse" poetry - tends to depend on -fanciful (but meaningful) line-breaks, indentation, and whitespace, which -publications of that poetry must preserve. This extension preserves that. +Poetry - particularly rhymically free, "free verse" poetry - tends to depend on +fanciful, often meaningful line-breaks, indentation, and whitespace, which +publication of that poetry must preserve. This extension preserves that. =head1 INSTALLATION @@ -19,75 +19,152 @@ directory for your Oddmuse Wiki. =cut package OddMuse; -$ModulesDescription .= '

$Id: poetry.pl,v 1.2 2008/10/19 01:51:43 leycec Exp $

'; +$ModulesDescription .= '

$Id: poetry.pl,v 1.3 2008/11/11 04:50:46 leycec Exp $

'; -# ....................{ INITIALIZATION }.................... -push(@MyInitVariables, \&PoetryInit); +# ....................{ CONFIGURATION }.................... -# A boolean that, if true, signifies that we are currently in a "verse" div. -# Testing InElement('div') is insufficient, since we might as well be in some -# other div element. -my $PoetryRuleInDiv; -sub PoetryInit { - $PoetryRuleInDiv = ''; -} +=head1 CONFIGURATION + +poetry is easily configurable; set these variables in the B +file for your Oddmuse Wiki. + +=cut +use vars qw($PoetryIsHandlingCreoleStyleMarkup + $PoetryIsHandlingXMLStyleMarkup); + +=head2 $PoetryIsHandlingCreoleStyleMarkup + +A boolean that, if true, enables handling of Creole-style markup. See +L below. By default, this boolean is true. + +=cut +$PoetryIsHandlingCreoleStyleMarkup = 1; + +=head2 $PoetryIsHandlingXMLStyleMarkup + +A boolean that, if true, enables handling of XML-style markup. See +L below. By default, this boolean is true. + +=cut +$PoetryIsHandlingXMLStyleMarkup = 1; # ....................{ MARKUP }.................... push(@MyRules, \&PoetryRule); =head2 MARKUP -poetry handles markup markup surrounded by three colons: +poetry handles two markup styles: Creole and XML. The Creole style is more +concise, but a bit less adjustable, than the XML style. + +The Creole style is three colons: ::: Like this, a - //poem// with its last + //poem// with default + class, ##poem##, and its last stanza indented, and linking to [[Another_Poem|another poem]]. ::: -This demonstrates that, for example, this extension preserves line-breaks, -indendation, and whitespace - and properly converts and interprets such Wiki -markup as links and italicized text. +The XML style is a "..." block: + + + Like this, a %%[[Haiku]]%% having + the HTML + classes, ##haiku## and ##poem##. + + +Or, more concisely: + + + Like this, a %%[[Haiku]]%% having + the default HT- + ML class, ##poem##. + + +Both markup produce a preformatted block (that is, a "
...
" block) +having the "poem" HTML class (for CSS stylization of that block). The XML style +permits customization of this HTML class; the Creole style does not. Thus, use +the XML style for poetry requiring unique CSS stylization. + +Both markup preserve linebreaks, leading indendation, and interspersed +whitespace, preserving the lyrical structure of the poetry this markup is +marking up. In other words, this markup does "the right thing." + +Both markup permit embedding of other Wiki markup -- like Wiki links, lists, +headers, and so on -- within themselves. (This permits, should you leverage it, +Wiki poets to pen interactive and actively interesting, Wiki-integrated poetry.) =cut -# Stanza line-breaks conflict with Creole-style line-breaks. +# Stanza linebreaks conflict with Creole-style line-breaks. $RuleOrder{\&PoetryRule} = 170; +my $PoetryHtmlTag = 'pre'; +my $PoetryHtmlAttrPattern = '^class="poem( \S|"$)'; + sub PoetryRule { - # ::: - # open a new "verse" div or close an existing one - if ($bol and m/\G:::(\n|$)/cg) { - if ($PoetryRuleInDiv) { - $PoetryRuleInDiv = ''; - return CloseHtmlEnvironments().AddHtmlEnvironment('p'); + if (InElement($PoetryHtmlTag, $PoetryHtmlAttrPattern)) { + # Closure for the current poem. + if ($bol and ( + ($PoetryIsHandlingCreoleStyleMarkup and m~\G:::(\n|$)~cg) or + ($PoetryIsHandlingXMLStyleMarkup and m~\G</poem\>[ \t]*(\n|$)~cg))) { + return CloseHtmlEnvironment($PoetryHtmlTag, $PoetryHtmlAttrPattern). + AddHtmlEnvironment('p'); } - else { - $PoetryRuleInDiv = 1; - return CloseHtmlEnvironments() - .AddHtmlEnvironment('div', 'class="verse"') - .AddHtmlEnvironment('p'); + # Linebreaks and paragraphs. This interprets one newline as a linebreak, two + # newlines as a paragraph, and N newlines, where N is greater than two, as a + # paragraph followed by N-2 linebreaks. This produces appropriate vertical + # tracking, surprisingly. + elsif (m~\G(\s*\n)+~cg) { + $number_of_newlines = ($1 =~ tr/\n//); + + my $html = ''; + if ($number_of_newlines > 1) { + $number_of_newlines -= 2; + $html .= CloseHtmlEnvironmentUntil($PoetryHtmlTag, $PoetryHtmlAttrPattern) + .AddHtmlEnvironment('p'); + } + $html .= $q->br() x $number_of_newlines; + return $html; } - } - # Otherwise, if we are currently in an existing "verse" div, force proper - # whitespace with liberal use of
tags. (We cannot use a simple "pre" - # tag, as such preformatted blocks do not permit embedding of HTML tags.) - elsif ($PoetryRuleInDiv) { - if (m/\G\s*\n(\s*\n)+/cg) { # paragraphs: at least two newlines - return CloseHtmlEnvironmentUntil('div').AddHtmlEnvironment('p'); - } - elsif (m/\G\s*\n/cg) { # line break: one newline - return $q->br(); - } - elsif ($bol and m/\G(\s*)/cg) { # indentation + # Indentation. (Embedding poetry within a preformatted block ensures excess + # whitespace within a line is displayed as is, while whitespace at the fore + # of a line is not displayed, but ignored. This corrects that.) + elsif ($bol and m~\G(\s*)~cg) { # indentation return ' ' x length($1); } } + # A new poem. + elsif ($bol and ( + ($PoetryIsHandlingCreoleStyleMarkup and m~\G:::(\n|$)~cg) or + ($PoetryIsHandlingXMLStyleMarkup and + m~\G\<poem(\s+(?:class\s*=\s*)?"(.+?)")?\>[ \t]*(\n|$)~cg))) { + return CloseHtmlEnvironments() + .AddHtmlEnvironment($PoetryHtmlTag, 'class="poem'. + (defined $2 ? ' '.$2 : '').'"') + .AddHtmlEnvironment('p'); + } return undef; } +# ....................{ FUNCTIONS }.................... +*CloseHtmlEnvironmentsPoetryOld = *CloseHtmlEnvironments; +*CloseHtmlEnvironments = *CloseHtmlEnvironmentsPoetry; + +=head2 CloseHtmlEnvironmentsPoetry + +Closes HTML environments for the current poetry "
", up to but not including +the "
" associated with the current poetry "
". + +=cut +sub CloseHtmlEnvironmentsPoetry { + return InElement ($PoetryHtmlTag, $PoetryHtmlAttrPattern) + ? CloseHtmlEnvironmentUntil($PoetryHtmlTag, $PoetryHtmlAttrPattern) + : CloseHtmlEnvironmentsPoetryOld(); +} + =head1 COPYRIGHT AND LICENSE The information below applies to everything in this distribution,