我可以在 perlpod 文档中嵌入自定义标题吗？答案

【问题标题】：Can I embed a custom title in a perlpod document?我可以在 perlpod 文档中嵌入自定义标题吗？
【发布时间】：2013-01-16 00:17:27
【问题描述】：

在编写将导出为 HTML 的 perlpod 文档时，我可以在 POD 指令中嵌入生成的 HTML 文件的标题吗？

我希望能够使用 pod2html 命令将多个 POD 文本文件转换为 HTML，并且不想在命令行中提供 --title="My Title" 参数。

例如，这是一个带有 perlpod 格式的文本文件：

=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

当我将其转换为 HTML 时，pod2html 会发出关于没有标题的警告：

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

在生成的 HTML 文件中，标题设置为文件名 (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>

我想找到一种在 perpod 文档中给出标题的方法，可能使用如下指令：

=title This is my custom title

在 Perl 文档中，我看到文档标题设置得很好。这一切都是在 pod 文档本身没有文档标题的情况下完成的吗？

【问题讨论】：

标签： perl perl-pod

【解决方案1】：

没有。

POD 的存在主要是为了编写 Perl 模块文档²，因此没有很多花哨的功能。此外，POD 的主要输出媒介是终端，在概念上不存在标题之类的东西³。毕竟，它只是普通的和旧的文档。
1. 令人惊讶的是，许多 Perl 书籍都是用 POD 编写的。
2. POD文件的位置与文中讨论的内容一致。
3. ps 名称/$0 变量很接近，但在这里没用。

这也是一个技术问题：pod2html 使用 Pod::Html，它解析命令行，并将自己包裹在 Pod::Simple::XHTML 或其他东西上，而不做或干扰实际的解析。但是，它已经提供了一个页眉和一个页脚，这会明智地覆盖任何可能发出的默认页眉。

有两个有趣的选项可以解决您的问题：

您编写了一个后处理器，将第一个h1 的值放入title。在支持 XPath 的解析器中，这应该少于 10 行。然后你编写一个小脚本将它们联系在一起，并且可以被调用而不是pod2html。
您可以利用现有丰富的 POD 解析器（和源代码），从 POD 生成器中生成您自己的 HTML。如果您实际上所做的只是一个小分支，您可以尝试提供对原始模块的修改。

【讨论】：

【解决方案2】：

Pod 文档中没有任何内容可以控制文档的标题。这取决于将 Pod 文档转换为您想要的格式的程序。大多数用于生成文档的 pod2doc 程序都有一个类似Pod::Text 或Pod::Html 的模块。这些在转换中完成了大部分繁重的工作。

pod2html 采用--title 参数。但是，您想要的是 pod2html 无需指定即可执行此操作。你可以做的是滚动你自己的版本的pod2html。让我们看看pod2html 脚本本身，也许你可以弄清楚你可以做些什么来得到你想要的。

删除所有的POD文档，我看到了::

use Pod::Html
pod2html @ARGV

这就是整个程序。

看起来你可以制作一个pod2steve 程序来做你想做的事。您想要获取最后一个参数（我假设这是您想要的标题），并简单地将其传递给pod2html 子例程。你的 pod2steve 看起来像这样：

use strict;
use warnings;

use Pod::Html
my $program_name = $ARGV[$#ARGV];
pod2html --title=$program_name @ARGV

应该可以的。

【讨论】：