Pod::Checker(3perPerl Programmers Reference GuPod::Checker(r) NAME Pod::Checker, podchecker() - check pod documents for syn- tax errors SYNOPSIS use Pod::Checker; $syntax_okay = podchecker($filepath, $outputpath, %options); my $checker = new Pod::Checker %options; $checker->parse_from_file($filepath, \*STDERR); OPTIONS/ARGUMENTS $filepath is the input POD to read and $outputpath is where to write POD syntax error messages. Either argument may be a scalar indicating a file-path, or else a refer- ence to an open filehandle. If unspecified, the input- file it defaults to "\*STDIN", and the output-file defaults to "\*STDERR". podchecker() This function can take a hash of options: -warnings => val Turn warnings on/off. val is usually 1 for on, but higher values trigger additional warnings. See "Warn- ings". DESCRIPTION podchecker will perform syntax checking of Perl5 POD for- mat documentation. NOTE THAT THIS MODULE IS CURRENTLY IN THE BETA STAGE! It is hoped that curious/ambitious user will help flesh out and add the additional features they wish to see in Pod::Checker and podchecker and verify that the checks are consistent with perlpod. The following checks are currently preformed: o Unknown '=xxxx' commands, unknown 'X<...>' inte- rior-sequences, and unterminated interior sequences. o Check for proper balancing of "=begin" and "=end". The contents of such a block are generally ignored, i.e. no syntax checks are performed. o Check for proper nesting and balancing of "=over", "=item" and "=back". o Check for same nested interior-sequences (e.g. "L<...L<...>...>"). o Check for malformed or nonexisting entities "E<...>". o Check for correct syntax of hyperlinks "L<...>". See perlpod for details. o Check for unresolved document-internal links. This check may also reveal misspelled links that seem to be internal links but should be links to something else. DIAGNOSTICS Errors o empty =headn A heading ("=head1" or "=head2") without any text? That ain't no heading! o =over on line N without closing =back The "=over" command does not have a corresponding "=back" before the next heading ("=head1" or "=head2") or the end of the file. o =item without previous =over o =back without previous =over An "=item" or "=back" command has been found outside a "=over"/"=back" block. o No argument for =begin A "=begin" command was found that is not followed by the formatter specification. o =end without =begin A standalone "=end" command was found. o Nested =begin's There were at least two consecutive "=begin" commands without the corresponding "=end". Only one "=begin" may be active at a time. o =for without formatter specification There is no specification of the formatter after the "=for" command. o unresolved internal link NAME The given link to NAME does not have a matching node in the current POD. This also happend when a single word node name is not enclosed in "". o Unknown command "CMD" An invalid POD command has been found. Valid are "=head1", "=head2", "=over", "=item", "=back", "=begin", "=end", "=for", "=pod", "=cut" o Unknown interior-sequence "SEQ" An invalid markup command has been encountered. Valid are: "B<>", "C<>", "E<>", "F<>", "I<>", "L<>", "S<>", "X<>", "Z<>" o nested commands CMD<...CMD<...>...> Two nested identical markup commands have been found. Generally this does not make sense. o garbled entity STRING The STRING found cannot be interpreted as a character entity. o Entity number out of range An entity specified by number (dec, hex, oct) is out of range (1-255). o malformed link L<> The link found cannot be parsed because it does not conform to the syntax described in perlpod. o nonempty Z<> The "Z<>" sequence is supposed to be empty. o empty X<> The index entry specified contains nothing but whites- pace. o Spurious text after =pod / =cut The commands "=pod" and "=cut" do not take any argu- ments. o Spurious character(r) after =back The "=back" command does not take any arguments. Warnings These may not necessarily cause trouble, but indicate mediocre style. o multiple occurence of link target name The POD file has some "=item" and/or "=head" commands that have the same text. Potential hyperlinks to such a text cannot be unique then. o line containing nothing but whitespace in paragraph There is some whitespace on a seemingly empty line. POD is very sensitive to such things, so this is flagged. vi users switch on the list option to avoid this problem. o previous =item has no contents There is a list "=item" right above the flagged line that has no text contents. You probably want to delete empty items. o preceding non-item paragraph(h) A list introduced by "=over" starts with a text or verbatim paragraph, but continues with "=item"s. Move the non-item paragraph out of the "=over"/"=back" block. o =item type mismatch (one vs. two) A list started with e.g. a bulletted "=item" and con- tinued with a numbered one. This is obviously incon- sistent. For most translators the type of the first "=item" determines the type of the list. o N unescaped "<>" in paragraph Angle brackets not written as "<lt>" and "<gt>" can potentially cause errors as they could be misinter- preted as markup commands. This is only printed when the -warnings level is greater than 1. o Unknown entity A character entity was found that does not belong to the standard ISO set or the POD specials "verbar" and "sol". o No items in =over The list opened with "=over" does not contain any items. o No argument for =item "=item" without any parameters is deprecated. It should either be followed by "*" to indicate an unordered list, by a number (optionally followed by a dot) to indicate an ordered (numbered) list or simple text for a definition list. o empty section in previous paragraph The previous section (introduced by a "=head" command) does not contain any text. This usually indicates that something is missing. Note: A "=head1" followed imme- diately by "=head2" does not trigger this warning. o Verbatim paragraph in NAME section The NAME section ("=head1 NAME") should consist of a single paragraph with the script/module name, followed by a dash `-' and a very short description of what the thing is good for. Hyperlinks There are some warnings wrt. malformed hyperlinks. o ignoring leading/trailing whitespace in link There is whitespace at the beginning or the end of the contents of L<...>. o (section) in '$page' deprecated There is a section detected in the page name of L<...>, e.g. "L>passwd(d)>". POD hyperlinks may point to POD documents only. Please write "C<passwd(d)>" instead. Some formatters are able to expand this to appropriate code. For links to (builtin) functions, please say "L<perlfunc/mkdir>", without (). o alternative text/node '%s' contains non-escaped | or / The characters "|" and "/" are special in the L<...> context. Although the hyperlink parser does its best to determine which "/" is text and which is a delim- iter in case of doubt, one ought to escape these lit- eral characters like this: / E<sol> | E<verbar> RETURN VALUE podchecker returns the number of POD syntax errors found or -1 if there were no POD commands at all found in the file. EXAMPLES [T.B.D.] INTERFACE While checking, this module collects document properties, e.g. the nodes for hyperlinks ("=headX", "=item") and index entries ("X<>"). POD translators can use this fea- ture to syntax-check and get the nodes in a first pass before actually starting to convert. This is expensive in terms of execution time, but allows for very robust con- versions. "Pod::Checker->new( %options )" Return a reference to a new Pod::Checker object that inherits from Pod::Parser and is used for calling the required methods later. The following options are rec- ognized: "-warnings => num" Print warnings if "num" is true. The higher the value of "num", the more warnings are printed. Cur- rently there are only levels 1 and 2. "-quiet => num" If "num" is true, do not print any errors/warnings. This is useful when Pod::Checker is used to munge POD code into plain text from within POD formatters. "$checker->poderror( @args )" "$checker->poderror( {%opts}, @args )" Internal method for printing errors and warnings. If no options are given, simply prints "@_". The follow- ing options are recognized and used to form the out- put: -msg A message to print prior to @args. -line The line number the error occurred in. -file The file (name) the error occurred in. -severity The error level, should be 'WARNING' or 'ERROR'. "$checker->num_errors()" Set (if argument specified) and retrieve the number of errors found. "$checker->name()" Set (if argument specified) and retrieve the canonical name of POD as found in the "=head1 NAME" section. "$checker->node()" Add (if argument specified) and retrieve the nodes (as defined by "=headX" and "=item") of the current POD. The nodes are returned in the order of their occurence. They consist of plain text, each piece of whitespace is collapsed to a single blank. "$checker->idx()" Add (if argument specified) and retrieve the index entries (as defined by "X<>") of the current POD. They consist of plain text, each piece of whitespace is collapsed to a single blank. "$checker->hyperlink()" Add (if argument specified) and retrieve the hyper- links (as defined by "L<>") of the current POD. They consist of an 2-item array: line number and "Pod::Hyperlink" object. AUTHOR Brad Appleton <bradapp@enteract.com> (initial version), Marek Rouchal <marek@saftsack.fs.uni-bayreuth.de> Based on code for Pod::Text::pod2text() written by Tom Christiansen <tchrist@mox.perl.com> perl v5.6.1 2001-02-23 Pod::Checker(r)