Pod::Readme (3)

Leading comments

Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)

Standard preamble:
========================================================================

(The comments found at the beginning of the groff file "man3/Pod::Readme.3pm".)

NAME

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

SYNOPSIS

In a module's

  =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 to generate a file, by using commands to specify which parts are included or excluded from the file.

POD COMMANDS

=for readme stop

Stop including the that follows in the .

=for readme start

=for readme continue

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

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

file in the . 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 to include only in the .

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

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

ATTRIBUTES

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

translation_class

The class used to translate the filtered 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 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 file, which depends on the ``translation_class''.

translate_file

This method runs translates the resulting 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

has been processed, since plugins may add to the dependencies. A side-effect of this is that when generating a formatted 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 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

parser.

Acknowledgements

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

Suggestions, Bug Reporting and Contributing

This module is developed on GitHub at <github.com/bigpresh/Pod-Readme>

LICENSE

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.