FM / perl-Pod-Parser

/usr/share/doc/perl-Pod-Parser

Name	Size	Mode	Actions
ANNOUNCE	974	0644	edit dl rm
CHANGES	41185	0644	edit dl rm
README	6351	0644	edit dl rm
TODO	3932	0644	edit dl rm

Edit: /usr/share/doc/perl-Pod-Parser/TODO (3932B)

TO DO
 =====

SHORT TERM
 ----------
 * Remove Pod::PlainText from the PodParser distribution once it has
   replaced Pod::Text (in functin and in name) in the latest stable
   Perl distribution (this is slated to happen for Perl 5.6, its currently
   in 5.005_58 now but thats stil considered a development versin rather
   than "stable").

* Make the test-suite more portable (for Mac + VMS + NT) without having
   to use lots of ugly conditional code. There has to be a better way
   to to dissect and reconstruct filepaths than what 5.004 currently
   offers.

* Add the ability to use callbacks _instead_ _of_ inheritance if so
   desired (or mix+match 'em as you wish). This means that there should
   be a way to use callbacks instead of inheritance for the equivalent
   of each of the abstract base class methods that do text processing
   (like preprocess_xxxxx and {begin,end}_xxxx and others). This will go
   into a module named Pod::Callbacks.

* IMPROVE PERFORMANCE!!! (its getting kind of slow)

* Implement -ranges "option" to Pod::Select & podselect

LONG TERM
 ---------

* Maybe create a Pod::Compiler class that reads a POD and returns a
   list of Pod::Paragraphs objects?

* Make changes necessary to accommodate Kenneth Albanowski's Pod::Simplify
   module so that it may use Pod::Parser.

* See about providing the ability (perhaps via constructor options) to turn
   off certain unwanted Pod::Parser features in order to improve performance
   (things like calling preprocess_xxx() methods and/or some other "virtual"
   member function calls that a subclass might not want to make use of).

* Try to allow the user to provide a callback function/method which could
   be used in place of the parse_paragraph() method and/or the command(),
   verbatim(), and textblock() methods.  Such a callback might be provided
   as a constructor argument to Pod::Parser.  Perhaps it might be possible
   to pass the callback method an array of lines or of paragraphs (rather
   than one input block at a time) if certain options are specified.

* In Pod::Checker, check that =encoding specifies a valid encoding;
   possibly by using the Encode module?

* Add a check of Perl core pods (as suggested by M. Schwern):
   The follow test runs each pod/*.pod file through Pod::Checker and fails
   if there are any warnings or errors.  There are a handful of errors and 
   huge amounts of warnings.
   This patch should not be applied to the main sources until the warnings 
   are cleaned up.

--- t/pod/corepods.t	2002/12/10 22:36:52	1.1
+++ t/pod/corepods.t	2002/12/10 23:21:25
@@ -0,0 +1,22 @@
+#!perl -w
+
+BEGIN {
+    chdir 't';
+    @INC = '../lib';
+}
+
+use Pod::Checker;
+use Test::More;
+use File::Spec;
+
+chdir File::Spec->updir;
+my @podfiles = glob "pod/*.pod";
+plan tests => scalar @podfiles;
+
+my $checker = Pod::Checker->new;
+
+foreach my $podfile (@podfiles) {
+    $checker->parse_from_file($podfile, \*STDERR);
+    is( $checker->num_errors,   0, "podchecker $podfile error check" );
+    is( $checker->num_warnings, 0, "podchecker $podfile warnings check" );
+}

Pod::Checker etc.:

Brad:

* I do not think there should ever be any complaint about the first
   =pod directive being something other than =head (or other than =pod and
   =head) unless some kind of '-strictmanpagestyle' option is set. There is
   no law that says the beginning of ever document has to be a heading.
   Sometimes it useful to have an untitled intro. Now it *is* true that any
   manpage should start with a heading, but not any POD document in general.

=> implement '-manpage' option for Pod::Checker?

Wolfgang Laun:

* =over/=back without intervening =item produces a warning even when
   there are pararaphs in between. But this could be used to produce
   indented paragraphs. Restrict warning to completely empty lists?

=> is this legal POD at all? Currently a warning is printed

cmd: