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

I'm getting a Pod error when I do a make.

Here is the error... 
erickn@cofjora01d:/home/erickn/ace_server/ACE/Find> make
Manifying blib/man3/ACE::Find.3
Find.pm:442: Unknown formatting code O</component>

[download]
here is a section around the pod error.. 
=over 4

<ace-find-response  xmlns="http://hdsupply.com/ace/find">
   <address style="discrete">
      <line name="address">6739 follette st</line>
      <line name="city">carlsbad</line>
      <line name="state">ca</line>
      <line name="zip">92011</line>
   </address>
   <components>
      <component name="zip4">1234</component>
      <component name="county">321</component>
      <component name="countyname">SAN DIEGO</component>
   </components>
   <status code="S90000">success</status>
</ace-find-response>

=back

[download]
Line 442 is the component line with SAN DIEGO in it. 
component name="countyname">SAN DIEGO</component>

[download]
I think I've run into some special POD encoding strings with my XML document example starting with the "0<".
How should I be formatting an XML document so I don't get this error?

Replies are listed 'Best First'.
Re: POD error help
by Perl Mouse (Chaplain) on Nov 03, 2005 at 15:41 UTC
    As it's an example, you probably want it to be unformatted - that is, you want the example in the final document to look the same as you wrote it, including line breaks and indentation.

    The simplest way to archieve this is by indenting the entire example - one space will be enough. In POD, an indented paragraph is left as is - no formatting, and no processing for tags is done.

    This will solve your problem.

    Otherwise, if you do want things to be formatted, replace the < following the capital letter by E<lt>.

    Perl --((8:>*
[reply]
[d/l]
Re: POD error help
by davorg (Chancellor) on Nov 03, 2005 at 15:42 UTC

    Your pod parser is assuming that O< is starting a formatting sequence (like I<...>). Really, all < signs in your pod should be encoded as E<lt>.

    Update: Yeah. This isn't really true. Well, the first part is. The second part is overkill. What Perl Mouse says below is much more accurate.

    --
    <http://dave.org.uk>

    "The first rule of Perl club is you do not talk about Perl club."
    -- Chip Salzenberg

[reply]
      Really, all < signs in your pod should be encoded as E<lt>.
      No, no, no! POD is not a "let's make the programmer jump through as many hoops as we can language". The following quote is from man perlpod:
      The Intent

      The intent is simplicity of use, not power of expression.

      Another quote, the first sentence of the description:
      Pod is a simple-to-use markup language used for writing documentation for Perl, Perl programs, and Perl modules.
      There is no need to encode every < as E<lt> - that would violate the first principle of POD - that writing documentation should be simple.

      All inline markup in POD consists of a single capital letter followed by one or more less then signs. Any other less then sign is not markup, and hence, does not need to be written as E<lt>.

      Perl --((8:>*
[reply]
[d/l]
[select]
Re: POD error help
by xdg (Monsignor) on Nov 03, 2005 at 15:43 UTC

    =over blocks don't turn off normal Pod processing. You should be escaping all your "<", ">", "/" and "|" as E<lt>, E<gt>, E<sol>, E<verbar>. Alternatively, you could indent that whole block with at least one space character and the block would render as preformatted (i.e. code) text as is. I suspect the latter is what you want. See perldoc for details.

    -xdg

    Code written by xdg and posted on PerlMonks is public domain. It is provided as is with no warranties, express or implied, of any kind. Posted code may not have been tested. Use of posted code is at your own risk.

[reply]
[d/l]
      You should be escaping all your "<", ">", "/" and "|" as E<lt>, E<gt>, E<sol>, E<verbar>.
      No, there's no need. Giving advice like that shows you don't understand the intend of POD. Go read the manual page. Pay attention to the first sentence of the description, and the paragraph "Intent".

      For further details, read my reply to davorg's post.

      Perl --((8:>*
[reply]

        Leaving aside whether I "understand the intent", I said should, not must The actual text from perlpod about the escape codes is this:

        The above four are optional except in other formatting codes, notably "L<...>", and when preceded by a capital letter.

        Notice that it doesn't say "the above four are unnecessary except in...". "Optional" can cut either way. I prefer advising general rules as opposed to the special cases because its easier to remember and follow. You prefer special cases because it's less to type and less hassle. That's cool -- no need to make it a religious war and get personal about it.

        As to intent, I personally think even Pod is not simple enough. See Pod::WikiDoc, which simplifies some things even more (though sadly at the cost of more complexity elsewhere).

        -xdg

        Code written by xdg and posted on PerlMonks is public domain. It is provided as is with no warranties, express or implied, of any kind. Posted code may not have been tested. Use of posted code is at your own risk.

[reply]

Back to Seekers of Perl Wisdom