From 10e3f0397ea30cd4051d6f2e49bee8e03f1cd7eb Mon Sep 17 00:00:00 2001 From: Marc Green Date: Mon, 15 Aug 2011 21:07:37 -0400 Subject: [PATCH] Update Pod::Checker documentation --- cpan/Pod-Parser/lib/Pod/Checker.pm | 91 ++++++++++++++++++++++-------- cpan/Pod-Parser/pc-errors-todo | 5 -- 2 files changed, 68 insertions(+), 28 deletions(-) diff --git a/cpan/Pod-Parser/lib/Pod/Checker.pm b/cpan/Pod-Parser/lib/Pod/Checker.pm index 82c73bd386..7784ff6819 100644 --- a/cpan/Pod-Parser/lib/Pod/Checker.pm +++ b/cpan/Pod-Parser/lib/Pod/Checker.pm @@ -116,30 +116,54 @@ heading! =item * =over on line I without closing =back +=item * You forgot a '=back' before '=headI' + +=item * =over is the last thing in the document?! + The C<=over> command does not have a corresponding C<=back> before the next heading (C<=head1> or C<=head2>) or the end of the file. -=item * =item without previous =over +=item * '=item' outside of any '=over' -=item * =back without previous =over +=item * =back without =over An C<=item> or C<=back> command has been found outside a C<=over>/C<=back> block. +=item * Can't have a 0 in =over I + +You need to indent a strictly positive number of spaces, not 0. + +=item * =over should be: '=over' or '=over positive_number' + +Either have an argumentless =over, or have its argument a strictly positive number. + =item * =begin I without matching =end I A C<=begin> command was found that has no matching =end command. -=item * No argument for =begin +=item * =begin without a target? A C<=begin> command was found that is not followed by the formatter specification. -=item * =end without =begin +=item * =end I without matching =begin. A standalone C<=end> command was found. -=item * =for without formatter specification +=item * '=end' without a target? + +'=end' directives need to have a target, just like =begin directives. + +=item * '=end I' is invalid. + +I needs to be one word + +=item * =end I doesn't match =begin. + +I needs to match =begin's target + +=item * =for without a target? There is no specification of the formatter after the C<=for> command. @@ -162,29 +186,28 @@ CE>, CE>, CE>, CE>, CE>, CE>, CE>, CE>, CE> +=item * Unterminated IEE sequence + +An unclosed formatting code + =item * nested commands IE...IE...E...E Two nested identical markup commands have been found. Generally this does not make sense. -=item * garbled entity I +=item * An EE...E surrounding strange content The I found cannot be interpreted as a character entity. -=item * Entity number out of range - -An entity specified by number (dec, hex, oct) is out of range (1-255). +=item * An empty L<> -=item * malformed link LEE +There needs to be content inside an L<> formatting code. -The link found cannot be parsed because it does not conform to the -syntax described in L. - -=item * nonempty ZEE +=item * A non-empty ZEE The CE> sequence is supposed to be empty. -=item * empty XEE +=item * An empty XEE The index entry specified contains nothing but whitespace. @@ -192,10 +215,22 @@ The index entry specified contains nothing but whitespace. The commands C<=pod> and C<=cut> do not take any arguments. -=item * Spurious character(s) after =back +=item * =back doesn't take any parameters, but you said =back I The C<=back> command does not take any arguments. +=item * =pod directives shouldn't be over one line long! Ignoring all I lines of content + +Self explanatory + +=item * =cut found outside a pod block. + +A '=cut' directive found in the middle of non-POD + +=item * Invalid =encoding syntax: I + +Syntax error in =encoding directive + =back =head2 Warnings @@ -216,23 +251,31 @@ There is some whitespace on a seemingly empty line. POD is very sensitive to such things, so this is flagged. B users switch on the B option to avoid this problem. -=item * previous =item has no contents +=item * =item has no contents -There is a list C<=item> right above the flagged line that has no -text contents. You probably want to delete empty items. +There is a list C<=item> that has no text contents. You probably want to delete +empty items. -=item * preceding non-item paragraph(s) +=item * You can't have =items (as at line I) unless the first thing after the =over is an =item A list introduced by C<=over> starts with a text or verbatim paragraph, but continues with C<=item>s. Move the non-item paragraph out of the C<=over>/C<=back> block. -=item * =item type mismatch (I vs. I) +=item * Expected '=item I' + +=item * Expected '=item *' A list started with e.g. a bullet-like C<=item> and continued with a numbered one. This is obviously inconsistent. For most translators the type of the I C<=item> determines the type of the list. +=item * You have '=item x' instead of the expected '=item I' + +Erroneous numbering of =item numbers + +XXX make the above a warning not an error in whine() + =item * I unescaped CE> in paragraph Angle brackets not written as CltE> and CgtE> @@ -240,10 +283,12 @@ can potentially cause errors as they could be misinterpreted as markup commands. This is only printed when the -warnings level is greater than 1. -=item * Unknown entity +=item * Unknown E content in EEIE A character entity was found that does not belong to the standard -ISO set or the POD specials C and C. +ISO set or the POD specials C and C. I =item * empty =over/=back block diff --git a/cpan/Pod-Parser/pc-errors-todo b/cpan/Pod-Parser/pc-errors-todo index f67c8ec27e..224db82e36 100644 --- a/cpan/Pod-Parser/pc-errors-todo +++ b/cpan/Pod-Parser/pc-errors-todo @@ -33,11 +33,6 @@ This is most probably something you do not want. =over -=item * =over on line I without closing =back - -The C<=over> command does not have a corresponding C<=back> before the -next heading (C<=head1> or C<=head2>) or the end of the file. - =item * =item without previous =over =item * =back without previous =over