Pod::Readme - generate README files from 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 ...
This module filters POD to generate a README file, by using POD commands to specify what parts of included or excluded from the README file.
=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.
start
=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).
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.
=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 compatability, it is not standard POD.
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.
undef
Only subclasses of Pod::Simple are supported.
translate_to_fh
The IO::Handle to save the translated file to.
translate_to_file
The Path::Class::File to save the translated file to. If omitted, then it will be saved to STDOUT.
STDOUT
output_file
The Pod::Readme::Filter output_file will default to a temporary file.
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.
filter_file
run
This method runs filter_file and then "translate_file".
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 perlpod, perlpodspec and podlators.
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.
This module is developed on GitHub at http://github.com/bigpresh/Pod-Readme
Copyright (c) 2005-2014 Robert Rothenberg. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
1 POD Error
The following errors were encountered while parsing the POD:
Unknown directive: =head
To install Pod::Readme, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Pod::Readme
CPAN shell
perl -MCPAN -e shell install Pod::Readme
For more information on module installation, please visit the detailed CPAN module installation guide.