[perl #82226] Three issues in pod2html

# New Ticket Created by  John Davies 
# Please include the string:  [perl #82226]
# in the subject line of all future correspondence about this issue. 
# <URL: http://rt.perl.org/rt3/Ticket/Display.html?id=82226 >


First, a rant. perlbug asks me lots of questions I have no idea about 
and then goes into an infinite loop:

Can't spawn "cmd.exe": No such file or directory at 
F:\Perl\bin/perlbug.bat line
  766, <> line 13.
It then tells me to hit Enter, and when I do I get the same message 
until I disobey and hit {Ctrl Break}.

The documentation is incomprehensible. Example 1:

A bug report which includes a patch to fix it will almost definitely be 
fixed. When sending a patch, please use the diff program with the -u 
option to generate "unified" diff files.

F:\BugZilla>diff -u
'diff' is not recognized as an internal or external command,
operable program or batch file.

Example 2:
Make sure your patch really does work (make test , if the thing you're 
patching is covered by Perl's test suite).

How am I supposed to know the answer to this? Even if I did ...

F:\BugZilla>make test
'make' is not recognized as an internal or external command,
operable program or batch file.

So I can't even find out how to do the things the documentation says you 
want.

There are many more examples. I suspect that the belief is that everyone 
uses Linux. Unfortunately, some of us get paid to use losedows and would 
like to use it as sanely as possible. Almost everything in Perl, and 
especially everything to do with perlbug, seems designed to maximise the 
difficulty of moving towards Linux from losedows. Linux is like sex. I'm 
sure it would be wonderful if only I could do it properly.

End of rant.

Please do not put my email address anywhere where it may be harvested by 
spammers. It will be permanently disabled after the first spam and all 
subsequent emails to it will be destroyed silently.

Issue 1: pod2html adds code tags where other translators do not. I know 
it adds code tags I do not want. I have been told about the other 
translators in the following thread, which describes the problem and my 
workaround:
http://www.perlmonks.org/index.pl?node_id=881687

POD:
=head4 Function Assert  AssertFailure

AssertFailure(Optional msg As String = "") As Boolean

Returns True if an error occurs.

This is the converse of AssertSuccess.


=head4 Function Assert  BackupTRM

BackupTRM() As Boolean

Returns True if an error occurs.

HTML:
<h4><a name="function_assert_assertfailure">Function Assert 
AssertFailure</a></
h4>
<p>AssertFailure(Optional msg As String = &quot;&quot;) As Boolean</p>
<p>Returns True if an error occurs.</p>
<p>This is the converse of AssertSuccess.</p>
<p>
</p>
<h4><a name="function_assert_backuptrm">Function Assert  BackupTRM</a></h4>
<p><code>BackupTRM()</code> As Boolean</p>
<p>Returns True if an error occurs.</p>

Note the code tags around BackupTRM(). As far as I can tell from reading 
the code (and my Perl is pretty poor), this is intended behaviour. But 
there's no mention of it that I can find in the documentation, and no 
way to turn it off. If perlbug (the .bat or the documentation) worked, I 
would try to patch this by passing a command line parameter into 
$notinIS, but I can't see any point in trying this given my problems 
described in my rant.

Issue 2:
POD (snipped for brevity):
=head1 Introduction

=head2 Change Log

=head3 Changes from version r13

=over

=item * Fixed issue 2 
(L<http://code.google.com/p/excelvbaunit/issues/detail?id=2>)
to allow test modules with no tests. This is important because users may 
already have
modules called *Tester to test for other things. These would 
automatically be treated by
xRun as modules expected to contain tests. It also allows projects 
without test modules.

=item * Fixed issue 1 
(L<http://code.google.com/p/excelvbaunit/issues/detail?id=1>). This
now produces a messagebox if the project can't be found.

=back

Both links appear as
http://code.google.com/p/excelvbaunit/issues/detail
, i.e. with the "?id=n" part stripped. This is undocumented and awkward, 
given the difficulty of using external links.

Issue 3:
POD
=head3 foo bar

=head3
foo bar

=head3 foo
bar

The first two work perfectly. The last produces a header in the body of 
"foo bar" but an entry in the index of "foo". This hyperlink doesn't 
work - understandably, as there is no header "foo" for it to find.

I was advised to report this in
http://www.perlmonks.org/index.pl?node_id=803236
, but fell foul of perlbug and was too busy to fight it.

Sorry about the rant, but when I wanted to report a bug to BugZilla, it 
took seconds to work out how. I've spent about a day in total on perlbug 
and still can't use it. I hope that this email tells you all you need to 
know. If not, I will gladly try to help. I can also be /msg'ed at 
PerlMonks, where I am davies.

Regards,

John Davies

• [perl #82226] Three issues in pod2html by John Davies