POD error help

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?

Comment on POD error help Select or Download Code

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]
Re^2: POD error help by Perl Mouse (Chaplain) on Nov 03, 2005 at 15:52 UTC
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]
Re^2: POD error help by Perl Mouse (Chaplain) on Nov 03, 2005 at 15:56 UTC
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]
Re^3: POD error help by xdg (Monsignor) on Nov 03, 2005 at 16:43 UTC
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]


Perl: the Markov chain saw
	PerlMonks