=pod To better view this file, use: perldoc README =head1 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. =head1 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: =over 2 =item * Install the Perl module Module::Signature from http://search.cpan.org =item * Get my key from http://bloodgate.com/tels.asc, import it into GnuPG with: gpg --import tels.asc You may also let the C<cpansign> utility fetch it automatically from a keyserver, if that works for you. =item * Extract the package to a directory, change there and then: =item * Type on a console: cpansign --verify inside the unpacked directory. =back If the last step says "good signature" or "SIGNATURE VERIFIED OK", everything is all right. Note that if you C<cpansign> let GnuPG download my key from a keyserver, it might put a C<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. B<NOTE:> Please notify me immidiately if the signature does not verify. In that case do B<NOT> install this software, your system might get compromised! =head1 Installation Install the following Perl modules into your system: Pod-Simple HTML-Parser HTML-Tagset You can get these modules from C<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!). =head2 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 C<lib/> in the C<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. =head2 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. =head2 Backup! B<Make a backup of your wiki! I repeat, MAKE A BACKUP! You have been warned!> =head2 Copy the files Then place the following two files from this Mediawiki-POD.tar.gz file so that into the subdirectory C<extensions> of your wiki installation like this: http_docroot \ - cgi-bin etc \ - wiki \ - extensions <-- here \ - math etc You need the following files inside C<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 C<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 C<LocalSettings.php>, but before the "?>" line: include_once('extensions/POD.php'); =head2 Manual test Change the permissions of C<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. =head2 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. =head1 BUGS Please report bugs, feature requests or POD errors to: http://rt.cpan.org/ =head1 AUTHOR Copyright (C) 2007 by Tels http://bloodgate.com/ Contact: <email@example.com> (literally :) This library is free software; you can redistribute it and/or modify it under the same terms of the GPL.