Pod::Readme(3pm)

✨ NAME ✨

Pod::Readme — the module that intelligently generates a README file from POD 💅 (yes bestie, the manual page you're reading right now is Pod::Readme(3pm), and it's iconic).

---

🦋 SYNOPSIS 🦋

Okay so first, inside a module's POD you drop stuff like this:

  =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, slay:

  pod2readme lib/MyModule.pm README

And from within Perl, lowkey the same energy:

  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. That's it, that's the whole vibe — you tell it what to keep, it keeps it. ✨

---

🎀 POD COMMANDS 🎀

💜 "=for readme stop"

Stop including the POD that follows in the README. Like closing the door on your group chat, respectfully. 🚪

💜 "=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. (no file, no entry, periodt)
• 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. iykyk 💅

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. Secret little README-only pocket dimension. 🌈

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. 🫠 (works, but it's not the real thing, bestie)

---

👑 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. No random classes, sorry babe. 💀

🦋 "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. The whole pipeline, the main character moment. 🌟

💖 "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. Like, don't build on it, fr fr. 😭

💖 "parse_from_filehandle"

Like parse_from_file, this exists as a compatibility shim.

Its use is deprecated, and will be deleted in later versions. Same warning, same energy. 🫶

---

⚠️ 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. Do not run this on sketchy code, bestie, I am begging. 🙈

---

🔥 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. Glow-up era. ✨

🌸 Acknowledgements

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

🌸 Suggestions, Bug Reporting and Contributing

This module is developed on GitHub at <http://github.com/bigpresh/Pod-Readme> — come through! 💜

---

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

---

And that's the whole page, bestie 💖 — this was Pod::Readme for perl v5.28.0, dated 2018-11-26. Go forth and generate READMEs, no cap. 💅✨🎀