John McNamara > App-Pod2CpanHtml-0.02 > App::Pod2CpanHtml

Download:
App-Pod2CpanHtml-0.02.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.02   Source   Latest Release: App-Pod2CpanHtml-0.04

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 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.

syntax highlighting: