podweb - convert POD into HTML


  podweb [options] <file1 ... fileN>


podweb converts POD in a Perl file into HTML and saves the translated POD to an output file. The default translations will produce a nice, readable HTML version of the POD (by the author's aesthetics). Some or all of the translations can be modified to the user's tastes; see the MAPPINGS section for information about adjusting the translations.

podweb has a standard translation format, which is described in the TRANSLATIONS section below. These defaults can be modified by the user with command-line options and a map file.

After translating all the POD in a file, a boilerplate set of starting and ending HTML is added to the POD. Other than the title, which may be modified with the -title option, this is the same regardless of file.

After creating an HTML file with podweb, you would be well-advised to verify that the resulting file looks the way you want it to look. Aesthetics are a very personal thing, and you should ensure you like the result.

By default, the translated POD is written to a new file named by appending ".html" to the translated file's name. For example, running "podweb foo" will have the translated output written to foo.html. The output file must not exist and must be in a directory in which podweb can write. If the -stdout option is given, the translated POD will be written to standard output.

The POD parsing is performed by the Pod::Parser(3pm) module.

There are other POD/HTML converters, such as pod2html. None met my needs or formatting preferences, so podweb came to be.


There are two types of pod commands that are translated. The =commands are those pod commands that start with an equals sign. The pod-character commands are those single-character commands that are surrounded by angle brackets. The default POD-to-HTML translations are provided int the DEFAULT MAPPINGS section.

The =commands are translated in this way:

    =pod      nothing

    =cut      nothing

    =head1    adds a <h3> header section

    =head2    adds a <h4> header section

    =head3    adds a <h5> header section

    =head4    adds a <h5> header section

    =over     starts an itemized list with a <ul> tag

    =back     closes an itemized list with a </ul> tag

    =item     adds a list entry with a <li> tag

The pod-character commands are translated in this manner:

    B<text>    bolds the enclosed text

    C<code>    puts the enclosed code in double quotes

    E<esc>     four escape values are defined
               E<lt>         <
               E<gt>         >
               E<sol>        /
               E<verbar>     |

    F<file>    underlines the enclosed filename

    I<text>    italicizes the enclosed text

    L<link>    puts the enclosed text in an <a> tag

    S<text>    does nothing to the enclosed text

    X<idx>     enclosed the text in comments

    Z<>        enclosed the text in comments


The mappings used by podweb define how various POD commands and internal sequences are translated to HTML tags. Many HTML tags are used in pairs, one tag to initiate a format and another to terminate it. podweb mappings allow you to specify the set of initial tags and the set of terminal tags. Multiple HTML tags can be included in a mapping.

The basic format for a podweb mapping is:


The initial-tags portion of the mapping will be inserted before any relevant text; the terminal-tags portion will be inserted after the text. The two mapping parts are separated by a comma.

For example, this mapping can be used with the -head1 option to define how =head1 POD commands are translated:

    -head1 '<center><h2>,</h2></center>'

This particular mapping will translate =head1 commands to use the HTML h2 section header, and center the header line. The text from the =head1 command will be placed between the two parts of the mapping.

The quotes are not required for the mapping, but they are highly likely to be needed when specified on a command line.

Either the initial-tags or the terminal-tags part of the mapping may be left blank. This will cause podweb to use the default value for that mapping piece. If the one of these is given as a hyphen, then the nothing will be used for that part of the mapping at all.

These two mappings show how this may be used:

    -item '<li>,-' -over '<ol start=42>,'

The first mapping will not add a </li> tag at the end of the =item line. The second mapping will make =over lists be ordered lists starting with number 42.

The default mappings will be modified by the .podmwebrc file, a -mapfile option mapfile, and command-line options, in that order. The final set of mappings may get a little confusing when the defaults, map files, and command-line options are swirled together. The -table option will display the mappings that will be used, but it will not translate a file.


For the sake of convenience, a map file may be set up to hold frequently used mappings. If the .podwebrc file is in the user's home directory, mappings will be read from that file. The -mapfile option may be used to specify an alternate map file.

Map files consist of a set of lines that correspond to the podweb command line options. However, the initial dash needed by options is not used with map file entries.

Comments are started with a pound sign ('#') and are ignored by podweb. The pound sign should not be used in mappings. Blank lines are also ignored.

The following is an example of a map file:

    title       big hunk of docs
    item        <li>,-
    over        <ol start=42>,
    back        </ol>,


The following are the default mappings for most POD commands:

    POD        HTML opening tag              HTML closing tag
    pod        (nothing)                     (nothing)
    cut        (nothing)                     (nothing)
    head1      <h3>                          </h3>     
    head2      <h4>                          </h4>     
    head3      <h5>                          </h5>     
    head4      <h5>                          </h5>     
    over       <ul>                          (nothing)
    back       </ul>                         (nothing)
    item       <li>                          </li>     
    B          <b>                           </b>      
    C          "                             "         
    F          <u>                           </u>      
    L          <a href={link}>{link}</a>     (nothing)
    I          <i>                           </i>      
    S          <i>                           </i>      
    X          <!--                          -->      
    Z          <!---                         --->     

When the S<> command is given, enclosed blanks are replaced with HTML's &nbsp; tag for non-breaking spaces.

When POD escape commands are given, the actual character is inserted in place of the escape command. The following POD escape commands are recognized:

    POD           Replacement Character
    E<lt>         <
    E<gt>         >
    E<sol>        /
    E<verbar>     |
The following are default values for options that do not have a direct HTML analog:

    headmatch:      off
    nodefaults:     off
    noheader:       off
    notrailer:      off
    openli flag:    off
    title string:   INSERT TITLE LINE


podweb takes the several types of options. The mapping options modify either POD commands or POD internal sequences, and are described in their own sections. There is a small set of options that affect translations, and these are described in the "General Mapping Options" section. A final set of options are described in the "Miscellaneous Options" section.

General Mapping Options

Command Mapping Options

Interior Sequence Mapping Options

Miscellaneous Options


podweb has the following limitations:

    - The =begin, =for, and =end commands are not handled.

    - The L<link> format cannot be changed without editting podweb.

    - The S<text> format cannot be changed without editting podweb.

It is hoped that these limitations will be fixed eventually.


Wayne Morrison,


Copyright 2013 Wayne Morrison

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.


perlpod(1), pod2html(1)