1

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.

Jonas
  • 121,568
  • 97
  • 310
  • 388
Chas. Owens
  • 64,182
  • 22
  • 135
  • 226

2 Answers2

0

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.

brian d foy
  • 129,424
  • 31
  • 207
  • 592
  • Using C<<>> doesn't help, it still says: "close)", The perldoc command does the right thing with it even when it is "C)>" – Chas. Owens Apr 04 '09 at 21:14
  • I have Pod::Html version 1.0504 and pod2html seems to just be perl -MPod::Html -e 'pod2html @ARGV' with some POD attached at the beginning. – Chas. Owens Apr 04 '09 at 21:21
  • No, the C<< >> isn't related to your question. It's just a general statement about nested Pod directives. – brian d foy Apr 04 '09 at 23:46
0

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.

Chas. Owens
  • 64,182
  • 22
  • 135
  • 226