The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Pod-Multi-0.10
River stage zero No dependents
++
/ Pod::Multi

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:

  • source

    The source key is mandatory; its value must be the path to the source file containing documentation in the POD format.

  • options

    The options key is, of course, optional. (But why would you use the multiple argument version unless you wanted to specify options?) The value of the options key must be a reference to an hash (named or anonymous) which holds a list of key-value pairs. The elements in that hash are as follows:

    • $options{text}

      With one exception, the key-value pairs are those you would normally supply to Pod::Text::new().

          text => {
        sentence    =>  0,
        width       => 78,
        ...
    },

      The exception is that if you wish to specify a directory for the creation of the output file, you may do so with the outputpath option.

          text => {
        outputpath  => /path/to/textoutput/,
        ...
    },

      Internally, pod2multi() prepends this to the basename of the source file and provides the result as the second argument to Pod::Text::parse_from_file(). Note that this is a directory where the output file will reside -- not the full path to that file.

    • $options{man}

      With one exception, the key-value pairs are those you would normally supply to Pod::Man::new().

          man => {
        release     => $VERSION,
        section     => 8,
        ...
    },

      The exception is that if you wish to specify a directory for the creation of the output file, you may do so with the outputpath option.

          man => {
        outputpath  => /path/to/manoutput/,
        ...
    },

      Internally, pod2multi() prepends this to the basename of the source file and provides the result as the second argument to Pod::Man::parse_from_file(). Note that this is a directory where the output file will reside -- not the full path to that file.

    • $options{html}

      The html option works in the same way as <text> and <man>, except that there is no <outputpath> sub-option. That's because the key-value pairs which should be supplied via hash reference to $options{html} are the contents of the ''long options'' normally supplied to Pod::Html::pod2html. That function, which <pod2multi() calls internally, expects arguments in the long option format:

          --infile=/path/to/source,
    --outfile=/path/to/htmloutput,
    --title="Title for HTML",

      ... rather than in list-of-key-value-pairs format. For consistency, pod2multi() expects arguments to $options{html} in the same format as to $options{text} and $options{man}, then converts them internally to the long options needed by Pod::Html::pod2html().

          html    => {
        infile   => "/path/to/source",
        outfile  => "/path/to/htmloutput",
        title    => "Title for HTML",
        ...
    },

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