Pod::Readme

(source, CPAN)

v1.2.3

NAME
SYNOPSIS
DESCRIPTION
POD COMMANDS
ATTRIBUTES
METHODS
CAVEATS
SEE ALSO
AUTHORS
- Acknowledgements
- Suggestions, Bug Reporting and Contributing
LICENSE

#NAME

Pod::Readme - Intelligently generate a README file from POD

#SYNOPSIS

In a module's POD:

=head1 NAME

MyApp - my nifty app

=for readme plugin version

=head1 DESCRIPTION

This is a nifty app.

=begin :readme

=for readme plugin requires

=head1 INSTALLATION

...

=end :readme

=for readme stop

=head1 METHODS

...

Then from the command-line:

pod2readme lib/MyModule.pm README

From within Perl:

use Pod::Readme;

my $prf = Pod::Readme->new(
  input_file		=> 'lib/MyModule.pm',
  translate_to_file	=> $dest,
  translation_class	=> 'Pod::Simple::Text',
);

$prf->run();

#DESCRIPTION

This module filters POD to generate a README file, by using POD commands to specify which parts are included or excluded from the README file.

#POD COMMANDS

#`=for readme stop`

Stop including the POD that follows in the README.

#`=for readme start`

#`=for readme continue`

Start (or continue to) include the POD that follows in the README.

Note that the start command was added as a synonym in version 1.0.0.

#`=for readme include`

=for readme include file="INSTALL" type="text"

Include a text or POD file in the README. It accepts the following options:

#file: Required. This is the file name to include.
#type: Can be "text" or "pod" (default).
#start: An optional regex of where to start including the file.
#stop: An optional regex of where to stop including the file.

#`=for readme plugin`

Loads a plugin, e.g.

=for readme plugin version

Note that specific plugins may add options, e.g.

=for readme plugin changes title='CHANGES'

See Pod::Readme::Plugin for more information.

Note that the plugin command was added in version 1.0.0.

#`=begin :readme`

#`=end :readme`

Specify a block of POD to include only in the README.

You can also specify a block in another format:

=begin readme text

...

=end readme text

This will be translated into

=begin text

...

=end text

and will only be included in README files of that format.

Note: earlier versions of this module suggested using

=begin readme

...

=end readme

While this version supports that syntax for backwards compatibility, it is not standard POD.

#ATTRIBUTES

This module extends Pod::Readme::Filter with the following attributes:

#`translation_class`

The class used to translate the filtered POD into another format, e.g. Pod::Simple::Text.

If it is undef, then there is no translation.

Only subclasses of Pod::Simple are supported.

#`translate_to_fh`

The IO::Handle to save the translated file to.

#`translate_to_file`

The Path::Tiny filename to save the translated file to. If omitted, then it will be saved to STDOUT.

#`output_file`

The Pod::Readme::Filter output_file will default to a temporary file.

#`force`

For a new README to be generated, even if the dependencies have not been updated.

See "dependencies_updated".

#`zilla`

For use with Dist::Zilla plugins.

This allows plugins which normally depend on files in the distribution to use metadata from here instead.

#METHODS

This module extends Pod::Readme::Filter with the following methods:

#`default_readme_file`

The default name of the README file, which depends on the "translation_class".

#`translate_file`

This method runs translates the resulting POD from filter_file.

#`dependencies_updated`

Used to determine when the dependencies have been updated, and a translation can be run.

Note that this only returns a meaningful value after the POD has been processed, since plugins may add to the dependencies. A side-effect of this is that when generating a POD formatted README is that it will always be updated, even when "force" is false.

#`run`

This method runs filter_file and then "translate_file".

#`parse_from_file`

my $parser = Pod::Readme->new();
$parser->parse_from_file( 'README.pod', 'README' );

Pod::Readme->parse_from_file( 'README.pod', 'README' );

This is a class method that acts as a Pod::Select compatibility shim for software that is designed for versions of Pod::Readme prior to v1.0.

Its use is deprecated, and will be deleted in later versions.

#`parse_from_filehandle`

Like "parse_from_file", this exists as a compatibility shim.

Its use is deprecated, and will be deleted in later versions.

#CAVEATS

This module is intended to be used by module authors for their own modules. It is not recommended for generating README files from arbitrary Perl modules from untrusted sources.

#SEE ALSO

See perlpod, perlpodspec and podlators.

#AUTHORS

The original version was by Robert Rothenberg <rrwo@cpan.org> until 2010, when maintenance was taken over by David Precious <davidp@preshweb.co.uk>.

In 2014, Robert Rothenberg rewrote the module to use filtering instead of subclassing a POD parser.

#Acknowledgements

Thanks to people who gave feedback and suggestions to posts about the rewrite of this module on http://blogs.perl.org.

#Suggestions, Bug Reporting and Contributing

This module is developed on GitHub at http://github.com/bigpresh/Pod-Readme

CONTENTS

#NAME

#SYNOPSIS

#DESCRIPTION

#POD COMMANDS

#`=for readme stop`

#`=for readme start`

#`=for readme continue`

#`=for readme include`

#`=for readme plugin`

#`=begin :readme`

#`=end :readme`

#ATTRIBUTES

#`translation_class`

#`translate_to_fh`

#`translate_to_file`

#`output_file`

#`force`

#`zilla`

#METHODS

#`default_readme_file`

#`translate_file`

#`dependencies_updated`

#`run`

#`parse_from_file`

#`parse_from_filehandle`

#CAVEATS

#SEE ALSO

#AUTHORS

#Acknowledgements

#Suggestions, Bug Reporting and Contributing

#LICENSE

CONTENTS

#NAME

#SYNOPSIS

#DESCRIPTION

#POD COMMANDS

#=for readme stop

#=for readme start

#=for readme continue

#=for readme include

#=for readme plugin

#=begin :readme

#=end :readme

#ATTRIBUTES

#translation_class

#translate_to_fh

#translate_to_file

#output_file

#force

#zilla

#METHODS

#default_readme_file

#translate_file

#dependencies_updated

#run

#parse_from_file

#parse_from_filehandle

#CAVEATS

#SEE ALSO

#AUTHORS

#Acknowledgements

#Suggestions, Bug Reporting and Contributing

#LICENSE

#`=for readme stop`

#`=for readme start`

#`=for readme continue`

#`=for readme include`

#`=for readme plugin`

#`=begin :readme`

#`=end :readme`

#`translation_class`

#`translate_to_fh`

#`translate_to_file`

#`output_file`

#`force`

#`zilla`

#`default_readme_file`

#`translate_file`

#`dependencies_updated`

#`run`

#`parse_from_file`

#`parse_from_filehandle`