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