Home/ Questions/Q 9242755
In Process

The Archive Base Latest Questions

Editorial Team
  • 0
Asked: 2026-06-18T08:38:59+00:00

When writing perlpod documentation that will be exported to HTML, can I embed the

  • 0

When writing perlpod documentation that will be exported to HTML, can I embed the title of the resulting HTML file in the POD directives?

I want to be able to convert multiple POD text files to HTML with the pod2html command, and don’t want to have to give the --title="My Title" parameter on the command-line.

For example, here is a text file with perlpod formatting:

=pod

=head1 This is a heading

This is some text. I'd like to set the title of this document in the resulting HTML file.

=cut

When I convert it to HTML, pod2html gives a warning about there being no title:

$ pod2html test.txt > test.html
/usr/bin/pod2html: no title for test.txt

In the resulting HTML file, the title is set to the filename (test.txt):

<?xml version="1.0" ?> 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>test.txt</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:root@localhost" />
</head>

<body style="background-color: white">

<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->

<ul>

        <li><a href="#this_is_a_heading_">This is a heading.</a></li>
</ul>
<!-- INDEX END -->

<hr />
<p>
</p>
<hr />
<h1><a name="this_is_a_heading_">This is a heading.</a></h1>
<p>This is some text. I'd like to set the title of this document.</p>

</body>

</html>

I’d like to find a way to have the title given in the perpod document, perhaps with a directive like this:

=title This is my custom title

In the Perl documentation, I see that the document titles are set nicely. Is this all done without having the document title in the pod document itself?

Share

Leave an answer

You must login to add an answer.

Need An Account,

1 Answer

  1. Editorial Team

    No.

    POD exists mainly¹ to write Perl module documentation², and therefore doesn’t have many fancy features. Also, the primary output medium for POD is the terminal, where no such thing as a title exists conceptially³. It is, after all, just Plain and Old documentation.

        1. Suprisingly many Perl books are written in POD.
        2. The location of the POD document coincides with the thing discussed in the text.
        3. The ps name / $0 variable comes close, but is useless here.

    This is also a technical problem: pod2html uses Pod::Html, which parses the command line, and wraps itself around Pod::Simple::XHTML or something, without doing, or interfering with, the actual parsing. However, it already supplies a header and a footer, which sensibly overrides any default headers that might be emitted.

    There are two interesting options how your problem can be solved:

    1. You write a postprocessor that puts the value of the first h1 into the title. This should be <10 lines in a parser with XPath-support. Then you write a little script that ties these together, and can be invoked instead of pod2html.

    2. You take the existing wealth of POD parsers (and source code), and whip up your own HTML from POD generator. If all you are actually doing is a small fork, you could try to offer the modification to the original module.

    • 0