POD File Format (.pod)

A POD file holds Perl documentation written in Plain Old Documentation, the lightweight markup Perl scripts and modules embed directly in their source so perldoc, pod2man and pod2html can render it separately from the code.

.podDocuments

POD at a glance#

Full name	Perl Plain Old Documentation
File extension	.pod
Category	Documents
Compression	Uncompressed
Specification	perlpodspec
FileFlip support	FileFlip reads this format but does not write it

What a .pod file can hold#

These are the things a POD file either supports or does not, and they are what decides whether a conversion keeps everything or quietly drops something.

Selectable text	Yes
Human readable	Yes

Strengths and limitations of POD#

What POD does well

Lives inline in .pm and .pl source files, so documentation ships in the same file as the code it describes and rarely drifts out of sync
A handful of commands, =head1, =item, =cut, with no nesting, so it's fast to write and fast to read as raw text
Every Perl install already carries perldoc, pod2man and pod2text, so no extra tooling is needed to render it

Where POD falls short

Inline formatting is limited to B<>, I<>, C<>, L<> and a few other codes, nowhere near the layout options of Markdown tables or HTML
The =cut, =pod and =end markers make a POD block fussy to move around without breaking the Perl parser it's embedded in
Almost no tooling outside the Perl ecosystem reads it directly

Write documentation as POD when it's embedded inside a Perl module or script that ships to CPAN.

Convert POD to Markdown or HTML once its documentation needs to be read outside Perl's own toolchain, such as on a project website.

How to open a .pod file#

A .pod file opens in the programs below, grouped by the platform you are on. If you would rather not install anything, FileFlip converts POD into a format your machine already opens, and it does it in the browser tab rather than on a server.

Platform	Programs that open it
Windows	perldoc (via Strawberry Perl), Notepad++
macOS	perldoc, Vim
Linux	perldoc, Vim, Emacs
Web	FileFlip

POD questions people ask#

What is a .pod file?

A .pod file holds standalone Perl documentation written in POD, the same markup Perl modules embed inline in their .pm source. A standalone .pod file is normal for tutorials and overview documents that aren't attached to one specific piece of code.

How do I read a POD file?

Running `perldoc file.pod` renders a POD file the way Perl's own module documentation appears, formatted and paged like a man page. Opened in a plain text editor, a POD file is still readable, since its markup is designed to make sense unformatted.

What's the difference between POD and Markdown?

POD is Perl's own documentation markup, built around a small set of command paragraphs (=head1, =item) and inline codes (B<>, C<>) with no nesting. Markdown is a general-purpose format with a larger feature set, which is why POD is usually converted to Markdown rather than the other way around when documentation needs to leave the Perl ecosystem.

Converting POD files#

FileFlip does not write .pod files, so nothing on the site converts into this format. It works as a source only.

Every conversion runs inside your browser. The file is read from your disk, the work happens on your own machine, and nothing is uploaded. How FileFlip works names the engine behind each family and how to verify that for yourself.