mingw/html/lib/Pod/Checker.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>podchecker - check pod documents for syntax errors</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;podchecker - check pod documents for syntax errors</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#options_arguments">OPTIONS/ARGUMENTS</a></li>
  25         <ul>
  26
  27                 <li><a href="#podchecker__"><code>podchecker()</code></a></li>
  28         </ul>
  29
  30         <li><a href="#description">DESCRIPTION</a></li>
  31         <li><a href="#diagnostics">DIAGNOSTICS</a></li>
  32         <ul>
  33
  34                 <li><a href="#errors">Errors</a></li>
  35                 <li><a href="#warnings">Warnings</a></li>
  36                 <li><a href="#hyperlinks">Hyperlinks</a></li>
  37         </ul>
  38
  39         <li><a href="#return_value">RETURN VALUE</a></li>
  40         <li><a href="#examples">EXAMPLES</a></li>
  41         <li><a href="#interface">INTERFACE</a></li>
  42         <li><a href="#author">AUTHOR</a></li>
  43 </ul>
  44 <!-- INDEX END -->
  45
  46 <hr />
  47 <p>
  48 </p>
  49 <h1><a name="name">NAME</a></h1>
  50 <p>Pod::Checker, <code>podchecker()</code> - check pod documents for syntax errors</p>
  51 <p>
  52 </p>
  53 <hr />
  54 <h1><a name="synopsis">SYNOPSIS</a></h1>
  55 <pre>
  56   use Pod::Checker;</pre>
  57 <pre>
  58   $syntax_okay = podchecker($filepath, $outputpath, %options);</pre>
  59 <pre>
  60   my $checker = new Pod::Checker %options;
  61   $checker-&gt;parse_from_file($filepath, \*STDERR);</pre>
  62 <p>
  63 </p>
  64 <hr />
  65 <h1><a name="options_arguments">OPTIONS/ARGUMENTS</a></h1>
  66 <p><code>$filepath</code> is the input POD to read and <code>$outputpath</code> is
  67 where to write POD syntax error messages. Either argument may be a scalar
  68 indicating a file-path, or else a reference to an open filehandle.
  69 If unspecified, the input-file it defaults to <code>\*STDIN</code>, and
  70 the output-file defaults to <code>\*STDERR</code>.</p>
  71 <p>
  72 </p>
  73 <h2><a name="podchecker__"><code>podchecker()</code></a></h2>
  74 <p>This function can take a hash of options:</p>
  75 <dl>
  76 <dt><strong><a name="item__2dwarnings__3d_3e_val"><strong>-warnings</strong> =&gt; <em>val</em></a></strong>
  77
  78 <dd>
  79 <p>Turn warnings on/off. <em>val</em> is usually 1 for on, but higher values
  80 trigger additional warnings. See <a href="#warnings">Warnings</a>.</p>
  81 </dd>
  82 </li>
  83 </dl>
  84 <p>
  85 </p>
  86 <hr />
  87 <h1><a name="description">DESCRIPTION</a></h1>
  88 <p><strong>podchecker</strong> will perform syntax checking of Perl5 POD format documentation.</p>
  89 <p>Curious/ambitious users are welcome to propose additional features they wish
  90 to see in <strong>Pod::Checker</strong> and <strong>podchecker</strong> and verify that the checks are
  91 consistent with <a href="file://C|\msysgit\mingw\html/pod/perlpod.html">the perlpod manpage</a>.</p>
  92 <p>The following checks are currently performed:</p>
  93 <ul>
  94 <li>
  95 <p>Unknown '=xxxx' commands, unknown 'X&lt;...&gt;' interior-sequences,
  96 and unterminated interior sequences.</p>
  97 </li>
  98 <li>
  99 <p>Check for proper balancing of <code>=begin</code> and <code>=end</code>. The contents of such
 100 a block are generally ignored, i.e. no syntax checks are performed.</p>
 101 </li>
 102 <li>
 103 <p>Check for proper nesting and balancing of <code>=over</code>, <code>=item</code> and <code>=back</code>.</p>
 104 </li>
 105 <li>
 106 <p>Check for same nested interior-sequences (e.g.
 107 <code>L&lt;...L&lt;...&gt;...&gt;</code>).</p>
 108 </li>
 109 <li>
 110 <p>Check for malformed or nonexisting entities <code>E&lt;...&gt;</code>.</p>
 111 </li>
 112 <li>
 113 <p>Check for correct syntax of hyperlinks <code>L&lt;...&gt;</code>. See <a href="file://C|\msysgit\mingw\html/pod/perlpod.html">the perlpod manpage</a>
 114 for details.</p>
 115 </li>
 116 <li>
 117 <p>Check for unresolved document-internal links. This check may also reveal
 118 misspelled links that seem to be internal links but should be links
 119 to something else.</p>
 120 </li>
 121 </ul>
 122 <p>
 123 </p>
 124 <hr />
 125 <h1><a name="diagnostics">DIAGNOSTICS</a></h1>
 126 <p>
 127 </p>
 128 <h2><a name="errors">Errors</a></h2>
 129 <ul>
 130 <li><strong><a name="item_empty__3dheadn">empty =headn</a></strong>
 131
 132 <p>A heading (<code>=head1</code> or <code>=head2</code>) without any text? That ain't no
 133 heading!</p>
 134 </li>
 135 <li><strong><a name="item__3dover_on_line_n_without_closing__3dback">=over on line <em>N</em> without closing =back</a></strong>
 136
 137 <p>The <code>=over</code> command does not have a corresponding <code>=back</code> before the
 138 next heading (<code>=head1</code> or <code>=head2</code>) or the end of the file.</p>
 139 </li>
 140 <li><strong><a name="item__3ditem_without_previous__3dover">=item without previous =over</a></strong>
 141
 142 <li><strong><a name="item__3dback_without_previous__3dover">=back without previous =over</a></strong>
 143
 144 <p>An <code>=item</code> or <code>=back</code> command has been found outside a
 145 <code>=over</code>/<code>=back</code> block.</p>
 146 </li>
 147 <li><strong><a name="item_no_argument_for__3dbegin">No argument for =begin</a></strong>
 148
 149 <p>A <code>=begin</code> command was found that is not followed by the formatter
 150 specification.</p>
 151 </li>
 152 <li><strong><a name="item__3dend_without__3dbegin">=end without =begin</a></strong>
 153
 154 <p>A standalone <code>=end</code> command was found.</p>
 155 </li>
 156 <li><strong><a name="item_nested__3dbegin_27s">Nested =begin's</a></strong>
 157
 158 <p>There were at least two consecutive <code>=begin</code> commands without
 159 the corresponding <code>=end</code>. Only one <code>=begin</code> may be active at
 160 a time.</p>
 161 </li>
 162 <li><strong><a name="item__3dfor_without_formatter_specification">=for without formatter specification</a></strong>
 163
 164 <p>There is no specification of the formatter after the <code>=for</code> command.</p>
 165 </li>
 166 <li><strong><a name="item_unresolved_internal_link_name">unresolved internal link <em>NAME</em></a></strong>
 167
 168 <p>The given link to <em>NAME</em> does not have a matching node in the current
 169 POD. This also happend when a single word node name is not enclosed in
 170 <code>&quot;&quot;</code>.</p>
 171 </li>
 172 <li><strong><a name="item_unknown_command__22cmd_22">Unknown command ``<em>CMD</em>''</a></strong>
 173
 174 <p>An invalid POD command has been found. Valid are <code>=head1</code>, <code>=head2</code>,
 175 <code>=head3</code>, <code>=head4</code>, <code>=over</code>, <code>=item</code>, <code>=back</code>, <code>=begin</code>, <code>=end</code>,
 176 <code>=for</code>, <code>=pod</code>, <code>=cut</code></p>
 177 </li>
 178 <li><strong><a name="item_unknown_interior_2dsequence__22seq_22">Unknown interior-sequence ``<em>SEQ</em>''</a></strong>
 179
 180 <p>An invalid markup command has been encountered. Valid are:
 181 <code>B&lt;&gt;</code>, <code>C&lt;&gt;</code>, <code>E&lt;&gt;</code>, <code>F&lt;&gt;</code>,
 182 <code>I&lt;&gt;</code>, <code>L&lt;&gt;</code>, <code>S&lt;&gt;</code>, <code>X&lt;&gt;</code>,
 183 <code>Z&lt;&gt;</code></p>
 184 </li>
 185 <li><strong><a name="item_nested_commands_cmd_3c_2e_2e_2ecmd_3c_2e_2e_2e_3e_">nested commands <em>CMD</em>&lt;...<em>CMD</em>&lt;...&gt;...&gt;</a></strong>
 186
 187 <p>Two nested identical markup commands have been found. Generally this
 188 does not make sense.</p>
 189 </li>
 190 <li><strong><a name="item_garbled_entity_string">garbled entity <em>STRING</em></a></strong>
 191
 192 <p>The <em>STRING</em> found cannot be interpreted as a character entity.</p>
 193 </li>
 194 <li><strong><a name="item_entity_number_out_of_range">Entity number out of range</a></strong>
 195
 196 <p>An entity specified by number (dec, hex, oct) is out of range (1-255).</p>
 197 </li>
 198 <li><strong><a name="item_malformed_link_l_3c_3e">malformed link L&lt;&gt;</a></strong>
 199
 200 <p>The link found cannot be parsed because it does not conform to the
 201 syntax described in <a href="file://C|\msysgit\mingw\html/pod/perlpod.html">the perlpod manpage</a>.</p>
 202 </li>
 203 <li><strong><a name="item_nonempty_z_3c_3e">nonempty Z&lt;&gt;</a></strong>
 204
 205 <p>The <code>Z&lt;&gt;</code> sequence is supposed to be empty.</p>
 206 </li>
 207 <li><strong><a name="item_empty_x_3c_3e">empty X&lt;&gt;</a></strong>
 208
 209 <p>The index entry specified contains nothing but whitespace.</p>
 210 </li>
 211 <li><strong><a name="item_spurious_text_after__3dpod__2f__3dcut">Spurious text after =pod / =cut</a></strong>
 212
 213 <p>The commands <code>=pod</code> and <code>=cut</code> do not take any arguments.</p>
 214 </li>
 215 <li><strong><a name="item_character">Spurious <code>character(s)</code> after =back</a></strong>
 216
 217 <p>The <code>=back</code> command does not take any arguments.</p>
 218 </li>
 219 </ul>
 220 <p>
 221 </p>
 222 <h2><a name="warnings">Warnings</a></h2>
 223 <p>These may not necessarily cause trouble, but indicate mediocre style.</p>
 224 <ul>
 225 <li><strong><a name="item_multiple_occurrence_of_link_target_name">multiple occurrence of link target <em>name</em></a></strong>
 226
 227 <p>The POD file has some <code>=item</code> and/or <code>=head</code> commands that have
 228 the same text. Potential hyperlinks to such a text cannot be unique then.
 229 This warning is printed only with warning level greater than one.</p>
 230 </li>
 231 <li><strong><a name="item_line_containing_nothing_but_whitespace_in_paragrap">line containing nothing but whitespace in paragraph</a></strong>
 232
 233 <p>There is some whitespace on a seemingly empty line. POD is very sensitive
 234 to such things, so this is flagged. <strong>vi</strong> users switch on the <strong>list</strong>
 235 option to avoid this problem.</p>
 236 </li>
 237 <li><strong><a name="item_previous__3ditem_has_no_contents">previous =item has no contents</a></strong>
 238
 239 <p>There is a list <code>=item</code> right above the flagged line that has no
 240 text contents. You probably want to delete empty items.</p>
 241 </li>
 242 <li><strong><a name="item_paragraph">preceding non-item <code>paragraph(s)</code></a></strong>
 243
 244 <p>A list introduced by <code>=over</code> starts with a text or verbatim paragraph,
 245 but continues with <code>=item</code>s. Move the non-item paragraph out of the
 246 <code>=over</code>/<code>=back</code> block.</p>
 247 </li>
 248 <li><strong><a name="item_mismatch">=item type mismatch (<em>one</em> vs. <em>two</em>)</a></strong>
 249
 250 <p>A list started with e.g. a bulletted <code>=item</code> and continued with a
 251 numbered one. This is obviously inconsistent. For most translators the
 252 type of the <em>first</em> <code>=item</code> determines the type of the list.</p>
 253 </li>
 254 <li><strong><a name="item_n_unescaped__3c_3e_in_paragraph"><em>N</em> unescaped <code>&lt;&gt;</code> in paragraph</a></strong>
 255
 256 <p>Angle brackets not written as <code>&lt;lt&gt;</code> and <code>&lt;gt&gt;</code>
 257 can potentially cause errors as they could be misinterpreted as
 258 markup commands. This is only printed when the -warnings level is
 259 greater than 1.</p>
 260 </li>
 261 <li><strong><a name="item_unknown_entity">Unknown entity</a></strong>
 262
 263 <p>A character entity was found that does not belong to the standard
 264 ISO set or the POD specials <code>verbar</code> and <code>sol</code>.</p>
 265 </li>
 266 <li><strong><a name="item_no_items_in__3dover">No items in =over</a></strong>
 267
 268 <p>The list opened with <code>=over</code> does not contain any items.</p>
 269 </li>
 270 <li><strong><a name="item_no_argument_for__3ditem">No argument for =item</a></strong>
 271
 272 <p><code>=item</code> without any parameters is deprecated. It should either be followed
 273 by <code>*</code> to indicate an unordered list, by a number (optionally followed
 274 by a dot) to indicate an ordered (numbered) list or simple text for a
 275 definition list.</p>
 276 </li>
 277 <li><strong><a name="item_empty_section_in_previous_paragraph">empty section in previous paragraph</a></strong>
 278
 279 <p>The previous section (introduced by a <code>=head</code> command) does not contain
 280 any text. This usually indicates that something is missing. Note: A
 281 <code>=head1</code> followed immediately by <code>=head2</code> does not trigger this warning.</p>
 282 </li>
 283 <li><strong><a name="item_verbatim_paragraph_in_name_section">Verbatim paragraph in NAME section</a></strong>
 284
 285 <p>The NAME section (<code>=head1 NAME</code>) should consist of a single paragraph
 286 with the script/module name, followed by a dash `-' and a very short
 287 description of what the thing is good for.</p>
 288 </li>
 289 <li><strong><a name="item__3dheadn_without_preceding_higher_level">=head<em>n</em> without preceding higher level</a></strong>
 290
 291 <p>For example if there is a <code>=head2</code> in the POD file prior to a
 292 <code>=head1</code>.</p>
 293 </li>
 294 </ul>
 295 <p>
 296 </p>
 297 <h2><a name="hyperlinks">Hyperlinks</a></h2>
 298 <p>There are some warnings wrt. malformed hyperlinks.</p>
 299 <ul>
 300 <li><strong><a name="item_ignoring_leading_2ftrailing_whitespace_in_link">ignoring leading/trailing whitespace in link</a></strong>
 301
 302 <p>There is whitespace at the beginning or the end of the contents of
 303 L&lt;...&gt;.</p>
 304 </li>
 305 <li><strong><a name="item__28section_29_in__27_24page_27_deprecated">(section) in '$page' deprecated</a></strong>
 306
 307 <p>There is a section detected in the page name of L&lt;...&gt;, e.g.
 308 <code>L&lt;passwd(2)&gt;</code>. POD hyperlinks may point to POD documents only.
 309 Please write <code>C&lt;passwd(2)&gt;</code> instead. Some formatters are able
 310 to expand this to appropriate code. For links to (builtin) functions,
 311 please say <code>L&lt;perlfunc/mkdir&gt;</code>, without ().</p>
 312 </li>
 313 <li><strong><a name="item_alternative_text_2fnode__27_25s_27_contains_non_2d">alternative text/node '%s' contains non-escaped | or /</a></strong>
 314
 315 <p>The characters <code>|</code> and <code>/</code> are special in the L&lt;...&gt; context.
 316 Although the hyperlink parser does its best to determine which ``/'' is
 317 text and which is a delimiter in case of doubt, one ought to escape
 318 these literal characters like this:</p>
 319 <pre>
 320   /     E&lt;sol&gt;
 321   |     E&lt;verbar&gt;</pre>
 322 </li>
 323 </ul>
 324 <p>
 325 </p>
 326 <hr />
 327 <h1><a name="return_value">RETURN VALUE</a></h1>
 328 <p><strong>podchecker</strong> returns the number of POD syntax errors found or -1 if
 329 there were no POD commands at all found in the file.</p>
 330 <p>
 331 </p>
 332 <hr />
 333 <h1><a name="examples">EXAMPLES</a></h1>
 334 <p>See <a href="#synopsis">SYNOPSIS</a></p>
 335 <p>
 336 </p>
 337 <hr />
 338 <h1><a name="interface">INTERFACE</a></h1>
 339 <p>While checking, this module collects document properties, e.g. the nodes
 340 for hyperlinks (<code>=headX</code>, <code>=item</code>) and index entries (<code>X&lt;&gt;</code>).
 341 POD translators can use this feature to syntax-check and get the nodes in
 342 a first pass before actually starting to convert. This is expensive in terms
 343 of execution time, but allows for very robust conversions.</p>
 344 <p>Since PodParser-1.24 the <strong>Pod::Checker</strong> module uses only the <strong>poderror</strong>
 345 method to print errors and warnings. The summary output (e.g.
 346 ``Pod syntax OK'') has been dropped from the module and has been included in
 347 <strong>podchecker</strong> (the script). This allows users of <strong>Pod::Checker</strong> to
 348 control completely the output behaviour. Users of <strong>podchecker</strong> (the script)
 349 get the well-known behaviour.</p>
 350 <dl>
 351 <dt><strong><a name="item_new"><code>Pod::Checker-&gt;new( %options )</code></a></strong>
 352
 353 <dd>
 354 <p>Return a reference to a new Pod::Checker object that inherits from
 355 Pod::Parser and is used for calling the required methods later. The
 356 following options are recognized:</p>
 357 </dd>
 358 <dd>
 359 <p><code>-warnings =&gt; num</code>
 360   Print warnings if <code>num</code> is true. The higher the value of <code>num</code>,
 361 the more warnings are printed. Currently there are only levels 1 and 2.</p>
 362 </dd>
 363 <dd>
 364 <p><code>-quiet =&gt; num</code>
 365   If <code>num</code> is true, do not print any errors/warnings. This is useful
 366 when Pod::Checker is used to munge POD code into plain text from within
 367 POD formatters.</p>
 368 </dd>
 369 </li>
 370 <dt><strong><a name="item_poderror"><code>$checker-&gt;poderror( @args )</code></a></strong>
 371
 372 <dt><strong><code>$checker-&gt;poderror( {%opts}, @args )</code></strong>
 373
 374 <dd>
 375 <p>Internal method for printing errors and warnings. If no options are
 376 given, simply prints ``@_''. The following options are recognized and used
 377 to form the output:</p>
 378 </dd>
 379 <dd>
 380 <pre>
 381   -msg</pre>
 382 </dd>
 383 <dd>
 384 <p>A message to print prior to <code>@args</code>.</p>
 385 </dd>
 386 <dd>
 387 <pre>
 388   -line</pre>
 389 </dd>
 390 <dd>
 391 <p>The line number the error occurred in.</p>
 392 </dd>
 393 <dd>
 394 <pre>
 395   -file</pre>
 396 </dd>
 397 <dd>
 398 <p>The file (name) the error occurred in.</p>
 399 </dd>
 400 <dd>
 401 <pre>
 402   -severity</pre>
 403 </dd>
 404 <dd>
 405 <p>The error level, should be 'WARNING' or 'ERROR'.</p>
 406 </dd>
 407 </li>
 408 <dt><strong><a name="item_num_errors"><code>$checker-&gt;num_errors()</code></a></strong>
 409
 410 <dd>
 411 <p>Set (if argument specified) and retrieve the number of errors found.</p>
 412 </dd>
 413 </li>
 414 <dt><strong><a name="item_num_warnings"><code>$checker-&gt;num_warnings()</code></a></strong>
 415
 416 <dd>
 417 <p>Set (if argument specified) and retrieve the number of warnings found.</p>
 418 </dd>
 419 </li>
 420 <dt><strong><a name="item_name"><code>$checker-&gt;name()</code></a></strong>
 421
 422 <dd>
 423 <p>Set (if argument specified) and retrieve the canonical name of POD as
 424 found in the <code>=head1 NAME</code> section.</p>
 425 </dd>
 426 </li>
 427 <dt><strong><a name="item_node"><code>$checker-&gt;node()</code></a></strong>
 428
 429 <dd>
 430 <p>Add (if argument specified) and retrieve the nodes (as defined by <code>=headX</code>
 431 and <code>=item</code>) of the current POD. The nodes are returned in the order of
 432 their occurrence. They consist of plain text, each piece of whitespace is
 433 collapsed to a single blank.</p>
 434 </dd>
 435 </li>
 436 <dt><strong><a name="item_idx"><code>$checker-&gt;idx()</code></a></strong>
 437
 438 <dd>
 439 <p>Add (if argument specified) and retrieve the index entries (as defined by
 440 <code>X&lt;&gt;</code>) of the current POD. They consist of plain text, each piece
 441 of whitespace is collapsed to a single blank.</p>
 442 </dd>
 443 </li>
 444 <dt><strong><a name="item_hyperlink"><code>$checker-&gt;hyperlink()</code></a></strong>
 445
 446 <dd>
 447 <p>Add (if argument specified) and retrieve the hyperlinks (as defined by
 448 <code>L&lt;&gt;</code>) of the current POD. They consist of a 2-item array: line
 449 number and <code>Pod::Hyperlink</code> object.</p>
 450 </dd>
 451 </li>
 452 </dl>
 453 <p>
 454 </p>
 455 <hr />
 456 <h1><a name="author">AUTHOR</a></h1>
 457 <p>Please report bugs using <a href="http://rt.cpan.org">http://rt.cpan.org</a>.</p>
 458 <p>Brad Appleton &lt;<a href="mailto:bradapp@enteract.com">bradapp@enteract.com</a>&gt; (initial version),
 459 Marek Rouchal &lt;<a href="mailto:marekr@cpan.org">marekr@cpan.org</a>&gt;</p>
 460 <p>Based on code for <strong>Pod::Text::pod2text()</strong> written by
 461 Tom Christiansen &lt;<a href="mailto:tchrist@mox.perl.com">tchrist@mox.perl.com</a>&gt;</p>
 462 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 463 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 464 <big><strong><span class="block">&nbsp;podchecker - check pod documents for syntax errors</span></strong></big>
 465 </td></tr>
 466 </table>
 467
 468 </body>
 469
 470 </html>