---
name: "Pod::Readme"
section: "3pm"
platform: "linux"
package: "libpod-readme-perl"
version: "1.2.3-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Pod::Readme"
---

# Pod::Readme(3pm)

Intelligently generate a README file from POD

## 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\>

## 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.