Chip 2000 May

home *** CD-ROM | disk | FTP | other *** search

/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _310fc07d5dbfe94eafe434485274ab2e < prev next >

Wrap

Text File | 2000-03-23 | 16KB | 378 lines

<HTML> <HEAD> <TITLE>podchecker - check pod documents for syntax errors</TITLE> <LINK REL="stylesheet" HREF="../../Active.css" TYPE="text/css"> <LINK REV="made" HREF="mailto:"> </HEAD> <BODY> <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%> <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc"> podchecker - check pod documents for syntax errors </TD></TR> </TABLE> <A NAME="__index__"></A>  <UL> <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI> <LI><A HREF="#synopsis">SYNOPSIS</A></LI> <LI><A HREF="#options/arguments">OPTIONS/ARGUMENTS</A></LI> <UL> <LI><A HREF="#podchecker()"><CODE>podchecker()</CODE></A></LI> </UL> <LI><A HREF="#description">DESCRIPTION</A></LI> <LI><A HREF="#diagnostics">DIAGNOSTICS</A></LI> <UL> <LI><A HREF="#errors">Errors</A></LI> <LI><A HREF="#warnings">Warnings</A></LI> </UL> <LI><A HREF="#return value">RETURN VALUE</A></LI> <LI><A HREF="#examples">EXAMPLES</A></LI> <LI><A HREF="#interface">INTERFACE</A></LI> <LI><A HREF="#author">AUTHOR</A></LI> </UL>  <HR> <H1><A NAME="name">NAME</A></H1> Pod::Checker, <CODE>podchecker()</CODE> - check pod documents for syntax errors <HR> <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1> <UL> <LI>Linux</LI> <LI>Solaris</LI> <LI>Windows</LI> </UL> <HR> <H1><A NAME="synopsis">SYNOPSIS</A></H1> <PRE> use Pod::Checker;</PRE> <PRE> $syntax_okay = podchecker($filepath, $outputpath, %options);</PRE> <PRE> my $checker = new Pod::Checker %options; $checker->parse_from_file($filepath, \*STDERR);</PRE> <HR> <H1><A NAME="options/arguments">OPTIONS/ARGUMENTS</A></H1> <CODE>$filepath</CODE> is the input POD to read and <CODE>$outputpath</CODE> 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 <CODE>\*STDIN</CODE>, and the output-file defaults to <CODE>\*STDERR</CODE>. <H2><A NAME="podchecker()"><CODE>podchecker()</CODE></A></H2> This function can take a hash of options: <DL> <DT><A NAME="item_%2Dwarnings_%3D%3E_val">-warnings => val</A> <DD> Turn warnings on/off. See <A HREF="#warnings">Warnings</A>. </DL> <HR> <H1><A NAME="description">DESCRIPTION</A></H1> podchecker will perform syntax checking of Perl5 POD format 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 <A HREF="../../lib/Pod/perlpod.html">the perlpod manpage</A>. The following checks are currently preformed: <UL> <LI> Unknown '=xxxx' commands, unknown 'X<...>' interior-sequences, and unterminated interior sequences. <LI> Check for proper balancing of <CODE>=begin</CODE> and <CODE>=end</CODE>. The contents of such a block are generally ignored, i.e. no syntax checks are performed. <LI> Check for proper nesting and balancing of <CODE>=over</CODE>, <CODE>=item</CODE> and <CODE>=back</CODE>. <LI> Check for same nested interior-sequences (e.g. <CODE>L<...L<...>...></CODE>). <LI> Check for malformed or nonexisting entities <CODE>E<...></CODE>. <LI> Check for correct syntax of hyperlinks <CODE>L<...></CODE>. See <A HREF="../../lib/Pod/perlpod.html">the perlpod manpage</A> for details. <LI> 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. </UL> <HR> <H1><A NAME="diagnostics">DIAGNOSTICS</A></H1> <H2><A NAME="errors">Errors</A></H2> <UL> <LI><A NAME="item_empty_%3Dheadn">empty =headn</A> A heading (<CODE>=head1</CODE> or <CODE>=head2</CODE>) without any text? That ain't no heading! <LI><A NAME="item_%3Dover_on_line_N_without_closing_%3Dback">=over on line N without closing =back</A> The <CODE>=over</CODE> command does not have a corresponding <CODE>=back</CODE> before the next heading (<CODE>=head1</CODE> or <CODE>=head2</CODE>) or the end of the file. <LI><A NAME="item_%3Ditem_without_previous_%3Dover">=item without previous =over</A> <LI><A NAME="item_%3Dback_without_previous_%3Dover">=back without previous =over</A> An <CODE>=item</CODE> or <CODE>=back</CODE> command has been found outside a <CODE>=over</CODE>/<CODE>=back</CODE> block. <LI><A NAME="item_No_argument_for_%3Dbegin">No argument for =begin</A> A <CODE>=begin</CODE> command was found that is not followed by the formatter specification. <LI><A NAME="item_%3Dend_without_%3Dbegin">=end without =begin</A> A standalone <CODE>=end</CODE> command was found. <LI><A NAME="item_Nested_%3Dbegin%27s">Nested =begin's</A> There were at least two consecutive <CODE>=begin</CODE> commands without the corresponding <CODE>=end</CODE>. Only one <CODE>=begin</CODE> may be active at a time. <LI><A NAME="item_%3Dfor_without_formatter_specification">=for without formatter specification</A> There is no specification of the formatter after the <CODE>=for</CODE> command. <LI><A NAME="item_unresolved_internal_link_NAME">unresolved internal link NAME</A> 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 <CODE>""</CODE>. <LI><A NAME="item_Unknown_command_%22CMD%22">Unknown command ``CMD''</A> An invalid POD command has been found. Valid are <CODE>=head1</CODE>, <CODE>=head2</CODE>, <CODE>=over</CODE>, <CODE>=item</CODE>, <CODE>=back</CODE>, <CODE>=begin</CODE>, <CODE>=end</CODE>, <CODE>=for</CODE>, <CODE>=pod</CODE>, <CODE>=cut</CODE> <LI><A NAME="item_Unknown_interior%2Dsequence_%22SEQ%22">Unknown interior-sequence ``SEQ''</A> An invalid markup command has been encountered. Valid are: <CODE>B<></CODE>, <CODE>C<></CODE>, <CODE>E<></CODE>, <CODE>F<></CODE>, <CODE>I<></CODE>, <CODE>L<></CODE>, <CODE>S<></CODE>, <CODE>X<></CODE>, <CODE>Z<></CODE> <LI><A NAME="item_nested_commands_CMD%3C%2E%2E%2ECMD%3C%2E%2E%2E%3E%">nested commands CMD<...CMD<...>...></A> Two nested identical markup commands have been found. Generally this does not make sense. <LI><A NAME="item_garbled_entity_STRING">garbled entity STRING</A> The STRING found cannot be interpreted as a character entity. <LI><A NAME="item_Entity_number_out_of_range">Entity number out of range</A> An entity specified by number (dec, hex, oct) is out of range (1-255). <LI><A NAME="item_malformed_link_L%3C%3E">malformed link L<></A> The link found cannot be parsed because it does not conform to the syntax described in <A HREF="../../lib/Pod/perlpod.html">the perlpod manpage</A>. <LI><A NAME="item_nonempty_Z%3C%3E">nonempty Z<></A> The <CODE>Z<></CODE> sequence is supposed to be empty. <LI><A NAME="item_empty_X%3C%3E">empty X<></A> The index entry specified contains nothing but whitespace. <LI><A NAME="item_Spurious_text_after_%3Dpod_%2F_%3Dcut">Spurious text after =pod / =cut</A> The commands <CODE>=pod</CODE> and <CODE>=cut</CODE> do not take any arguments. <LI><A NAME="item_character">Spurious <CODE>character(s)</CODE> after =back</A> The <CODE>=back</CODE> command does not take any arguments. </UL> <H2><A NAME="warnings">Warnings</A></H2> These may not necessarily cause trouble, but indicate mediocre style. <UL> <LI><A NAME="item_multiple_occurence_of_link_target_name">multiple occurence of link target name</A> The POD file has some <CODE>=item</CODE> and/or <CODE>=head</CODE> commands that have the same text. Potential hyperlinks to such a text cannot be unique then. <LI><A NAME="item_line_containing_nothing_but_whitespace_in_paragrap">line containing nothing but whitespace in paragraph</A> 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. <LI><A NAME="item_file_does_not_start_with_%3Dhead">file does not start with =head</A> The file starts with a different POD directive than head. This is most probably something you do not want. <LI><A NAME="item_No_numeric_argument_for_%3Dover">No numeric argument for =over</A> The <CODE>=over</CODE> command is supposed to have a numeric argument (the indentation). <LI><A NAME="item_previous_%3Ditem_has_no_contents">previous =item has no contents</A> There is a list <CODE>=item</CODE> right above the flagged line that has no text contents. You probably want to delete empty items. <LI><A NAME="item_paragraph">preceding non-item <CODE>paragraph(s)</CODE></A> A list introduced by <CODE>=over</CODE> starts with a text or verbatim paragraph, but continues with <CODE>=item</CODE>s. Move the non-item paragraph out of the <CODE>=over</CODE>/<CODE>=back</CODE> block. <LI><A NAME="item_mismatch">=item type mismatch (one vs. two)</A> A list started with e.g. a bulletted <CODE>=item</CODE> and continued with a numbered one. This is obviously inconsistent. For most translators the type of the first <CODE>=item</CODE> determines the type of the list. <LI><A NAME="item_N_unescaped_%3C%3E_in_paragraph">N unescaped <CODE><></CODE> in paragraph</A> Angle brackets not written as <CODE><lt></CODE> and <CODE><gt></CODE> can potentially cause errors as they could be misinterpreted as markup commands. <LI><A NAME="item_Unknown_entity">Unknown entity</A> A character entity was found that does not belong to the standard ISO set or the POD specials <CODE>verbar</CODE> and <CODE>sol</CODE>. <LI><A NAME="item_No_items_in_%3Dover">No items in =over</A> The list opened with <CODE>=over</CODE> does not contain any items. <LI><A NAME="item_No_argument_for_%3Ditem">No argument for =item</A> <CODE>=item</CODE> without any parameters is deprecated. It should either be followed by <CODE>*</CODE> 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. <LI><A NAME="item_empty_section_in_previous_paragraph">empty section in previous paragraph</A> The previous section (introduced by a <CODE>=head</CODE> command) does not contain any text. This usually indicates that something is missing. Note: A <CODE>=head1</CODE> followed immediately by <CODE>=head2</CODE> does not trigger this warning. <LI><A NAME="item_Verbatim_paragraph_in_NAME_section">Verbatim paragraph in NAME section</A> The NAME section (<CODE>=head1 NAME</CODE>) 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. <LI><A NAME="item_Hyperlinks">Hyperlinks</A> There are some warnings wrt. hyperlinks: Leading/trailing whitespace, newlines in hyperlinks, brackets <CODE>()</CODE>. </UL> <HR> <H1><A NAME="return value">RETURN VALUE</A></H1> podchecker returns the number of POD syntax errors found or -1 if there were no POD commands at all found in the file. <HR> <H1><A NAME="examples">EXAMPLES</A></H1> [T.B.D.] <HR> <H1><A NAME="interface">INTERFACE</A></H1> While checking, this module collects document properties, e.g. the nodes for hyperlinks (<CODE>=headX</CODE>, <CODE>=item</CODE>) and index entries (<CODE>X<></CODE>). 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. <DL> <DT><A NAME="item_poderror"><CODE>$checker->poderror( @args )</CODE></A> <DD> <DT><CODE>$checker->poderror( {%opts}, @args )</CODE> <DD> 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: <PRE> -msg</PRE> A message to print prior to <CODE>@args</CODE>. <PRE> -line</PRE> The line number the error occurred in. <PRE> -file</PRE> The file (name) the error occurred in. <PRE> -severity</PRE> The error level, should be 'WARNING' or 'ERROR'. <DT><A NAME="item_num_errors"><CODE>$checker->num_errors()</CODE></A> <DD> Set (if argument specified) and retrieve the number of errors found. <DT><A NAME="item_name"><CODE>$checker->name()</CODE></A> <DD> Set (if argument specified) and retrieve the canonical name of POD as found in the <CODE>=head1 NAME</CODE> section. <DT><A NAME="item_node"><CODE>$checker->node()</CODE></A> <DD> Add (if argument specified) and retrieve the nodes (as defined by <CODE>=headX</CODE> and <CODE>=item</CODE>) 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. <DT><A NAME="item_idx"><CODE>$checker->idx()</CODE></A> <DD> Add (if argument specified) and retrieve the index entries (as defined by <CODE>X<></CODE>) of the current POD. They consist of plain text, each piece of whitespace is collapsed to a single blank. <DT><A NAME="item_hyperlink"><CODE>$checker->hyperlink()</CODE></A> <DD> Add (if argument specified) and retrieve the hyperlinks (as defined by <CODE>L<></CODE>) of the current POD. They consist of an 2-item array: line number and <CODE>Pod::Hyperlink</CODE> object. </DL> <HR> <H1><A NAME="author">AUTHOR</A></H1> Brad Appleton <<A HREF="mailto:bradapp@enteract.com">bradapp@enteract.com</A>> (initial version), Marek Rouchal <<A HREF="mailto:marek@saftsack.fs.uni-bayreuth.de">marek@saftsack.fs.uni-bayreuth.de</A>> Based on code for Pod::Text::pod2text() written by Tom Christiansen <<A HREF="mailto:tchrist@mox.perl.com">tchrist@mox.perl.com</A>> <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%> <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc"> podchecker - check pod documents for syntax errors </TD></TR> </TABLE> </BODY> </HTML>