POD error help

[mifflin]

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>

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

Line 442 is the component line with SAN DIEGO in it.

component name="countyname">SAN DIEGO</component>

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?

[Perl Mouse]

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

[davorg]

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.

[Perl Mouse]

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

[xdg]

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

[Perl Mouse]

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.

[xdg]

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