Paul Kraus wrote:
> Ok if I understand this then if
> --help is called from the page then should display this
> =head1 SYNOPSIS
Nope. The
=head markup tag should not be shown. That is source code, not output. It is a
different style from that called for in program code for a very good reason--to
make distinction instantly and visibly clear.
>
>
> sample [options] [file ...]
>
> Options:
> -help brief help message
> -man full documentation
>
> =head1 OPTIONS
>
> If --man or infact if nothing is passed then the entire pod documents should
> be displayed
> GetOptions('help|?' => \$help, man => \$man) or pod2usage(2);
> Which to me read if help or man is undefined then pod2usage(-verbose => 2)
> Which is called before this line which states to display just the no files
> given message.
> pod2usage("$0: No files given.") if ((@ARGV == 0) && (-t STDIN));
>
> now when I pass in --help I get nothing when I pass in nothing I get the no
> files given message and when I pass in --man I get the entire document. This
> code taken from the pod::usage docs.
>
> #!/usr/bin/perl
>
> 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|?' => \$help, man => \$man) or pod2usage(2);
> print "$help\n";
> print "$man\n";
> pod2usage(-verbose => 0) 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
This doesn't make sense, Paul. A class 1 heading indicates a topic on the same
level of organization as other class 1 headings. Why is this a class 1 if logic
calls for it to be indented.
> =cut
>
> Paul Kraus
POD is certainly a bit clunky and tech-ish in its style, but it doesn't have to
be this mixed up. It has its own conventions, like any protocol. Just respect
them and use the protocol as it was meant to be used. It actually can help
clarify code on a high level, and in combination with good naming conventions
can pretty much obviate any need for commenting. While the POD below is not
written for the reader of the source code, rather for the user of the module,
it does provide a focus for the code to which it refers by describing the
intended effects:
=head2 is_interlaced
Returns a boolean value indicating whether the image is encoded in an
interlaced pattern. This parameter is nmecessary for proper rendering
of the decoded image. If true, the decoded lines should be layed out in
a pattern that first thinly samples the entire veritcal scope of the
image, then fills in the intervening lines with progressively deeper
resolution. The pattern resembles [with progressive passes being more
deeply indented]:
_______ 1
________ 4
________ 3
________ 4
________ 2
________ 4
________ 3
________ 4
_______ 1
=over 4
=item Syntax
$image_map->add_in_pattern if $image_descriptor->is_interlaced;
=back
=cut
sub is_interlaced {
my $self = shift;
return $self->{'interlaced'};
}
When read as per design, the POD above resolves to:
METHODS
... other methods
is_interlaced
Returns a boolean value indicating whether the image is encoded in an
interlaced pattern. This parameter is necessary for proper rendering of
the decoded image. If true, the decoded lines should be layed out in a
pattern that first thinly samples the entire veritcal scope of the
image, then fills in the intervening lines with progressively deeper
resolution. The pattern resembles [with progressive passes being more
deeply indented]:
_______ 1
________ 4
________ 3
________ 4
________ 2
________ 4
________ 3
________ 4
_______ 1
Syntax
$image_map->add_in_pattern if $image_descriptor->is_interlaced;
I am a little unclear about how uasge messages tie in with POD. Usage messages
should probably use straightforward error statements. Error messages are not
documentation, and shouldn't be mixed up with documentation, except possibly to
refer the user to resources providing more detail.
Joseph
--
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
<http://learn.perl.org/> <http://learn.perl.org/first-response>
