How to Open & Convert POD to PDF to Read Perl Documentation

Joel Lee 26-04-2016

Though it was once an integral language for web programming Which Programming Language to Learn - Web Programming Today we're going to take a look at the various web programming languages that power the Internet. This is the fourth part in a beginners programming series. In part 1, we learnt the basic of... Read More , Perl has now fallen by the wayside in favor of more modern languages like Python, Ruby, and JavaScript. Very few people think it’s worth the effort to learn Perl these days.


But that doesn’t mean the language is useless or obsolete. In fact, a lot of modern websites and web tools still rely on Perl for day-to-day operations — including Craigslist, IMDb, and DuckDuckGo — so if you’re interested in learning it, don’t let anyone stop you or dissuade you 7 Useful Tricks for Mastering a New Programming Language It's okay to be overwhelmed when you are learning to code. You'll probably forget things as quickly as you learn them. These tips can help you to better retain all that new information. Read More .

If you’re going to learn Perl, then you’ll also want to get acquainted with POD. Here’s what that is, why it’s important, and what to do when you run into such files.

What Are POD Files?

POD stands for Plain Old Documentation, which is a basic markup language that’s used to format text without much effort involved. It’s similar to the Markdown markup language What Is Markdown? 4 Reasons Why You Should Learn It Now Tired of HTML and WYSIWYG editors? Then Markdown is the answer for you no matter who you are. Read More , but specifically designed for documenting Perl source code and modules.

POD can be used in two ways: it can exist directly within the source code of a Perl file OR it can exist as a separate POD file. When it exists within the code, you can think of it like comments in any other programming language, except fancier and more flexible.


use strict;

use warnings;


=head1 Header Example

This script does some cool stuff, like this and that. The following parameters must exist for it to work properly. Do not try doing this on a machine with issues.


print “Only this code is executed. \n”;

Embedded documentation works well for standalone scripts or when you want to make sure that anyone who comes across the file also has guaranteed access to the documentation, but it can be cumbersome when you want to document an entire codebase at a higher level.


Fortunately, POD can also be used to create manual-type pages that are better suited for user-oriented documents (since users may not want to delve into the source code of a script itself). That’s when POD files come in handy.

How to Read POD Files

To be clear, embedded POD documentation is found within actual Perl script files in between lines of code, and these script files come in one of two extension formats: .PL or .PM. When you see a .POD extension, it indicates that the file is pure documentation and includes no source code.

While it’s possible to open POD files in any text editor including Notepad, you probably only want to do that if you’re actually editing the raw documentation itself. Think of it like opening an HTML file in an editor: with all of the markup, the actual text content is hard to read.



Instead, you should use some kind of reader tool that takes the raw POD documentation and presents it in an easy-to-read manner.

The easiest way is to use the perldoc command line tool which is automatically included when Perl is installed to your system. Most OS X and Linux systems come with Perl already installed, but Windows users will have to manually install it. (Fortunately, it’s no harder than running an installer file.)

Now launch the command line, navigate to where the POD file is located, and type perldoc [.POD file] to view it as properly formatted. For example, if the file was named library.pod then you’d type perldoc library.pod and that’s it.

How to Convert POD to Other Formats

Even though the perldoc tool isn’t too difficult to use, it’s not exactly convenient when you want to share the documentation with others or when you want to read it away from your computer. That’s when you may want to consider converting into another format.


Converting to HTML: Install and use the pod2html tool which provides an easy way to translate any POD file into a readable HTML file. Unfortunately, it can only perform a one-to-one conversion (so you can’t combine multiple POD files into a single HTML file).

Converting to PDF: Install and use the pod2pdf tool, which is similar to and just as easy to use as the pod2html tool above, except it converts into PDF rather than HTML.

Another option would be to convert POD to HTML using the method shown above, open the HTML file in a browser like Chrome or Firefox, and then print the page as PDF.



Converting to Markdown: Install and use the pod2markdown tool to translate between POD and Markdown. Markdown is a general purpose markup language, meaning users are more likely to be familiar with it and there are more tools out there that can accept and display Markdown.

Converting to LaTeX: Install and use the pod2latex tool. LaTeX is another markup language, one that’s less common than Markdown, but still more popular than POD. LaTeX is mainly used in academic and scientific documents, but in case you need it, this converter exists.

Converting to Plain Text: Install and use the pod2text tool, which produces a text-only file with ASCII-based formatting. You probably won’t need to use this, but in case you ever do, know that the option exists.

Was This Post Helpful?

Once you’ve got the hang of it, POD files are extremely simple and convenient to use. There is a bit of a learning curve, but it’s very minor — especially if you’ve used a markup language before. Hopefully you now feel comfortable dealing with POD files.

If you’re feeling overwhelmed, ask yourself these important questions for newbie coders 4 Questions to Ask Yourself Before Learning How to Code Learning a programming language is popular. But is it for everybody? Before you commit to it, do ask yourself the following questions and be honest. Read More . Having difficulty doesn’t necessarily mean that you aren’t meant to be a programmer 6 Signs That You Are Not Meant to Be a Programmer Not everyone is cut out to be a programmer. If you aren't completely sure that you're meant to be a programmer, here are some signs that may point you in the right direction. Read More , but it’s important to be honest with yourself and manage your expectations.

That being said, heed these tips for learning how to code without stress How to Learn Programming Without All the Stress Maybe you've decided to pursue programming, whether for a career or just as a hobby. Great! But maybe you're starting to feel overwhelmed. Not so great. Here's help to ease your journey. Read More and knowing how to tell good coding tutorials from bad What Makes a Good Programming Tutorial? Not all programming tutorials are made equal. Some benefit you and others end up wasting your time. Here's what to look for in a quality programming tutorial. Read More .

What are you using Perl for? Got any other tips to share or questions to ask? Let us know in the comments below!

Related topics: File Conversion, PDF, Programming.

Affiliate Disclosure: By buying the products we recommend, you help keep the site alive. Read more.

Whatsapp Pinterest

Leave a Reply

Your email address will not be published. Required fields are marked *