James E Keenan > Pod-Multi > Pod::Multi

Download:
Pod-Multi-0.09.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.09   Source  

NAME ^

Pod::Multi - pod2man, pod2text, pod2html simultaneously

SYNOPSIS ^

From the command-line:

  pod2multi file_with_pod

or:

  pod2multi file_with_pod Title for HTML Version

Inside a Perl program:

  use Pod::Multi;

  pod2multi("/path/to/file_with_pod");

or:

  %options = (
        text     => {
            sentence    =>  0,
            width       => 78,
            outputpath  => "/outputpath/for/text/",
            ...
        },
        man     => {
            manoption1  => 'manvalue1',
            manoption2  => 'manvalue2',
            outputpath  => "/outputpath/for/man/",
            ...
        },
        html     => {
            infile       => "/path/to/infile",
            outfile      => "/path/to/outfile",
            title        => "Title for HTML",
            ...
        },
  );

  pod2multi(
    source  => "/path/to/file_with_pod",
    options => \%options,
  );

  use Pod::Multi qw(make_options_defaults);
  make_options_defaults( \%options );

DESCRIPTION ^

When you install a Perl module from CPAN, documentation gets installed which is readable with perldoc and (at least on *nix-like systems) with man as well. You can convert that documentation to text and HTML formats with two utilities that come along with Perl: pod2text and pod2html.

In production environments documentation of Perl programs tends to be less rigorous than that of CPAN modules. If you want to convince your co-workers of the value of writing documentation for such programs, you may want a painless way to generate that documentation in a variety of formats. If you already know how to write documentation in Perl's Plain Old Documentation (POD) format, Pod::Multi will save you some keystrokes by simultaneously generating documentation in manpage, plain-text and HTML formats from a source file containing POD.

In its current version, Pod::Multi generates those documentary files in the same directory as the source file. It does not attempt to install those files anywhere else. In particular, it does not attempt to install the manpage version in a MANPATH directory. This may change in a future version, but for the time being, we're keeping it simple.

Pod::Multi is intended to be used primarily via its associated command-line utility, pod2multi. pod2multi requires only one argument: the path to a file containing documentation in POD format. In the interest of simplicity, any other arguments provided on the command-line are concatenated into a wordspace-separated string which will serve as the title tag of the HTML version of the documentation. No other options are offered because, in the author's opinion, if you want more options you'll probably use as many keystrokes as you would if you ran pod2man, pod2text or pod2html individually.

The functional interface may be used inside Perl programs and, if you have personal preferences for the options you would normally provide to pod2man, pod2text or pod2html, you can specify them in the functional interface. If you have a strong set of personal preferences as to how you like your text, manpage and HTML versions of your POD to look, you can even save them with the make_options_defaults() function, which stores those options in a .pod2multirc file in an appropriate place underneath your home directory.

USAGE ^

Command-Line Interface: pod2multi

Default Case

  pod2multi file_with_pod

Will create files called file_with_pod.man, file_with_pod.txt and file_with_pod.html in the same directory where file_with_pod is located. You must have write permissions to that directory. The name file_with_pod cannot contain wordspaces. Unless you have saved a .pod2multirc personal defaults file under your home directory, these files will be created with the default options you would get by calling pod2man, pod2text and pod2html individually. This in turn means the the files so generated will follow the format of the Pod::Man, Pod::Text and Pod::Html modules you have installed on your system. The title tag in the HTML version will be file_with_pod.

Provide Title Tag for HTML Version

  pod2multi file_with_pod Title for HTML Version

Exactly the same as the default case, with one exception: the title tag in the HTML version will be Title for HTML Version.

Functional Interface: pod2multi()

When called into a Perl program via use, require or do, Pod::Multi automatically exports a single function: pod2multi.

Default Case: Single Argument

  pod2multi("/path/to/file_with_pod");

This is analogous to the default case in the command-line interface (above). If pod2multi() is supplied with just one argument, it assumes that that argument is the path to a file containing documentation in POD format and proceeds to create files called file_with_pod.man, file_with_pod.txt and file_with_pod.html in directory /path/to/ (assuming that directory is writable). The title tag for the HTML version will be file_with_pod.

Alternative Case: Multiple Arguments in List of Key-Value Pairs

This is how Pod::Multi works internally; otherwise it's only recommended for people who have strong preferences. Arguments can be provided to pod2multi() in a list of key-value pairs subject to the following requirements:

make_options_defaults()

If you have strong preferences as to how you like your manpage, text and HTML manuals to look, you can have pod2multi produce the same results everytime by saving your chosen defaults in a file called .pod2multirc which is stored underneath your home directory. Place your preferences in a %options with man, text and/or html keys as needed. Then pass a reference to that hash to make_options_defaults() and call that function in a Perl program.

The place where <.pod2multirc> will be stored is determined by a call to File::Save::Home::get_home_directory(). File::Save::Home, by the same author as Pod::Multi and available from CPAN, is a pre-requisite to Pod::Multi.

make_options_defaults() is not exported by default. You must explicitly request it with:

    use Pod::Multi qw( C<make_options_defaults()> );

PREREQUISITES ^

Perl Core Modules

    Carp
    Data::Dumper
    File::Basename
    File::Path
    File::Spec
    Pod::Html
    Pod::Man
    Pod::Text
    Test::Simple

CPAN Modules

    File::Save::Home
    IO::Capture

BUGS ^

None reported yet.

SUPPORT ^

Contact author at his cpan [dot] org address below.

AUTHOR ^

    James E Keenan
    CPAN ID: JKEENAN
    jkeenan@cpan.org
    http://search.cpan.org/~jkeenan/
    http://thenceforward.net/perl/modules/Pod-Multi/

ACKNOWLEDGEMENTS ^

Steven Lembark made the suggestion about submitting all modules needed to a use_ok at the start of the very first test.

David H Adler and David A Golden assisted with debugging.

COPYRIGHT ^

Copyright 2006 James E Keenan. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

SEE ALSO ^

perl(1). perldoc(1). man(1). pod2man(1). pod2text(1). pod2html(1). Pod::Man(3pm). Pod::Text(3pm). Pod::Html(3pm).

syntax highlighting: