POD2README(1p)

💖 POD2README — bestie edition 💖

okay so. you've got a .pm file with a bunch of POD in it and you want a README out of it? pod2readme literally does that for you. it's a lil Perl utility, it's intelligently generating a README from POD, no cap. 💅

---

🌸 USAGE 🌸

    pod2readme [-cfho] [long options...] input-file [output-file] [target]

        Intelligently generate a README file from POD

        -t --target     target type (default: 'readme')
        -f --format     output format (default: 'text')
        -b --backup     backup output file
        -o --output     output filename (default based on target)
        -c --stdout     output to stdout (console)
        -F --force      only update if files are changed
        -h --help       print usage and exit

like. that's the whole vibe. input file goes in, README comes out. ✨

---

🦋 SYNOPSIS 🦋

    pod2readme -f markdown lib/MyApp.pm

that's it, that's the girl. markdown README from your module. periodt. 🎀

---

💜 DESCRIPTION 💜

so what's actually happening here? this utility uses Pod::Readme to pull a README file out of a POD document. the way that it does this is very cute:

1. it extracts and filters the POD 🧚
2. then it calls the appropriate filter program to convert that POD into another format 🌈

that's the whole pipeline, bestie. extract → filter → convert → slay. 🔥

---

👑 OPTIONS 👑

✨ --backup

by default, pod2readme will back up the output file. safety first, always. 💖

but if you don't want that? use the --no-backup option. your file, your rules.

✨ --output

this one specifies the name of the output file. if you omit it, it'll use the second command line argument instead — or it defaults to the --target plus the corresponding extension of the --format.

for all intents, the default is README. 👑

and if you pick a format other than text, the appropriate extension gets added, e.g. for markdown, the default output file is README.md. see? smart girl behaviour.

✨ --target

the target of the filter. defaults to readme. that's it, that's the whole option. 💅

✨ --format

the output format, which defaults to text.

other supposed formats are github, html, latex, man, markdown, pod, rtf, and xhtml. you can also use gfm instead of github. similary you can use md for markdown. (yes, "similary" — we keep the lore exact, okay? 😭)

so many options and every single one of them ate. 💖

✨ --stdout

if enabled, it will output to the console instead of to --output. for when you just wanna see it first, yk? 🫶

✨ --force

by default, the README will be generated if the source files have been changed. using --force will force the file to be updated. no thoughts, just update. 🔥

⚠️ note: POD format files will always be updated. always. no exceptions, bestie, that's just how it is.

✨ --help

prints the usage and exits. the classic. 🌸

---

🌈 SEE ALSO 🌈

• pod2text
• pod2markdown

go check those out too, they're in the same friend group. 💜

---

and that's the whole manpage, bestie!! this one's from perl v5.28.0, dated 2018-11-26 — iconic behaviour honestly, still serving after all these years. 💖✨🎀 bye luv u 🫶