package Pod::Simple::Wiki::Mediawiki;
###############################################################################
#
# Pod::Simple::Wiki::Mediawiki - A class for creating Pod to Mediawiki filters.
#
#
# Copyright 2003-2008, John McNamara, jmcnamara@cpan.org
#
# Documentation after __END__
#
use Pod::Simple::Wiki;
use strict;
use vars qw(@ISA $VERSION);
@ISA = qw(Pod::Simple::Wiki);
$VERSION = '0.08';
###############################################################################
#
# The tag to wiki mappings.
#
my $tags = {
'<b>' => "'''",
'</b>' => "'''",
'<i>' => "''",
'</i>' => "''",
'<tt>' => '<tt>',
'</tt>' => '</tt>',
'<pre>' => "<code>\n",
'</pre>' => "\n</code>\n",
'<h1>' => '==',
'</h1>' => "==\n",
'<h2>' => '===',
'</h2>' => "===\n",
'<h3>' => '====',
'</h3>' => "====\n",
'<h4>' => '=====',
'</h4>' => "=====\n",
};
###############################################################################
#
# new()
#
# Simple constructor inheriting from Pod::Simple::Wiki.
#
sub new {
my $class = shift;
my $self = Pod::Simple::Wiki->new('wiki', @_);
$self->{_tags} = $tags;
bless $self, $class;
$self->accept_targets('mediawiki');
$self->nbsp_for_S(1);
return $self;
}
###############################################################################
#
# _append()
#
# Appends some text to the buffered Wiki text.
#
sub _append {
my $self = shift;
if ($self->{_indent_text}) {
$self->{_wiki_text} .= $self->{_indent_text};
$self->{_indent_text} = '';
}
$self->{_wiki_text} .= $_[0];
}
###############################################################################
#
# _indent_item()
#
# Indents an "over-item" to the correct level.
#
sub _indent_item {
my $self = shift;
my $item_type = $_[0];
my $item_param = $_[1];
my $indent_level = $self->{_item_indent};
if ($item_type eq 'bullet') {
$self->_append('*' x $indent_level . ' ');
}
elsif ($item_type eq 'number') {
$self->_append('#' x $indent_level . ' ');
}
elsif ($item_type eq 'text') {
$self->_append(':' x ($indent_level-1) . '; ');
}
}
###############################################################################
#
# Functions to deal with links.
sub _start_L {
my ($self, $attr) = @_;
unless ($self->_skip_headings) {
$self->_append(''); # In case we have _indent_text pending
$self->_output; # Flush the text buffer, so it will contain only the link text
$self->{_link_attr} = $attr; # Save for later
} # end unless skipping formatting because in heading
} # end _start_L
sub _end_L {
my $self = $_[0];
my $attr = delete $self->{_link_attr};
if ($attr and my $method = $self->can('_format_link')) {
$self->{_wiki_text} = $method->($self, $self->{_wiki_text}, $attr);
} # end if link to be processed
} # end _end_L
###############################################################################
#
# _format_link
sub _format_link {
my ($self, $text, $attr) = @_;
if ($attr->{type} eq 'url') {
my $link = $attr->{to};
return $link if $attr->{'content-implicit'};
return "[$link $text]";
} # end if hyperlink to URL
# Manpage:
if ($attr->{type} eq 'man') {
# FIXME link to http://www.linuxmanpages.com?
return "<tt>$text</tt>" if $attr->{'content-implicit'};
return "$text (<tt>$attr->{to}</tt>)";
} # end if manpage
die "Unknown link type $attr->{type}" unless $attr->{type} eq 'pod';
# Handle a link within this page:
return "[[#$attr->{section}|$text]]" unless defined $attr->{to};
# Handle a link to a specific section in another page:
return "[[$attr->{to}#$attr->{section}|$text]]" if defined $attr->{section};
return "[[$attr->{to}]]" if $attr->{'content-implicit'};
return "[[$attr->{to}|$text]]";
} # end _format_link
###############################################################################
#
# _handle_text()
#
# Perform any necessary transforms on the text. This is mainly used to escape
# inadvertent CamelCase words.
#
sub _handle_text {
my $self = shift;
my $text = $_[0];
unless ($self->{_in_Data}) {
# Escape colons in definition lists:
if ($self->{_in_item_text}) {
$text =~ s/:/:/g; # A colon would end the item
}
# Escape empty lines in verbatim sections:
if ($self->{_in_Verbatim}) {
$text =~ s/^$/ /mg; # An empty line would split the section
}
$text =~ s/\xA0/ /g; # Convert non-breaking spaces to entities
$text =~ s/''/''/g; # It's not a formatting code
} # end unless in data paragraph
$self->_append($text);
}
###############################################################################
#
# Functions to deal with =over ... =back regions for
#
# Bulleted lists
# Numbered lists
# Text lists
# Block lists
#
sub _end_item_text { } # _start_Para will insert the :
###############################################################################
#
# _start_Para()
#
# Special handling for paragraphs that are part of an "over" block.
#
sub _start_Para {
my $self = shift;
my $indent_level = $self->{_item_indent};
if ($self->{_in_over_block}) {
$self->{_indent_text} = (':' x $indent_level);
}
if ($self->{_in_over_text}) {
$self->{_indent_text} = "\n" . (':' x $indent_level);
}
}
######################################################################
#
# _end_Data
#
# Special handling for data paragraphs
sub _end_Data { $_[0]->_output("\n\n") }
1;
__END__
=head1 NAME
Pod::Simple::Wiki::Mediawiki - A class for creating Pod to Mediawiki wiki filters.
=head1 SYNOPSIS
This module isn't used directly. Instead it is called via C<Pod::Simple::Wiki>:
#!/usr/bin/perl -w
use strict;
use Pod::Simple::Wiki;
my $parser = Pod::Simple::Wiki->new('mediawiki');
...
Convert Pod to a Mediawiki wiki format using the installed C<pod2wiki> utility:
pod2wiki --style mediawiki file.pod > file.wiki
=head1 DESCRIPTION
The C<Pod::Simple::Wiki::Mediawiki> module is used for converting Pod text to Wiki text.
Pod (Plain Old Documentation) is a simple markup language used for writing Perl documentation.
For an introduction to Mediawiki see: http://www.mediawiki.org/wiki/MediaWiki
This module isn't generally invoked directly. Instead it is called via C<Pod::Simple::Wiki>. See the L<Pod::Simple::Wiki> and L<pod2wiki> documentation for more information.
=head1 METHODS
Pod::Simple::Wiki::Mediawiki inherits all of the methods of C<Pod::Simple> and C<Pod::Simple::Wiki>. See L<Pod::Simple> and L<Pod::Simple::Wiki> for more details.
=head1 SEE ALSO
This module also installs a C<pod2wiki> command line utility. See C<pod2wiki --help> for details.
=head1 ACKNOWLEDGEMENTS
Thanks Tony Sidaway for initial Wikipedia/MediaWiki support. Christopher J. Madsen for several major additions and tests.
=head1 DISCLAIMER OF WARRANTY
Please refer to the DISCLAIMER OF WARRANTY in L<Pod::Simple::Wiki>.
=head1 AUTHORS
John McNamara jmcnamara@cpan.org
Christopher J. Madsen perl@cjmweb.net
=head1 COPYRIGHT
© MMIII-MMVIII, John McNamara.
All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.