POD2USAGE(1perl)

📦
version 5.44.0 · 2 versions
, in arch rolling

💖 POD2USAGE 💖

okay bestie, so you know how every good little script needs to tell people how to use it? this is the icon that does exactly that 💅

pod2usage — prints usage messages straight out of the embedded pod docs chillin' inside your files. no cap, it's giving ✨documentation✨ but make it a usage message.

It's part of the Perl Programmers Reference Guide, so you know it's legit.

✨ SYNOPSIS ✨

pod2usage   [-help] [-man] [-exit exitval] [-output outfile] [-verbose
            level] [-pathlist dirlist] [-formatter module] [-utf8] file

she's short, she's sweet, she's fully loaded 🎀

🦋 OPTIONS AND ARGUMENTS 🦋

every flag, every argument, no gatekeeping 🫶

  • -help — prints a lil brief help message and then dips (exits, bestie).
  • -man — prints this command's manual page and then exits. very meta of her, obsessed. 👑
  • -exit exitval — the exit status value she hands back when she's done. pick your number, she'll take it.
  • -output outfile — where the output goes. it's the output file to print to. and listen, there are some special names with ✨main character energy✨:
    • - or >&1 or >&STDOUT → standard output is used 💫
    • >&2 or >&STDERR → standard error is used 😈
  • -verbose level — how much tea she spills. the desired level of verbosity to use:
    • 1 : print SYNOPSIS only
    • 2 : print SYNOPSIS sections and any OPTIONS/ARGUMENTS sections
    • 3 : print the entire manpage (similar to running pod2text)
  • -pathlist dirlist — tells her one or more directories to go searching through for the input file, in case you didn't hand over an absolute path (rude of you honestly, but okay 🙈). every directory path in the list needs to be separated by a ':' on Unix, and by a ';' on MSWin32 and DOS. slay, cross-platform queen.
  • -formatter module — which text formatter to use. default is Pod::Text. an alternative would be, like, Pod::Text::Termcap or whatever your heart desires 💜
  • -utf8 — this option assumes the formatter (see above, bestie, keep up) understands the option "utf8". it turns on generation of utf8 output. cute accents, no problem 🌸
  • file — the pathname of a file containing pod documentation that's gonna be output in usage message format. and here's the tea: if you omit it, standard input gets read — but the output is then formatted with Pod::Text only — unless you specifically named a formatter with -formatter. iykyk.

🌈 DESCRIPTION 🌈

pod2usage will read the input file you gave her, hunting for pod documentation, and will print the corresponding usage message. if no input file is specified, then standard input is read. simple as that, periodt. 💅

under the hood, pod2usage invokes the pod2usage() function in the Pod::Usage module. please see "pod2usage()" in Pod::Usage for the deets. 🧚

🎀 SEE ALSO 🎀

the whole friend group fr fr 💖
  • Pod::Usage
  • pod2text
  • Pod::Text
  • Pod::Text::Termcap
  • perldoc

🌟 AUTHOR 🌟

bugs?? please report them using <http://rt.cpan.org>. she wants to hear from you 🫶

Brad Appleton <bradapp@enteract.com> 👑

based on code for pod2text(1) written by Tom Christiansen <tchrist@mox.perl.com> ⭐

and that's the whole vibe bestie! this page is from perl v5.44.0, dated 2026-10-17, and it's the POD2USAGE(1perl) manual. go forth and print beautiful usage messages 💖✨🎀🦋🌸💅

📦 where this page comes from