/ 
App-Pod2CpanHtml-0.04
River stage zero No dependents
/ App::Pod2CpanHtml

NAME

App::Pod2CpanHtml - Convert Pod to search.cpan.org style HTML.

DESCRIPTION

This module is used for converting Pod documents to http://search.cpan.org/ style HTML.

Pod is Perl's Plain Old Documentation format, see perlpod.

App::Pod2CpanHtml produces HTML output similar to search.cpan.org by using the same conversion module, Pod::Simple::HTML and the same CSS, http://search.cpan.org/s/style.css.

It should be noted that this utility isn't the actual program used to create the HTML for seach.cpan.org. However, the output should visually be the same.

This module comes with a pod2cpanhtml utility that will convert Pod to search.cpan.org style HTML on the command line.

SYNOPSIS

To create a simple filter to convert Pod to search.cpan.org style HTML.

#!/usr/bin/perl -w

use strict;
use App::Pod2CpanHtml;


my $parser = App::Pod2CpanHtml->new();

if (defined $ARGV[0]) {
    open IN, $ARGV[0]  or die "Couldn't open $ARGV[0]: $!\n";
} else {
    *IN = *STDIN;
}

if (defined $ARGV[1]) {
    open OUT, ">$ARGV[1]" or die "Couldn't open $ARGV[1]: $!\n";
} else {
    *OUT = *STDOUT;
}

$parser->output_fh(*OUT);
$parser->parse_file(*IN);

__END__

To convert Pod to search.cpan.org style HTML using the installed pod2cpanhtml utility:

pod2cpanhtml file.pod > file.html

METHODS

new()

The new method is used to create a new App::Pod2CpanHtml object.

Other methods

App::Pod2CpanHtml inherits all of the methods of its parent modules Pod::Simple and Pod::Simple::HTML. See Pod::Simple for more details if you need finer control over the output of this module.

RATIONALE

This module is a very thin wrapper around Pod::Simple::HTML. I wrote the initial version is response to a question on Perlmonks http://www.perlmonks.com/?node_id=596075.

Despite its simplicity it has proved to be very useful tool for proofing Pod documentation prior to uploading to CPAN. It is also the basis of a script that I frequently copy from machine to machine and it is the answer to a question that is frequently asked on Perl forums. As such, I thought it was time to roll it into a module.

SEE ALSO

This module also installs a pod2cpanhtml command line utility. See pod2cpanhtml --help for details.

You can render a Pod document using search.cpan's own engine at the following link: http://search.cpan.org/pod2html.

Graham Barr's patch to Pod::Simple to produce the search.cpan output: http://cpan.org/authors/id/G/GB/GBARR/search.cpan.org-Pod-Simple-HTML.patch

See Pod::ProjectDocs for generating multiple, inter-linked, search.cpan like documents

ACKNOWLEDGEMENTS

Thanks to Sean M. Burke and the past and current maintainers for Pod::Simple.

Thanks to Graham Barr and everyone involved with http://search.cpan.org.

Thanks to Lars Dieckow for the useful links.

The initial structure of this module was created using Module::Starter, thanks to Andy Lester.

AUTHOR

John McNamara, jmcnamara@cpan.org

COPYRIGHT & LICENSE

Copyright 2009 John McNamara.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License. See http://dev.perl.org/licenses/ for more information.