如何阻止 pod2html 将“=head2 open() foo”视为函数定义？答案

【问题标题】：How do I stop pod2html from treating "=head2 open() foo" as a function definition?如何阻止 pod2html 将“=head2 open() foo”视为函数定义？
【发布时间】：2009-04-04 20:20:50
【问题描述】：

我有一些 POD，看起来像

=head2 C<close() on unopened filehandle %s>

=over

=item C<Yer tryna close() %s what ain't been opened yet>

=back

pod2html 命令把它变成

<h2><a name="close____on_unopened_filehandle__s"><a href="#item_close"><code>close () on unopened filehandle %s</code></a></a></h2>
<dl>
<dt><strong><a name="item_close"><code>Yer tryna close() %s what ain't been opened yet</code></a></strong>

</dl>

问题是<a href="#item_close"></a>。我假设这样做是有帮助的（在=item func() 是函数定义的开头的常见情况下），但在我的情况下它是不合适的（这是一条警告消息）。

我已经尝试（没有成功）以下方法使 pod2html 看不到 =item open() 作为函数定义：

=head2 C<closeZ<>() on unopened filehandle %s>

=head2 C<closeE<40>) on unopened filehandle %s>

=head2 C<closeE<0x28>) on unopened filehandle %s>

最后两个不打印“（”。我是否错误地使用了 E？这是 pod2html 中的错误（我在 OS X 上使用 Perl 5.8.8）吗？

基于一个想法布莱恩的回答引发了我尝试另一个实验：

=head2 C<closeE<60>) on unopened filehandle %s>

这应该产生<code>close<) on unopened filehandle %s</code>，但它却产生了<code>close) on unopened filehandle %s</code>。所以看起来pod2html 不喜欢数字实体。

【问题讨论】：

标签： perl perl-pod

【解决方案1】：

您使用的是哪个版本的 pod2html 和 Pod::Html（或您的 pod2html 加载的任何内容）？我在我的 Mac 上使用的是 Pod::Html 1.0504，并且总是会尝试在它在 =item 中看到的文本的第一个实例上创建链接。请记住，您始终可以查看源代码以了解它为什么会这样做:)

而且，我会避免在标题中使用 C。让处理器弄清楚如何显示这些。

如果你想要嵌套的内部序列，你可以添加更多的尖括号以便于识别：

C<< closeE<40> >>

尽管如此，我还是建议您使用 perldiag 格式，它不会对项目中的 open paren 做任何特别的事情。如果您不喜欢现有的 pod2html，请自己编写；使用 Pod::Simple 真的很容易。

【讨论】：

使用 C> 没有帮助，它仍然说：“close)”，即使它是“C<opene>)>"</opene>
我有 Pod::Html 版本 1.0504 和 pod2html 似乎只是 perl -MPod::Html -e 'pod2html @ARGV' 开头附加了一些 POD。
不，C> 与您的问题无关。这只是关于嵌套 Pod 指令的一般说明。

【解决方案2】：

看起来 Pod::Html 不喜欢 C<> 内的数字实体，即使 perldoc 对它们没有问题。如果我关闭C<>

=head2 closeE<40>) on unopened filehandle %s

它工作得很好（并防止pod2html 创建虚假链接）。所以答案似乎是不要在这里使用C<>。

【讨论】：

好吧，=head 处理与=item 处理不同。 :)