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

NAME

Pod::Elemental::Transformer::Include - include output via files and commands

VERSION

version 1.001

SYNOPSIS

    =head1 DIRECTORY LISTING

    include_file:header.txt

        include_cmd:ls

    include_cmd:blah

    include_file:footer.txt

DESCRIPTION

A simple way to include files and output of commands in POD via Pod::Weaver.

USING

There are two supported identifiers include_file: and include_cmd:. They must be placed at the beginning of the line optionally followed by white space. When there is white space then the every line of output included will be prefixed with that same amount of white space. For example,

    include_cmd:echo no white space

becomes,

    no white space

Where as,

    include_cmd:    echo 4 spaces

becomes,

        4 spaces

Errors are not fatal. But, you will see if something failed by prints to standard output.

  • include_file: - Replaces line with the file contents and does no transformation on the data.

  • include_cmd: - Replaces the line with the command output and does no transformation on the data.

WARNING

Be careful what you execute with include_cmd:.

SETUP

There may be another eloquent and preferred way, but I've gone with a Pod::Weaver PluginBundle in conjunction with Dist::Zilla. A quick howto:

First setup a PluginBundle:

    package Pod::Weaver::PluginBundle::aflott;
    sub mvp_bundle_config {
      return (
        [ '@aflott/Default', 'Pod::Weaver::PluginBundle::Default', {} ],
        [ '@aflott/List',    'Pod::Weaver::Plugin::Transformer', { 'transformer' => 'List' } ],
        [ '@aflott/Include', 'Pod::Weaver::Plugin::Transformer', { 'transformer' => 'Include' } ],
      );
    }

Then insider your dist.ini,

    [PodWeaver]
    config_plugin = @aflott

And now,

    $ dzil build

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Pod::Elemental::Transformer::Include

You can also look for information at:

AUTHOR

  Adam Flott <adam@npjh.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2010 by Adam Flott.

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