From: Gurusamy Sarathy Date: Sun, 6 Feb 2000 14:45:17 +0000 (+0000) Subject: revised notes about Pod::Parser & Co. X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=f48e6a7ed0ae5288c213782f2491a0e6126db30c;p=p5sagit%2Fp5-mst-13.2.git 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 --- 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. Some scripts may even wish to go so far as to provide a means of printing their complete documentation to C -(perhaps by allowing a C<-man> option). The following example uses -B in combination with B to do all of these +(perhaps by allowing a C<-man> option). The following complete example +uses B in combination with B 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 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 --- 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, L, -L and L. +For further information, please see L and L. -=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. 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. - 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 traverses directory structures and +returns found pod files, along with their canonical names (like +C). L contains +B (useful for storing pod list information), B +(for parsing the contents of CE> sequences) and B +(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. - =head1 DESCRIPTION +=item Pod::Usage, pod2usage - B 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. +For details and examples, please see L. =item Pod::Text and Pod::Man