File perl-Pod-Usage.spec of Package perl-Pod-Usage

#
# spec file for package perl-Pod-Usage
#
# Copyright (c) 2025 SUSE LLC
#
# All modifications and additions to the file contributed by third parties
# remain the property of their copyright owners, unless otherwise agreed
# upon. The license for this file, and modifications and additions to the
# file, is the same license as for the pristine package itself (unless the
# license for the pristine package is not an Open Source License, in which
# case the license is the MIT License). An "Open Source License" is a
# license that conforms to the Open Source Definition (Version 1.9)
# published by the Open Source Initiative.

# Please submit bugfixes or comments via https://bugs.opensuse.org/
#


%define cpan_name Pod-Usage
Name:           perl-Pod-Usage
Version:        2.05
Release:        0
License:        Artistic-1.0 OR GPL-1.0-or-later
Summary:        Extracts POD documentation and shows usage information
URL:            https://metacpan.org/release/%{cpan_name}
Source0:        https://cpan.metacpan.org/authors/id/M/MA/MAREKR/%{cpan_name}-%{version}.tar.gz
BuildArch:      noarch
BuildRequires:  perl
BuildRequires:  perl-macros
BuildRequires:  perl(Pod::Perldoc) >= 3.28
BuildRequires:  perl(Pod::Simple) >= 3.40
BuildRequires:  perl(Pod::Text) >= 4.00
Requires:       perl(Pod::Perldoc) >= 3.28
Requires:       perl(Pod::Simple) >= 3.40
Requires:       perl(Pod::Text) >= 4.00
%{perl_requires}

%description
*pod2usage* will print a usage message for the invoking script (using its
embedded pod documentation) and then exit the script with the desired exit
status. The usage message printed may have any one of three levels of
"verboseness": If the verbose level is 0, then only a synopsis is printed.
If the verbose level is 1, then the synopsis is printed along with a
description (if present) of the command line options and arguments. If the
verbose level is 2, then the entire manual page is printed.

Unless they are explicitly specified, the default values for the exit
status, verbose level, and output stream to use are determined as follows:

  * If neither the exit status nor the verbose level is specified, then the
default is to use an exit status of 2 with a verbose level of 0.

  * If an exit status _is_ specified but the verbose level is _not_, then the
verbose level will default to 1 if the exit status is less than 2 and will
default to 0 otherwise.

  * If an exit status is _not_ specified but verbose level _is_ given, then the
exit status will default to 2 if the verbose level is 0 and will default to
1 otherwise.

  * If the exit status used is less than 2, then output is printed on 'STDOUT'.
Otherwise output is printed on 'STDERR'.

Although the above may seem a bit confusing at first, it generally does
"the right thing" in most situations. This determination of the default
values to use is based upon the following typical Unix conventions:

  * An exit status of 0 implies "success". For example, *diff(1)* exits with a
status of 0 if the two files have the same contents.

  * An exit status of 1 implies possibly abnormal, but non-defective, program
termination. For example, *grep(1)* exits with a status of 1 if it did
_not_ find a matching line for the given regular expression.

  * An exit status of 2 or more implies a fatal error. For example, *ls(1)*
exits with a status of 2 if you specify an illegal (unknown) option on the
command line.

  * Usage messages issued as a result of bad command-line syntax should go to
'STDERR'. However, usage messages issued due to an explicit request to
print usage (like specifying *-help* on the command line) should go to
'STDOUT', just in case the user wants to pipe the output to a pager (such
as *more(1)*).

  * If program usage has been explicitly requested by the user, it is often
desirable to exit with a status of 1 (as opposed to 0) after issuing the
user-requested usage message. It is also desirable to give a more verbose
description of program usage in this case.

*pod2usage* does not force the above conventions upon you, but it will use
them by default if you don't expressly tell it to do otherwise. The ability
of *pod2usage()* to accept a single number or a string makes it convenient
to use as an innocent looking error message handling function:

    use strict;
    use Pod::Usage;
    use Getopt::Long;

    ## Parse options
    my %opt;
    GetOptions(\%opt, "help|?", "man", "flag1")  ||  pod2usage(2);
    pod2usage(1)  if ($opt{help});
    pod2usage(-exitval => 0, -verbose => 2)  if ($opt{man});

    ## Check for too many filenames
    pod2usage("$0: Too many files given.\n")  if (@ARGV > 1);

Some user's however may feel that the above "economy of expression" is not
particularly readable nor consistent and may instead choose to do something
more like the following:

    use strict;
    use Pod::Usage qw(pod2usage);
    use Getopt::Long qw(GetOptions);

    ## Parse options
    my %opt;
    GetOptions(\%opt, "help|?", "man", "flag1")  ||
      pod2usage(-verbose => 0);

    pod2usage(-verbose => 1)  if ($opt{help});
    pod2usage(-verbose => 2)  if ($opt{man});

    ## Check for too many filenames
    pod2usage(-verbose => 2, -message => "$0: Too many files given.\n")
      if (@ARGV > 1);

As with all things in Perl, _there's more than one way to do it_, and
*pod2usage()* adheres to this philosophy. If you are interested in seeing a
number of different ways to invoke *pod2usage* (although by no means
exhaustive), please refer to "EXAMPLES".

%prep
%autosetup  -n %{cpan_name}-%{version}

%build
perl Makefile.PL INSTALLDIRS=vendor
%make_build

%check
make test

%install
%perl_make_install
%perl_process_packlist
%perl_gen_filelist

%files -f %{name}.files
%doc Changes README
%license LICENSE

%changelog
Places

File perl-Pod-Usage.spec of Package perl-Pod-Usage

Places
