SEARCH
NEW RPMS
DIRECTORIES
ABOUT
FAQ
VARIOUS
BLOG
DONATE


YUM REPOSITORY

 
 

MAN page from CentOS 8 perl-Pod-Checker-1.73-395.module_el8.0.0+50+c3b345cd.noarch.rpm

Pod::Checker

Section: User Contributed Perl Documentation (3)
Updated: 2016-05-30
Index 

NAME

Pod::Checker - check pod documents for syntax errors 

SYNOPSIS

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

OPTIONS/ARGUMENTS

$filepath is the input POD to read and $outputpath iswhere to write POD syntax error messages. Either argument may be a scalarindicating a file-path, or else a reference to an open filehandle.If unspecified, the input-file it defaults to "\*STDIN", andthe 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 valuestrigger additional warnings. See ``Warnings''.
-quiet => val
If "val" is true, do not print any errors/warnings.
 

DESCRIPTION

podchecker will perform syntax checking of Perl5 POD format documentation.

Curious/ambitious users are welcome to propose additional features they wishto see in Pod::Checker and podchecker and verify that the checks areconsistent 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 sucha 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 perlpodfor details.
*
Check for unresolved document-internal links. This check may also revealmisspelled links that seem to be internal links but should be linksto something else.
 

DIAGNOSTICS

 

Errors

*
empty =headn

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

*
=over on line N without closing =back
*
You forgot a '=back' before '=headN'
*
=over is the last thing in the document?!

The "=over" command does not have a corresponding "=back" before thenext 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 TARGET without matching =end TARGET

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

*
=end TARGET 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 TARGET' is invalid.

TARGET needs to be one word

*
=end CONTENT doesn't match =begin TARGET

CONTENT needs to match =begin's TARGET.

*
=for without a target?

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

*
unresolved internal link NAME

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

*
Unknown directive: CMD

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 SEQ

An invalid markup command has been encountered. Valid are:"B<>", "C<>", "E<>", "F<>","I<>", "L<>", "S<>", "X<>","Z<>"

*
Unterminated SEQ<> sequence

An unclosed formatting code

*
An E<...> surrounding strange content

The STRING 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.

*
A non-empty Z<>

The "Z<>" sequence is supposed to be empty.

*
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 ARGUMENT

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: CONTENT

Syntax error in =encoding directive

 

Warnings

These may not necessarily cause trouble, but indicate mediocre style.
*
nested commands CMD<...CMD<...>...>

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

*
multiple occurrences (N) of link target name

The POD file has some "=item" and/or "=head" commands that havethe 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 sensitiveto such things, so this is flagged. vi users switch on the listoption to avoid this problem.

*
=item has no contents

There is a list "=item" that has no text contents. You probably want to deleteempty 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 EXPECTED VALUE'
*
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 anumbered one. This is obviously inconsistent. For most translators thetype of the first "=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<CONTENT>

A character entity was found that does not belong to the standardISO set or the POD specials "verbar" and "sol". Currently, this warningonly appears if a character entity was found that does not have a Unicodecharacter. This should be fixed to adhere to the original warning.

*
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 containany 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 paragraphwith the script/module name, followed by a dash `-' and a very shortdescription of what the thing is good for.

*
=headn without preceding higher level

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

 

Hyperlinks

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

*
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 ``/'' istext and which is a delimiter in case of doubt, one ought to escapethese literal characters like this:

  /     E<sol>  |     E<verbar>

Note that the line number of the error/warning may refer to the line number ofthe 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/warningsrelated to formatting codes. This should be fixed. 

RETURN VALUE

podchecker returns the number of POD syntax errors found or -1 ifthere were no POD commands at all found in the file. 

EXAMPLES

See ``SYNOPSIS'' 

SCRIPTS

The podchecker script that comes with this distribution is a lean wrapperaround this module. See the online manual with

  podchecker -help  podchecker -man
 

INTERFACE

While checking, this module collects document properties, e.g. the nodesfor hyperlinks ("=headX", "=item") and index entries ("X<>").POD translators can use this feature to syntax-check and get the nodes ina first pass before actually starting to convert. This is expensive in termsof execution time, but allows for very robust conversions.

Since v1.24 the Pod::Checker module uses only the poderrormethod to print errors and warnings. The summary output (e.g.``Pod syntax OK'') has been dropped from the module and has been included inpodchecker (the script). This allows users of Pod::Checker tocontrol completely the output behavior. Users of podchecker (the script)get the well-known behavior.

v1.45 inherits from Pod::Simple as opposed to all previous versionsinheriting from Pod::Parser. Do not use Pod::Simple's interface whenusing Pod::Checker unless it is documented somewhere on this page. Irepeat, DO NOT USE POD::SIMPLE'S INTERFACE.

Pod::Checker->new( %options )
Return a reference to a new Pod::Checker object that inherits fromPod::Simple and is used for calling the required methods later. Thefollowing 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 usefulwhen Pod::Checker is used to munge POD code into plain text from withinPOD 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 formthe 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 currentfile 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 asfound 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 oftheir occurrence. They consist of plain text, each piece of whitespace iscollapsed 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 pieceof whitespace is collapsed to a single blank.
$checker->hyperlinks()
Retrieve an array containing the hyperlinks to things outsidethe current POD (as defined by "L<>").

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

line()
Returns the approximate line number in which the link was encountered
type()
Returns the type of the link; one of:"url" for things like"http://www.foo", "man" for man pages, or "pod".
page()
Returns the linked-to page or url.
node()
Returns the anchor or node within the linked-to page, or an empty string("") if none appears in the link.
 

AUTHOR

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

Brad Appleton <bradappAATTenteract.com> (initial version),Marek Rouchal <marekrAATTcpan.org>,Marc Green <marcgreenAATTcpan.org> (port to Pod::Simple)Ricardo Signes <rjbsAATTcpan.org> (more porting to Pod::Simple)Karl Williamson <khwAATTcpan.org> (more porting to Pod::Simple)

Based on code for Pod::Text::pod2text() written byTom Christiansen <tchristAATTmox.perl.com>


 

Index

NAME
SYNOPSIS
OPTIONS/ARGUMENTS
podchecker()
DESCRIPTION
DIAGNOSTICS
Errors
Warnings
Hyperlinks
RETURN VALUE
EXAMPLES
SCRIPTS
INTERFACE
AUTHOR

This document was created byman2html,using the manual pages.