Module...romPod(3pm)

💖 Module::Install::ReadmeFromPod — bestie edition 💖

okay so this is Module...romPod(3pm) from the User Contributed Perl Documentation, and it's genuinely one of the most "wait that's so smart" little extensions out there. it's a Module::Install extension that auto-converts your POD into a README, so you never have to hand-write that thing again. no cap.

---

✨ NAME ✨

Module::Install::ReadmeFromPod — a Module::Install extension that automatically converts POD to a README 🎀

---

🌸 SYNOPSIS 🌸

# In Makefile.PL

use inc::Module::Install;
author 'Vestan Pants';
license 'perl';
readme_from 'lib/Some/Module.pm';
readme_from 'lib/Some/Module.pm', { clean => 1, format => 'htm', output_file => 'SomeModule.html' };

so like. a README file will be generated from the POD of the module file you point at. that's the whole vibe. 💅

heads up bestie: the author needs to make sure Module::Install::ReadmeFromPod is installed before running the Makefile.PL. (the extension gets bundled into the user-side distribution, so your users are fine — it's just you who needs it.) 🫶

---

🦋 DESCRIPTION 🦋

Module::Install::ReadmeFromPod is a Module::Install extension that generates a README file automatically from an indicated file containing POD, whenever the author runs Makefile.PL. it's giving ✨automation✨.

several output formats are supported: plain-text, HTML, PDF or manpage. pick your fighter. 👑

---

💅 COMMANDS 💅

this plugin adds the following Module::Install command:

• readme_from — does literally nothing on the user-side. on the author-side it will generate a README file.

readme_from 'lib/Some/Module.pm';

if a second parameter is set to a true value, then the README will be removed at make distclean.

readme_from 'lib/Some/Module.pm', 1;

a third parameter can be used to determine the format of the README file.

readme_from 'lib/Some/Module.pm', 1, 'htm';

valid formats for this third parameter are:

• txt, text — produce a plain-text README file using Pod::Text. the 'txt' format is the default. (default behaviour, we love her for that 💖)
• htm, html — produce an HTML README.htm file using Pod::Html.
• man — produce a README.1 manpage using Pod::Man.
• md — produce a README.md file using Pod::Markdown.
• pdf — produce a PDF README.pdf file with App::pod2pdf if this module is installed.

a fourth parameter can be used to supply an output filename.

readme_from 'lib/Some/Module.pm', 0, 'pdf', 'SomeModule.pdf';

finally, you can pass additional arguments to the POD formatter that handles the requested format.

my @options = ( 'release' => 1.03, 'section' => 8 ); # options for Pod::Man
readme_from 'lib/Some/Module.pm', 1, 'man', undef, @options;

but instead of passing this long list of optional arguments to readme_from, you should probably pass these arguments as a named hashref for clarity. (fr fr, your future self will thank you 🙈)

my @options = ( 'release' => 1.03, 'section' => 8 );
readme_from 'lib/Some/Module.pm', {clean => 1, format => 'man', output_file => undef, options => @options};

if you use the all_from command, readme_from will default to that value. iconic behaviour honestly.

all_from 'lib/Some/Module.pm';
readme_from;              # Create README from lib/Some/Module.pm
readme_from '','clean';   # Put a empty string before 'clean'

---

👑 AUTHOR 👑

Chris "BinGOs" Williams — absolute legend, ate and left no crumbs. 🍓

---

🌈 LICENSE 🌈

Copyright © Chris Williams

this module may be used, modified, and distributed under the same terms as Perl itself. please see the license that came with your Perl distribution for details. 🎀

---

💜 SEE ALSO 💜

• Module::Install
• Pod::Text
• Pod::Html
• Pod::Man
• Pod::Markdown
• App::pod2pdf

---

and that's the whole page bestie!! this one shipped as part of perl v5.36.0, dated 2022-12-06, in the User Contributed Perl Documentation, filed under Module...romPod(3pm). go generate that README, you main character. 💖✨🦋