To better view this file, use:

        perldoc README

podcnv

Take POD text (Plain Old Documentation, Perl's way to write documentation) and render it as HTML inside a wiki page.

For instance this file here could be pasted between <pod> and </pod> tags inside a wiki and would then be displayed as HTML for any visitor.

The reason for this extensionis that multiple authors can edit one POD file at the same time, and enjoy the advantages of Mediawiki like revision history, diffs, undo function, collapsable table of contents etc.

Check the Signature

First you need to check the signature on the package to verify that it is untampered and intact. To do this you have to:

• Install the Perl module Module::Signature from http://search.cpan.org

• Get my key from http://bloodgate.com/tels.asc, import it into GnuPG with:

          gpg --import tels.asc

  You may also let the cpansign utility fetch it automatically from a keyserver, if that works for you.

• Extract the package to a directory, change there and then:

• Type on a console:

          cpansign --verify

  inside the unpacked directory.

If the last step says "good signature" or "SIGNATURE VERIFIED OK", everything is all right.

Note that if you cpansign let GnuPG download my key from a keyserver, it might put a tels.asc file in the package directory, and then afterward complain that "tels.asc" is not in the MANIFEST:

 Not in MANIFEST: tels.asc
 ==> MISMATCHED content between MANIFEST and distribution files! <==

You can safely ignore this warning.

NOTE: Please notify me immidiately if the signature does not verify. In that case do NOT install this software, your system might get compromised!

Installation

Install the following Perl modules into your system:

        Pod-Simple
        HTML-Parser
        HTML-Tagset

You can get these modules from http://search.cpan.org/.

Afterwards, you should be able to run this on any command line:

        perl -MPod-Simple\ 99

and it should report your installed Pod::Simple (like v3.04).

        Pod::Simple version 99 required--this is only version 3.04.
        BEGIN failed--compilation aborted.

If it says something about "Pod::Simple" not being found, you need to install it first as root (see above!).

Installation on a shared host

On a shared host you typically do not have the rights to install Perl modules. An easy way around that limitation is to place the modules inside a directory called lib/ in the extensions directory:

        http_docroot
                \ - cgi-bin                     etc
                \ - wiki
                        \ - pod
                        \ - extensions          etc
                                \ - lib         <-- here

Untar Pod::Simple and the other modules you need into this directory.

Run the testsuite

If you are on a shared host, skip this step.

Otherwise, after installing the Perl modules from above into the system, then run in the directory of this package:

        perl Makefile.PL
        make test

All tests should pass. If not, please notify me.

Backup!

Make a backup of your wiki! I repeat, MAKE A BACKUP! You have been warned!

Copy the files

Then place the following two files from this Mediawiki-POD.tar.gz file so that into the subdirectory extensions of your wiki installation like this:

        http_docroot
                \ - cgi-bin                     etc
                \ - wiki
                        \ - extensions          <-- here
                        \ - math                etc

You need the following files inside wiki/extensions:

        podcnv
        POD.php

Then either install this module:

        sudo make install

Or if you on a shared host, place all the files from the lib/ subdirectory under the extensions directory, too:

        lib/Mediawiki/POD.pm       =>  extensions/lib/Mediawiki/POD.pm
        lib/Mediawiki/POD/HTML.pm  =>  extensions/lib/Mediawiki/POD/HTML.pm
        

Then include the following line at the bottom of your LocalSettings.php, but before the "?>" line:

        include_once('extensions/POD.php');

Manual test

Change the permissions of podcnv to be executable:

        chmod a+x extensions/podcnv

Now you should be able to run manually (from your wiki directory):

        echo "=head1 NAME" | extensions/podcnv

and should print some HTML code on the console.

Wiki test

Finally you should be able to edit any page of the wiki and insert:

        <pod>
        =head1 NAME

        Some test.
        </pod>

and hit preview.

If you get an error messages like:

        Error running podcnv.

make sure that you followed the steps above correctly.

BUGS

Please report bugs, feature requests or POD errors to:

        http://rt.cpan.org/

AUTHOR

Copyright (C) 2007 by Tels http://bloodgate.com/

Contact: <nospam-abuse@bloodgate.com> (literally :)

This library is free software; you can redistribute it and/or modify it under the same terms of the GPL.

cpanm Mediawiki::POD

perl -MCPAN -e shell
install Mediawiki::POD