podweb [options] <file1 ... fileN>
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.
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> tagThe 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 basic format for a podweb mapping is:
initial-tags,terminal-tagsThe 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.
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:
headmatch
openli
title big hunk of docs
item <li>,-
over <ol start=42>,
back </ol>,
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 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
- 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.
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
http://www.apache.org/licenses/LICENSE-2.0
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.
Pod::Parser(3pm)