davies has asked for the wisdom of the Perl Monks concerning the following question:

I have cut down the POD to the following:

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

[download]
Running Pod2HTML gives (at the end after all headers and index information): 
<h4><a name="function_assert_assertfailure">Function Assert  AssertFai
+lure</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>

[download]

I cannot find any documentation indicating why BackupTRM() should be surrounded in code tags. Note that there is no space at the start of the line - if I put one in, the whole line is wrapped in "Pre" tags. The sequence C<> at the start of the line merely adds another pair of code tags. Nor is it anything to do with the word backup - prepending an "a" gets that inside the tags, too. However, putting the "a" in the brackets clears the problem, although it is something I want not to do. Does anyone know if this is intended behaviour (in which case, is it documented anywhere) or if there is a workaround?

Regards,

John Davies

Update: Putting a Z<> sequence in the brackets seems to work, but again it's something I'd prefer to avoid doing if there's anything better available.

Corrected over-enthusiastic insertion of paragraph tags that leaked into POD!

Replies are listed 'Best First'.
Re: Unexpected HTML from POD
by toolic (Bishop) on Jan 11, 2011 at 15:30 UTC
    I don't have the answer to your question, but I noticed that the "code" HTML tags disappear if you get rid of the empty parentheses in your POD: 
    BackupTRM As Boolean

    [download]
    Searching through the docs, here is the closest thing I see, from perlpodspec (emphasis mine):
    At time of writing, L<name> values are of two types: either the name of a Pod page like L<Foo::Bar> (which might be a real Perl module or program in an @INC / PATH directory, or a .pod file in those places); or the name of a Unix man page, like L<crontab(5)> . In theory, L<chmod> in ambiguous between a Pod page called "chmod", or the Unix man page "chmod" (in whatever man-section). However, the presence of a string in parens, as in "crontab(5)", is sufficient to signal that what is being discussed is not a Pod page, and so is presumably a Unix man page. The distinction is of no importance to many Pod processors, but some processors that render to hypertext formats may need to distinguish them in order to know how to render a given L<foo> code.
    Looking through the source code of Pod::Html, I see this comment: 
        # has parenthesis so should have been a C<> ref
    ## try for a pagename (perlXXX(1))?

    [download]
[reply]
[d/l]
[select]

      Thanks. It seems the behaviour is intended but undocumented! Just above the comments in the source code that you quoted is a regex test that is looking for certain specific things in brackets. One of the things it looks for - six lines above your comment - is nothing. So in the POD I am giving it, it sees a function name followed by nothing in brackets and that matches this regex. Therefore, like Bill Gates, it knows best. I can't see any options that refer to this and it seems that the only way to change the behaviour is to change the code. The smallest amount of work, since I want this to work on any machine, is to change my code. I have code that writes POD, and changing this to include s/()/(Z<>)/g is not too challenging. I think all I have to do is work out which of those characters need escaping.

      Regards,

      John Davies

[reply]
[d/l]
        > Thanks. It seems the behaviour is intended but undocumented!

        Hmm, will you send a bug report?

        Cheers Rolf

[reply]

Back to Seekers of Perl Wisdom