Pod::Checker(3p) Perl Programmers Reference Guide Pod::Checker(3p) #

Pod::Checker(3p) Perl Programmers Reference Guide Pod::Checker(3p)

NNAAMMEE #

 Pod::Checker - check pod documents for syntax errors

SSYYNNOOPPSSIISS #

   use Pod::Checker;

   $syntax_okay = podchecker($filepath, $outputpath, %options);

   my $checker = Pod::Checker->new(%options);
   $checker->parse_from_file($filepath, \*STDERR);

OOPPTTIIOONNSS//AARRGGUUMMEENNTTSS #

 $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 reference to an open filehandle.  If unspecified, the
 input-file it defaults to "\*STDIN", and the output-file defaults to

“*STDERR”. #

ppooddcchheecckkeerr(()) This function can take a hash of options:

 --wwaarrnniinnggss => _v_a_l
     Turn warnings on/off. _v_a_l is usually 1 for on, but higher values
     trigger additional warnings. See "Warnings".

 --qquuiieett => _v_a_l
     If "val" is true, do not print any errors/warnings.

DDEESSCCRRIIPPTTIIOONN #

 ppooddcchheecckkeerr will perform syntax checking of Perl5 POD format
 documentation.

 Curious/ambitious users are welcome to propose additional features they
 wish to see in PPoodd::::CChheecckkeerr and ppooddcchheecckkeerr and verify that the checks are
 consistent with perlpod.

 The following checks are currently performed:

 •   Unknown '=xxxx' commands, unknown 'X<...>' interior-sequences, and
     unterminated interior sequences.

 •   Check for proper balancing of "=begin" and "=end". The contents of
     such a block are generally ignored, i.e. no syntax checks are
     performed.

 •   Check for proper nesting and balancing of "=over", "=item" and
     "=back".

 •   Check for same nested interior-sequences (e.g.  "L<...L<...>...>").

 •   Check for malformed or non-existing entities "E<...>".

 •   Check for correct syntax of hyperlinks "L<...>". See perlpod for
     details.

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

DDIIAAGGNNOOSSTTIICCSS #

EErrrroorrss • empty =headn

     A heading ("=head1" or "=head2") without any text? That ain't no
     heading!

 •   =over on line _N without closing =back

 •   You forgot a '=back' before '=head_N'

 •   =over is the last thing in the document?!

     The "=over" command does not have a corresponding "=back" before the
     next heading ("=head1" or "=head2") or the end of the file.

 •   '=item' outside of any '=over'

 •   =back without =over

     An "=item" or "=back" command has been found outside a
     "=over"/"=back" block.

 •   Can't have a 0 in =over _N

     You need to indent a strictly positive number of spaces, not 0.

 •   =over should be: '=over' or '=over positive_number'

     Either have an argumentless =over, or have its argument a strictly
     positive number.

 •   =begin _T_A_R_G_E_T without matching =end _T_A_R_G_E_T

     A "=begin" command was found that has no matching =end command.

 •   =begin without a target?

     A "=begin" command was found that is not followed by the formatter
     specification.

 •   =end _T_A_R_G_E_T without matching =begin.

     A standalone "=end" command was found.

 •   '=end' without a target?

     '=end' directives need to have a target, just like =begin directives.

 •   '=end _T_A_R_G_E_T' is invalid.

     _T_A_R_G_E_T needs to be one word

 •   =end _C_O_N_T_E_N_T doesn't match =begin _T_A_R_G_E_T

     _C_O_N_T_E_N_T needs to match =begin's _T_A_R_G_E_T.

 •   =for without a target?

     There is no specification of the formatter after the "=for" command.

 •   unresolved internal link _N_A_M_E

     The given link to _N_A_M_E does not have a matching node in the current
     POD. This also happened when a single word node name is not enclosed
     in "".

 •   Unknown directive: _C_M_D

     An invalid POD command has been found. Valid are "=head1", "=head2",
     "=head3", "=head4", "=over", "=item", "=back", "=begin", "=end",
     "=for", "=pod", "=cut"

 •   Deleting unknown formatting code _S_E_Q

     An invalid markup command has been encountered. Valid are: "B<>",

“C<>”, “E<>”, “F<>”, “I<>”, “L<>”, “S<>”, “X<>”, “Z<>” #

 •   Unterminated _S_E_Q<> sequence

     An unclosed formatting code

 •   An E<...> surrounding strange content

     The _S_T_R_I_N_G found cannot be interpreted as a character entity.

 •   An empty E<>

 •   An empty "L<>"

 •   An empty X<>

     There needs to be content inside E, L, and X formatting codes.

 •   Spurious text after =pod / =cut

     The commands "=pod" and "=cut" do not take any arguments.

 •   =back doesn't take any parameters, but you said =back _A_R_G_U_M_E_N_T

     The "=back" command does not take any arguments.

 •   =pod directives shouldn't be over one line long!  Ignoring all _N
     lines of content

     Self explanatory

 •   =cut found outside a pod block.

     A '=cut' directive found in the middle of non-POD

 •   Invalid =encoding syntax: _C_O_N_T_E_N_T

     Syntax error in =encoding directive

WWaarrnniinnggss These may not necessarily cause trouble, but indicate mediocre style.

 •   nested commands _C_M_D<..._C_M_D<...>...>

     Two nested identical markup commands have been found. Generally this
     does not make sense.

 •   multiple occurrences (_N) of link target _n_a_m_e

     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.
     This warning is printed only with warning level greater than one.

 •   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. vvii users switch on the
     lliisstt option to avoid this problem.

 •   =item has no contents

     There is a list "=item" that has no text contents. You probably want
     to delete empty items.

 •   You can't have =items (as at line _N) unless the first thing after the
     =over is an =item

     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.

 •   Expected '=item _E_X_P_E_C_T_E_D _V_A_L_U_E'

 •   Expected '=item *'

 •   Possible =item type mismatch: '_x' found leading a supposed definition
     =item

     A list started with e.g. a bullet-like "=item" and continued with a
     numbered one. This is obviously inconsistent. For most translators
     the type of the _f_i_r_s_t "=item" determines the type of the list.

 •   You have '=item x' instead of the expected '=item _N'

     Erroneous numbering of =item numbers; they need to ascend
     consecutively.

 •   Unknown E content in E<_C_O_N_T_E_N_T>

     A character entity was found that does not belong to the standard ISO
     set or the POD specials "verbar" and "sol". _C_u_r_r_e_n_t_l_y_, _t_h_i_s _w_a_r_n_i_n_g
     _o_n_l_y _a_p_p_e_a_r_s _i_f _a _c_h_a_r_a_c_t_e_r _e_n_t_i_t_y _w_a_s _f_o_u_n_d _t_h_a_t _d_o_e_s _n_o_t _h_a_v_e _a
     _U_n_i_c_o_d_e _c_h_a_r_a_c_t_e_r_. _T_h_i_s _s_h_o_u_l_d _b_e _f_i_x_e_d _t_o _a_d_h_e_r_e _t_o _t_h_e _o_r_i_g_i_n_a_l
     _w_a_r_n_i_n_g_.

 •   empty =over/=back block

     The list opened with "=over" does not contain anything.

 •   empty section in previous paragraph

     The previous section (introduced by a "=head" command) does not
     contain any valid content. This usually indicates that something is
     missing. Note: A "=head1" followed immediately by "=head2" does not
     trigger this warning.

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

 •   =head_n without preceding higher level

     For example if there is a "=head2" in the POD file prior to a
     "=head1".

 •   A non-empty Z<>

     The "Z<>" sequence is supposed to be empty. Caveat: this issue is
     detected in Pod::Simple and will be flagged as an _E_R_R_O_R by any client
     code; any contents of "Z<...>" will be disregarded, anyway.

HHyyppeerrlliinnkkss There are some warnings with respect to malformed hyperlinks:

 •   ignoring leading/trailing whitespace in link

     There is whitespace at the beginning or the end of the contents of

L<…>. #

 •   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 delimiter in case of doubt, one ought to escape
     these literal characters like this:

       /     E<sol>
       |     E<verbar>

 Note that the line number of the error/warning may refer to the line
 number of the start of the paragraph in which the error/warning exists,
 not the line number that the error/warning is on. This bug is present in
 errors/warnings related to formatting codes. _T_h_i_s _s_h_o_u_l_d _b_e _f_i_x_e_d_.

RREETTUURRNN VVAALLUUEE #

 ppooddcchheecckkeerr returns the number of POD syntax errors found or -1 if there
 were no POD commands at all found in the file.

EEXXAAMMPPLLEESS #

 See "SYNOPSIS"

SSCCRRIIPPTTSS #

 The ppooddcchheecckkeerr script that comes with this distribution is a lean wrapper
 around this module. See the online manual with

   podchecker -help
   podchecker -man

IINNTTEERRFFAACCEE #

 While checking, this module collects document properties, e.g. the nodes
 for hyperlinks ("=headX", "=item") and index entries ("X<>").  POD
 translators can use this feature 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 conversions.

 Since v1.24 the PPoodd::::CChheecckkeerr module uses only the ppooddeerrrroorr method to
 print errors and warnings. The summary output (e.g.  "Pod syntax OK") has
 been dropped from the module and has been included in ppooddcchheecckkeerr (the
 script). This allows users of PPoodd::::CChheecckkeerr to control completely the
 output behavior. Users of ppooddcchheecckkeerr (the script) get the well-known
 behavior.

 v1.45 inherits from Pod::Simple as opposed to all previous versions
 inheriting from Pod::Parser. Do nnoott use Pod::Simple's interface when
 using Pod::Checker unless it is documented somewhere on this page. I
 repeat, DO NNOOTT USE POD::SIMPLE'S INTERFACE.

 The following list documents the overrides to Pod::Simple, primarily to
 make Pod::Coverage happy:

 end_B
 end_C
 end_Document
 end_F
 end_I
 end_L
 end_Para
 end_S
 end_X
 end_fcode
 end_for
 end_head
 end_head1
 end_head2
 end_head3
 end_head4
 end_item
 end_item_bullet
 end_item_number
 end_item_text
 handle_pod_and_cut
 handle_text
 handle_whiteline
 hyperlink
 scream
 start_B
 start_C
 start_Data
 start_F
 start_I
 start_L
 start_Para
 start_S
 start_Verbatim
 start_X
 start_fcode
 start_for
 start_head
 start_head1
 start_head2
 start_head3
 start_head4
 start_item_bullet
 start_item_number
 start_item_text
 start_over
 start_over_block
 start_over_bullet
 start_over_empty
 start_over_number
 start_over_text
 whine
 "Pod::Checker->new( %options )"
     Return a reference to a new Pod::Checker object that inherits from
     Pod::Simple and is used for calling the required methods later. The
     following options are recognized:

     "-warnings => num"
       Print warnings if "num" is true. The higher the value of "num", the
     more warnings are printed. Currently 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 following options are recognized and
     used to form the output:

       -msg

     A message to print prior to @args.

       -line

     The line number the error occurred in.

       -file

     The file (name) the error occurred in. Defaults to the name of the
     current file being processed.

       -severity

     The error level, should be 'WARNING' or 'ERROR'.

 "$checker->num_errors()"
     Set (if argument specified) and retrieve the number of errors found.

 "$checker->num_warnings()"
     Set (if argument specified) and retrieve the number of warnings
     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 occurrence. 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->hyperlinks()"
     Retrieve an array containing the hyperlinks to things outside the
     current POD (as defined by "L<>").

     Each is an instance of a class with the following methods:

 lliinnee(())
     Returns the approximate line number in which the link was encountered

 ttyyppee(())
     Returns the type of the link; one of: "url" for things like
     "http://www.foo", "man" for man pages, or "pod".

 ppaaggee(())
     Returns the linked-to page or url.

 nnooddee(())
     Returns the anchor or node within the linked-to page, or an empty
     string ("") if none appears in the link.

AAUUTTHHOORR #

 Please report bugs using <http://rt.cpan.org>.

 Brad Appleton <bradapp@enteract.com> (initial version), Marek Rouchal
 <marekr@cpan.org>, Marc Green <marcgreen@cpan.org> (port to Pod::Simple)
 Ricardo Signes <rjbs@cpan.org> (more porting to Pod::Simple) Karl
 Williamson <khw@cpan.org> (more porting to Pod::Simple)

 Based on code for PPoodd::::TTeexxtt::::ppoodd22tteexxtt(()) written by Tom Christiansen
 <tchrist@mox.perl.com>

perl v5.36.3 2023-02-15 Pod::Checker(3p)