Shawn H Corey <[email protected]> writes: > How come I get this error?
> POD ERRORS > Hey! The above document had some coding errors, which are explained > below: > Around line 29: > You have '=item 1' instead of the expected '=item 2' > Every other formatter automatically renumbers lists so you don't have > to. Why doesn't POD do the same? I can see two different ways of handling this: 1. If the =item tags are numeric, ignore the value of the numbers and just renumber them. This is similar to what other markup languages do, but it has the significant problem of making it a bit more annoying to document, say, a list of exit status returns, where several numbers are skipped. 2. Use the =item text verbatim. Indicate whether it looks like a numeric list so that formatters can use the right tags for that, but always preserve the item text in case you're wrong (and require formatters to do the same). The current behavior seems like the worst of both worlds to me. It doesn't do the first, but if one instead wants the semantics of the second option, you get an ugly POD error in the document. (I haven't checked whether it has additional heuristics, like only triggering this if the first item is 1.) I would lean towards option two, personally. I think it's rather common to document things in POD that look like numeric lists but are actually exit statuses or response codes or something else that's numeric but not necessarily in order. It's also nice to be able to maintain the same item numbering across headers or intervening text, which you can't do if POD insists on ordering each list from 1. It feels like making people number their own lists properly is a small price to pay. In retrospect, it would have been nice to have different =item commands for numeric and bulleted lists, but, well, POD always made tradeoff decisions in favor of reducing the size of the language. -- Russ Allbery ([email protected]) <http://www.eyrie.org/~eagle/>
