Bug #24981 for Pod-Simple-Wiki: [PATCH] better Mediawiki support

I've been using pod2wiki to put module documentation on my company's wiki (powered by Mediawiki). It's been a great help, but I've encountered several issues. Unfortunately, I don't have time to submit individual patches, so I've gathered everything together here. The first issue was colons in =item entries (like Module::Name). I gave a patch for 0.06 in bug 24704, and updated it for 0.07 in this patch. After that, I discovered that nested over-text sections didn't format properly. Instead of indenting with multiple semicolons, you need to use colons, with only the last one being a semicolon. Next, it couldn't handle multiple paragraphs following one =item in an over-text section. I fixed that with _indent_text and changes to _start_Para & _end_item_text. Then, I found that blank lines in <code> sections caused them to split into separate sections. I added code in _handle_text to insert spaces. Finally, it didn't handle links at all. I added a very crude hack for that, but it's good enough for my needs. I updated the tests so "make test" should pass. I added a TODO test indicating that you're not really handling nested lists properly. It's supposed to nest like this: * Bullet item 1.0 *# Number item 1.1 *#; Foo *#:Definition item 1.2 *#; Bar *#:Definition item 2.2 *# Number item 2.1 * Bullet item 2.0 But what it currently outputs (with this patch) is this: * Bullet item 1.0 ## Number item 1.1 ::; Foo :::Definition item 1.2 ::; Bar :::Definition item 2.2 ## Number item 2.1 * Bullet item 2.0 My patch does not address this, as it would require a more fundamental architechtural change. I think it might be good to split the 'wiki' format into a derived class and keep Pod::Simple::Wiki an abstract base class. Otherwise, you can't make a change for 'wiki' format without risking it affecting the other formats (which may not want the change).

--- lib/Pod/Simple/Wiki.pm Thu Feb 01 16:04:02 2007 +++ lib/Pod/Simple/Wiki.pm Thu Feb 15 10:31:22 2007 @@ -104,6 +104,11 @@ my $self = shift; + if ($self->{_indent_text}) { + $self->{_wiki_text} .= $self->{_indent_text}; + $self->{_indent_text} = ''; + } + $self->{_wiki_text} .= $_[0]; } @@ -273,7 +278,7 @@ } # Rejoin the tokens and whitespace. - $self->{_wiki_text} .= join '', @tokens; + $self->_append(join '', @tokens); } @@ -285,12 +290,14 @@ sub _start_B {$_[0]->_append_tag('<b>') unless $_[0]->_skip_headings()} sub _start_C {$_[0]->_append_tag('<tt>') unless $_[0]->_skip_headings()} sub _start_F {$_[0]->_start_I} +sub _start_L {$_[0]->_append_tag('<a>') unless $_[0]->_skip_headings()} sub _end_I {$_[0]->_append_tag('</i>') unless $_[0]->_skip_headings()} sub _end_B {$_[0]->_append_tag('</b>') unless $_[0]->_skip_headings()} sub _end_C {$_[0]->_append_tag('</tt>') unless $_[0]->_skip_headings()} sub _end_F {$_[0]->_end_I} +sub _end_L {$_[0]->_append_tag('</a>') unless $_[0]->_skip_headings()} ############################################################################### --- lib/Pod/Simple/Wiki/Mediawiki.pm Thu Feb 01 16:04:06 2007 +++ lib/Pod/Simple/Wiki/Mediawiki.pm Thu Feb 15 13:30:52 2007 @@ -32,6 +32,8 @@ '</tt>' => '</tt>', '<pre>' => "\n<code>\n", '</pre>' => "\n</code>\n", + '<a>' => "[[", + '</a>' => "]]", '<h1>' => '==', '</h1>' => "==\n", @@ -81,7 +83,7 @@ $self->_append('#' x $indent_level . ' '); } elsif ($item_type eq 'text') { - $self->_append(';' x $indent_level . ' '); + $self->_append(':' x ($indent_level-1) . '; '); } } @@ -98,13 +100,17 @@ my $self = shift; my $text = $_[0]; - # Split the text into tokens but maintain the whitespace - my @tokens = split /(\s+)/, $text; + # Escape colons in definition lists: + if ($self->{_in_item_text}) { + $text =~ s/:/&#58;/g; # A colon would end the item + } - # Escape any tokens here. + # Escape empty lines in verbatim sections: + if ($self->{_in_Verbatim}) { + $text =~ s/^$/ /mg; # An empty line would split the section + } - # Rejoin the tokens and whitespace. - $self->{_wiki_text} .= join '', @tokens; + $self->_append($text); } @@ -117,7 +123,7 @@ # Text lists # Block lists # -sub _end_item_text {$_[0]->_output(' : ')} +sub _end_item_text { } # _start_Para will insert the : ############################################################################### @@ -132,8 +138,12 @@ my $indent_level = $self->{_item_indent}; if ($self->{_in_over_block}) { - # Do something here is necessary + $self->{_indent_text} = (':' x $indent_level); + } + + if ($self->{_in_over_text}) { + $self->{_indent_text} = "\n" . (':' x $indent_level); } } --- t/05_03_wikipedia_lists.t Thu Feb 01 09:39:52 2007 +++ t/05_03_wikipedia_lists.t Thu Feb 15 13:53:30 2007 @@ -13,7 +13,7 @@ use strict; use Pod::Simple::Wiki; -use Test::More tests => 12; +use Test::More tests => 14; my $style = 'wikipedia'; @@ -345,7 +345,8 @@ # Expected output. # # -; Foo : Definition item +; Foo +:Definition item ############################################################################### # @@ -375,9 +376,12 @@ # Expected output. # # -; Foo : Definition item 1.0 -; Bar : Definition item 2.0 -; Baz : Definition item 3.0 +; Foo +:Definition item 1.0 +; Bar +:Definition item 2.0 +; Baz +:Definition item 3.0 ############################################################################### # @@ -427,16 +431,24 @@ # Expected output. # # -; Foo : Definition item 1.0 -;; Foo : Definition item 1.1 -;;; Foo : Definition item 1.2 -;;; Bar : Definition item 2.2 -;; Bar : Definition item 2.1 -; Bar : Definition item 2.0 +; Foo +:Definition item 1.0 +:; Foo +::Definition item 1.1 +::; Foo +:::Definition item 1.2 +::; Bar +:::Definition item 2.2 +:; Bar +::Definition item 2.1 +; Bar +:Definition item 2.0 ############################################################################### # -# NAME: Test for varied nested list. +# NAME: Test for varied nested list (incorrect). +# +# Note that the output is not formatted correctly (see the next TODO test) # =pod @@ -484,17 +496,76 @@ # * Bullet item 1.0 \## Number item 1.1 -;;; Foo : Definition item 1.2 -;;; Bar : Definition item 2.2 +::; Foo +:::Definition item 1.2 +::; Bar +:::Definition item 2.2 \## Number item 2.1 * Bullet item 2.0 +############################################################################### +# +# NAME: Test for varied nested list. +# +# TODO: Nest lists correctly +# +=pod + +=over + +=item * + +Bullet item 1.0 + +=over + +=item 1 + +Number item 1.1 + +=over + +=item Foo + +Definition item 1.2 + +=item Bar + +Definition item 2.2 + +=back + +=item 2 + +Number item 2.1 + +=back + +=item * + +Bullet item 2.0 + +=back + +=cut +# +# +# Expected output. +# +# +* Bullet item 1.0 +*# Number item 1.1 +*#; Foo +*#:Definition item 1.2 +*#; Bar +*#:Definition item 2.2 +*# Number item 2.1 +* Bullet item 2.0 + ################################################################################ # # NAME: Test for definition list without =items, <blockquote>. # -# TODO: Fix this later. -# =pod =over @@ -509,14 +580,12 @@ # Expected output. # # -; : This is a long sentence that forms part of a definition block. +:This is a long sentence that forms part of a definition block. ################################################################################ # # NAME: Test for definition list without a definition. # -# TODO: Fix this later. -# =pod =over @@ -531,8 +600,31 @@ # Expected output. # # -; This is a long sentence that forms part of a definition block. : +; This is a long sentence that forms part of a definition block. +################################################################################ +# +# NAME: Test 2 for definition list without a definition. +# +# TODO: Needs a newline after the first item +# +=pod + +=over + +=item This is a long sentence that forms part of a definition block. +=item This is the next item. + +=back + +=cut +# +# +# Expected output. +# +# +; This is a long sentence that forms part of a definition block. +; This is the next item. ############################################################################### # # End