revised notes about Pod::Parser & Co.

p4raw-id: //depot/perl@5002

diff --git a/lib/Pod/Usage.pm b/lib/Pod/Usage.pm
index 6e6fb7b..aa3a009 100644 (file)
--- a/lib/Pod/Usage.pm
+++ b/lib/Pod/Usage.pm
@@ -311,22 +311,58 @@ command line syntax error is detected. They should also provide an
 option (usually C<-H> or C<-help>) to print a (possibly more verbose)
 usage message to C<STDOUT>. Some scripts may even wish to go so far as to
 provide a means of printing their complete documentation to C<STDOUT>
-(perhaps by allowing a C<-man> option). The following example uses
-B<Pod::Usage> in combination with B<Getopt::Long> to do all of these
+(perhaps by allowing a C<-man> option). The following complete example
+uses B<Pod::Usage> in combination with B<Getopt::Long> to do all of these
 things:
 
     use Getopt::Long;
     use Pod::Usage;
 
+    my $man = 0;
+    my $help = 0;
     ## Parse options and print usage if there is a syntax error,
     ## or if usage was explicitly requested.
-    GetOptions("help", "man", "flag1")  ||  pod2usage(2);
-    pod2usage(1)  if ($opt_help);
-    pod2usage(-verbose => 2)  if ($opt_man);
+    GetOptions('help|?' => \$help, man => \$man) or pod2usage(2);
+    pod2usage(1) if $help;
+    pod2usage(-verbose => 2) if $man;
 
     ## If no arguments were given, then allow STDIN to be used only
     ## if it's not connected to a terminal (otherwise print usage)
     pod2usage("$0: No files given.")  if ((@ARGV == 0) && (-t STDIN));
+    __END__
+
+    =head1 NAME
+
+    sample - Using GetOpt::Long and Pod::Usage
+
+    =head1 SYNOPSIS
+
+    sample [options] [file ...]
+
+     Options:
+       -help            brief help message
+       -man             full documentation
+
+    =head1 OPTIONS
+
+    =over 8
+
+    =item B<-help>
+
+    Print a brief help message and exits.
+
+    =item B<-man>
+
+    Prints the manual page and exits.
+
+    =back
+
+    =head1 DESCRIPTION
+
+    B<This program> will read the given input file(s) and do something
+    useful with the contents thereof.
+
+    =cut
 
 =head1 CAVEATS
 

diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index a22f75b..59c7571 100644 (file)
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -1535,93 +1535,66 @@ act as mutators (accessor $z->Re(), mutator $z->Re(3)).
 A little bit of radial trigonometry (cylindrical and spherical),
 radial coordinate conversions, and the great circle distance were added.
 
-=item Pod::Parser, Pod::InputObjects, Pod::ParseUtils, and Pod::Select
+=item Pod::Parser, Pod::InputObjects
 
-Pod::Parser is a new module that provides a base class for parsing and
-selecting sections of POD documentation from an input stream.  This
-module takes care of identifying POD paragraphs and commands in the
-input and hands off the parsed paragraphs and commands to user-defined
-methods which are free to interpret or translate them as they see fit.
+Pod::Parser is a base class for parsing and selecting sections of
+pod documentation from an input stream.  This module takes care of
+identifying pod paragraphs and commands in the input and hands off the
+parsed paragraphs and commands to user-defined methods which are free
+to interpret or translate them as they see fit.
 
 Pod::InputObjects defines some input objects needed by Pod::Parser, and
 for advanced users of Pod::Parser that need more about a command besides
-its name and text.  Pod::ParseUtils provides several object-oriented
-helpers for POD parsing and processing. Probably the most important is
-Pod::Hyperlink for parsing and expanding POD hyperlinks.  Pod::Select is
-a subclass of Pod::Parser which provides a function named "podselect()"
-to filter out user-specified sections of raw pod documentation from an
-input stream.
+its name and text.
 
 As of release 5.6 of Perl, Pod::Parser is now the officially sanctioned
 "base parser code" recommended for use by all pod2xxx translators.
 Pod::Text (pod2text) and Pod::Man (pod2man) have already been converted
-to use Pod::Parser and efforts to convert Pod::Html (pod2html) are
-already underway.  For any questions or comments about POD parsing and
-translating issues and utilities, please use the pod-people@perl.org
-mailing list.
+to use Pod::Parser and efforts to convert Pod::HTML (pod2html) are already
+underway.  For any questions or comments about pod parsing and translating
+issues and utilities, please use the pod-people@perl.org mailing list.
 
-For further information, please see L<Pod::Parser>, L<Pod::InputObjects>,
-L<Pod::ParseUtils> and L<Pod::Select>.
+For further information, please see L<Pod::Parser> and L<Pod::InputObjects>.
 
-=item Pod::Usage
+=item Pod::Checker, podchecker
 
-Pod::Usage provides the function "pod2usage()" to print usage messages for
-a Perl script based on its embedded pod documentation.  The pod2usage()
-function is generally useful to all script authors since it lets them
-write and maintain a single source (the PODs) for documentation, thus
-removing the need to create and maintain redundant usage message text
-consisting of information already in the PODs.
-
-Script authors are encouraged to use Pod::Usage with their favorite Perl
-option-parser to provide both terse and verbose formatted usage messages
-for their users.  Here is a simple example using Getopt::Long that prints
-only a synopsis for syntax errors, a synopsis and description of arguments
-when C<-help> is used, and the full manual page when C<-man> is used.
-
-    use Getopt::Long;
-    use Pod::Usage;
-    my $man = 0;
-    my $help = 0;
-    GetOptions('help|?' => \$help, man => \$man) or pod2usage(2);
-    pod2usage(1) if $help;
-    pod2usage(-exitstatus => 0, -verbose => 2) if $man;
-
-    __END__
-
-    =head1 NAME
-
-    sample - Using GetOpt::Long and Pod::Usage
-
-    =head1 SYNOPSIS
-
-    sample [options] [file ...]
-
-     Options:
-       -help            brief help message
-       -man             full documentation
-
-    =head1 OPTIONS
-
-    =over 8
-
-    =item B<-help>
+This utility checks pod files for correct syntax, according to
+L<perlpod>.  Obvious errors are flagged as such, while warnings are
+printed for mistakes that can be handled gracefully.  The checklist is
+not complete yet.  See L<Pod::Checker>.
 
-    Print a brief help message and exits.
+=item Pod::ParseUtils, Pod::Find
 
-    =item B<-man>
+These modules provide a set of gizmos that are useful mainly for pod
+translators.  L<Pod::Find|Pod::Find> traverses directory structures and
+returns found pod files, along with their canonical names (like
+C<File::Spec::Unix>).  L<Pod::ParseUtils|Pod::ParseUtils> contains
+B<Pod::List> (useful for storing pod list information), B<Pod::Hyperlink>
+(for parsing the contents of C<LE<gt>E<lt>> sequences) and B<Pod::Cache>
+(for caching information about pod files, e.g. link nodes).
 
-    Prints the manual page and exits.
+=item Pod::Select, podselect
 
-    =back
+Pod::Select is a subclass of Pod::Parser which provides a function
+named "podselect()" to filter out user-specified sections of raw pod
+documentation from an input stream. podselect is a script that provides
+access to Pod::Select from other scripts to be used as a filter.
+See L<Pod::Select>.
 
-    =head1 DESCRIPTION
+=item Pod::Usage, pod2usage
 
-    B<This program> will read the given input file(s) and do something
-    useful with the contents thereof.
+Pod::Usage provides the function "pod2usage()" to print usage messages for
+a Perl script based on its embedded pod documentation.  The pod2usage()
+function is generally useful to all script authors since it lets them
+write and maintain a single source (the pods) for documentation, thus
+removing the need to create and maintain redundant usage message text
+consisting of information already in the pods.
 
-    =cut
+There is also a pod2usage script which can be used from other kinds of
+scripts to print usage messages from pods (even for non-Perl scripts
+with pods embedded in comments).
 
-For details, please see L<Pod::Usage>.
+For details and examples, please see L<Pod::Usage>.
 
 =item Pod::Text and Pod::Man