How do I stop pod2html from treating "=head2 open() foo" as a function definition?

Question

I have some POD that looks like

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

=over

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

=back

The pod2html command turns it into

<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>

The problem is <a href="#item_close"></a>. I am assuming it is doing this to be helpful (in the common case where =item func() is the start of a function definition), but it is inappropriate in my case (it is a warning message).

I have tried (with no success) the following to make pod2html not see =item open() as a function definition:

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

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

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

The last two don't print "(". Am I using E<> incorrectly? Is this a bug in pod2html (I am using Perl 5.8.8 on OS X)?

Based on a thought brian's answer sparked I tried another experiment:

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

Which should have resulted in <code>close<) on unopened filehandle %s</code>, but it produced <code>close) on unopened filehandle %s</code> instead. So it looks like pod2html doesn't like numeric entities.

Answer 1

Which version of pod2html and Pod::Html (or whatever your pod2html loads) are you using? The one I have on my Mac is Pod::Html 1.0504 and will always try to make the link on the first instance of the text it sees in an =item. Remember, you can always look at the source to see why it's doing something :)

And, I'd avoid using C<> in headings. Let the processor figure out how to display those.

If you want nested interior sequences, you can add more angle brackets to make it easier to recognize:

C<< closeE<40> >>

Despite all of that, I recommend you use the format of perldiag, which doesn't do anything special with the open paren in an item. If you don't like the pod2html you have, write your own; it's really easy with Pod::Simple.

Answer 2

It looks like Pod::Html doesn't like numeric entities inside of C<> even though perldoc has no problem with them. If I take the C<> off

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

it works just fine (and prevents pod2html from creating the spurious link). So the answer seems to be to not use C<> here.