Update podlators to version 4.03
authorKaren Etheridge <ether@cpan.org>
Sun, 20 Dec 2015 03:08:24 +0000 (19:08 -0800)
committerJames E Keenan <jkeenan@cpan.org>
Sat, 2 Jan 2016 02:17:23 +0000 (21:17 -0500)
70 files changed:
MANIFEST
Porting/Maintainers.pl
cpan/podlators/.gitignore
cpan/podlators/Changes [new file with mode: 0644]
cpan/podlators/Makefile.PL [new file with mode: 0644]
cpan/podlators/bin/pod2man [moved from cpan/podlators/scripts/pod2man.PL with 76% similarity]
cpan/podlators/bin/pod2text [moved from cpan/podlators/scripts/pod2text.PL with 83% similarity]
cpan/podlators/lib/Pod/Man.pm
cpan/podlators/lib/Pod/ParseLink.pm
cpan/podlators/lib/Pod/Text.pm
cpan/podlators/lib/Pod/Text/Color.pm
cpan/podlators/lib/Pod/Text/Overstrike.pm
cpan/podlators/lib/Pod/Text/Termcap.pm
cpan/podlators/t/basic.t [deleted file]
cpan/podlators/t/data/basic.cap [moved from cpan/podlators/t/basic.cap with 100% similarity]
cpan/podlators/t/data/basic.clr [moved from cpan/podlators/t/basic.clr with 100% similarity]
cpan/podlators/t/data/basic.man [moved from cpan/podlators/t/basic.man with 100% similarity]
cpan/podlators/t/data/basic.ovr [moved from cpan/podlators/t/basic.ovr with 100% similarity]
cpan/podlators/t/data/basic.pod [moved from cpan/podlators/t/basic.pod with 100% similarity]
cpan/podlators/t/data/basic.txt [moved from cpan/podlators/t/basic.txt with 100% similarity]
cpan/podlators/t/data/perl.conf [new file with mode: 0644]
cpan/podlators/t/data/snippets/README [new file with mode: 0644]
cpan/podlators/t/data/snippets/man/cpp [new file with mode: 0644]
cpan/podlators/t/data/snippets/man/utf8-nonbreaking [new file with mode: 0644]
cpan/podlators/t/data/snippets/man/utf8-verbatim [new file with mode: 0644]
cpan/podlators/t/data/snippets/text/cpp [new file with mode: 0644]
cpan/podlators/t/data/termcap [new file with mode: 0644]
cpan/podlators/t/devise-date.t [deleted file]
cpan/podlators/t/docs/pod-spelling.t [new file with mode: 0644]
cpan/podlators/t/docs/pod.t [new file with mode: 0644]
cpan/podlators/t/docs/synopsis.t [new file with mode: 0644]
cpan/podlators/t/filehandle.t [deleted file]
cpan/podlators/t/general/basic.t [new file with mode: 0644]
cpan/podlators/t/general/filehandle.t [new file with mode: 0644]
cpan/podlators/t/general/pod-parser.t [new file with mode: 0644]
cpan/podlators/t/lib/Test/Podlators.pm [new file with mode: 0644]
cpan/podlators/t/lib/Test/RRA.pm [new file with mode: 0644]
cpan/podlators/t/lib/Test/RRA/Config.pm [new file with mode: 0644]
cpan/podlators/t/man-heading.t [deleted file]
cpan/podlators/t/man-options.t [deleted file]
cpan/podlators/t/man-perlio.t [deleted file]
cpan/podlators/t/man-utf8.t [deleted file]
cpan/podlators/t/man/basic.t [moved from cpan/podlators/t/man.t with 97% similarity]
cpan/podlators/t/man/devise-date.t [new file with mode: 0644]
cpan/podlators/t/man/devise-title.t [new file with mode: 0644]
cpan/podlators/t/man/empty.t [moved from cpan/podlators/t/man-empty.t with 97% similarity]
cpan/podlators/t/man/heading.t [new file with mode: 0644]
cpan/podlators/t/man/options.t [new file with mode: 0644]
cpan/podlators/t/man/utf8-io.t [new file with mode: 0644]
cpan/podlators/t/parselink/basic.t [moved from cpan/podlators/t/parselink.t with 98% similarity]
cpan/podlators/t/pod-parser.t [deleted file]
cpan/podlators/t/pod-spelling.t [deleted file]
cpan/podlators/t/pod.t [deleted file]
cpan/podlators/t/style/minimum-version.t [new file with mode: 0644]
cpan/podlators/t/style/module-version.t [new file with mode: 0644]
cpan/podlators/t/style/strict.t [new file with mode: 0644]
cpan/podlators/t/text/basic.t [moved from cpan/podlators/t/text.t with 98% similarity]
cpan/podlators/t/text/color.t [moved from cpan/podlators/t/color.t with 98% similarity]
cpan/podlators/t/text/empty.t [moved from cpan/podlators/t/text-empty.t with 96% similarity]
cpan/podlators/t/text/encoding.t [moved from cpan/podlators/t/text-encoding.t with 89% similarity]
cpan/podlators/t/text/options.t [moved from cpan/podlators/t/text-options.t with 95% similarity]
cpan/podlators/t/text/overstrike.t [moved from cpan/podlators/t/overstrike.t with 98% similarity]
cpan/podlators/t/text/perlio.t [moved from cpan/podlators/t/text-perlio.t with 81% similarity]
cpan/podlators/t/text/termcap.t [moved from cpan/podlators/t/termcap.t with 74% similarity]
cpan/podlators/t/text/utf8.t [moved from cpan/podlators/t/text-utf8.t with 82% similarity]
pod/perlpodstyle.pod
t/porting/known_pod_issues.dat
utils/Makefile.PL
utils/pod2man.PL [new file with mode: 0644]
utils/pod2text.PL [new file with mode: 0644]

index 205c83e..b2c0264 100644 (file)
--- a/MANIFEST
+++ b/MANIFEST
@@ -1864,42 +1864,58 @@ cpan/Pod-Escapes/lib/Pod/Escapes.pm     Pod::Escapes
 cpan/Pod-Escapes/t/01_about_verbose.t  test Pod::Escapes
 cpan/Pod-Escapes/t/10_main.t           test Pod::Escapes
 cpan/Pod-Escapes/t/15_name2charnum.t   test Pod::Escapes
+cpan/podlators/bin/pod2man                     Translator to turn pod into manpage
+cpan/podlators/bin/pod2text                    Translator to turn pod into text
+cpan/podlators/Changes                         podlators release notes
 cpan/podlators/lib/Pod/Man.pm                  Convert POD data to *roff
 cpan/podlators/lib/Pod/ParseLink.pm            Perl an L<> formatting code in POD text
 cpan/podlators/lib/Pod/Text/Color.pm           Convert POD data to color ASCII text
 cpan/podlators/lib/Pod/Text/Overstrike.pm      Convert POD data to formatted overstrike text
 cpan/podlators/lib/Pod/Text.pm                 Pod-Parser - convert POD data to formatted ASCII text
 cpan/podlators/lib/Pod/Text/Termcap.pm         Convert POD data to ASCII text with format escapes
-cpan/podlators/scripts/pod2man.PL      Precursor for translator to turn pod into manpage
-cpan/podlators/scripts/pod2text.PL     Precursor for translator to turn pod into text
-cpan/podlators/t/basic.cap                     podlators test
-cpan/podlators/t/basic.clr                     podlators test
-cpan/podlators/t/basic.man                     podlators test
-cpan/podlators/t/basic.ovr                     podlators test
-cpan/podlators/t/basic.pod                     podlators test
-cpan/podlators/t/basic.t                       podlators test
-cpan/podlators/t/basic.txt                     podlators test
-cpan/podlators/t/color.t                       podlators test
-cpan/podlators/t/devise-date.t                 podlators test
-cpan/podlators/t/filehandle.t                  podlators test
-cpan/podlators/t/man-empty.t                   podlators test
-cpan/podlators/t/man-heading.t                 podlators test
-cpan/podlators/t/man-options.t                 podlators test
-cpan/podlators/t/man-perlio.t                          podlators test
-cpan/podlators/t/man.t                         podlators test
-cpan/podlators/t/man-utf8.t                    podlators test
-cpan/podlators/t/overstrike.t                  podlators test
-cpan/podlators/t/parselink.t                   podlators test
-cpan/podlators/t/pod-parser.t                  podlators test
-cpan/podlators/t/pod-spelling.t                        podlators test
-cpan/podlators/t/pod.t                         podlators test
-cpan/podlators/t/termcap.t                     podlators test
-cpan/podlators/t/text-empty.t                  podlators test
-cpan/podlators/t/text-encoding.t               podlators test
-cpan/podlators/t/text-options.t                        podlators test
-cpan/podlators/t/text-perlio.t                 podlators test
-cpan/podlators/t/text.t                                podlators test
-cpan/podlators/t/text-utf8.t                   podlators test
+cpan/podlators/Makefile.PL                     podlators Makefile.PL
+cpan/podlators/t/data/basic.cap                        podlators test                  podlators test
+cpan/podlators/t/data/basic.clr                        podlators test
+cpan/podlators/t/data/basic.man                        podlators test
+cpan/podlators/t/data/basic.ovr                        podlators test
+cpan/podlators/t/data/basic.pod                        podlators test
+cpan/podlators/t/data/basic.txt                        podlators test
+cpan/podlators/t/data/perl.conf                        podlators test
+cpan/podlators/t/data/snippets/man/cpp                 podlators test
+cpan/podlators/t/data/snippets/man/utf8-nonbreaking                    podlators test
+cpan/podlators/t/data/snippets/man/utf8-verbatim                       podlators test
+cpan/podlators/t/data/snippets/README                  podlators test
+cpan/podlators/t/data/snippets/text/cpp                        podlators test
+cpan/podlators/t/data/termcap                  podlators test
+cpan/podlators/t/docs/pod-spelling.t                   podlators test
+cpan/podlators/t/docs/pod.t                    podlators test
+cpan/podlators/t/docs/synopsis.t                       podlators test
+cpan/podlators/t/general/basic.t                       podlators test
+cpan/podlators/t/general/filehandle.t                  podlators test
+cpan/podlators/t/general/pod-parser.t                  podlators test
+cpan/podlators/t/lib/Test/Podlators.pm                 podlators test
+cpan/podlators/t/lib/Test/RRA/Config.pm                        podlators test
+cpan/podlators/t/lib/Test/RRA.pm                       podlators test
+cpan/podlators/t/man/basic.t                   podlators test
+cpan/podlators/t/man/devise-date.t                     podlators test
+cpan/podlators/t/man/devise-title.t                    podlators test
+cpan/podlators/t/man/empty.t                   podlators test
+cpan/podlators/t/man/heading.t                 podlators test
+cpan/podlators/t/man/options.t                 podlators test
+cpan/podlators/t/man/utf8-io.t                 podlators test
+cpan/podlators/t/parselink/basic.t                     podlators test
+cpan/podlators/t/style/minimum-version.t                       podlators test
+cpan/podlators/t/style/module-version.t                        podlators test
+cpan/podlators/t/style/strict.t                        podlators test
+cpan/podlators/t/text/basic.t                  podlators test
+cpan/podlators/t/text/color.t                  podlators test
+cpan/podlators/t/text/empty.t                  podlators test
+cpan/podlators/t/text/encoding.t                       podlators test
+cpan/podlators/t/text/options.t                        podlators test
+cpan/podlators/t/text/overstrike.t                     podlators test
+cpan/podlators/t/text/perlio.t                 podlators test
+cpan/podlators/t/text/termcap.t                        podlators test
+cpan/podlators/t/text/utf8.t                   podlators test
 cpan/podlators/VERSION                         podlators distribution version
 cpan/Pod-Parser/lib/Pod/Find.pm                        find POD documents in directory trees
 cpan/Pod-Parser/lib/Pod/InputObjects.pm                Pod-Parser - define objects for input streams
@@ -5612,6 +5628,8 @@ utils/perlivp.PL          installation verification procedure
 utils/piconv.PL                        iconv(1), reinvented in perl
 utils/pl2pm.PL                 A pl to pm translator
 utils/pod2html.PL              Translator to turn pod into HTML
+utils/pod2man.PL               Convert POD data to formatted *roff input
+utils/pod2text.PL              Convert POD data to formatted ASCII text
 utils/prove.PL                 The prove harness utility
 utils/ptardiff.PL              The ptardiff utility
 utils/ptargrep.PL              The ptargrep utility
index 343698e..2f289d1 100755 (executable)
@@ -933,7 +933,7 @@ use File::Glob qw(:case);
     },
 
     'podlators' => {
-        'DISTRIBUTION' => 'RRA/podlators-2.5.3.tar.gz',
+        'DISTRIBUTION' => 'RRA/podlators-4.03.tar.gz',
         'FILES'        => q[cpan/podlators pod/perlpodstyle.pod],
 
         # The perl distribution has pod2man.PL and pod2text.PL,  which are
index e2a37b5..b7e08fd 100644 (file)
@@ -1,2 +1,12 @@
 /pod2man*
 /pod2text*
+/.travis.yml
+/LICENSE
+/MANIFEST
+/MANIFEST.SKIP
+/META.yml
+/META.json
+/NOTES
+/README
+/THANKS
+/TODO
diff --git a/cpan/podlators/Changes b/cpan/podlators/Changes
new file mode 100644 (file)
index 0000000..a632a0b
--- /dev/null
@@ -0,0 +1,945 @@
+                      User-Visible podlators Changes
+
+podlators 4.03 (2015-12-06)
+
+    Fix tests when POD_MAN_DATE or SOURCE_DATE_EPOCH are already set in
+    the environment.  Thanks, Niko Tyni.  (Debian Bug#807086)
+
+    Continue general improvements and refactoring of the test suite to
+    make it more maintainable and clean out duplicate or unnecessary code.
+
+podlators 4.02 (2015-12-02)
+
+    For versions of Perl prior to 5.11, install the modules into the Perl
+    core module directories, since in those versions site modules did not
+    take precedence over Perl core modules.  Thanks, Peter Rabbitson.
+    (#110024)
+
+podlators 4.01 (2015-12-01)
+
+    [Pod::Text::Termcap] Do not override the TERMPATH environment variable
+    if it's already set.  This should fix the test suite with Term::Cap
+    1.16 (which has a bug in termcap handling if TERMPATH doesn't point to
+    a valid file).  Also document the manipulation of TERMPATH.
+
+    Revert the switch to Module::Build as the build system.  This creates
+    a circular dependency with Module::Build, since it wants a newer
+    version of Pod::Man than in Perl versions prior to 5.10.1.  Instead,
+    add the new metadata to Makefile.PL and stick with a single build
+    system that will also work inside Perl core.
+
+podlators 4.00 (2015-11-28)
+
+    Increase the version number of the package to be larger than any of
+    the previous version numbers of any of the modules, and change all
+    modules to use the same version as the overall podlators package.
+    Switch to a simple decimal version number to avoid complexity with
+    v-strings and portability to old versions of Perl.
+
+    podlators now requires Perl 5.006 or later.  All modules enable
+    warnings.  Please report any unexpected or confusing warnings as bugs
+    in the bug tracker.
+
+    [pod2man] In previous versions, the -r or --release option could be
+    specified without an argument and was interpreted as setting that
+    value to the empty string.  That never made a great deal of sense, and
+    the original change to Perl was apparently because no one realized one
+    could pass the empty string as the argument value.  The argument is
+    now mandatory, but may be the empty string, which will cause some
+    *roff implementations to use the system default.
+
+    Allow any even number of characters to be specified as the quote marks
+    for Pod::Text and Pod::Man (and the corresponding --quotes options of
+    pod2text and pod2man), rather than being artificially limited to one-
+    or two-character quotes.  The first half of the string will be used as
+    the left quote and the second half as the right quote.  This allows
+    Unicode characters or groff escapes like \(lq and \(rq to be used.
+    (Partly addresses #103298)
+
+    [Pod::Man] Attempt to detect if the input came from a pipe and
+    therefore has a completely unhelpful (and nonreproducible) source file
+    name, and diagnose this as an error.  Document that the name option
+    (--name to pod2man) is required when processing POD source from
+    standard input.  (Debian Bug#777405)
+
+    [Pod::Man] Honor the environment variable SOURCE_DATE_EPOCH and use it
+    as the timestamp from which to derive the left-hand footer if the date
+    option is not set, overriding the timestamp of the input file.  This
+    is primarily useful to ensure reproducible builds of the same output
+    file given the same souce and Pod::Man version, even when file
+    timestamps may not be consistent.  Thanks, Niko Tyni.  (Debian
+    Bug#801621)
+
+    [Pod::Man] Honor the environment variable POD_MAN_DATE and use its
+    contents, if set, as the value of the left-hand footer if the date
+    option is not set, overriding the timestamp of the input file.  This
+    was an earlier version of SOURCE_DATE_EPOCH, but has been supported in
+    Debian for a while and doesn't serve exactly the same purpose, so both
+    continue to be supported.  Thanks, Niko Tyni.
+
+    [Pod::Man] The default left-hand footer date is now based on UTC
+    rather than the local time zone to make the output more reproducible.
+    Thanks, Chris Lamb.  (Debian Bug#780259)
+
+    [Pod::Man] Simplify the preamble code for handling the F register and
+    index entries, and add backslashes after the braces in the preamble
+    code for handling the F register to avoid introducing a spurious page
+    break before at the first page with AT&T *roff.  Thanks, Carsten
+    Kunze and Daphne Pfister.  (#92979)
+
+    [Pod::Man] Support setting the left-hand footer to the empty string.
+
+    Fix documentation of the utf8 option to Pod::Man and Pod::Text, and
+    the corresponding -u option to pod2man and pod2text, to reflect that
+    Pod::Simple now autodetects Latin-1 and UTF-8 but warns.
+
+    More clearly document the options that set values in the .TH header in
+    the pod2man and Pod::Man documentation.  Thanks, Guillem Jover.
+    (#103297)
+
+    [Pod::Text] Fix encoding handling in documents that start without an
+    encoding declaration and then declare an encoding partway through.
+    Previously, this would result in attempts to print wide characters if
+    there were non-ASCII characters in the document.  Thanks, Magnolia K.
+    (#101722)
+
+    [Pod::Text] Change the documentation to not say Pod::Text only
+    generates ASCII text.  (#89355)
+
+    Switch the preferred module build system to Module::Build, but still
+    provide a Makefile.PL file for backward compatibility and for the use
+    of Perl core.  (#108714)
+
+    Installation of this package no longer tries to overwrite the Pod::Man
+    and Pod::Text modules that come with Perl core, and instead relies on
+    the normal precedence rules in Perl's module search path that prefer
+    locally-installed modules over core modules.
+
+    Rename NEWS to Changes to match the normal Perl convention.
+
+    Work around a bug in Term::Cap 1.16 that caused the test suite to fail
+    by forcing a setting of TERMPATH to a termcap file provided by the
+    test suite while running tests.  (#98272)
+
+podlators 2.5.3 (2013-10-05)
+
+    Fix documentation of the default for the errors constructor parameter.
+
+    Skip the empty text and man page errors tests if Pod::Simple didn't
+    produce any errors, which happens with the version shipped with Perl
+    versions prior to 5.18.  Catch warnings as well as exceptions in these
+    tests.
+
+podlators 2.5.2 (2013-09-22)
+
+    The parse_lines and parse_string_document methods in Pod::Man and
+    Pod::Text now set a default output file handle of STDOUT if none was
+    set.
+
+    Perform document initialization even if the document is contentless.
+    Documents with only errors are shown as contentless but then have a
+    POD ERRORS section, and previously this led to internal errors because
+    state variables weren't properly initialized.  Thanks, Andreas Koenig.
+    (#88724)
+
+    Apply various optimization improvements from Dagfinn Ilmari Mannsåker.
+    There should be no changes in the output.  (#83253)
+
+    Fix an erroneous output_fh reference in the Pod::Man documentation.
+    Thanks, Andreas Koenig.  (#88723)
+
+    Fix various comment typos.  Thanks, David Steinbrunner.  (#85683)
+
+    In perlpodstyle, wrap verbatim license line in POD that was over 79
+    characters after the man page indentation.  Thanks, Brian Gottreu and
+    Steve Hay.  (#87440)
+
+podlators 2.5.1 (2013-02-27)
+
+    Adjust the tag width tests and the list handling tests to avoid
+    spurious warnings from Pod::Simple about mismatched =item types.
+
+podlators 2.5.0 (2013-01-02)
+
+    Support a new errors option in Pod::Man and Pod::Text.  Valid values
+    are die, stderr, pod, and none.  Convert the stderr option to the
+    errors option with value stderr.  Add the corresponding --errors
+    option to pod2man and pod2text.  (#39007)
+
+    Add a new nourls option to Pod::Man and Pod::Text to suppress the URL
+    from L<> formatting codes that contain anchor text, and add the
+    corresponding --nourls option to pod2man and pod2text.  (#62210)
+
+    [Pod::Man] Extend a small-caps section through the punctuation that
+    commonly appears in license disclaimers so that small caps isn't
+    turned on and off at the boundaries of every word, producing
+    unreadable *roff.
+
+    [Pod::Man] Collapse consecutive whitespace and remove newlines in
+    index term text.  Thanks, Kevin Ryde.  (#82332)
+
+podlators 2.4.2 (2012-06-01)
+
+    Remove the test of a POD document without an encoding.  We previously
+    tested that this interpreted the document as ISO 8859-1, but
+    Pod::Simple behavior has changed so that the test started failing,
+    plus Pod::Simple now warns about a missing =encoding.  (#77553)
+
+podlators 2.4.1 (2012-05-30)
+
+    Fix detection of PerlIO UTF-8 handling by requesting details on PerlIO
+    layers to look for the UTF8 flag, which is not a layer in its own
+    right.  Thanks, Leon Timmermans.  (#76440)
+
+    [Pod::Man] Fix handling of the F register when processing multiple
+    documents at once.  .IX will now continue to be defined for documents
+    after the first, and the page number will not be reset at the start of
+    each document.  Thanks to Nicholas Clark for the analysis.  (perl
+    #103202)
+
+    In the pod2man and pod2text driver scripts, report an error and remove
+    the empty output file if the input file had no content (if it did not
+    exist, for example).  Exit with non-zero status if there were any
+    errors.  Track contentless status inside Pod::Man and Pod::Text.
+    Thanks, Dmitry Smirnov.  (#75099)
+
+    Override parse_file in Pod::Man and Pod::Text to set output_fh to
+    STDOUT if it is not already set.  (#77530)
+
+    [Pod::Man] Format the URL text before comparing it to the anchor when
+    deciding whether to show separate anchor text.  This avoids spurious
+    mismatches between the URL target and anchor text because the anchor
+    text was already formatted and has (for example) hyphens escaped.
+    (#76396)
+
+    [Pod::Man] Define \*(C` and \*(C' to the empty string when processed
+    through troff to avoid groff warnings.  Avoid warnings from checking
+    the F register (used to enable index output) when running under groff.
+    Patch from Bjarni Ingi Gislason.  (#75434)
+
+    [Pod::Man] Fix the ASCII fallback string for the AE ligature to use
+    the string that was actually defined.
+
+    Stop removing pod2man and pod2text on make realclean, left over from
+    when they were generated from *.PL scripts.  (#74848)
+
+    Embed the PID in file names generated by the test suite to avoid
+    conflicts when running the test suite in parallel.  (#62083)
+
+podlators 2.4.0 (2010-10-10)
+
+    Switch UTF-8 output encoding to use Encode directly instead of adding
+    a PerlIO layer.  Probe the PerlIO layers with protection for Perl
+    versions without PerlIO and set a flag indicating whether we also need
+    to encode, to avoid double-encoding when writing to a file handle that
+    is already doing UTF-8 encoding via PerlIO.
+
+    [Pod::Man] Do not strip escaped trailing whitespace such as that
+    created by S<> at the end of a line, since the backslash is then taken
+    by *roff as escaping the newline.  Thanks, Kevin Ryde.  (#61781)
+
+    Add perlpodstyle, a new style guide for POD documentation, split
+    mostly from the NOTES section of the pod2man man page.  Remove the
+    NOTES section of pod2man's documentation.
+
+    Convert pod2man and pod2text from scripts generated from *.PL files to
+    simple scripts, relying on ExtUtils::MakeMaker to handle replacing the
+    #! path during the package build.
+
+podlators 2.3.1 (2010-02-17)
+
+    Increase $VERSION in Pod::Text::Color and Pod::Text::Termcap, missed
+    in the previous release.
+
+podlators 2.3.0 (2009-12-28)
+
+    Support anchor text for L<> links of type URL by rendering the anchor
+    text and then the URL in angle brackets.  Now requires Pod::Simple
+    3.06 or later.
+
+    [Pod::Text] When formatting item tags, use the width of the tag
+    without formatting codes.  This fixes formatting issues with
+    Pod::Text::Color, Pod::Text::Termcap, and Pod::Text::Overstrike.
+
+    [Pod::Man] Suppress all formatting in the NAME section to avoid
+    confusing lexgrog and fix mishandling of C<> markup in NAME.  Clarify
+    in the pod2man documentation that no markup should be used in the NAME
+    section of a manual page.  Thanks, Niko Tyni.
+
+    [Pod::Man] Escape backslashes in the quoted text of .IX macros
+    generated from X<> formatting code.
+
+    [Pod::Man] Avoid using POSIX::strftime because POSIX requires Fcntl,
+    which is an XS module, and hence can't build in miniperl.  This allows
+    ExtUtils::MakeMaker to build as a normal module in Perl core.  Thanks,
+    Michael G Schwern.
+
+    [Pod::ParseLink] Allow anchor text for URLs.  Fix the check of the
+    anchor text to not think no text was provided when the text was "0".
+
+    Remove the temporary files created by the test suite in a loop to
+    ensure that all versions are deleted on VMS.  Thanks, John
+    E. Malmberg.
+
+    Convert the test suite to Test::More.
+
+podlators 2.2.2 (2009-01-17)
+
+    [Pod::Text] Correctly handle indentation of verbatim paragraphs that
+    contain lines with only whitespace.  Thanks, Renee Baecker.
+
+podlators 2.2.1 (2008-12-19)
+
+    [Pod::Text] In the legacy pod2text method, properly initialize the
+    output file handle when called with only one argument.  Thanks,
+    Michael G Schwern.
+
+    Fix the t/text-encoding.t test on Windows by setting raw encoding on
+    the output file handle.  Thanks, Steve Hay.
+
+podlators 2.2.0 (2008-10-05)
+
+    [Pod::Text] Try to preserve the previous behavior of setting the
+    output encoding to match the input encoding if utf8 is not set, but
+    support forcing an output encoding of utf8 with the utf8 option.  Add
+    a corresponding --utf8 option to pod2text.  Document the PerlIO
+    limitations of the current utf8 support.
+
+    Quote all module version numbers to preserve any trailing zeroes.
+
+    Skip spelling tests unless RRA_MAINTAINER_TESTS is set in the
+    environment.  Spelling dictionaries are too different between systems.
+
+podlators 2.1.4 (2008-09-21)
+
+    Support aspell as a spell checker for spelling tests.
+
+    Skip UTF-8 tests for versions of Perl prior to 5.8.
+
+podlators 2.1.3 (2008-09-14)
+
+    Add a stderr option to Pod::Man and Pod::Text that sends POD errors to
+    standard error instead of adding a POD ERRORS section to the generated
+    documentation.  Add a corresponding --stderr option to pod2man and
+    pod2text.
+
+    [Pod::Man] Stop remapping the code point for non-breaking space.  This
+    should not be necessary and was wrong when the string from Pod::Simple
+    was a character string and not a byte string.  It was papering over a
+    bug in setting the encoding of an input POD file.
+
+    In the test suite, properly set encoding on file descriptors so that
+    the UTF-8 tests are handled with the correct encoding.  Test that
+    non-breaking spaces don't interfere with hyphen detection.
+
+podlators 2.1.2 (2008-07-20)
+
+    [Pod::Man] Use .SS instead of a local .Sh macro for subheadings, and
+    stop defining .Sh.
+
+    [Pod::Man] Remap ISO 8850-1 non-breaking spaces produced by
+    Pod::Simple to the corresponding UTF-8 code point for UTF-8 output.
+
+    Add a test for spelling and fix multiple spelling and markup errors.
+
+podlators 2.1.1 (2008-07-03)
+
+    [Pod::Man] Do not include the accent mark definitions in generated
+    *roff if the output is in UTF-8.
+
+    Fix the test for S<> handling with all whitespace to not give a
+    spurious failure with Pod::Simple 3.06.
+
+podlators 2.1.0 (2008-06-01)
+
+    Add a new utf8 option to Pod::Man.  If set, do not convert non-ASCII
+    characters to *roff escapes or X, and instead output literal UTF-8
+    characters.  Add a new --utf8 option to pod2man.
+
+    [Pod::Man] Match text between \f(CW and \fP or \fR in headings
+    non-greedily to get the fonts right with multiple C<> formatting
+    codes.
+
+    [Pod::Man] Protect .Sh text against leading *roff control characters
+    since some *roff implementations apparently "look through" font
+    escapes at the beginning of lines.
+
+    [Pod::Man] Escape backslashes separately from processing non-ASCII
+    characters and do that, dash escaping, and underscore adjustment
+    before processing non-ASCII characters.  Otherwise, we escape the
+    hyphen in eth characters.
+
+podlators 2.0.6 (2007-11-28)
+
+    [Pod::Man] Escape apostrophes and backquotes in verbatim and C<> text.
+
+    [Pod::Man] Define the IX macro to empty rather than leaving it
+    undefined when indexing is not requested to eliminate warnings when
+    groff warnings are enabled.
+
+    [Pod::Man] Simplify the logic to skip lib directories to avoid Perl
+    warnings and unnecessary checks.
+
+podlators 2.0.5 (2006-09-16)
+
+    Accept and mostly ignore a hash of options as the first option to
+    parse_from_file.  Support an option of -cutting and configure
+    Pod::Simple to assume the POD has already started.  This is for
+    backward compatibility with Pod::Parser.
+
+    [Pod::Man] Recognize more uses of hyphens in regular English text and
+    allow them to be regular hyphens.
+
+    [Pod::Man] Turn off hyphenation and, for nroff, justification after
+    the .TH macro since that's where groff turns them on.
+
+    [Pod::Man] Stop mapping vertical bar to \(bv, since it produces
+    Unicode characters where they aren't desirable.  Remove the preamble
+    reference to the Tr string, which was never defined.
+
+podlators 2.0.4 (2006-02-19)
+
+    [Pod::Man] Pod::Simple's source_filename method returns garbage if
+    we're parsing from a file handle, so use the current time if stating
+    the returned input file fails.
+
+    Add parse_from_filehandle methods to Pod::Man and Pod::Text for
+    backward compatibility with the earlier versions based on Pod::Parser.
+
+podlators 2.0.3 (2006-01-28)
+
+    In the test suite, pass in a file handle for Pod::Simple output and
+    then close it afterwards.  This works around Pod::Simple leaving file
+    handles open and preventing removal of temporary files on Windows.
+    This is temporary until a new Pod::Simple release offers a better
+    approach.
+
+podlators 2.0.2 (2006-01-25)
+
+    In the parse_from_file method, flush the output file handle rather
+    than closing it.  Closing it is unexpected and could break callers.
+
+    In Pod::Text::Termcap and Pod::Text::Color, Use additional temporary
+    variables to avoid ${char}{0,$width}, which only works in very recent
+    Perls.
+
+    Fix man test that needs an ISO 8859-1 encoding.
+
+podlators 2.0.1 (2006-01-20)
+
+    Call reinit before calling the Pod::Simple parse_from_file method to
+    preserve the previous capability of reusing the same Pod::Man object
+    for multiple documents.  Close the output file handle after
+    Pod::Simple returns to force the output to flush.
+
+    [Pod::Text] The legacy pod2text method was broken because
+    Pod::Simple's parse_file method only takes one argument.  Pass the
+    second argument to output_fh instead.
+
+    Fix portability issues with Perl 5.005.
+
+    Use a single object for all conversions in pod2man and pod2text for a
+    minor speedup.
+
+podlators 2.00 (2005-11-28)
+
+    Rewrite all modules and driver scripts to use Pod::Simple instead of
+    Pod::Parser.  The output should be identical except that C<> with no
+    content outputs quotes for Pod::Text-based parsers, E<> handling is
+    improved, and various small bugs have been fixed.  Thanks, Sean Burke.
+
+    [pod2man] Create a new parser for each file since Pod::Simple parsers
+    are not reusable.
+
+    [pod2text] Add support for multiple pairs of input and output files,
+    similar to pod2man.
+
+    [Pod::Man] Strip vendor_perl as well as site_perl when determining the
+    man page title.  Thanks, Alexey Tourbin.
+
+    Fall back on fullstop_space_harden if preserve_whitespace is not
+    available, for compatibility with older Pod::Simple.
+
+    Count text lengths correctly when wrapping in Pod::Text::Color and
+    Pod::Text::Termcap when there are multiple adjacent escape sequences.
+    Use a temporary variable to make the regex clearer.
+
+    Change section ordering in some documentation following perl5-porters
+    discussion.
+
+    Remove obsolete documentation caution against enclosing URLs in L<>.
+
+    Force a particular terminal configuration to get reliable results in
+    the Pod::Text::Termcap test suite.
+
+    Enhance the test suite substantially with additional tests from Sean
+    Burke.
+
+podlators 1.27 (2003-07-09)
+
+    [Pod::Text::Termcap] Handle the case where the HOME environment
+    variable isn't set, mostly for Windows.
+
+podlators 1.26 (2003-03-30)
+
+    [Pod::Man] Make sure the module returns 1 to keep Perl 5.8.0 happy.
+
+podlators 1.25 (2003-01-04)
+
+    [Pod::Man] Track the type of items in an =over list and only map
+    asterisk to a real bullet if the item type is bullet.  Fix a bug where
+    =item 0 was treated the same as =item with no tag.
+
+podlators 1.24 (2002-08-03)
+
+    Support a margin option in Pod::Text and use it to set the initial
+    indentation level.  Fix handling of the colon in the margin when the
+    alt format is enabled.  Add a new -m option to pod2text to set the
+    margin.
+
+podlators 1.23 (2002-07-14)
+
+    Clean up some old-style L<> links in pod2text that were workarounds
+    for fixed bugs in Pod::Man and Pod::Text.
+
+    Add a pointer to the module web site in the documentation.
+
+podlators 1.22 (2002-06-23)
+
+    Tweak the regex for matching numbers in C<> to not consider a single
+    period to be a number, which affects whether surrounding quotes are
+    added.
+
+podlators 1.21 (2002-02-16)
+
+    [Pod::Text::Overstrike] Fix the regex for wrapping lines to use a
+    non-backtracking section for each character to avoid exponential
+    backtracking on lines with a lot of markup.
+
+podlators 1.20 (2002-01-27)
+
+    [Pod::Text::Overstrike] Use [\b] instead of \cH in regexes to match
+    backspaces, for platforms that use EBCDIC where \b and \cH aren't the
+    same character.
+
+podlators 1.19 (2002-01-02)
+
+    [Pod::Man] Do not apply guesswork to the text inside the NAME section,
+    since it may confuse programs like catman.  Do not output .UC after
+    the .TH macro.  catman doesn't like anything between the NAME section
+    and .TH, and .UC doesn't appear to actually do anything on any modern
+    platform.
+
+    [Pod::Man] Correctly handle a verbatim paragraph right before a
+    heading.
+
+    [Pod::Text] Fix error reporting for unknown sequences and unknown
+    commands to be more consistent and update the documentation to match.
+
+    [Pod::Text::Termcap] Terminal speed should be a number, not a string.
+    Also fall back on a hard-coded terminal speed if getospeed doesn't
+    work.
+
+podlators 1.18 (2001-11-30)
+
+    [Pod::Text::Termcap] Fall back on a hard-coded terminal speed if
+    POSIX::Termios doesn't work, such as on VMS.
+
+    [Pod::ParseLink] Escape L<> in the NAME section of the documentation.
+
+podlators 1.17 (2001-11-27)
+
+    [Pod::Man] Return references to arrays rather than references to
+    scalars for already-formatted text.  There are too many odd bugs with
+    scalar references in older versions of Perl.  No longer bless
+    references since the current Pod::Parser doesn't require it.  Now
+    requires Pod::Parser 1.13 or later.
+
+    Change all documentation references from interior sequences to
+    formatting codes to match the terminology of perlpodspec.
+
+    [Pod::Text::Termcap] Fix an incorrect heading in the documentation.
+
+podlators 1.16 (2001-11-26)
+
+    Use an @INC path of ../lib and a new function to find source files for
+    when the module test suite is being run as part of the Perl core
+    tests.
+
+podlators 1.15 (2001-11-26)
+
+    [Pod::Text::Termcap] Wrap the call to Term::Cap with eval because it
+    throws exceptions if the terminal can't be found.  Fall back on the
+    ANSI escape sequences rather than dying if the termcap entry is
+    incomplete.  Note the fallback in the documentation.
+
+    Delete the lax option in pod2man before calling Pod::Man and document
+    that it is obsolete and podchecker should be used instead.
+
+    Improve the pod2man and Pod::Man documentation to refer to podchecker,
+    add discussion of guesswork and 8-bit character handling, and mention
+    the fragility of the heuristics.
+
+podlators 1.14 (2001-11-23)
+
+    [Pod::Text::Overstrike] Interpolate before formatting to prevent the
+    formatting codes from ending up in the output, and strip any existing
+    formatting before applying new formatting.
+
+    [Pod::Man] Use font escapes rather than .I to avoid strange problems
+    with quoting, at least for =head3.  =head1 and =head2 likely still
+    have troubles with repeated double-quotes.  Fix all fixed-width font
+    changes for nroff, not just the simple ones, and don't hard-code the
+    value of any fixed-width font.
+
+    [Pod::Man] Improve and simplify the handling of indentation shifts.
+
+    [Pod::Man] When intuiting the man page name for a module, also strip
+    $^O by itself as a directory component even when not preceeded or
+    followed by a dash and other text.
+
+    [Pod::Text] Fix handling of =for or =begin/=end in =item paragraphs.
+    Default to a tag of "*" if none is given.  Insert some whitespace for
+    empty item paragraphs to keep them from blending into subsequent text.
+
+    [Pod::ParseLink] Fix a bug in the handling of link text that's
+    entirely in quotes.  Double quotes are now only removed around
+    sections, not names.  Text enclosed entirely in double quotes is
+    interpreted as a link to a section.
+
+    Fix various -w warnings.
+
+podlators 1.13 (2001-11-15)
+
+    Fix -w warnings with hyphen handling.
+
+podlators 1.12 (2001-11-15)
+
+    Add a new module, Pod::ParseLink, to parse the contents of an L<>
+    sequence.  Use it everywhere.  Defer expansion of formatting escapes
+    inside L<> until after L<> is processed.  Surround URLs with angle
+    brackets in the output.
+
+    Remove the special handling of consecutive L</section> links.
+
+    Support E<apos>, E<nbsp>, and E<shy>.
+
+    [Pod::Man] Completely rewrite the name parsing code for modules to use
+    File::Spec.  In the process, fix a bug in dealing with the new
+    three-component version number directories.  Swap the order of date
+    and release in the .TH line to better comply with the man macro
+    documentation.
+
+    [Pod::Man] Rewrite the handling of dashes and hyphens.  Be much more
+    conservative about which hyphens are turned into dashes, and make all
+    hyphens non-breaking unless we can be fairly sure that they're inside
+    normal words.
+
+    [Pod::Man] Handle indentation of =item-less =over/=back blocks.
+
+    [Pod::Man] Include the version of Pod::Parser in the header.
+
+    [Pod::Man] Only try to determine a module name from the path for the
+    man page name if the man page we're generating is in section 3.
+
+    [Pod::Man] No longer insert a timestamp into the generated man page;
+    it just causes unnecessary differences and merge conflicts.
+
+    [Pod::Text] Inside S<>, convert all whitespace to non-breaking spaces,
+    not just spaces.
+
+    Add the --name option to pod2man and document the name option in
+    Pod::Man.
+
+    [Pod::Man] Use L<> for all man page references in the documentation
+    that should be highlighted.  Switch the rest to bold versions of the
+    program name.  Change func(n) to func(3) in the example of things that
+    are automatically formatted so that it will be formatted.  Remove from
+    BUGS the note that some of the path mangling assumes Unix directory
+    separators.  Don't give anchor text for L<> links that no longer
+    require it.
+
+    Update the documentation in Pod::Text and subclasses to use
+    now-allowable POD constructs like C<< >>.  Don't escape angle brackets
+    that don't require escaping.  Don't give anchor text for L<> links
+    that no longer require it.
+
+podlators 1.11 (2001-10-20)
+
+    Add the code option to Pod::Text to include the non-POD text of the
+    input file and document it.  Add the corresponding --code flag to
+    pod2text.
+
+    Converted warnings for unknown escapes, unknown sequences, and
+    unmatched =back into warnings from carps and include the file and line
+    number of the POD data instead of the Perl code.
+
+    [Pod::Text::Overstrike] Better handle the case where a highlighted
+    portion of text ends a line.
+
+    Add --verbose flag to pod2man to print out each output file as it is
+    generated.
+
+    [Pod::Man] Fix *roff syntax error from using .if with .el during quote
+    handling.
+
+    [Pod::Man] Fix output for X<> sequences.
+
+podlators 1.10 (2001-07-10)
+
+    Add heuristics to decide whether to quote the argument of C<>.
+
+    [Pod::Man] Remove font changes for nroff with C<> to work around a bug
+    in the Solaris 2.6 version of nroff's handling of \fP in headings.  No
+    longer add an extra level of quoting for =item; it isn't necessary.
+
+    [Pod::Man] Remove the logic turning PI into a pretty pi character.  It
+    produces too many false positives.
+
+    [Pod::Man] Remove the definition .Ip from the preamble.  Remove .bd B
+    3 from the preamble; this isn't part of the accent mark definitions
+    but instead changes the way bolding is done, confusing some other
+    translators.  Use .IP instead of .Ip everywhere.
+
+    In the POD style section of pod2man, add a description of the
+    COPYRIGHT AND LICENSE section, add a mention of a mailing list in SEE
+    ALSO, and mention that large logs are better kept separate from
+    HISTORY in the description of a standard manual page.
+
+    Standardize on COPYRIGHT AND LICENSE for licensing information across
+    all of the package documentation.
+
+podlators 1.09 (2001-04-09)
+
+    [Pod::Man] Fine-tune formatting guesswork.  Don't allow colons after
+    sequences to put in small caps since they're already handled by being
+    rolled into the sequence and were causing weird things to happen in
+    references to functions.  Allow small caps before an open paren.
+    Teach the handling of functions and manual page references about small
+    caps escapes, and be pickier about what constitutes a manual page
+    reference.
+
+    [Pod::Text] Fix again the incorrect mappings for E<Iacute> and
+    E<iacute>, and this time for E<Igrave> and E<igrave> too.  Thanks,
+    Sean Burke.
+
+podlators 1.08 (2001-02-09)
+
+    Output anything that looks like a URL verbatim rather than
+    interpreting it as a manual page reference.
+
+podlators 1.07 (2001-01-16)
+
+    [Pod::Man] Remove newlines from heading contents.
+
+    [Pod::Man] Quote the file name in the man page header if it contains
+    spaces.
+
+podlators 1.06 (2000-12-25)
+
+    New Pod::Text::Overstrike contributed by Joe Smith.  Add -o or
+    --overstrike to pod2text to use it for formatting.
+
+    [Pod::Man] =item text requires another level of quoting of double
+    quotes, which was already present but not working for C<> text because
+    it was in the wrong order.  Fix.
+
+podlators 1.05 (2000-11-18)
+
+    Change the default quote character for C<> to be double quotes rather
+    than matched left/right single quotes.
+
+    Add support for =head3 and =head4.
+
+    Allow pod2man to take multiple pairs of input and output files on the
+    command line to decrease the time that it takes to process all of
+    Perl's documentation.
+
+    [Pod::Man] Switch \*C` and \*C' sequences from C<> as well as literal
+    double-quotes if the quote character contains double quotes.  Not
+    doing this was causing weird output on some systems in some
+    circumstances.  Use a separate quote mapping function for text blocks
+    to work around a Solaris 2.6 nroff bug.
+
+    [Pod::Man] Use \fP to switch back to the default font rather than
+    changing back to \fR so that font changes work correctly in headings
+    using a different font.  Sprinkle \fP through all font changes so that
+    the default font is always the "previous" font so that the above
+    works.
+
+podlators 1.04 (2000-10-09)
+
+    [Pod::Man] Output .PD 0 and .PD around repeated =item tags so that
+    they're formatted without intervening blank lines, improving
+    formatting of, e.g., perlfunc.pod.
+
+    [Pod::Text] Fix incorrect mappings for E<Iacute> and E<iacute>.
+    Thanks, Sean Burke.
+
+podlators 1.03 (2000-09-03)
+
+    Support configuration of what quote characters to use around C<>
+    text.  Add a new --quotes option to pod2man and pod2text.
+
+    Report nicer errors when encountering an unknown paragraph command.
+
+    Add support for E<sol> and E<verbar>.
+
+    [Pod::Man] Fix the regex for stripping bullets from index entries so
+    that it doesn't strip a leading "o".
+
+    [Pod::Man] In the prelude, terminate the .IX definition with ".."
+    instead of ".    ." for groff.
+
+    [Pod::Text] The pod2text method, when given two arguments, was
+    incorrectly assigning to $_[0], causing other sane problems.  Fix.
+
+podlators 1.02 (2000-04-25)
+
+    [Pod::Man] Fix hyphens and underscores only in literal C<> content,
+    fixing mangling of hyphens and underscores that are the result of
+    other sequence processing.
+
+podlators 1.01 (2000-03-30)
+
+    Install the modules in the Perl core area if the Perl version is 5.6.0
+    or higher.
+
+    [Pod::Man] Strip a leading lib/ from a file name for module man pages,
+    needed for ExtUtils::MakeMaker.
+
+podlators 1.00 (2000-03-16)
+
+    This has now been incorporated into Perl core as pod2man and pod2text.
+    Rename pod2roff to pod2man accordingly.
+
+    Hide "-" arguments to the driver scripts from Getopt::Long so that
+    Pod::Parser will interpret them as STDIN or STDOUT.
+
+    [Pod::Man] Protect any line that starts with a backlash and leading
+    periods following font escapes.  Replace embedded newlines in titles
+    with spaces.
+
+    [Pod::Man] Use "perl v5.6.0" instead of "perl 5.6, patch 0" for the
+    default release string, handle both pre-5.6 and post-5.6 version
+    numbering schemes.  Zero-pad the month and day in the modification
+    date.  Avoid warnings when center, date, or release aren't set.
+
+    [Pod::Man] Allow for two-character fonts.
+
+    [Pod::Man] Work around a Perl 5.6 bug affecting L<> text generation.
+    Fix Z<> handling with current Perl.
+
+    [Pod::Man] Make filename munging safe even when $* is set and the
+    filenames contain embedded newlines.
+
+    [Pod::Man] Fix the regex to concatenate multiple L<> section links and
+    fix whitespace handling for it around "and".
+
+    [Pod::Text] Add the remaining ISO 8859-1 HTML entities.  Thanks, Tim
+    Jenness.
+
+    [pod2man] Change Getopt::Long config from bundling to
+    bundling_override so that options like -center work for backwards
+    compatibility.
+
+    [pod2text] Don't default to Pod::Text::Termcap even if STDOUT is a tty
+    until it works right on Windows, VMS, etc.
+
+podlators 0.08 (1999-10-07)
+
+    Add support for numeric E<> escapes.
+
+    [Pod::Man] Fix doubled quotes in links to sections.
+
+    [Pod::Text] Export pod2text for backwards compatibility.
+
+    [pod2roff] Fix argument passing to Pod::Parser to use an expanded hash
+    instead of a hash reference.
+
+podlators 0.07 (1999-09-25)
+
+    [Pod::Man] Change the parsing model so that, rather than deferring E<>
+    escapes until just before output, *roff output is generated by the
+    interior sequence parsing and the result is passed up the parse trees
+    as Pod::Man::String objects instead of scalars to mark the output as
+    already processed.  In the process, clean up what *roff escaping and
+    guesswork is applied where, and clean up the whole process of applying
+    guesswork.  Improve the escaping of dashes and hyphens to use a single
+    pass.
+
+    [Pod::Man] Improve the small caps guesswork to allow for more cases,
+    including several adjacent all caps words.
+
+    [Pod::Man] Fix some bugs with the link text generation for man page
+    references.
+
+    [Pod::Man] Improve the index generation slightly.
+
+    [Pod::Man] Fix several places that were clobbering the caller's $_.
+
+podlators 0.06 (1999-09-20)
+
+    Add pod2roff and Pod::Man, which convert POD to man pages.
+
+    Rename pod2txt to pod2text and Pod::PlainText to Pod::Text.
+
+    [Pod::Text] =begin text blocks are now output verbatim rather than
+    interpreted as POD.
+
+    [Pod::Text] Document the oddity with Ctrl-As as a restriction.
+
+    [Pod::Text] Always treat =for paragraphs as verbatim text.
+
+    [Pod::Text::Color] Add a BUGS note that the implementation is rather
+    incomplete, and document the reliance on Term::ANSIColor.
+
+    [pod2text] Add an explicit check for Term::ANSIColor if -c was given.
+
+    [Pod::Man] Add a BUGS entry for index entries for stuff in NAME.
+
+    [Pod::Text] Document two more diagnostics and a cross-reference to
+    pod2text.
+
+    [pod2text] Add documentation of -h and expand the DIAGNOSTICS section
+    to include directly-generated error messages and the most common
+    Getopt::Long message.
+
+podlators 0.05 (1999-09-18)
+
+    [Pod::Text::Color] Rename Pod::SimpleText to Pod::PlainText in one
+    more place in the documentation.
+
+podlators 0.04 (1999-08-30)
+
+    Use File::Spec during the build to build file paths for portability,
+    and remove the dist setting since current Perls get this right.
+
+    Fix the #! line in pod2txt during the build.
+
+podlators 0.03 (1999-08-30)
+
+    Rename Pod::SimpleText to Pod::PlainText.
+
+    [pod2txt] Document that Pod::Text::Termcap is used by default if
+    STDOUT is a tty.  Clarify the documentation of --loose.
+
+podlators 0.02 (1999-07-29)
+
+    Rename the package itself from Pod::SimpleText to podlators.
+
+    [Pod::SimpleText] Add a pod2text function for backwards compatibility.
+
+    [Pod::SimpleText] Properly wrap multiline =item tags.
+
+    [Pod::SimpleText] Fix a spurious space with =for text commands.
+
+    [Pod::SimpleText] Check the content of sequences against the empty
+    string specifically rather than testing truth so that it does the
+    right thing with 0.
+
+    [Pod::SimpleText] Process sequences for =head headings.
+
+podlators 0.01 (1999-06-12)
+
+    Initial release with pod2txt and Pod::SimpleText.
diff --git a/cpan/podlators/Makefile.PL b/cpan/podlators/Makefile.PL
new file mode 100644 (file)
index 0000000..5db6c15
--- /dev/null
@@ -0,0 +1,13 @@
+use strict;
+use warnings;
+
+use ExtUtils::MakeMaker;
+
+WriteMakefile(
+    NAME            => 'Pod',
+    DISTNAME        => 'podlators',
+    VERSION_FROM    => 'lib/Pod/Man.pm',
+    EXE_FILES       => [ 'bin/pod2man', 'bin/pod2text' ],
+    AUTHOR          => 'Russ Allbery (rra@stanford.edu)',
+    ABSTRACT        => 'Convert POD data to various other formats'
+);
similarity index 76%
rename from cpan/podlators/scripts/pod2man.PL
rename to cpan/podlators/bin/pod2man
index 6af3474..203e75f 100644 (file)
@@ -1,49 +1,16 @@
 #!perl
 
-use Config;
-use File::Basename qw(&basename &dirname);
-use Cwd;
-
-# List explicitly here the variables you want Configure to
-# generate.  Metaconfig only looks for shell variables, so you
-# have to mention them as if they were shell variables, not
-# %Config entries.  Thus you write
-#  $startperl
-# to ensure Configure will look for $Config{startperl}.
-
-# This forces PL files to create target in same directory as PL file.
-# This is so that make depend always knows where to find PL derivatives.
-$origdir = cwd;
-chdir dirname($0);
-$file = basename($0, '.PL');
-$file .= '.com' if $^O eq 'VMS';
-
-open OUT,">$file" or die "Can't create $file: $!";
-
-print "Extracting $file (with variable substitutions)\n";
-
-# In this section, perl variables will be expanded during extraction.
-# You can use $Config{...} to use Configure variables.
-
-print OUT <<"!GROK!THIS!";
-$Config{startperl}
-    eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}'
-        if \$running_under_some_shell;
-!GROK!THIS!
-
-# In the following, perl variables are not expanded during extraction.
-
-print OUT <<'!NO!SUBS!';
-
 # pod2man -- Convert POD data to formatted *roff input.
 #
-# Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2012, 2013
-#     Russ Allbery <rra@stanford.edu>
+# Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2012, 2013, 2014, 2015
+#     Russ Allbery <rra@cpan.org>
 #
 # This program is free software; you may redistribute it and/or modify it
 # under the same terms as Perl itself.
 
-require 5.004;
+use 5.006;
+use strict;
+use warnings;
 
 use Getopt::Long qw(GetOptions);
 use Pod::Man ();
@@ -66,7 +33,7 @@ Getopt::Long::config ('bundling_override');
 GetOptions (\%options, 'center|c=s', 'date|d=s', 'errors=s', 'fixed=s',
             'fixedbold=s', 'fixeditalic=s', 'fixedbolditalic=s', 'help|h',
             'lax|l', 'name|n=s', 'nourls', 'official|o', 'quotes|q=s',
-            'release|r:s', 'section|s=s', 'stderr', 'verbose|v', 'utf8|u')
+            'release|r=s', 'section|s=s', 'stderr', 'verbose|v', 'utf8|u')
     or exit 1;
 pod2usage (0) if $options{help};
 
@@ -124,7 +91,7 @@ pod2man - Convert POD data to formatted *roff input
 pod2man [B<--center>=I<string>] [B<--date>=I<string>] [B<--errors>=I<style>]
     [B<--fixed>=I<font>] [B<--fixedbold>=I<font>] [B<--fixeditalic>=I<font>]
     [B<--fixedbolditalic>=I<font>] [B<--name>=I<name>] [B<--nourls>]
-    [B<--official>] [B<--quotes>=I<quotes>] [B<--release>[=I<version>]]
+    [B<--official>] [B<--quotes>=I<quotes>] [B<--release>=I<version>]
     [B<--section>=I<manext>] [B<--stderr>] [B<--utf8>] [B<--verbose>]
     [I<input> [I<output>] ...]
 
@@ -169,16 +136,18 @@ complete information.
 
 =item B<-c> I<string>, B<--center>=I<string>
 
-Sets the centered page header to I<string>.  The default is "User
-Contributed Perl Documentation", but also see B<--official> below.
+Sets the centered page header for the C<.TH> macro to I<string>.  The
+default is "User Contributed Perl Documentation", but also see
+B<--official> below.
 
 =item B<-d> I<string>, B<--date>=I<string>
 
-Set the left-hand footer string to this value.  By default, the modification
-date of the input file will be used, or the current date if input comes from
-C<STDIN>.
+Set the left-hand footer string for the C<.TH> macro to I<string>.  By
+default, the modification date of the input file will be used, or the
+current date if input comes from C<STDIN>, and will be based on UTC (so
+that the output will be reproducible regardless of local time zone).
 
-=item B<-errors>=I<style>
+=item B<--errors>=I<style>
 
 Set the error handling style.  C<die> says to throw an exception on any
 POD formatting error.  C<stderr> says to report errors on standard error,
@@ -224,16 +193,23 @@ Accepted for backward compatibility; this option no longer does anything.
 
 =item B<-n> I<name>, B<--name>=I<name>
 
-Set the name of the manual page to I<name>.  Without this option, the manual
-name is set to the uppercased base name of the file being converted unless
-the manual section is 3, in which case the path is parsed to see if it is a
-Perl module path.  If it is, a path like C<.../lib/Pod/Man.pm> is converted
-into a name like C<Pod::Man>.  This option, if given, overrides any
-automatic determination of the name.
+Set the name of the manual page for the C<.TH> macro to I<name>.  Without
+this option, the manual name is set to the uppercased base name of the
+file being converted unless the manual section is 3, in which case the
+path is parsed to see if it is a Perl module path.  If it is, a path like
+C<.../lib/Pod/Man.pm> is converted into a name like C<Pod::Man>.  This
+option, if given, overrides any automatic determination of the name.
+
+Although one does not have to follow this convention, be aware that the
+convention for UNIX man pages for commands is for the man page title to be
+in all-uppercase, even if the command isn't.
 
-Note that this option is probably not useful when converting multiple POD
-files at once.  The convention for Unix man pages for commands is for the
-man page title to be in all-uppercase even if the command isn't.
+This option is probably not useful when converting multiple POD files at
+once.
+
+When converting POD source from standard input, this option is required,
+since there's otherwise no way to know what to use as the name of the
+manual page.
 
 =item B<--nourls>
 
@@ -259,24 +235,27 @@ Perl release, if B<--center> is not also given.
 
 Sets the quote marks used to surround CE<lt>> text to I<quotes>.  If
 I<quotes> is a single character, it is used as both the left and right
-quote; if I<quotes> is two characters, the first character is used as the
-left quote and the second as the right quoted; and if I<quotes> is four
-characters, the first two are used as the left quote and the second two as
-the right quote.
+quote.  Otherwise, it is split in half, and the first half of the string
+is used as the left quote and the second is used as the right quote.
 
 I<quotes> may also be set to the special value C<none>, in which case no
 quote marks are added around CE<lt>> text (but the font is still changed for
 troff output).
 
-=item B<-r>, B<--release>
+=item B<-r> I<version>, B<--release>=I<version>
+
+Set the centered footer for the C<.TH> macro to I<version>.  By default,
+this is set to the version of Perl you run B<pod2man> under.  Setting this
+to the empty string will cause some *roff implementations to use the
+system default value.
 
-Set the centered footer.  By default, this is the version of Perl you run
-B<pod2man> under.  Note that some system an macro sets assume that the
-centered footer will be a modification date and will prepend something like
-"Last modified: "; if this is the case, you may want to set B<--release> to
-the last modified date and B<--date> to the version number.
+Note that some system C<an> macro sets assume that the centered footer
+will be a modification date and will prepend something like "Last
+modified: ".  If this is the case for your target system, you may want to
+set B<--release> to the last modified date and B<--date> to the version
+number.
 
-=item B<-s>, B<--section>
+=item B<-s> I<string>, B<--section>=I<string>
 
 Set the section for the C<.TH> macro.  The standard section numbering
 convention is to use 1 for user commands, 2 for system calls, 3 for
@@ -314,10 +293,11 @@ supported by many implementations and may even result in segfaults and
 other bad behavior.
 
 Be aware that, when using this option, the input encoding of your POD
-source must be properly declared unless it is US-ASCII or Latin-1.  POD
-input without an C<=encoding> command will be assumed to be in Latin-1,
-and if it's actually in UTF-8, the output will be double-encoded.  See
-L<perlpod(1)> for more information on the C<=encoding> command.
+source should be properly declared unless it's US-ASCII.  Pod::Simple will
+attempt to guess the encoding and may be successful if it's Latin-1 or
+UTF-8, but it will warn, which by default results in a B<pod2man> failure.
+Use the C<=encoding> command to declare the encoding.  See L<perlpod(1)>
+for more information.
 
 =item B<-v>, B<--verbose>
 
@@ -378,21 +358,15 @@ Perl core distribution as of 5.6.0.
 
 =head1 AUTHOR
 
-Russ Allbery <rra@stanford.edu>, based I<very> heavily on the original
+Russ Allbery <rra@cpan.org>, based I<very> heavily on the original
 B<pod2man> by Larry Wall and Tom Christiansen.
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2012, 2013 Russ
-Allbery <rra@stanford.edu>.
+Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2012, 2013, 2014,
+2015 Russ Allbery <rra@cpan.org>.
 
 This program is free software; you may redistribute it and/or modify it
 under the same terms as Perl itself.
 
 =cut
-!NO!SUBS!
-
-close OUT or die "Can't close $file: $!";
-chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
-exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';
-chdir $origdir;
similarity index 83%
rename from cpan/podlators/scripts/pod2text.PL
rename to cpan/podlators/bin/pod2text
index f1acdbe..9394f0f 100644 (file)
@@ -1,44 +1,9 @@
 #!perl
 
-use Config;
-use File::Basename qw(&basename &dirname);
-use Cwd;
-
-# List explicitly here the variables you want Configure to
-# generate.  Metaconfig only looks for shell variables, so you
-# have to mention them as if they were shell variables, not
-# %Config entries.  Thus you write
-#  $startperl
-# to ensure Configure will look for $Config{startperl}.
-
-# This forces PL files to create target in same directory as PL file.
-# This is so that make depend always knows where to find PL derivatives.
-$origdir = cwd;
-chdir dirname($0);
-$file = basename($0, '.PL');
-$file .= '.com' if $^O eq 'VMS';
-
-open OUT,">$file" or die "Can't create $file: $!";
-
-print "Extracting $file (with variable substitutions)\n";
-
-# In this section, perl variables will be expanded during extraction.
-# You can use $Config{...} to use Configure variables.
-
-print OUT <<"!GROK!THIS!";
-$Config{startperl}
-    eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}'
-        if \$running_under_some_shell;
-!GROK!THIS!
-
-# In the following, perl variables are not expanded during extraction.
-
-print OUT <<'!NO!SUBS!';
-
 # pod2text -- Convert POD data to formatted ASCII text.
 #
-# Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2012, 2013
-#     Russ Allbery <rra@stanford.edu>
+# Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2012, 2013, 2014, 2015
+#     Russ Allbery <rra@cpan.org>
 #
 # This program is free software; you may redistribute it and/or modify it
 # under the same terms as Perl itself.
@@ -46,14 +11,14 @@ print OUT <<'!NO!SUBS!';
 # The driver script for Pod::Text, Pod::Text::Termcap, and Pod::Text::Color,
 # invoked by perldoc -t among other things.
 
-require 5.004;
+use 5.006;
+use strict;
+use warnings;
 
 use Getopt::Long qw(GetOptions);
 use Pod::Text ();
 use Pod::Usage qw(pod2usage);
 
-use strict;
-
 # Clean up $0 for error reporting.
 $0 =~ s%.*/%%;
 
@@ -174,12 +139,7 @@ code left intact.
 Format the output with ANSI color escape sequences.  Using this option
 requires that Term::ANSIColor be installed on your system.
 
-=item B<-i> I<indent>, B<--indent=>I<indent>
-
-Set the number of spaces to indent regular text, and the default indentation
-for C<=over> blocks.  Defaults to 4 spaces if this option isn't given.
-
-=item B<-errors>=I<style>
+=item B<--errors>=I<style>
 
 Set the error handling style.  C<die> says to throw an exception on any
 POD formatting error.  C<stderr> says to report errors on standard error,
@@ -189,6 +149,11 @@ ignores POD errors entirely, as much as possible.
 
 The default is C<die>.
 
+=item B<-i> I<indent>, B<--indent=>I<indent>
+
+Set the number of spaces to indent regular text, and the default indentation
+for C<=over> blocks.  Defaults to 4 spaces if this option isn't given.
+
 =item B<-h>, B<--help>
 
 Print out usage information and exit.
@@ -232,10 +197,8 @@ to convert this to bold or underlined text.
 
 Sets the quote marks used to surround CE<lt>> text to I<quotes>.  If
 I<quotes> is a single character, it is used as both the left and right
-quote; if I<quotes> is two characters, the first character is used as the
-left quote and the second as the right quoted; and if I<quotes> is four
-characters, the first two are used as the left quote and the second two as
-the right quote.
+quote.  Otherwise, it is split in half, and the first half of the string
+is used as the left quote and the second is used as the right quote.
 
 I<quotes> may also be set to the special value C<none>, in which case no
 quote marks are added around CE<lt>> text.
@@ -271,10 +234,11 @@ encoding (to be backward-compatible with older versions).  This option
 says to instead force the output encoding to UTF-8.
 
 Be aware that, when using this option, the input encoding of your POD
-source must be properly declared unless it is US-ASCII or Latin-1.  POD
-input without an C<=encoding> command will be assumed to be in Latin-1,
-and if it's actually in UTF-8, the output will be double-encoded.  See
-L<perlpod(1)> for more information on the C<=encoding> command.
+source should be properly declared unless it's US-ASCII.  Pod::Simple
+will attempt to guess the encoding and may be successful if it's
+Latin-1 or UTF-8, but it will warn, which by default results in a
+B<pod2text> failure.  Use the C<=encoding> command to declare the
+encoding.  See L<perlpod(1)> for more information.
 
 =item B<-w>, B<--width=>I<width>, B<->I<width>
 
@@ -345,20 +309,14 @@ Perl core distribution as of 5.6.0.
 
 =head1 AUTHOR
 
-Russ Allbery <rra@stanford.edu>.
+Russ Allbery <rra@cpan.org>.
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2012, 2013 Russ
-Allbery <rra@stanford.edu>.
+Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2012, 2013, 2014, 2015
+Russ Allbery <rra@cpan.org>
 
 This program is free software; you may redistribute it and/or modify it
 under the same terms as Perl itself.
 
 =cut
-!NO!SUBS!
-
-close OUT or die "Can't close $file: $!";
-chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
-exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';
-chdir $origdir;
index 72ca9ff..0d2edd0 100644 (file)
 # me any patches at the address above in addition to sending them to the
 # standard Perl mailing lists.
 #
-# Copyright 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
-#     2010, 2012, 2013 Russ Allbery <rra@stanford.edu>
+# Written by Russ Allbery <rra@cpan.org>
 # Substantial contributions by Sean Burke <sburke@cpan.org>
+# Copyright 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
+#     2010, 2012, 2013, 2014, 2015 Russ Allbery <rra@cpan.org>
 #
 # This program is free software; you may redistribute it and/or modify it
 # under the same terms as Perl itself.
 
 package Pod::Man;
 
-require 5.005;
-
+use 5.006;
 use strict;
+use warnings;
+
 use subs qw(makespace);
 use vars qw(@ISA %ESCAPES $PREAMBLE $VERSION);
 
@@ -36,7 +38,7 @@ use Pod::Simple ();
 
 @ISA = qw(Pod::Simple);
 
-$VERSION = '2.28';
+$VERSION = '4.03';
 
 # Set the debugging level.  If someone has inserted a debug function into this
 # class already, use that.  Otherwise, use any Pod::Simple debug function
@@ -204,10 +206,10 @@ sub init_quotes {
         $$self{LQUOTE} = $$self{RQUOTE} = '';
     } elsif (length ($$self{quotes}) == 1) {
         $$self{LQUOTE} = $$self{RQUOTE} = $$self{quotes};
-    } elsif ($$self{quotes} =~ /^(.)(.)$/
-             || $$self{quotes} =~ /^(..)(..)$/) {
-        $$self{LQUOTE} = $1;
-        $$self{RQUOTE} = $2;
+    } elsif (length ($$self{quotes}) % 2 == 0) {
+        my $length = length ($$self{quotes}) / 2;
+        $$self{LQUOTE} = substr ($$self{quotes}, 0, $length);
+        $$self{RQUOTE} = substr ($$self{quotes}, $length);
     } else {
         croak(qq(Invalid quote specification "$$self{quotes}"))
     }
@@ -788,7 +790,7 @@ sub start_document {
         } else {
             ($name, $section) = $self->devise_title;
         }
-        my $date = $$self{date} || $self->devise_date;
+        my $date = defined($$self{date}) ? $$self{date} : $self->devise_date;
         $self->preamble ($name, $section, $date)
             unless $self->bare_output or DEBUG > 9;
     }
@@ -828,6 +830,17 @@ sub devise_title {
     $section = 3 if (!$$self{section} && $name =~ /\.pm\z/i);
     $name =~ s/\.p(od|[lm])\z//i;
 
+    # If Pod::Parser gave us an IO::File reference as the source file name,
+    # convert that to the empty string as well.  Then, if we don't have a
+    # valid name, emit a warning and convert it to STDIN.
+    if ($name =~ /^IO::File(?:=\w+)\(0x[\da-f]+\)$/i) {
+        $name = '';
+    }
+    if ($name eq '') {
+        $self->whine (1, 'No name given for document');
+        $name = 'STDIN';
+    }
+
     # If the section isn't 3, then the name defaults to just the basename of
     # the file.  Otherwise, assume we're dealing with a module.  We want to
     # figure out the full module name from the path to the file, but we don't
@@ -876,25 +889,55 @@ sub devise_title {
 }
 
 # Determine the modification date and return that, properly formatted in ISO
-# format.  If we can't get the modification date of the input, instead use the
-# current time.  Pod::Simple returns a completely unuseful stringified file
-# handle as the source_filename for input from a file handle, so we have to
-# deal with that as well.
+# format.
+#
+# If POD_MAN_DATE is set, that overrides anything else.  This can be used for
+# reproducible generation of the same file even if the input file timestamps
+# are unpredictable or the POD coms from standard input.
+#
+# Otherwise, if SOURCE_DATE_EPOCH is set and can be parsed as seconds since
+# the UNIX epoch, base the timestamp on that.  See
+# <https://reproducible-builds.org/specs/source-date-epoch/>
+#
+# Otherwise, use the modification date of the input if we can stat it.  Be
+# aware that Pod::Simple returns the stringification of the file handle as
+# source_filename for input from a file handle, so we'll stat some random ref
+# string in that case.  If that fails, instead use the current time.
+#
+# $self - Pod::Man object, used to get the source file
+#
+# Returns: YYYY-MM-DD date suitable for the left-hand footer
 sub devise_date {
     my ($self) = @_;
-    my $input = $self->source_filename;
+
+    # If POD_MAN_DATE is set, always use it.
+    if (defined($ENV{POD_MAN_DATE})) {
+        return $ENV{POD_MAN_DATE};
+    }
+
+    # If SOURCE_DATE_EPOCH is set and can be parsed, use that.
     my $time;
-    if ($input) {
-        $time = (stat $input)[9] || time;
-    } else {
-        $time = time;
+    if (defined($ENV{SOURCE_DATE_EPOCH}) && $ENV{SOURCE_DATE_EPOCH} !~ /\D/) {
+        $time = $ENV{SOURCE_DATE_EPOCH};
+    }
+
+    # Otherwise, get the input filename and try to stat it.  If that fails,
+    # use the current time.
+    if (!defined $time) {
+        my $input = $self->source_filename;
+        if ($input) {
+            $time = (stat($input))[9] || time();
+        } else {
+            $time = time();
+        }
     }
 
-    # Can't use POSIX::strftime(), which uses Fcntl, because MakeMaker
-    # uses this and it has to work in the core which can't load dynamic
-    # libraries.
-    my ($year, $month, $day) = (localtime $time)[5,4,3];
-    return sprintf ("%04d-%02d-%02d", $year + 1900, $month + 1, $day);
+    # Can't use POSIX::strftime(), which uses Fcntl, because MakeMaker uses
+    # this and it has to work in the core which can't load dynamic libraries.
+    # Use gmtime instead of localtime so that the generated man page does not
+    # depend on the local time zone setting and is more reproducible
+    my ($year, $month, $day) = (gmtime($time))[5,4,3];
+    return sprintf("%04d-%02d-%02d", $year + 1900, $month + 1, $day);
 }
 
 # Print out the preamble and the title.  The meaning of the arguments to .TH
@@ -1461,7 +1504,7 @@ sub preamble_template {
 .ie \n(.g .ds Aq \(aq
 .el       .ds Aq '
 .\"
-.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" If the F register is >0, we'll generate index entries on stderr for
 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
 .\" entries marked with X<> in POD.  Of course, you'll have to process the
 .\" output yourself in some meaningful fashion.
@@ -1469,20 +1512,16 @@ sub preamble_template {
 .\" Avoid warning from groff about undefined register 'F'.
 .de IX
 ..
-.nr rF 0
-.if \n(.g .if rF .nr rF 1
-.if (\n(rF:(\n(.g==0)) \{
-.    if \nF \{
-.        de IX
-.        tm Index:\\$1\t\\n%\t"\\$2"
+.if !\nF .nr F 0
+.if \nF>0 \{\
+.    de IX
+.    tm Index:\\$1\t\\n%\t"\\$2"
 ..
-.        if !\nF==2 \{
-.            nr % 0
-.            nr F 2
-.        \}
+.    if !\nF==2 \{\
+.        nr % 0
+.        nr F 2
 .    \}
 .\}
-.rr rF
 ----END OF PREAMBLE----
 #'# for cperl-mode
 
@@ -1566,7 +1605,7 @@ __END__
 =for stopwords
 en em ALLCAPS teeny fixedbold fixeditalic fixedbolditalic stderr utf8
 UTF-8 Allbery Sean Burke Ossanna Solaris formatters troff uppercased
-Christiansen nourls parsers
+Christiansen nourls parsers Kernighan
 
 =head1 NAME
 
@@ -1629,8 +1668,19 @@ argument.
 
 =item center
 
-Sets the centered page header to use instead of "User Contributed Perl
-Documentation".
+Sets the centered page header for the C<.TH> macro.  The default, if this
+option is not specified, is "User Contributed Perl Documentation".
+
+=item date
+
+Sets the left-hand footer for the C<.TH> macro.  If this option is not set,
+the contents of the environment variable POD_MAN_DATE, if set, will be used.
+Failing that, the value of SOURCE_DATE_EPOCH, the modification date of the
+input file, or the current time if stat() can't find that file (which will be
+the case if the input is from C<STDIN>) will be used.  If obtained from the
+file modification date or the current time, the date will be formatted as
+C<YYYY-MM-DD> and will be based on UTC (so that the output will be
+reproducible regardless of local time zone).
 
 =item errors
 
@@ -1642,13 +1692,6 @@ POD errors entirely, as much as possible.
 
 The default is C<pod>.
 
-=item date
-
-Sets the left-hand footer.  By default, the modification date of the input
-file will be used, or the current date if stat() can't find that file (the
-case if the input is from C<STDIN>), and the date will be formatted as
-C<YYYY-MM-DD>.
-
 =item fixed
 
 The fixed-width font to use for verbatim text and code.  Defaults to
@@ -1675,12 +1718,16 @@ for B<troff> output.
 
 =item name
 
-Set the name of the manual page.  Without this option, the manual name is
-set to the uppercased base name of the file being converted unless the
-manual section is 3, in which case the path is parsed to see if it is a Perl
-module path.  If it is, a path like C<.../lib/Pod/Man.pm> is converted into
-a name like C<Pod::Man>.  This option, if given, overrides any automatic
-determination of the name.
+Set the name of the manual page for the C<.TH> macro.  Without this
+option, the manual name is set to the uppercased base name of the file
+being converted unless the manual section is 3, in which case the path is
+parsed to see if it is a Perl module path.  If it is, a path like
+C<.../lib/Pod/Man.pm> is converted into a name like C<Pod::Man>.  This
+option, if given, overrides any automatic determination of the name.
+
+If generating a manual page from standard input, this option is required,
+since there's otherwise no way for Pod::Man to know what to use for the
+manual page name.
 
 =item nourls
 
@@ -1701,10 +1748,9 @@ important.
 =item quotes
 
 Sets the quote marks used to surround CE<lt>> text.  If the value is a
-single character, it is used as both the left and right quote; if it is two
-characters, the first character is used as the left quote and the second as
-the right quoted; and if it is four characters, the first two are used as
-the left quote and the second two as the right quote.
+single character, it is used as both the left and right quote.  Otherwise,
+it is split in half, and the first half of the string is used as the left
+quote and the second is used as the right quote.
 
 This may also be set to the special value C<none>, in which case no quote
 marks are added around CE<lt>> text (but the font is still changed for troff
@@ -1712,11 +1758,16 @@ output).
 
 =item release
 
-Set the centered footer.  By default, this is the version of Perl you run
-Pod::Man under.  Note that some system an macro sets assume that the
-centered footer will be a modification date and will prepend something like
-"Last modified: "; if this is the case, you may want to set C<release> to
-the last modified date and C<date> to the version number.
+Set the centered footer for the C<.TH> macro.  By default, this is set to
+the version of Perl you run Pod::Man under.  Setting this to the empty
+string will cause some *roff implementations to use the system default
+value.
+
+Note that some system C<an> macro sets assume that the centered footer
+will be a modification date and will prepend something like "Last
+modified: ".  If this is the case for your target system, you may want to
+set C<release> to the last modified date and C<date> to the version
+number.
 
 =item section
 
@@ -1756,10 +1807,10 @@ by many implementations and may even result in segfaults and other bad
 behavior.
 
 Be aware that, when using this option, the input encoding of your POD
-source must be properly declared unless it is US-ASCII or Latin-1.  POD
-input without an C<=encoding> command will be assumed to be in Latin-1,
-and if it's actually in UTF-8, the output will be double-encoded.  See
-L<perlpod(1)> for more information on the C<=encoding> command.
+source should be properly declared unless it's US-ASCII.  Pod::Simple will
+attempt to guess the encoding and may be successful if it's Latin-1 or
+UTF-8, but it will produce warnings.  Use the C<=encoding> command to
+declare the encoding.  See L<perlpod(1)> for more information.
 
 =back
 
@@ -1800,8 +1851,8 @@ canonical versions of B<nroff> and B<troff> don't either).
 =item Invalid quote specification "%s"
 
 (F) The quote specification given (the C<quotes> option to the
-constructor) was invalid.  A quote specification must be one, two, or four
-characters long.
+constructor) was invalid.  A quote specification must be either one
+character long or an even number (greater than one) characters long.
 
 =item POD document had syntax errors
 
@@ -1810,6 +1861,36 @@ option was set to C<die>.
 
 =back
 
+=head1 ENVIRONMENT
+
+=over 4
+
+=item POD_MAN_DATE
+
+If set, this will be used as the value of the left-hand footer unless the
+C<date> option is explicitly set, overriding the timestamp of the input
+file or the current time.  This is primarily useful to ensure reproducible
+builds of the same output file given the same source and Pod::Man version,
+even when file timestamps may not be consistent.
+
+=item SOURCE_DATE_EPOCH
+
+If set, and POD_MAN_DATE and the C<date> options are not set, this will be
+used as the modification time of the source file, overriding the timestamp of
+the input file or the current time.  It should be set to the desired time in
+seconds since UNIX epoch.  This is primarily useful to ensure reproducible
+builds of the same output file given the same source and Pod::Man version,
+even when file timestamps may not be consistent.  See
+L<https://reproducible-builds.org/specs/source-date-epoch/> for the full
+specification.
+
+(Arguably, according to the specification, this variable should be used only
+if the timestamp of the input file is not available and Pod::Man uses the
+current time.  However, for reproducible builds in Debian, results were more
+reliable if this variable overrode the timestamp of the input file.)
+
+=back
+
 =head1 BUGS
 
 Encoding handling assumes that PerlIO is available and does not work
@@ -1860,7 +1941,7 @@ only matters for troff output.
 
 =head1 AUTHOR
 
-Russ Allbery <rra@stanford.edu>, based I<very> heavily on the original
+Russ Allbery <rra@cpan.org>, based I<very> heavily on the original
 B<pod2man> by Tom Christiansen <tchrist@mox.perl.com>.  The modifications to
 work with Pod::Simple instead of Pod::Parser were originally contributed by
 Sean Burke (but I've since hacked them beyond recognition and all bugs are
@@ -1869,7 +1950,7 @@ mine).
 =head1 COPYRIGHT AND LICENSE
 
 Copyright 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008,
-2009, 2010, 2012, 2013 Russ Allbery <rra@stanford.edu>.
+2009, 2010, 2012, 2013, 2014, 2015 Russ Allbery <rra@cpan.org>
 
 This program is free software; you may redistribute it and/or modify it
 under the same terms as Perl itself.
index 750fdfb..8d9d7ce 100644 (file)
@@ -1,6 +1,6 @@
 # Pod::ParseLink -- Parse an L<> formatting code in POD text.
 #
-# Copyright 2001, 2008, 2009 by Russ Allbery <rra@stanford.edu>
+# Copyright 2001, 2008, 2009, 2014 by Russ Allbery <rra@cpan.org>
 #
 # This program is free software; you may redistribute it and/or modify it
 # under the same terms as Perl itself.
 
 package Pod::ParseLink;
 
-require 5.004;
-
+use 5.006;
 use strict;
+use warnings;
+
 use vars qw(@EXPORT @ISA $VERSION);
 
 use Exporter;
 @ISA    = qw(Exporter);
 @EXPORT = qw(parselink);
 
-$VERSION = '1.10';
+$VERSION = '4.03';
 
 ##############################################################################
 # Implementation
@@ -123,7 +124,8 @@ markup Allbery URL
 =head1 SYNOPSIS
 
     use Pod::ParseLink;
-    my ($text, $inferred, $name, $section, $type) = parselink ($link);
+    my $link = get_link();
+    my ($text, $inferred, $name, $section, $type) = parselink($link);
 
 =head1 DESCRIPTION
 
@@ -180,11 +182,11 @@ L<http://www.eyrie.org/~eagle/software/podlators/>.
 
 =head1 AUTHOR
 
-Russ Allbery <rra@stanford.edu>.
+Russ Allbery <rra@cpan.org>.
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 2001, 2008, 2009 Russ Allbery <rra@stanford.edu>.
+Copyright 2001, 2008, 2009 Russ Allbery <rra@cpan.org>.
 
 This program is free software; you may redistribute it and/or modify it
 under the same terms as Perl itself.
index 87f9e81..f8033cc 100644 (file)
@@ -1,4 +1,4 @@
-# Pod::Text -- Convert POD data to formatted ASCII text.
+# Pod::Text -- Convert POD data to formatted text.
 #
 # This module converts POD to formatted text.  It replaces the old Pod::Text
 # module that came with versions of Perl prior to 5.6.0 and attempts to match
@@ -11,8 +11,8 @@
 # me any patches at the address above in addition to sending them to the
 # standard Perl mailing lists.
 #
-# Copyright 1999, 2000, 2001, 2002, 2004, 2006, 2008, 2009, 2012, 2013
-#     Russ Allbery <rra@stanford.edu>
+# Copyright 1999, 2000, 2001, 2002, 2004, 2006, 2008, 2009, 2012, 2013, 2014,
+#     2015 Russ Allbery <rra@cpan.org>
 #
 # This program is free software; you may redistribute it and/or modify it
 # under the same terms as Perl itself.
 
 package Pod::Text;
 
-require 5.004;
-
+use 5.006;
 use strict;
+use warnings;
+
 use vars qw(@ISA @EXPORT %ESCAPES $VERSION);
 
 use Carp qw(carp croak);
@@ -38,7 +39,7 @@ use Pod::Simple ();
 # We have to export pod2text for backward compatibility.
 @EXPORT = qw(pod2text);
 
-$VERSION = '3.18';
+$VERSION = '4.03';
 
 ##############################################################################
 # Initialization
@@ -126,10 +127,10 @@ sub new {
         $$self{LQUOTE} = $$self{RQUOTE} = '';
     } elsif (length ($$self{opt_quotes}) == 1) {
         $$self{LQUOTE} = $$self{RQUOTE} = $$self{opt_quotes};
-    } elsif ($$self{opt_quotes} =~ /^(.)(.)$/
-             || $$self{opt_quotes} =~ /^(..)(..)$/) {
-        $$self{LQUOTE} = $1;
-        $$self{RQUOTE} = $2;
+    } elsif (length ($$self{opt_quotes}) % 2 == 0) {
+        my $length = length ($$self{opt_quotes}) / 2;
+        $$self{LQUOTE} = substr ($$self{opt_quotes}, 0, $length);
+        $$self{RQUOTE} = substr ($$self{opt_quotes}, $length);
     } else {
         croak qq(Invalid quote specification "$$self{opt_quotes}");
     }
@@ -273,12 +274,12 @@ sub output {
     my ($self, @text) = @_;
     my $text = join ('', @text);
     $text =~ tr/\240\255/ /d;
-    unless ($$self{opt_utf8} || $$self{CHECKED_ENCODING}) {
+    unless ($$self{opt_utf8}) {
         my $encoding = $$self{encoding} || '';
-        if ($encoding) {
+        if ($encoding && $encoding ne $$self{ENCODING}) {
+            $$self{ENCODING} = $encoding;
             eval { binmode ($$self{output_fh}, ":encoding($encoding)") };
         }
-        $$self{CHECKED_ENCODING} = 1;
     }
     if ($$self{ENCODE}) {
         print { $$self{output_fh} } encode ('UTF-8', $text);
@@ -312,7 +313,7 @@ sub start_document {
     $$self{PENDING} = [[]];     # Pending output.
 
     # We have to redo encoding handling for each document.
-    delete $$self{CHECKED_ENCODING};
+    $$self{ENCODING} = '';
 
     # When UTF-8 output is set, check whether our output file handle already
     # has a PerlIO encoding layer set.  If it does not, we'll need to encode
@@ -326,6 +327,7 @@ sub start_document {
             my $flag = (PerlIO::get_layers ($$self{output_fh}, @options))[-1];
             if ($flag & PerlIO::F_UTF8 ()) {
                 $$self{ENCODE} = 0;
+                $$self{ENCODING} = 'UTF-8';
             }
         };
     }
@@ -759,7 +761,7 @@ parsers
 
 =head1 NAME
 
-Pod::Text - Convert POD data to formatted ASCII text
+Pod::Text - Convert POD data to formatted text
 
 =head1 SYNOPSIS
 
@@ -774,10 +776,10 @@ Pod::Text - Convert POD data to formatted ASCII text
 
 =head1 DESCRIPTION
 
-Pod::Text is a module that can convert documentation in the POD format (the
-preferred language for documenting Perl) into formatted ASCII.  It uses no
-special formatting controls or codes whatsoever, and its output is therefore
-suitable for nearly any device.
+Pod::Text is a module that can convert documentation in the POD format
+(the preferred language for documenting Perl) into formatted text.  It
+uses no special formatting controls or codes whatsoever, and its output is
+therefore suitable for nearly any device.
 
 As a derived class from Pod::Simple, Pod::Text supports the same methods and
 interfaces.  See L<Pod::Simple> for all the details; briefly, one creates a
@@ -850,10 +852,9 @@ important.
 =item quotes
 
 Sets the quote marks used to surround CE<lt>> text.  If the value is a
-single character, it is used as both the left and right quote; if it is two
-characters, the first character is used as the left quote and the second as
-the right quoted; and if it is four characters, the first two are used as
-the left quote and the second two as the right quote.
+single character, it is used as both the left and right quote.  Otherwise,
+it is split in half, and the first half of the string is used as the left
+quote and the second is used as the right quote.
 
 This may also be set to the special value C<none>, in which case no quote
 marks are added around CE<lt>> text.
@@ -880,10 +881,10 @@ doesn't encode its output).  If this option is given, the output encoding
 is forced to UTF-8.
 
 Be aware that, when using this option, the input encoding of your POD
-source must be properly declared unless it is US-ASCII or Latin-1.  POD
-input without an C<=encoding> command will be assumed to be in Latin-1,
-and if it's actually in UTF-8, the output will be double-encoded.  See
-L<perlpod(1)> for more information on the C<=encoding> command.
+source should be properly declared unless it's US-ASCII.  Pod::Simple will
+attempt to guess the encoding and may be successful if it's Latin-1 or
+UTF-8, but it will produce warnings.  Use the C<=encoding> command to
+declare the encoding.  See L<perlpod(1)> for more information.
 
 =item width
 
@@ -933,8 +934,8 @@ and the input file it was given could not be opened.
 =item Invalid quote specification "%s"
 
 (F) The quote specification given (the C<quotes> option to the
-constructor) was invalid.  A quote specification must be one, two, or four
-characters long.
+constructor) was invalid.  A quote specification must be either one
+character long or an even number (greater than one) characters long.
 
 =item POD document had syntax errors
 
@@ -989,7 +990,7 @@ Perl core distribution as of 5.6.0.
 
 =head1 AUTHOR
 
-Russ Allbery <rra@stanford.edu>, based I<very> heavily on the original
+Russ Allbery <rra@cpan.org>, based I<very> heavily on the original
 Pod::Text by Tom Christiansen <tchrist@mox.perl.com> and its conversion to
 Pod::Parser by Brad Appleton <bradapp@enteract.com>.  Sean Burke's initial
 conversion of Pod::Man to use Pod::Simple provided much-needed guidance on
@@ -997,8 +998,8 @@ how to use Pod::Simple.
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 1999, 2000, 2001, 2002, 2004, 2006, 2008, 2009, 2012, 2013 Russ
-Allbery <rra@stanford.edu>.
+Copyright 1999, 2000, 2001, 2002, 2004, 2006, 2008, 2009, 2012, 2013, 2014,
+2015 Russ Allbery <rra@cpan.org>
 
 This program is free software; you may redistribute it and/or modify it
 under the same terms as Perl itself.
index a114ed9..0102553 100644 (file)
@@ -4,7 +4,8 @@
 # better use of color, take options changing what colors are used for what
 # text, and the like.
 #
-# Copyright 1999, 2001, 2004, 2006, 2008, 2009 Russ Allbery <rra@stanford.edu>
+# Copyright 1999, 2001, 2004, 2006, 2008, 2009, 2014
+#     Russ Allbery <rra@cpan.org>
 #
 # This program is free software; you may redistribute it and/or modify it
 # under the same terms as Perl itself.
 
 package Pod::Text::Color;
 
-require 5.004;
+use 5.006;
+use strict;
+use warnings;
 
 use Pod::Text ();
 use Term::ANSIColor qw(colored);
 
-use strict;
 use vars qw(@ISA $VERSION);
 
 @ISA = qw(Pod::Text);
 
-$VERSION = '2.07';
+$VERSION = '4.03';
 
 ##############################################################################
 # Overrides
@@ -143,11 +145,11 @@ Perl core distribution as of 5.6.0.
 
 =head1 AUTHOR
 
-Russ Allbery <rra@stanford.edu>.
+Russ Allbery <rra@cpan.org>.
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 1999, 2001, 2004, 2006, 2008, 2009 Russ Allbery <rra@stanford.edu>.
+Copyright 1999, 2001, 2004, 2006, 2008, 2009 Russ Allbery <rra@cpan.org>.
 
 This program is free software; you may redistribute it and/or modify it
 under the same terms as Perl itself.
index f5dce02..0aaabd5 100644 (file)
@@ -12,9 +12,9 @@
 # independent.
 #
 # Created by Joe Smith <Joe.Smith@inwap.com> 30-Nov-2000
-#   (based on Pod::Text::Color by Russ Allbery <rra@stanford.edu>)
+#   (based on Pod::Text::Color by Russ Allbery <rra@cpan.org>)
 # Copyright 2000 Joe Smith <Joe.Smith@inwap.com>.
-# Copyright 2001, 2004, 2008 Russ Allbery <rra@stanford.edu>.
+# Copyright 2001, 2004, 2008, 2014 Russ Allbery <rra@cpan.org>.
 #
 # This program is free software; you may redistribute it and/or modify it
 # under the same terms as Perl itself.
 
 package Pod::Text::Overstrike;
 
-require 5.004;
-
-use Pod::Text ();
-
+use 5.006;
 use strict;
+use warnings;
+
 use vars qw(@ISA $VERSION);
 
+use Pod::Text ();
+
 @ISA = qw(Pod::Text);
 
-$VERSION = '2.05';
+$VERSION = '4.03';
 
 ##############################################################################
 # Overrides
@@ -195,12 +196,12 @@ Perl core distribution as of 5.6.0.
 =head1 AUTHOR
 
 Joe Smith <Joe.Smith@inwap.com>, using the framework created by Russ Allbery
-<rra@stanford.edu>.
+<rra@cpan.org>.
 
 =head1 COPYRIGHT AND LICENSE
 
 Copyright 2000 by Joe Smith <Joe.Smith@inwap.com>.
-Copyright 2001, 2004, 2008 by Russ Allbery <rra@stanford.edu>.
+Copyright 2001, 2004, 2008 by Russ Allbery <rra@cpan.org>.
 
 This program is free software; you may redistribute it and/or modify it
 under the same terms as Perl itself.
index 18ba7b2..3f7f53d 100644 (file)
@@ -4,8 +4,8 @@
 # output the right termcap escape sequences for formatted text on the current
 # terminal type.
 #
-# Copyright 1999, 2001, 2002, 2004, 2006, 2008, 2009
-#     Russ Allbery <rra@stanford.edu>
+# Copyright 1999, 2001, 2002, 2004, 2006, 2008, 2009, 2014, 2015
+#     Russ Allbery <rra@cpan.org>
 #
 # This program is free software; you may redistribute it and/or modify it
 # under the same terms as Perl itself.
 
 package Pod::Text::Termcap;
 
-require 5.004;
+use 5.006;
+use strict;
+use warnings;
 
 use Pod::Text ();
 use POSIX ();
 use Term::Cap;
 
-use strict;
 use vars qw(@ISA $VERSION);
 
 @ISA = qw(Pod::Text);
 
-$VERSION = '2.08';
+$VERSION = '4.03';
 
 ##############################################################################
 # Overrides
@@ -42,9 +43,11 @@ sub new {
 
     # $ENV{HOME} is usually not set on Windows.  The default Term::Cap path
     # may not work on Solaris.
-    my $home = exists $ENV{HOME} ? "$ENV{HOME}/.termcap:" : '';
-    $ENV{TERMPATH} = $home . '/etc/termcap:/usr/share/misc/termcap'
-                           . ':/usr/share/lib/termcap';
+    unless (exists $ENV{TERMPATH}) {
+        my $home = exists $ENV{HOME} ? "$ENV{HOME}/.termcap:" : '';
+        $ENV{TERMPATH} =
+          "${home}/etc/termcap:/usr/share/misc/termcap:/usr/share/lib/termcap";
+    }
 
     # Fall back on a hard-coded terminal speed if POSIX::Termios isn't
     # available (such as on VMS).
@@ -144,7 +147,7 @@ __END__
 Pod::Text::Termcap - Convert POD data to ASCII text with format escapes
 
 =for stopwords
-ECMA-48 VT100 Allbery
+ECMA-48 VT100 Allbery Solaris TERMPATH
 
 =head1 SYNOPSIS
 
@@ -164,6 +167,18 @@ text using the correct termcap escape sequences for the current terminal.
 Apart from the format codes, it in all ways functions like Pod::Text.  See
 L<Pod::Text> for details and available options.
 
+=head1 ENVIRONMENT
+
+This module sets the TERMPATH environment variable globally to:
+
+    $HOME/.termcap:/etc/termcap:/usr/share/misc/termcap:/usr/share/lib/termcap
+
+if it isn't already set.  (The first entry is omitted if the HOME
+environment variable isn't set.)  This is a (very old) workaround for
+problems finding termcap information on older versions of Solaris, and is
+not good module behavior.  Please do not rely on this behavior; it may be
+dropped in a future release.
+
 =head1 NOTES
 
 This module uses Term::Cap to retrieve the formatting escape sequences for
@@ -182,12 +197,12 @@ Perl core distribution as of 5.6.0.
 
 =head1 AUTHOR
 
-Russ Allbery <rra@stanford.edu>.
+Russ Allbery <rra@cpan.org>.
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 1999, 2001, 2002, 2004, 2006, 2008, 2009 Russ Allbery
-<rra@stanford.edu>.
+Copyright 1999, 2001, 2002, 2004, 2006, 2008, 2009, 2014, 2015 Russ Allbery
+<rra@cpan.org>
 
 This program is free software; you may redistribute it and/or modify it
 under the same terms as Perl itself.
diff --git a/cpan/podlators/t/basic.t b/cpan/podlators/t/basic.t
deleted file mode 100644 (file)
index 4103ed6..0000000
+++ /dev/null
@@ -1,117 +0,0 @@
-#!/usr/bin/perl -w
-#
-# basic.t -- Basic tests for podlators.
-#
-# Copyright 2001, 2002, 2004, 2006, 2009, 2012
-#     Russ Allbery <rra@stanford.edu>
-#
-# This program is free software; you may redistribute it and/or modify it
-# under the same terms as Perl itself.
-
-BEGIN {
-    chdir 't' if -d 't';
-    if ($ENV{PERL_CORE}) {
-        @INC = '../lib';
-    }
-    unshift (@INC, '../blib/lib');
-    $| = 1;
-}
-
-use strict;
-
-use Test::More tests => 15;
-
-BEGIN {
-    use_ok ('Pod::Man');
-    use_ok ('Pod::Text');
-    use_ok ('Pod::Text::Overstrike');
-    use_ok ('Pod::Text::Termcap');
-}
-
-# Find the path to the test source files.  This requires some fiddling when
-# these tests are run as part of Perl core.
-sub source_path {
-    my $file = shift;
-    if ($ENV{PERL_CORE}) {
-        require File::Spec;
-        my $updir = File::Spec->updir;
-        my $dir = File::Spec->catdir ($updir, 'lib', 'Pod', 't');
-        return File::Spec->catfile ($dir, $file);
-    } else {
-        return $file;
-    }
-}
-
-# Hard-code a few values to try to get reproducible results.
-$ENV{COLUMNS} = 80;
-$ENV{TERM} = 'xterm';
-$ENV{TERMCAP} = 'xterm:co=80:do=^J:md=\E[1m:us=\E[4m:me=\E[m';
-
-# Map of translators to file extensions to find the formatted output to
-# compare against.
-my %translators = ('Pod::Man'              => 'man',
-                   'Pod::Text'             => 'txt',
-                   'Pod::Text::Color'      => 'clr',
-                   'Pod::Text::Overstrike' => 'ovr',
-                   'Pod::Text::Termcap'    => 'cap');
-
-# Set default options to match those of pod2man and pod2text.
-our %options = (sentence => 0);
-
-for my $module (sort keys %translators) {
-  SKIP: {
-        if ($module eq 'Pod::Text::Color') {
-            eval { require Term::ANSIColor };
-            skip 'Term::ANSIColor not found', 3 if $@;
-            require_ok ('Pod::Text::Color');
-        }
-        my $parser = $module->new (%options);
-        isa_ok ($parser, $module, 'Parser object');
-
-        # For Pod::Man, strip out the autogenerated header up to the .TH title
-        # line.  That means that we don't check those things; oh well.  The
-        # header changes with each version change or touch of the input file.
-        open (OUT, "> out$$.tmp") or die "Cannot create out$$.tmp: $!\n";
-        $parser->parse_from_file (source_path ('basic.pod'), \*OUT);
-        close OUT;
-        if ($module eq 'Pod::Man') {
-            open (TMP, "out$$.tmp") or die "Cannot open out$$.tmp: $!\n";
-            open (OUTPUT, "> out$$.$translators{$module}")
-                or die "Cannot create out$$.$translators{$module}: $!\n";
-            local $_;
-            while (<TMP>) { last if /^\.nh/ }
-            print OUTPUT while <TMP>;
-            close OUTPUT;
-            close TMP;
-            1 while unlink "out$$.tmp";
-        } else {
-            rename ("out$$.tmp", "out$$.$translators{$module}")
-                or die "Cannot rename out$$.tmp: $!\n";
-        }
-
-        # Slurp the output and expected output and compare them.
-        my ($master, $output);
-        {
-            local $/;
-            open (MASTER, source_path ("basic.$translators{$module}"))
-                or die "Cannot open basic.$translators{$module}: $!\n";
-            open (OUTPUT, "out$$.$translators{$module}")
-                or die "Cannot open out$$.$translators{$module}: $!\n";
-            $master = <MASTER>;
-            $output = <OUTPUT>;
-            close MASTER;
-            close OUTPUT;
-        }
-
-        # OS/390 is EBCDIC, which uses a different character for ESC
-        # apparently.  Try to convert so that the test still works.
-        if ($^O eq 'os390' and $module eq 'Pod::Text::Termcap') {
-            $output =~ tr/\033/\047/;
-        }
-        if (ok ($master eq $output, "$module output is correct")) {
-            1 while unlink "out$$.$translators{$module}";
-        } else {
-            diag ("Non-matching output left in out$$.$translators{$module}\n");
-        }
-    }
-}
diff --git a/cpan/podlators/t/data/perl.conf b/cpan/podlators/t/data/perl.conf
new file mode 100644 (file)
index 0000000..8b76b1c
--- /dev/null
@@ -0,0 +1,7 @@
+# Configuration for Perl tests.  -*- perl -*-
+
+# Default minimum version requirement.
+$MINIMUM_VERSION = '5.006';
+
+# File must end with this line.
+1;
diff --git a/cpan/podlators/t/data/snippets/README b/cpan/podlators/t/data/snippets/README
new file mode 100644 (file)
index 0000000..0e7252d
--- /dev/null
@@ -0,0 +1,45 @@
+The files in this directory are used by the test suite to exercise various
+behavior of Pod::Man or Pod::Text.  They use a pseudo-ini-file syntax with
+free-form sections, normally an input and an output section and possibly
+others.
+
+Sections start with the section type in [].  The contents are normally
+just free-form.  The exception is an [options] section, where the contents
+are key/value pairs, where the key is separated from the value with
+whitespace.
+
+Valid sections are:
+
+    [name]
+    The name of this test for status reporting
+    
+    [options]
+    key value
+    key value
+    
+    [input]
+    POD input source.
+    
+    [output]
+    The results of running some formatter on the input.
+    
+    [errors]
+    Errors reported to standard error when running some formatter on the
+    input.
+    
+    [exception]
+    The text of an exception (with the file and line number information
+    stripped) thrown by running some formatter on the input.
+
+Files are organized into subdirectories named after the formatter, namely
+man (Pod::Man), text (Pod::Text), color (Pod::Text::Color), overstrike
+(Pod::Text::Overstrike), and termcap (Pod::Text::Termcap).
+
+-----
+
+Copyright 2015 Russ Allbery <rra@cpan.org>
+
+Copying and distribution of this file, with or without modification, are
+permitted in any medium without royalty provided the copyright notice and
+this notice are preserved.  This file is offered as-is, without any
+warranty.
diff --git a/cpan/podlators/t/data/snippets/man/cpp b/cpan/podlators/t/data/snippets/man/cpp
new file mode 100644 (file)
index 0000000..177aeee
--- /dev/null
@@ -0,0 +1,20 @@
+[name]
+Special handling of C++
+
+[input]
+=head1 NAME
+
+gcc - GNU project C and C++ compiler
+
+=head1 C++ NOTES
+
+Other mentions of C++.
+
+=cut
+
+[output]
+.SH "NAME"
+gcc \- GNU project C and C++ compiler
+.SH "\*(C+ NOTES"
+.IX Header " NOTES"
+Other mentions of \*(C+.
diff --git a/cpan/podlators/t/data/snippets/man/utf8-nonbreaking b/cpan/podlators/t/data/snippets/man/utf8-nonbreaking
new file mode 100644 (file)
index 0000000..8198a77
--- /dev/null
@@ -0,0 +1,17 @@
+[name]
+UTF-8 non-breaking space
+
+[options]
+utf8 1
+
+[input]
+=encoding utf-8
+
+=head1 SE<lt>E<gt> output with UTF-8
+
+This is S<non-breaking output>.
+
+[output]
+.SH "S<> output with UTF\-8"
+.IX Header "S<> output with UTF-8"
+This is non-breaking output.
diff --git a/cpan/podlators/t/data/snippets/man/utf8-verbatim b/cpan/podlators/t/data/snippets/man/utf8-verbatim
new file mode 100644 (file)
index 0000000..0eea4cc
--- /dev/null
@@ -0,0 +1,31 @@
+[name]
+UTF-8 handling in verbatim text
+
+[options]
+utf8 1
+
+[input]
+=encoding utf-8
+
+=head1 BEYONCÉ
+
+Beyoncé!  Beyoncé!  Beyoncé!!
+
+    Beyoncé!  Beyoncé!
+      Beyoncé!  Beyoncé!
+        Beyoncé!  Beyoncé!
+
+Older versions did not convert Beyoncé in verbatim.
+
+[output]
+.SH "BEYONCÉ"
+.IX Header "BEYONCÉ"
+Beyoncé!  Beyoncé!  Beyoncé!!
+.PP
+.Vb 3
+\&    Beyoncé!  Beyoncé!
+\&      Beyoncé!  Beyoncé!
+\&        Beyoncé!  Beyoncé!
+.Ve
+.PP
+Older versions did not convert Beyoncé in verbatim.
diff --git a/cpan/podlators/t/data/snippets/text/cpp b/cpan/podlators/t/data/snippets/text/cpp
new file mode 100644 (file)
index 0000000..b788777
--- /dev/null
@@ -0,0 +1,20 @@
+[name]
+Special handling of C++
+
+[input]
+=head1 NAME
+
+gcc - GNU project C and C++ compiler
+
+=head1 C++ NOTES
+
+Other mentions of C++.
+
+=cut
+
+[output]
+NAME
+    gcc - GNU project C and C++ compiler
+
+C++ NOTES
+    Other mentions of C++.
diff --git a/cpan/podlators/t/data/termcap b/cpan/podlators/t/data/termcap
new file mode 100644 (file)
index 0000000..8094815
--- /dev/null
@@ -0,0 +1,8 @@
+# Simple termcap file.  -*- conf -*-
+#
+# Term::Cap 1.16 will try to fall back to infocmp or a dumb terminal setting
+# unless termcap_path() finds a path to a termcap file.  This is a bug in
+# Term::Cap (see <https://rt.cpan.org/Public/Bug/Display.html?id=96695>), but
+# provide this file anyway to ensure the test suite will still run.
+
+xterm:co=#80:do=^J:md=\E[1m:us=\E[4m:me=\E[m
diff --git a/cpan/podlators/t/devise-date.t b/cpan/podlators/t/devise-date.t
deleted file mode 100644 (file)
index 3cce9f5..0000000
+++ /dev/null
@@ -1,15 +0,0 @@
-#!/usr/bin/perl -w
-
-# In order for MakeMaker to build in the core, nothing can use
-# Fcntl which includes POSIX.  devise_date()'s use of strftime()
-# was replaced.  This tests that it's identical.
-
-use strict;
-
-use Test::More tests => 1;
-
-use Pod::Man;
-use POSIX qw(strftime);
-
-my $parser = Pod::Man->new;
-is $parser->devise_date, strftime("%Y-%m-%d", localtime);
diff --git a/cpan/podlators/t/docs/pod-spelling.t b/cpan/podlators/t/docs/pod-spelling.t
new file mode 100644 (file)
index 0000000..6debd42
--- /dev/null
@@ -0,0 +1,66 @@
+#!/usr/bin/perl
+#
+# Check for spelling errors in POD documentation.
+#
+# The canonical version of this file is maintained in the rra-c-util package,
+# which can be found at <http://www.eyrie.org/~eagle/software/rra-c-util/>.
+#
+# Written by Russ Allbery <eagle@eyrie.org>
+# Copyright 2013, 2014
+#     The Board of Trustees of the Leland Stanford Junior University
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the "Software"),
+# to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+# DEALINGS IN THE SOFTWARE.
+
+use 5.006;
+use strict;
+use warnings;
+
+use lib 't/lib';
+
+use Test::More;
+use Test::RRA qw(skip_unless_author use_prereq);
+
+# Only run this test for the module author since the required stopwords are
+# too sensitive to the exact spell-checking program and dictionary.
+skip_unless_author('Spelling tests');
+
+# Load prerequisite modules.
+use_prereq('Test::Spelling');
+
+# Check all POD in the Perl distribution.  Add the examples directory if it
+# exists.  Also add any files in usr/bin or usr/sbin, which are widely used in
+# Stanford-internal packages.
+my @files = all_pod_files();
+if (-d 'examples') {
+    push(@files, all_pod_files('examples'));
+}
+for my $dir (qw(usr/bin usr/sbin)) {
+    if (-d $dir) {
+        push(@files, glob("$dir/*"));
+    }
+}
+
+# We now have a list of all files to check, so output a plan and run the
+# tests.  We can't use all_pod_files_spelling_ok because it refuses to check
+# non-Perl files and Stanford-internal packages have a lot of shell scripts
+# with POD documentation.
+plan tests => scalar(@files);
+for my $file (@files) {
+    pod_file_spelling_ok($file);
+}
diff --git a/cpan/podlators/t/docs/pod.t b/cpan/podlators/t/docs/pod.t
new file mode 100644 (file)
index 0000000..674ce30
--- /dev/null
@@ -0,0 +1,65 @@
+#!/usr/bin/perl
+#
+# Check all POD documents for POD formatting errors.
+#
+# The canonical version of this file is maintained in the rra-c-util package,
+# which can be found at <http://www.eyrie.org/~eagle/software/rra-c-util/>.
+#
+# Written by Russ Allbery <eagle@eyrie.org>
+# Copyright 2012, 2013, 2014
+#     The Board of Trustees of the Leland Stanford Junior University
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the "Software"),
+# to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+# DEALINGS IN THE SOFTWARE.
+
+use 5.006;
+use strict;
+use warnings;
+
+use lib 't/lib';
+
+use Test::More;
+use Test::RRA qw(skip_unless_automated use_prereq);
+
+# Skip this test for normal user installs, although pod2man may still fail.
+skip_unless_automated('POD syntax tests');
+
+# Load prerequisite modules.
+use_prereq('Test::Pod');
+
+# Check all POD in the Perl distribution.  Add the examples directory if it
+# exists.  Also add any files in usr/bin or usr/sbin, which are widely used in
+# Stanford-internal packages.
+my @files = all_pod_files();
+if (-d 'examples') {
+    push(@files, all_pod_files('examples'));
+}
+for my $dir (qw(usr/bin usr/sbin)) {
+    if (-d $dir) {
+        push(@files, glob("$dir/*"));
+    }
+}
+
+# We now have a list of all files to check, so output a plan and run the
+# tests.  We can't use all_pod_files_ok because it refuses to check non-Perl
+# files and Stanford-internal packages have a lot of shell scripts with POD
+# documentation.
+plan tests => scalar(@files);
+for my $file (@files) {
+    pod_file_ok($file);
+}
diff --git a/cpan/podlators/t/docs/synopsis.t b/cpan/podlators/t/docs/synopsis.t
new file mode 100644 (file)
index 0000000..3d5b44a
--- /dev/null
@@ -0,0 +1,60 @@
+#!/usr/bin/perl
+#
+# Check the SYNOPSIS section of the documentation for syntax errors.
+#
+# The canonical version of this file is maintained in the rra-c-util package,
+# which can be found at <http://www.eyrie.org/~eagle/software/rra-c-util/>.
+#
+# Written by Russ Allbery <eagle@eyrie.org>
+# Copyright 2013, 2014
+#     The Board of Trustees of the Leland Stanford Junior University
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the "Software"),
+# to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+# DEALINGS IN THE SOFTWARE.
+
+use 5.006;
+use strict;
+use warnings;
+
+use lib 't/lib';
+
+use Test::More;
+use Test::RRA qw(skip_unless_automated use_prereq);
+
+# Skip for normal user installs since this doesn't affect functionality.
+skip_unless_automated('Synopsis syntax tests');
+
+# Load prerequisite modules.
+use_prereq('Perl::Critic::Utils');
+use_prereq('Test::Synopsis');
+
+# The default Test::Synopsis all_synopsis_ok() function requires that the
+# module be in a lib directory.  Use Perl::Critic::Utils to find the modules
+# in blib, or lib if it doesn't exist.  However, strip out anything in
+# blib/script, since scripts use a different SYNOPSIS syntax.
+my @files = Perl::Critic::Utils::all_perl_files('blib');
+@files = grep { !m{blib/script/}xms } @files;
+if (!@files) {
+    @files = Perl::Critic::Utils::all_perl_files('lib');
+}
+plan tests => scalar @files;
+
+# Run the actual tests.
+for my $file (@files) {
+    synopsis_ok($file);
+}
diff --git a/cpan/podlators/t/filehandle.t b/cpan/podlators/t/filehandle.t
deleted file mode 100644 (file)
index 8c07416..0000000
+++ /dev/null
@@ -1,110 +0,0 @@
-#!/usr/bin/perl -w
-#
-# filehandle.t -- Test the parse_from_filehandle interface.
-#
-# Copyright 2006, 2009, 2012 by Russ Allbery <rra@stanford.edu>
-#
-# This program is free software; you may redistribute it and/or modify it
-# under the same terms as Perl itself.
-
-BEGIN {
-    chdir 't' if -d 't';
-    if ($ENV{PERL_CORE}) {
-        @INC = '../lib';
-    }
-    unshift (@INC, '../blib/lib');
-    $| = 1;
-}
-
-use strict;
-
-use Test::More tests => 6;
-
-BEGIN {
-    use_ok ('Pod::Man');
-    use_ok ('Pod::Text');
-}
-
-my $man = Pod::Man->new;
-isa_ok ($man, 'Pod::Man', 'Pod::Man parser object');
-my $text = Pod::Text->new;
-isa_ok ($text, 'Pod::Text', 'Pod::Text parser object');
-while (<DATA>) {
-    next until $_ eq "###\n";
-    open (TMP, "> tmp$$.pod") or die "Cannot create tmp.pod: $!\n";
-    while (<DATA>) {
-        last if $_ eq "###\n";
-        print TMP $_;
-    }
-    close TMP;
-
-    # Test Pod::Man output.
-    open (IN, "< tmp$$.pod") or die "Cannot open tmp$$.pod: $!\n";
-    open (OUT, "> out$$.tmp") or die "Cannot create out$$.tmp: $!\n";
-    $man->parse_from_filehandle (\*IN, \*OUT);
-    close IN;
-    close OUT;
-    open (OUT, "out$$.tmp") or die "Cannot open out$$.tmp: $!\n";
-    while (<OUT>) { last if /^\.nh/ }
-    my $output;
-    {
-        local $/;
-        $output = <OUT>;
-    }
-    close OUT;
-    my $expected = '';
-    while (<DATA>) {
-        last if $_ eq "###\n";
-        $expected .= $_;
-    }
-    is ($output, $expected, 'Pod::Man output is correct');
-
-    # Test Pod::Text output.
-    open (IN, "< tmp$$.pod") or die "Cannot open tmp$$.pod: $!\n";
-    open (OUT, "> out$$.tmp") or die "Cannot create out$$.tmp: $!\n";
-    $text->parse_from_filehandle (\*IN, \*OUT);
-    close IN;
-    close OUT;
-    open (OUT, "out$$.tmp") or die "Cannot open out$$.tmp: $!\n";
-    {
-        local $/;
-        $output = <OUT>;
-    }
-    close OUT;
-    1 while unlink ("tmp$$.pod", "out$$.tmp");
-    $expected = '';
-    while (<DATA>) {
-        last if $_ eq "###\n";
-        $expected .= $_;
-    }
-    is ($output, $expected, 'Pod::Text output is correct');
-}
-
-# Below the marker are bits of POD, corresponding expected nroff output, and
-# corresponding expected text output.  The input and output are separated by
-# lines containing only ###.
-
-__DATA__
-
-###
-=head1 NAME
-
-gcc - GNU project C and C++ compiler
-
-=head1 C++ NOTES
-
-Other mentions of C++.
-###
-.SH "NAME"
-gcc \- GNU project C and C++ compiler
-.SH "\*(C+ NOTES"
-.IX Header " NOTES"
-Other mentions of \*(C+.
-###
-NAME
-    gcc - GNU project C and C++ compiler
-
-C++ NOTES
-    Other mentions of C++.
-
-###
diff --git a/cpan/podlators/t/general/basic.t b/cpan/podlators/t/general/basic.t
new file mode 100644 (file)
index 0000000..9b676cc
--- /dev/null
@@ -0,0 +1,108 @@
+#!/usr/bin/perl
+#
+# Basic tests for podlators.
+#
+# This test case uses a single sample file and runs it through all available
+# formatting modules, comparing the results to known-good output that's
+# included with the package.  This provides a general sanity check that the
+# modules are working properly.
+#
+# New regression tests and special cases should probably not be added to the
+# sample input file, since updating all the output files is painful.  Instead,
+# the machinery to run small POD snippets through the specific formatter being
+# tested should probably be used instead.
+#
+# Copyright 2001, 2002, 2004, 2006, 2009, 2012, 2014, 2015
+#     Russ Allbery <rra@cpan.org>
+#
+# This program is free software; you may redistribute it and/or modify it
+# under the same terms as Perl itself.
+
+use 5.006;
+use strict;
+use warnings;
+
+use lib 't/lib';
+
+use File::Spec;
+use Test::More tests => 15;
+use Test::Podlators qw(slurp);
+
+# Check that all the modules can be loaded.
+BEGIN {
+    use_ok('Pod::Man');
+    use_ok('Pod::Text');
+    use_ok('Pod::Text::Color');
+    use_ok('Pod::Text::Overstrike');
+    use_ok('Pod::Text::Termcap');
+}
+
+# Flush output, since otherwise our diag messages come after other tests.
+local $| = 1;
+
+# Hard-code configuration for Term::Cap to get predictable results.
+local $ENV{COLUMNS}  = 80;
+local $ENV{TERM}     = 'xterm';
+local $ENV{TERMPATH} = File::Spec->catfile('t', 'data', 'termcap');
+local $ENV{TERMCAP}  = 'xterm:co=#80:do=^J:md=\\E[1m:us=\\E[4m:me=\\E[m';
+
+# Find the source of the test file.
+my $INPUT = File::Spec->catfile('t', 'data', 'basic.pod');
+
+# Map of translators to the file containing the formatted output to compare
+# against.
+my %OUTPUT = (
+    'Pod::Man'              => File::Spec->catfile('t', 'data', 'basic.man'),
+    'Pod::Text'             => File::Spec->catfile('t', 'data', 'basic.txt'),
+    'Pod::Text::Color'      => File::Spec->catfile('t', 'data', 'basic.clr'),
+    'Pod::Text::Overstrike' => File::Spec->catfile('t', 'data', 'basic.ovr'),
+    'Pod::Text::Termcap'    => File::Spec->catfile('t', 'data', 'basic.cap'),
+);
+
+# Options to pass to all formatting modules.  Match the pod2text default.
+my @OPTIONS = (sentence => 0);
+
+# Walk through teach of the modules and format the sample file, checking to
+# ensure the results match the pre-generated file.
+for my $module (sort keys %OUTPUT) {
+    my $parser = $module->new(@OPTIONS);
+    isa_ok($parser, $module, 'parser object');
+
+    # Run the formatting module.  Store the output into a Perl variable
+    # instead of a file.
+    my $got;
+    $parser->output_string(\$got);
+    $parser->parse_file($INPUT);
+
+    # If the test module is Pod::Man, strip off the header.  This test does
+    # not attempt to compare it, since it contains version numbers that
+    # change.
+    if ($module eq 'Pod::Man') {
+        $got =~ s{ \A .* \n [.]nh \n }{}xms;
+    }
+
+    # OS/390 is EBCDIC, which apparently uses a different character for ESC.
+    # Try to convert so that the test still works.
+    if ($^O eq 'os390' && $module eq 'Pod::Text::Termcap') {
+        $got =~ tr{\033}{\047};
+    }
+
+    # Check the output.  If it doesn't match, save the erroneous output in a
+    # file for later inspection.
+    my $expected = slurp($OUTPUT{$module});
+    if (!ok($got eq $expected, "$module output is correct")) {
+        my ($suffix) = ($OUTPUT{$module} =~ m{ [.] ([^.]+) \z }xms);
+        my $tmpdir = File::Spec->catdir('t', 'tmp');
+        if (!-d $tmpdir) {
+            mkdir($tmpdir, 0777);
+        }
+        my $outfile = File::Spec->catfile('t', 'tmp', "out$$.$suffix");
+        open(my $output, '>', $outfile)
+          or BAIL_OUT("cannot create $outfile for failed output: $!");
+        print {$output} $got
+          or BAIL_OUT("cannot write failed output to $outfile: $!");
+        close($output)
+          or BAIL_OUT("cannot write failed output to $outfile: $!");
+        diag("Non-matching output left in $outfile");
+    }
+}
diff --git a/cpan/podlators/t/general/filehandle.t b/cpan/podlators/t/general/filehandle.t
new file mode 100644 (file)
index 0000000..f726db2
--- /dev/null
@@ -0,0 +1,82 @@
+#!/usr/bin/perl
+#
+# Test the parse_from_filehandle method.
+#
+# This backward compatibility interface is not provided by Pod::Simple, so
+# Pod::Man and Pod::Text had to implement it directly.  Test to be sure it's
+# working properly.
+#
+# Copyright 2006, 2009, 2012, 2014, 2015 Russ Allbery <rra@cpan.org>
+#
+# This program is free software; you may redistribute it and/or modify it
+# under the same terms as Perl itself.
+
+use 5.006;
+use strict;
+use warnings;
+
+use lib 't/lib';
+
+use File::Spec;
+use Test::More tests => 4;
+use Test::Podlators qw(read_snippet slurp);
+
+# Ensure the modules load properly.
+BEGIN {
+    use_ok('Pod::Man');
+    use_ok('Pod::Text');
+}
+
+# Create a temporary directory to use for output, but don't fail if it already
+# exists.  If we failed to create it, we'll fail later on.  We unfortunately
+# have to create files on disk to easily create file handles for testing.
+my $tmpdir = File::Spec->catdir('t', 'tmp');
+if (!-d $tmpdir) {
+    mkdir($tmpdir, 0777);
+}
+
+# Load the tests.
+my $man_data_ref  = read_snippet('man/cpp');
+my $text_data_ref = read_snippet('text/cpp');
+
+# Write the POD source to a temporary file for the input file handle.
+my $infile = File::Spec->catfile('t', 'tmp', "tmp$$.pod");
+open(my $input, '>', $infile) or BAIL_OUT("cannot create $infile: $!");
+print {$input} $man_data_ref->{input}
+  or BAIL_OUT("cannot write to $infile: $!");
+close($input) or BAIL_OUT("cannot write to $infile: $!");
+
+# Write the Pod::Man output to a file.
+my $outfile = File::Spec->catfile('t', 'tmp', "tmp$$.man");
+open($input,     '<', $infile)  or BAIL_OUT("cannot open $infile: $!");
+open(my $output, '>', $outfile) or BAIL_OUT("cannot open $outfile: $!");
+my $parser = Pod::Man->new;
+$parser->parse_from_filehandle($input, $output);
+close($input)  or BAIL_OUT("cannot read from $infile: $!");
+close($output) or BAIL_OUT("cannot write to $outfile: $!");
+
+# Read the output back in and compare it.
+my $got = slurp($outfile, 'man');
+is($got, $man_data_ref->{output}, 'Pod::Man output');
+
+# Clean up the temporary output file.
+unlink($outfile);
+
+# Now, do the same drill with Pod::Text.  Parse the input to a temporary file.
+$outfile = File::Spec->catfile('t', 'tmp', "tmp$$.txt");
+open($input,  '<', $infile)  or BAIL_OUT("cannot open $infile: $!");
+open($output, '>', $outfile) or BAIL_OUT("cannot open $outfile: $!");
+$parser = Pod::Text->new;
+$parser->parse_from_filehandle($input, $output);
+close($input)  or BAIL_OUT("cannot read from $infile: $!");
+close($output) or BAIL_OUT("cannot write to $outfile: $!");
+
+# Read the output back in and compare it.  Pod::Text adds a trailing blank
+# line that we need to strip out.
+$got = slurp($outfile);
+$got =~ s{ \n \s+ \z }{\n}xms;
+is($got, $text_data_ref->{output}, 'Pod::Text output');
+
+# Clean up temporary files.
+unlink($infile, $outfile);
+rmdir($tmpdir);
diff --git a/cpan/podlators/t/general/pod-parser.t b/cpan/podlators/t/general/pod-parser.t
new file mode 100644 (file)
index 0000000..b8adc88
--- /dev/null
@@ -0,0 +1,83 @@
+#!/usr/bin/perl -w
+#
+# Tests for backward compatibility with Pod::Parser.
+#
+# Copyright 2006, 2008, 2009, 2012, 2015 by Russ Allbery <rra@cpan.org>
+#
+# This program is free software; you may redistribute it and/or modify it
+# under the same terms as Perl itself.
+
+use 5.006;
+use strict;
+use warnings;
+
+use lib 't/lib';
+
+use File::Spec;
+use Test::More tests => 7;
+use Test::Podlators qw(slurp);
+
+# Ensure the modules load properly.
+BEGIN {
+    use_ok('Pod::Man');
+    use_ok('Pod::Text');
+}
+
+# Create a temporary directory to use for output, but don't fail if it already
+# exists.  If we failed to create it, we'll fail later on.  We unfortunately
+# have to create files on disk to easily create file handles for testing.
+my $tmpdir = File::Spec->catdir('t', 'tmp');
+if (!-d $tmpdir) {
+    mkdir($tmpdir, 0777);
+}
+
+# Create some test POD to use to test the -cutting option.
+my $infile = File::Spec->catfile('t', 'tmp', "tmp$$.pod");
+open(my $input, '>', $infile) or BAIL_OUT("cannot create $infile: $!");
+print {$input} "Some random B<text>.\n"
+  or BAIL_OUT("cannot write to $infile: $!");
+close($input) or BAIL_OUT("cannot write to $infile: $!");
+
+# Test the -cutting option with Pod::Man.
+my $parser = Pod::Man->new;
+isa_ok($parser, 'Pod::Man', 'Pod::Man parser object');
+my $outfile = File::Spec->catfile('t', 'tmp', "tmp$$.man");
+open(my $output, '>', $outfile) or BAIL_OUT("cannot open $outfile: $!");
+$parser->parse_from_file({ -cutting => 0 }, $infile, $output);
+close($output) or BAIL_OUT("cannot write to $outfile: $!");
+my $got = slurp($outfile, 'man');
+is($got, "Some random \\fBtext\\fR.\n", 'Pod::Man -cutting output');
+unlink($outfile);
+
+# Likewise for Pod::Text.
+$parser = Pod::Text->new;
+isa_ok($parser, 'Pod::Text', 'Pod::Text parser object');
+$outfile = File::Spec->catfile('t', 'tmp', "tmp$$.txt");
+open($output, '>', $outfile) or BAIL_OUT("cannot open $outfile: $!");
+$parser->parse_from_file({ -cutting => 0 }, $infile, $output);
+close($output) or BAIL_OUT("cannot write to $outfile: $!");
+$got = slurp($outfile);
+is($got, "    Some random text.\n\n", 'Pod::Text -cutting output');
+unlink($outfile);
+
+# Rewrite the input file to be fully valid POD since we won't use -cutting.
+unlink($infile);
+open($input, '>', $infile) or BAIL_OUT("cannot create $infile: $!");
+print {$input} "=pod\n\nSome random B<text>.\n"
+  or BAIL_OUT("cannot write to $infile: $!");
+close($input) or BAIL_OUT("cannot write to $infile: $!");
+
+# Now test the pod2text function with a single output.  This will send the
+# results to standard output, so we need to redirect that to a file.
+open($output,         '>',  $outfile) or BAIL_OUT("cannot open $outfile: $!");
+open(my $save_stdout, '>&', STDOUT)   or BAIL_OUT("cannot dup stdout: $!");
+open(STDOUT, '>&', $output) or BAIL_OUT("cannot redirect stdout: $!");
+pod2text($infile);
+close($output) or BAIL_OUT("cannot write to $outfile: $!");
+open(STDOUT, '>&', $save_stdout) or BAIL_OUT("cannot fix stdout: $!");
+close($save_stdout) or BAIL_OUT("cannot close saved stdout: $!");
+$got = slurp($outfile);
+is($got, "    Some random text.\n\n", 'Pod::Text pod2text function');
+
+# Clean up.
+unlink($infile, $outfile);
diff --git a/cpan/podlators/t/lib/Test/Podlators.pm b/cpan/podlators/t/lib/Test/Podlators.pm
new file mode 100644 (file)
index 0000000..7794557
--- /dev/null
@@ -0,0 +1,510 @@
+# Helper functions to test the podlators distribution.
+#
+# This module is an internal implementation detail of the podlators test
+# suite.  It provides some supporting functions to make it easier to write
+# tests.
+#
+# Copyright 2015 Russ Allbery <rra@cpan.org>
+#
+# This program is free software; you may redistribute it and/or modify it
+# under the same terms as Perl itself.
+
+package Test::Podlators;
+
+use 5.006;
+use strict;
+use warnings;
+
+use Encode qw(decode encode);
+use Exporter;
+use File::Spec;
+use Test::More;
+
+# For Perl 5.006 compatibility.
+## no critic (ClassHierarchies::ProhibitExplicitISA)
+
+# Declare variables that should be set in BEGIN for robustness.
+our (@EXPORT_OK, @ISA, $VERSION);
+
+# Set $VERSION and everything export-related in a BEGIN block for robustness
+# against circular module loading (not that we load any modules, but
+# consistency is good).
+BEGIN {
+    @ISA       = qw(Exporter);
+    $VERSION   = '2.00';
+    @EXPORT_OK = qw(
+      read_snippet read_test_data slurp test_snippet test_snippet_with_io
+    );
+}
+
+# The file handle used to capture STDERR while we mess with file descriptors.
+my $OLD_STDERR;
+
+# The file name used to capture standard error output.
+my $SAVED_STDERR;
+
+# Internal function to clean up the standard error output file.  The "1 while"
+# construct is for VMS, in case there are multiple versions of the file.
+sub _stderr_cleanup {
+    if ($SAVED_STDERR && -f $SAVED_STDERR) {
+        unlink($SAVED_STDERR);
+    }
+    my $tmpdir = File::Spec->catdir('t', 'tmp');
+    if (-d $tmpdir) {
+        rmdir($tmpdir);
+    }
+    return;
+}
+
+# Remove saved standard error on exit, even if we have an abnormal exit.
+END {
+    _stderr_cleanup();
+}
+
+# Internal function to redirect stderr to a file.  Stores the name in
+# $SAVED_STDERR.
+sub _stderr_save {
+    my $tmpdir = File::Spec->catdir('t', 'tmp');
+    if (!-d $tmpdir) {
+        mkdir('t/tmp', 0777) or BAIL_OUT("cannot create t/tmp: $!");
+    }
+    my $path = File::Spec->catfile($tmpdir, "out$$.err");
+
+    ## no critic(InputOutput::RequireBriefOpen)
+    open($OLD_STDERR, '>&', STDERR) or BAIL_OUT("cannot dup STDERR: $!");
+    open(STDERR, '>', $path) or BAIL_OUT("cannot redirect STDERR: $!");
+    ## use critic
+
+    $SAVED_STDERR = $path;
+    return;
+}
+
+# Internal function to restore stderr.
+#
+# Returns: The contents of the stderr file.
+sub _stderr_restore {
+    return if !$SAVED_STDERR;
+    close(STDERR) or BAIL_OUT("cannot close STDERR: $!");
+    open(STDERR, '>&', $OLD_STDERR) or BAIL_OUT("cannot dup STDERR: $!");
+    close($OLD_STDERR) or BAIL_OUT("cannot close redirected STDERR: $!");
+    my $stderr = slurp($SAVED_STDERR);
+    _stderr_cleanup();
+    return $stderr;
+}
+
+# Read one test snippet from the provided relative file name and return it.
+# For the format, see t/data/snippets/README.
+#
+# $path - Relative path to read test data from
+#
+# Returns: Reference to hash of test data with the following keys:
+#            name      - Name of the test for status reporting
+#            options   - Hash of options
+#            input     - The input block of the test data
+#            output    - The output block of the test data
+#            errors    - Expected errors
+#            exception - Text of exception (with file and line stripped)
+sub read_snippet {
+    my ($path) = @_;
+    $path = File::Spec->catfile('t', 'data', 'snippets', $path);
+    my %data;
+
+    # Read the sections and store them in the %data hash.
+    my ($line, $section);
+    open(my $fh, '<', $path) or BAIL_OUT("cannot open $path: $!");
+    while (defined($line = <$fh>)) {
+        $line = decode('UTF-8', $line);
+        if ($line =~ m{ \A \s* \[ (\S+) \] \s* \z }xms) {
+            $section = $1;
+        } elsif ($section) {
+            $data{$section} ||= q{};
+            $data{$section} .= $line;
+        }
+    }
+    close($fh) or BAIL_OUT("cannot close $path: $!");
+
+    # Strip trailing blank lines from all sections.
+    for my $section (keys %data) {
+        $data{$section} =~ s{ \n\s+ \z }{\n}xms;
+    }
+
+    # Clean up the name section by removing newlines and extra space.
+    if ($data{name}) {
+        $data{name} =~ s{ \A \s+ }{}xms;
+        $data{name} =~ s{ \s+ \z }{}xms;
+        $data{name} =~ s{ \s+ }{ }xmsg;
+    }
+
+    # Turn the options section into a hash.
+    if ($data{options}) {
+        my @lines = split(m{ \n }xms, $data{options});
+        delete $data{options};
+        for my $optline (@lines) {
+            next if $optline !~ m{ \S }xms;
+            my ($option, $value) = split(q{ }, $optline, 2);
+            if (defined($value)) {
+                chomp($value);
+            } else {
+                $value = q{};
+            }
+            $data{options}{$option} = $value;
+        }
+    }
+
+    # Return the results.
+    return \%data;
+}
+
+# Read one set of test data from the provided file handle and return it.
+# There are several different possible formats, which are specified by the
+# format option.
+#
+# The data read from the file handle will be ignored until a line consisting
+# solely of "###" is found.  Then, two or more blocks separated by "###" are
+# read, ending with another line of "###".  There will always be at least an
+# input and an output block, and may be more blocks based on the format
+# configuration.
+#
+# $fh         - File handle to read the data from
+# $format_ref - Reference to a hash of options describing the data
+#   errors  - Set to true to read expected errors after the output section
+#   options - Set to true to read a hash of options as the first data block
+#
+# Returns: Reference to hash of test data with the following keys:
+#            input   - The input block of the test data
+#            output  - The output block of the test data
+#            errors  - Expected errors if errors was set in $format_ref
+#            options - Hash of options if options was set in $format_ref
+#          or returns undef if no more test data is found.
+sub read_test_data {
+    my ($fh, $format_ref) = @_;
+    $format_ref ||= {};
+    my %data;
+
+    # Find the first block of test data.
+    my $line;
+    while (defined($line = <$fh>)) {
+        last if $line eq "###\n";
+    }
+    if (!defined($line)) {
+        return;
+    }
+
+    # If the format contains the options key, read the options into a hash.
+    if ($format_ref->{options}) {
+        while (defined($line = <$fh>)) {
+            last if $line eq "###\n";
+            my ($option, $value) = split(q{ }, $line, 2);
+            if (defined($value)) {
+                chomp($value);
+            } else {
+                $value = q{};
+            }
+            $data{options}{$option} = $value;
+        }
+    }
+
+    # Read the input and output sections.
+    my @sections = qw(input output);
+    if ($format_ref->{errors}) {
+        push(@sections, 'errors');
+    }
+    for my $key (@sections) {
+        $data{$key} = q{};
+        while (defined($line = <$fh>)) {
+            last if $line eq "###\n";
+            $data{$key} .= $line;
+        }
+    }
+    return \%data;
+}
+
+# Slurp output data back from a file handle.  It would be nice to use
+# Perl6::Slurp, but this is a core module, so we have to implement our own
+# wheels.  BAIL_OUT is called on any failure to read the file.
+#
+# $file  - File to read
+# $strip - If set to "man", strip out the Pod::Man header
+#
+# Returns: Contents of the file, possibly stripped
+sub slurp {
+    my ($file, $strip) = @_;
+    open(my $fh, '<', $file) or BAIL_OUT("cannot open $file: $!");
+
+    # If told to strip the man header, do so.
+    if (defined($strip) && $strip eq 'man') {
+        while (defined(my $line = <$fh>)) {
+            last if $line eq ".nh\n";
+        }
+    }
+
+    # Read the rest of the file and return it.
+    my $data = do { local $/ = undef; <$fh> };
+    close($fh) or BAIL_OUT("cannot read from $file: $!");
+    return $data;
+}
+
+# Test a formatter on a particular POD snippet.  This does all the work of
+# loading the snippet, creating the formatter, running it, and checking the
+# results, and reports those results with Test::More.
+#
+# $class   - Class name of the formatter, as a string
+# $snippet - Path to the snippet file defining the test
+sub test_snippet {
+    my ($class, $snippet) = @_;
+    my $data_ref = read_snippet($snippet);
+
+    # Create the formatter object.
+    my $parser = $class->new(%{ $data_ref->{options} }, name => 'TEST');
+    isa_ok($parser, $class, 'Parser object');
+
+    # Save stderr to a temporary file and then run the parser, storing the
+    # output into a Perl variable.
+    my $errors = _stderr_save();
+    my $got;
+    $parser->output_string(\$got);
+    eval { $parser->parse_string_document($data_ref->{input}) };
+    my $exception = $@;
+    my $stderr    = _stderr_restore();
+
+    # If we were testing Pod::Man, strip off everything prior to .nh from the
+    # output so that we aren't testing the generated header.
+    if ($class eq 'Pod::Man') {
+        $got =~ s{ \A .* \n [.]nh \n }{}xms;
+    }
+
+    # Check the output, errors, and any exception.
+    is($got, $data_ref->{output}, "$data_ref->{name}: output");
+    if ($data_ref->{errors}) {
+        is($stderr, $data_ref->{errors}, "$data_ref->{name}: errors");
+    }
+    if ($data_ref->{exception} || $exception) {
+        if ($exception) {
+            $exception =~ s{ [ ] at [ ] .* }{}xms;
+        }
+        is($exception, $data_ref->{exception}, "$data_ref->{name}: exception");
+    }
+    return;
+}
+
+# Test a formatter with I/O streams on a particular POD snippet.  This does
+# all the work of loading the snippet, creating the formatter, running it, and
+# checking the results, and reports those results with Test::More.  It's
+# similar to test_snippet, but uses input and output temporary files instead
+# to test encoding layers and also checks the Pod::Man accent output.
+#
+# $class       - Class name of the formatter, as a string
+# $snippet     - Path to the snippet file defining the test
+# $options_ref - Hash of options with the following keys:
+#   perlio_utf8 - Set to 1 to set a PerlIO UTF-8 encoding on the output file
+sub test_snippet_with_io {
+    my ($class, $snippet, $options_ref) = @_;
+    my $data_ref = read_snippet($snippet);
+
+    # Create the formatter object.
+    my $parser = $class->new(%{ $data_ref->{options} }, name => 'TEST');
+    isa_ok($parser, $class, 'Parser object');
+
+    # Write the input POD to a temporary file prefaced by the encoding
+    # directive.
+    my $tmpdir = File::Spec->catdir('t', 'tmp');
+    if (!-d $tmpdir) {
+        mkdir($tmpdir, 0777);
+    }
+    my $input_file = File::Spec->catfile('t', 'tmp', "tmp$$.pod");
+    open(my $input, '>', $input_file)
+      or BAIL_OUT("cannot create $input_file: $!");
+    print {$input} encode('UTF-8', $data_ref->{input})
+      or BAIL_OUT("cannot write to $input_file: $!");
+    close($input) or BAIL_OUT("cannot flush output to $input_file: $!");
+
+    # Create an output file and parse from the input file to the output file.
+    my $output_file = File::Spec->catfile('t', 'tmp', "out$$.tmp");
+    open(my $output, '>', $output_file)
+      or BAIL_OUT("cannot create $output_file: $!");
+    if ($options_ref->{perlio_utf8}) {
+        ## no critic (BuiltinFunctions::ProhibitStringyEval)
+        ## no critic (ValuesAndExpressions::RequireInterpolationOfMetachars)
+        eval 'binmode($output, ":encoding(utf-8)")';
+        ## use critic
+    }
+
+    # Parse the input file into the output file.
+    $parser->parse_from_file($input_file, $output);
+    close($output) or BAIL_OUT("cannot flush output to $output_file: $!");
+
+    # Read back in the results, checking to ensure that we didn't output the
+    # accent definitions if we wrote UTF-8 output.
+    open(my $results, '<', $output_file)
+      or BAIL_OUT("cannot open $output_file: $!");
+    my ($line, $saw_accents);
+    while (defined($line = <$results>)) {
+        $line = decode('UTF-8', $line);
+        if ($line =~ m{ Accent [ ] mark [ ] definitions }xms) {
+            $saw_accents = 1;
+        }
+        last if $line =~ m{ \A [.]nh }xms;
+    }
+    my $saw = do { local $/ = undef; <$results> };
+    $saw = decode('UTF-8', $saw);
+    close($results) or BAIL_OUT("cannot close output file: $!");
+
+    # Clean up.
+    unlink($input_file, $output_file);
+
+    # Check the accent definitions and the output.
+    my $perlio = $options_ref->{perlio_utf8} ? ' (PerlIO)' : q{};
+    is(
+        $saw_accents,
+        $data_ref->{options}{utf8} ? undef : 1,
+        "$data_ref->{name}: accent definitions$perlio"
+    );
+    is($saw, $data_ref->{output}, "$data_ref->{name}: output$perlio");
+    return;
+}
+
+1;
+__END__
+
+=for stopwords
+Allbery podlators PerlIO UTF-8 formatter FH whitespace
+
+=head1 NAME
+
+Test::Podlators - Helper functions for podlators tests
+
+=head1 SYNOPSIS
+
+    use Test::Podlators qw(read_test_data);
+
+    # Read the next block of test data, including options.
+    my $data = read_test_data(\*DATA, { options => 1 });
+
+=head1 DESCRIPTION
+
+This module collects various utility functions that are useful for writing
+test cases for the podlators distribution.  It is not intended to be, and
+probably isn't, useful outside of the test suite for that module.
+
+=head1 FUNCTIONS
+
+None of these functions are imported by default.  The ones used by a script
+should be explicitly imported.
+
+=over 4
+
+=item read_snippet(PATH[, OPTIONS])
+
+Read one test snippet from the provided relative file name and return it.  The
+path should be relative to F<t/data/snippets>.  For the format, see
+F<t/data/snippets/README>.
+
+OPTIONS, if present, is a hash that currently supports only one key: C<utf8>,
+to set a PerlIO input encoding layer of UTF-8 when reading the snippet.
+
+The result will be a hash with the following keys:
+
+=over 4
+
+=item name
+
+The name of the test, for reporting purposes.
+
+=item options
+
+A hash of any options to values, if any options were specified.
+
+=item input
+
+Input POD to try formatting.
+
+=item output
+
+The expected output.
+
+=item errors
+
+Expected errors from the POD formatter.
+
+=item exception
+
+An expected exception from the POD formatter, with the file and line
+information stripped from the end of the exception.
+
+=back
+
+=item read_test_data(FH, FORMAT)
+
+Reads a block of test data from FH, looking for test information according to
+the description provided in FORMAT.  All data prior to the first line
+consisting of only C<###> will be ignored.  Then, the test data must consist
+of two or more blocks separated by C<###> and ending in a final C<###> line.
+
+FORMAT is optional, in which case the block of test data should be just input
+text and output text.  If provided, it should be a reference to a hash with
+one or more of the following keys:
+
+=over 4
+
+=item options
+
+If set, the first block of data in the test description is a set of options in
+the form of a key, whitespace, and a value, one per line.  The value may be
+missing, in which case the value associated with the key is the empty string.
+
+=back
+
+The return value is a hash with at least some of the following keys:
+
+=over 4
+
+=item input
+
+The input data for the test.  This is always present.
+
+=item options
+
+If C<options> is set in the FORMAT argument, this is the hash of keys and
+values in the options section of the test data.
+
+=item output
+
+The output data for the test.  This is always present.
+
+=back
+
+=item slurp(FILE[, STRIP])
+
+Read the contents of FILE and return it as a string.  If STRIP is set to
+C<man>, strip off any Pod::Man header from the file before returning it.
+
+=item test_snippet(CLASS, SNIPPET)
+
+Test a formatter on a particular POD snippet.  This does all the work of
+loading the snippet, creating the formatter by instantiating CLASS, running
+it, and checking the results.  Results are reported with Test::More.
+
+=item test_snippet_with_io(CLASS, SNIPPET[, OPTIONS])
+
+The same as test_snippet(), except, rather than parsing the input into a
+string buffer, this function uses real, temporary input and output files.
+This can be used to test I/O layer handling and proper encoding.
+
+OPTIONS, if present, is a reference to a hash of options.  Currently, only
+one key is supported: C<perlio>, which, if set to true, will set a PerlIO
+UTF-8 encoding layer on the output file before writing to it.
+
+=back
+
+=head1 AUTHOR
+
+Russ Allbery <rra@cpan.org>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2015 Russ Allbery <rra@cpan.org>
+
+This program is free software; you may redistribute it and/or modify it
+under the same terms as Perl itself.
+
+=cut
diff --git a/cpan/podlators/t/lib/Test/RRA.pm b/cpan/podlators/t/lib/Test/RRA.pm
new file mode 100644 (file)
index 0000000..3870cc1
--- /dev/null
@@ -0,0 +1,235 @@
+# Helper functions for test programs written in Perl.
+#
+# This module provides a collection of helper functions used by test programs
+# written in Perl.  This is a general collection of functions that can be used
+# by both C packages with Automake and by stand-alone Perl modules.  See
+# Test::RRA::Automake for additional functions specifically for C Automake
+# distributions.
+
+package Test::RRA;
+
+use 5.006;
+use strict;
+use warnings;
+
+use Exporter;
+use Test::More;
+
+# For Perl 5.006 compatibility.
+## no critic (ClassHierarchies::ProhibitExplicitISA)
+
+# Declare variables that should be set in BEGIN for robustness.
+our (@EXPORT_OK, @ISA, $VERSION);
+
+# Set $VERSION and everything export-related in a BEGIN block for robustness
+# against circular module loading (not that we load any modules, but
+# consistency is good).
+BEGIN {
+    @ISA       = qw(Exporter);
+    @EXPORT_OK = qw(skip_unless_author skip_unless_automated use_prereq);
+
+    # This version should match the corresponding rra-c-util release, but with
+    # two digits for the minor version, including a leading zero if necessary,
+    # so that it will sort properly.
+    $VERSION = '5.09';
+}
+
+# Skip this test unless author tests are requested.  Takes a short description
+# of what tests this script would perform, which is used in the skip message.
+# Calls plan skip_all, which will terminate the program.
+#
+# $description - Short description of the tests
+#
+# Returns: undef
+sub skip_unless_author {
+    my ($description) = @_;
+    if (!$ENV{AUTHOR_TESTING}) {
+        plan skip_all => "$description only run for author";
+    }
+    return;
+}
+
+# Skip this test unless doing automated testing or release testing.  This is
+# used for tests that should be run by CPAN smoke testing or during releases,
+# but not for manual installs by end users.  Takes a short description of what
+# tests this script would perform, which is used in the skip message.  Calls
+# plan skip_all, which will terminate the program.
+#
+# $description - Short description of the tests
+#
+# Returns: undef
+sub skip_unless_automated {
+    my ($description) = @_;
+    for my $env (qw(AUTOMATED_TESTING RELEASE_TESTING AUTHOR_TESTING)) {
+        return if $ENV{$env};
+    }
+    plan skip_all => "$description normally skipped";
+    return;
+}
+
+# Attempt to load a module and skip the test if the module could not be
+# loaded.  If the module could be loaded, call its import function manually.
+# If the module could not be loaded, calls plan skip_all, which will terminate
+# the program.
+#
+# The special logic here is based on Test::More and is required to get the
+# imports to happen in the caller's namespace.
+#
+# $module  - Name of the module to load
+# @imports - Any arguments to import, possibly including a version
+#
+# Returns: undef
+sub use_prereq {
+    my ($module, @imports) = @_;
+
+    # If the first import looks like a version, pass it as a bare string.
+    my $version = q{};
+    if (@imports >= 1 && $imports[0] =~ m{ \A \d+ (?: [.][\d_]+ )* \z }xms) {
+        $version = shift(@imports);
+    }
+
+    # Get caller information to put imports in the correct package.
+    my ($package) = caller;
+
+    # Do the import with eval, and try to isolate it from the surrounding
+    # context as much as possible.  Based heavily on Test::More::_eval.
+    ## no critic (BuiltinFunctions::ProhibitStringyEval)
+    ## no critic (ValuesAndExpressions::ProhibitImplicitNewlines)
+    my ($result, $error, $sigdie);
+    {
+        local $@            = undef;
+        local $!            = undef;
+        local $SIG{__DIE__} = undef;
+        $result = eval qq{
+            package $package;
+            use $module $version \@imports;
+            1;
+        };
+        $error = $@;
+        $sigdie = $SIG{__DIE__} || undef;
+    }
+
+    # If the use failed for any reason, skip the test.
+    if (!$result || $error) {
+        my $name = length($version) > 0 ? "$module $version" : $module;
+        plan skip_all => "$name required for test";
+    }
+
+    # If the module set $SIG{__DIE__}, we cleared that via local.  Restore it.
+    ## no critic (Variables::RequireLocalizedPunctuationVars)
+    if (defined($sigdie)) {
+        $SIG{__DIE__} = $sigdie;
+    }
+    return;
+}
+
+1;
+__END__
+
+=for stopwords
+Allbery Allbery's DESC bareword sublicense MERCHANTABILITY NONINFRINGEMENT
+rra-c-util
+
+=head1 NAME
+
+Test::RRA - Support functions for Perl tests
+
+=head1 SYNOPSIS
+
+    use Test::RRA
+      qw(skip_unless_author skip_unless_automated use_prereq);
+
+    # Skip this test unless author tests are requested.
+    skip_unless_author('Coding style tests');
+
+    # Skip this test unless doing automated or release testing.
+    skip_unless_automated('POD syntax tests');
+
+    # Load modules, skipping the test if they're not available.
+    use_prereq('Perl6::Slurp', 'slurp');
+    use_prereq('Test::Script::Run', '0.04');
+
+=head1 DESCRIPTION
+
+This module collects utility functions that are useful for Perl test
+scripts.  It assumes Russ Allbery's Perl module layout and test
+conventions and will only be useful for other people if they use the
+same conventions.
+
+=head1 FUNCTIONS
+
+None of these functions are imported by default.  The ones used by a
+script should be explicitly imported.
+
+=over 4
+
+=item skip_unless_author(DESC)
+
+Checks whether AUTHOR_TESTING is set in the environment and skips the
+whole test (by calling C<plan skip_all> from Test::More) if it is not.
+DESC is a description of the tests being skipped.  A space and C<only run
+for author> will be appended to it and used as the skip reason.
+
+=item skip_unless_automated(DESC)
+
+Checks whether AUTHOR_TESTING, AUTOMATED_TESTING, or RELEASE_TESTING are
+set in the environment and skips the whole test (by calling C<plan
+skip_all> from Test::More) if they are not.  This should be used by tests
+that should not run during end-user installs of the module, but which
+should run as part of CPAN smoke testing and release testing.
+
+DESC is a description of the tests being skipped.  A space and C<normally
+skipped> will be appended to it and used as the skip reason.
+
+=item use_prereq(MODULE[, VERSION][, IMPORT ...])
+
+Attempts to load MODULE with the given VERSION and import arguments.  If
+this fails for any reason, the test will be skipped (by calling C<plan
+skip_all> from Test::More) with a skip reason saying that MODULE is
+required for the test.
+
+VERSION will be passed to C<use> as a version bareword if it looks like a
+version number.  The remaining IMPORT arguments will be passed as the
+value of an array.
+
+=back
+
+=head1 AUTHOR
+
+Russ Allbery <eagle@eyrie.org>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2013, 2014 The Board of Trustees of the Leland Stanford Junior
+University
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+
+=head1 SEE ALSO
+
+Test::More(3), Test::RRA::Automake(3), Test::RRA::Config(3)
+
+This module is maintained in the rra-c-util package.  The current version
+is available from L<http://www.eyrie.org/~eagle/software/rra-c-util/>.
+
+The functions to control when tests are run use environment variables
+defined by the L<Lancaster
+Consensus|https://github.com/Perl-Toolchain-Gang/toolchain-site/blob/master/lancaster-consensus.md>.
+
+=cut
diff --git a/cpan/podlators/t/lib/Test/RRA/Config.pm b/cpan/podlators/t/lib/Test/RRA/Config.pm
new file mode 100644 (file)
index 0000000..7c29f1a
--- /dev/null
@@ -0,0 +1,215 @@
+# Configuration for Perl test cases.
+#
+# In order to reuse the same Perl test cases in multiple packages, I use a
+# configuration file to store some package-specific data.  This module loads
+# that configuration and provides the namespace for the configuration
+# settings.
+
+package Test::RRA::Config;
+
+use 5.006;
+use strict;
+use warnings;
+
+# For Perl 5.006 compatibility.
+## no critic (ClassHierarchies::ProhibitExplicitISA)
+
+use Exporter;
+use Test::More;
+
+# Declare variables that should be set in BEGIN for robustness.
+our (@EXPORT_OK, @ISA, $VERSION);
+
+# Set $VERSION and everything export-related in a BEGIN block for robustness
+# against circular module loading (not that we load any modules, but
+# consistency is good).
+BEGIN {
+    @ISA       = qw(Exporter);
+    @EXPORT_OK = qw(
+      $COVERAGE_LEVEL @COVERAGE_SKIP_TESTS @CRITIC_IGNORE $LIBRARY_PATH
+      $MINIMUM_VERSION %MINIMUM_VERSION @POD_COVERAGE_EXCLUDE @STRICT_IGNORE
+      @STRICT_PREREQ
+    );
+
+    # This version should match the corresponding rra-c-util release, but with
+    # two digits for the minor version, including a leading zero if necessary,
+    # so that it will sort properly.
+    $VERSION = '5.09';
+}
+
+# If BUILD or SOURCE are set in the environment, look for data/perl.conf under
+# those paths for a C Automake package.  Otherwise, look in t/data/perl.conf
+# for a standalone Perl module.  Don't use Test::RRA::Automake since it may
+# not exist.
+our $PATH;
+for my $base ($ENV{BUILD}, $ENV{SOURCE}, 't') {
+    next if !defined($base);
+    my $path = "$base/data/perl.conf";
+    if (-r $path) {
+        $PATH = $path;
+        last;
+    }
+}
+if (!defined($PATH)) {
+    BAIL_OUT('cannot find data/perl.conf');
+}
+
+# Pre-declare all of our variables and set any defaults.
+our $COVERAGE_LEVEL = 100;
+our @COVERAGE_SKIP_TESTS;
+our @CRITIC_IGNORE;
+our $LIBRARY_PATH;
+our $MINIMUM_VERSION = '5.008';
+our %MINIMUM_VERSION;
+our @POD_COVERAGE_EXCLUDE;
+our @STRICT_IGNORE;
+our @STRICT_PREREQ;
+
+# Load the configuration.
+if (!do($PATH)) {
+    my $error = $@ || $! || 'loading file did not return true';
+    BAIL_OUT("cannot load data/perl.conf: $error");
+}
+
+1;
+__END__
+
+=for stopwords
+Allbery rra-c-util Automake perlcritic .libs namespace subdirectory
+sublicense MERCHANTABILITY NONINFRINGEMENT
+
+=head1 NAME
+
+Test::RRA::Config - Perl test configuration
+
+=head1 SYNOPSIS
+
+    use Test::RRA::Config qw($MINIMUM_VERSION);
+    print "Required Perl version is $MINIMUM_VERSION\n";
+
+=head1 DESCRIPTION
+
+Test::RRA::Config encapsulates per-package configuration for generic Perl
+test programs that are shared between multiple packages using the
+rra-c-util infrastructure.  It handles locating and loading the test
+configuration file for both C Automake packages and stand-alone Perl
+modules.
+
+Test::RRA::Config looks for a file named F<data/perl.conf> relative to the
+root of the test directory.  That root is taken from the environment
+variables BUILD or SOURCE (in that order) if set, which will be the case
+for C Automake packages using C TAP Harness.  If neither is set, it
+expects the root of the test directory to be a directory named F<t>
+relative to the current directory, which will be the case for stand-alone
+Perl modules.
+
+The following variables are supported:
+
+=over 4
+
+=item $COVERAGE_LEVEL
+
+The coverage level achieved by the test suite for Perl test coverage
+testing using Test::Strict, as a percentage.  The test will fail if test
+coverage less than this percentage is achieved.  If not given, defaults
+to 100.
+
+=item @COVERAGE_SKIP_TESTS
+
+Directories under F<t> whose tests should be skipped when doing coverage
+testing.  This can be tests that won't contribute to coverage or tests
+that don't run properly under Devel::Cover for some reason (such as ones
+that use taint checking).  F<docs> and F<style> will always be skipped
+regardless of this setting.
+
+=item @CRITIC_IGNORE
+
+Additional directories to ignore when doing recursive perlcritic testing.
+The contents of this directory must be either top-level directory names or
+directory names starting with F<tests/>.
+
+=item $LIBRARY_PATH
+
+Add this directory (or a F<.libs> subdirectory) relative to the top of the
+source tree to LD_LIBRARY_PATH when checking the syntax of Perl modules.
+This may be required to pick up libraries that are used by in-tree Perl
+modules so that Perl scripts can pass a syntax check.
+
+=item $MINIMUM_VERSION
+
+Default minimum version requirement for included Perl scripts.  If not
+given, defaults to 5.008.
+
+=item %MINIMUM_VERSION
+
+Minimum version exceptions for specific directories.  The keys should be
+minimum versions of Perl to enforce.  The value for each key should be a
+reference to an array of either top-level directory names or directory
+names starting with F<tests/>.  All files in those directories will have
+that minimum Perl version constraint imposed instead of $MINIMUM_VERSION.
+
+=item @POD_COVERAGE_EXCLUDE
+
+Regexes that match method names that should be excluded from POD coverage
+testing.  Normally, all methods have to be documented in the POD for a
+Perl module, but methods matching any of these regexes will be considered
+private and won't require documentation.
+
+=item @STRICT_IGNORE
+
+Additional directories to ignore when doing recursive Test::Strict testing
+for C<use strict> and C<use warnings>.  The contents of this directory
+must be either top-level directory names or directory names starting with
+F<tests/>.
+
+=item @STRICT_PREREQ
+
+A list of Perl modules that have to be available in order to do meaningful
+Test::Strict testing.  If any of the modules cannot be loaded via C<use>,
+Test::Strict checking will be skipped.  There is currently no way to
+require specific versions of the modules.
+
+=back
+
+No variables are exported by default, but the variables can be imported
+into the local namespace to avoid long variable names.
+
+=head1 AUTHOR
+
+Russ Allbery <eagle@eyrie.org>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2013, 2014 The Board of Trustees of the Leland Stanford Junior
+University
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+
+=head1 SEE ALSO
+
+perlcritic(1), Test::MinimumVersion(3), Test::RRA(3),
+Test::RRA::Automake(3), Test::Strict(3)
+
+This module is maintained in the rra-c-util package.  The current version
+is available from L<http://www.eyrie.org/~eagle/software/rra-c-util/>.
+
+The C TAP Harness test driver and libraries for TAP-based C testing are
+available from L<http://www.eyrie.org/~eagle/software/c-tap-harness/>.
+
+=cut
diff --git a/cpan/podlators/t/man-heading.t b/cpan/podlators/t/man-heading.t
deleted file mode 100644 (file)
index fa4792c..0000000
+++ /dev/null
@@ -1,90 +0,0 @@
-#!/usr/bin/perl -w
-#
-# man-options.t -- Additional tests for Pod::Man options.
-#
-# Copyright 2002, 2004, 2006, 2008, 2009, 2012 Russ Allbery <rra@stanford.edu>
-#
-# This program is free software; you may redistribute it and/or modify it
-# under the same terms as Perl itself.
-
-BEGIN {
-    chdir 't' if -d 't';
-    if ($ENV{PERL_CORE}) {
-        @INC = '../lib';
-    }
-    unshift (@INC, '../blib/lib');
-    $| = 1;
-}
-
-use strict;
-
-use Test::More tests => 7;
-BEGIN { use_ok ('Pod::Man') }
-
-my $n = 1;
-while (<DATA>) {
-    my %options;
-    next until $_ eq "###\n";
-    while (<DATA>) {
-        last if $_ eq "###\n";
-        my ($option, $value) = split (' ', $_, 2);
-        chomp $value;
-        $options{$option} = $value;
-    }
-    open (TMP, '> tmp.pod') or die "Cannot create tmp.pod: $!\n";
-    print TMP "=head1 NAME\n\ntest - Test man page\n";
-    close TMP;
-    my $parser = Pod::Man->new (%options);
-    isa_ok ($parser, 'Pod::Man', 'Parser object');
-    open (OUT, "> out$$.tmp") or die "Cannot create out$$.tmp: $!\n";
-    $parser->parse_from_file ('tmp.pod', \*OUT);
-    close OUT;
-    open (TMP, "out$$.tmp") or die "Cannot open out$$.tmp: $!\n";
-    my $heading;
-    while (<TMP>) {
-        if (/^\.TH/) {
-            $heading = $_;
-            last;
-        }
-    }
-    close TMP;
-    1 while unlink ('tmp.pod', "out$$.tmp");
-    my $expected = '';
-    while (<DATA>) {
-        last if $_ eq "###\n";
-        $expected .= $_;
-    }
-    is ($heading, $expected, "Heading is correct for test $n");
-    $n++;
-}
-
-# Below the marker are sets of options and the corresponding expected .TH line
-# from the man page.  This is used to test specific features or problems with
-# Pod::Man.  The options and output are separated by lines containing only
-# ###.
-
-__DATA__
-
-###
-date 2009-01-17
-release 1.0
-###
-.TH TMP 1 "2009-01-17" "1.0" "User Contributed Perl Documentation"
-###
-
-###
-date 2009-01-17
-name TEST
-section 8
-release 2.0-beta
-###
-.TH TEST 8 "2009-01-17" "2.0-beta" "User Contributed Perl Documentation"
-###
-
-###
-date 2009-01-17
-release 1.0
-center Testing Documentation
-###
-.TH TMP 1 "2009-01-17" "1.0" "Testing Documentation"
-###
diff --git a/cpan/podlators/t/man-options.t b/cpan/podlators/t/man-options.t
deleted file mode 100644 (file)
index 898abb9..0000000
+++ /dev/null
@@ -1,286 +0,0 @@
-#!/usr/bin/perl -w
-#
-# Additional tests for Pod::Man options.
-#
-# Copyright 2002, 2004, 2006, 2008, 2009, 2012, 2013
-#     Russ Allbery <rra@stanford.edu>
-#
-# This program is free software; you may redistribute it and/or modify it
-# under the same terms as Perl itself.
-
-BEGIN {
-    chdir 't' if -d 't';
-    if ($ENV{PERL_CORE}) {
-        @INC = '../lib';
-    }
-    unshift (@INC, '../blib/lib');
-    $| = 1;
-}
-
-use strict;
-
-use Test::More tests => 28;
-BEGIN { use_ok ('Pod::Man') }
-
-# Redirect stderr to a file.
-sub stderr_save {
-    open (OLDERR, '>&STDERR') or die "Can't dup STDERR: $!\n";
-    open (STDERR, "> out$$.err") or die "Can't redirect STDERR: $!\n";
-}
-
-# Restore stderr.
-sub stderr_restore {
-    close STDERR;
-    open (STDERR, '>&OLDERR') or die "Can't dup STDERR: $!\n";
-    close OLDERR;
-}
-
-my $n = 1;
-while (<DATA>) {
-    my %options;
-    next until $_ eq "###\n";
-    while (<DATA>) {
-        last if $_ eq "###\n";
-        my ($option, $value) = split;
-        $options{$option} = $value;
-    }
-    open (TMP, "> tmp$$.pod") or die "Cannot create tmp$$.pod: $!\n";
-    while (<DATA>) {
-        last if $_ eq "###\n";
-        print TMP $_;
-    }
-    close TMP;
-    my $parser = Pod::Man->new (%options);
-    isa_ok ($parser, 'Pod::Man', 'Parser object');
-    open (OUT, "> out$$.tmp") or die "Cannot create out$$.tmp: $!\n";
-    stderr_save;
-    eval { $parser->parse_from_file ("tmp$$.pod", \*OUT) };
-    my $exception = $@;
-    stderr_restore;
-    close OUT;
-    my $accents = 0;
-    open (TMP, "out$$.tmp") or die "Cannot open out$$.tmp: $!\n";
-    while (<TMP>) {
-        last if /^\.nh/;
-    }
-    my $output;
-    {
-        local $/;
-        $output = <TMP>;
-    }
-    close TMP;
-    1 while unlink ("tmp$$.pod", "out$$.tmp");
-    my $expected = '';
-    while (<DATA>) {
-        last if $_ eq "###\n";
-        $expected .= $_;
-    }
-    is ($output, $expected, "Output correct for test $n");
-    open (ERR, "out$$.err") or die "Cannot open out.err: $!\n";
-    my $errors;
-    {
-        local $/;
-        $errors = <ERR>;
-    }
-    close ERR;
-    $errors =~ s/\Qtmp$$.pod/tmp.pod/g;
-    1 while unlink ("out$$.err");
-    if ($exception) {
-        $exception =~ s/ at .*//;
-        $errors .= "EXCEPTION: $exception";
-    }
-    $expected = '';
-    while (<DATA>) {
-        last if $_ eq "###\n";
-        $expected .= $_;
-    }
-    is ($errors, $expected, "Errors are correct for test $n");
-    $n++;
-}
-
-# Below the marker are bits of POD and corresponding expected text output and
-# error output.  This is used to test specific features or problems with
-# Pod::Man.  The options, input, output, and errors are separated by lines
-# containing only ###.
-
-__DATA__
-
-###
-fixed CR
-fixedbold CY
-fixeditalic CW
-fixedbolditalic CX
-###
-=head1 FIXED FONTS
-
-C<foo B<bar I<baz>> I<bay>>
-###
-.SH "FIXED FONTS"
-.IX Header "FIXED FONTS"
-\&\f(CR\*(C`foo \f(CYbar \f(CXbaz\f(CY\f(CR \f(CWbay\f(CR\*(C'\fR
-###
-###
-
-###
-###
-=over 4
-
-=item Foo
-
-Bar.
-
-=head1 NEXT
-###
-.IP "Foo" 4
-.IX Item "Foo"
-Bar.
-.SH "NEXT"
-.IX Header "NEXT"
-.SH "POD ERRORS"
-.IX Header "POD ERRORS"
-Hey! \fBThe above document had some coding errors, which are explained below:\fR
-.IP "Around line 7:" 4
-.IX Item "Around line 7:"
-You forgot a '=back' before '=head1'
-###
-###
-
-###
-stderr 1
-###
-=over 4
-
-=item Foo
-
-Bar.
-
-=head1 NEXT
-###
-.IP "Foo" 4
-.IX Item "Foo"
-Bar.
-.SH "NEXT"
-.IX Header "NEXT"
-###
-tmp.pod around line 7: You forgot a '=back' before '=head1'
-###
-
-###
-nourls 1
-###
-=head1 URL suppression
-
-L<anchor|http://www.example.com/>
-###
-.SH "URL suppression"
-.IX Header "URL suppression"
-anchor
-###
-###
-
-###
-errors stderr
-###
-=over 4
-
-=item Foo
-
-Bar.
-
-=head1 NEXT
-###
-.IP "Foo" 4
-.IX Item "Foo"
-Bar.
-.SH "NEXT"
-.IX Header "NEXT"
-###
-tmp.pod around line 7: You forgot a '=back' before '=head1'
-###
-
-###
-errors die
-###
-=over 4
-
-=item Foo
-
-Bar.
-
-=head1 NEXT
-###
-.IP "Foo" 4
-.IX Item "Foo"
-Bar.
-.SH "NEXT"
-.IX Header "NEXT"
-###
-tmp.pod around line 7: You forgot a '=back' before '=head1'
-EXCEPTION: POD document had syntax errors
-###
-
-###
-errors pod
-###
-=over 4
-
-=item Foo
-
-Bar.
-
-=head1 NEXT
-###
-.IP "Foo" 4
-.IX Item "Foo"
-Bar.
-.SH "NEXT"
-.IX Header "NEXT"
-.SH "POD ERRORS"
-.IX Header "POD ERRORS"
-Hey! \fBThe above document had some coding errors, which are explained below:\fR
-.IP "Around line 7:" 4
-.IX Item "Around line 7:"
-You forgot a '=back' before '=head1'
-###
-###
-
-###
-errors none
-###
-=over 4
-
-=item Foo
-
-Bar.
-
-=head1 NEXT
-###
-.IP "Foo" 4
-.IX Item "Foo"
-Bar.
-.SH "NEXT"
-.IX Header "NEXT"
-###
-###
-
-###
-errors none
-###
-=over 4
-
-=item foo
-
-Not a bullet.
-
-=item *
-
-Also not a bullet.
-
-=back
-###
-.IP "foo" 4
-.IX Item "foo"
-Not a bullet.
-.IP "*" 4
-Also not a bullet.
-###
diff --git a/cpan/podlators/t/man-perlio.t b/cpan/podlators/t/man-perlio.t
deleted file mode 100644 (file)
index e6aad3a..0000000
+++ /dev/null
@@ -1,135 +0,0 @@
-#!/usr/bin/perl -w
-#
-# man-perlio.t -- Test Pod::Man with a PerlIO UTF-8 encoding layer.
-#
-# Copyright 2002, 2004, 2006, 2008, 2009, 2010, 2012
-#     Russ Allbery <rra@stanford.edu>
-#
-# This program is free software; you may redistribute it and/or modify it
-# under the same terms as Perl itself.
-
-BEGIN {
-    chdir 't' if -d 't';
-    if ($ENV{PERL_CORE}) {
-        @INC = '../lib';
-    }
-    unshift (@INC, '../blib/lib');
-    $| = 1;
-}
-
-use strict;
-
-use Test::More;
-
-# UTF-8 support requires Perl 5.8 or later.
-BEGIN {
-    if ($] < 5.008) {
-        plan skip_all => 'Perl 5.8 required for UTF-8 support';
-    } else {
-        plan tests => 7;
-    }
-}
-BEGIN { use_ok ('Pod::Man') }
-
-# Force UTF-8 on all relevant file handles.  Do this inside eval in case the
-# encoding parameter doesn't work.
-eval { binmode (\*DATA, ':encoding(utf-8)') };
-eval { binmode (\*STDOUT, ':encoding(utf-8)') };
-my $builder = Test::More->builder;
-eval { binmode ($builder->output, ':encoding(utf-8)') };
-eval { binmode ($builder->failure_output, ':encoding(utf-8)') };
-
-my $n = 1;
-while (<DATA>) {
-    my %options;
-    next until $_ eq "###\n";
-    while (<DATA>) {
-        last if $_ eq "###\n";
-        my ($option, $value) = split;
-        $options{$option} = $value;
-    }
-    open (TMP, "> tmp$$.pod") or die "Cannot create tmp$$.pod: $!\n";
-    eval { binmode (\*TMP, ':encoding(utf-8)') };
-    print TMP "=encoding utf-8\n\n";
-    while (<DATA>) {
-        last if $_ eq "###\n";
-        print TMP $_;
-    }
-    close TMP;
-    my $parser = Pod::Man->new (%options);
-    isa_ok ($parser, 'Pod::Man', 'Parser object');
-    open (OUT, "> out$$.tmp") or die "Cannot create out$$.tmp: $!\n";
-    eval { binmode (\*OUT, ':encoding(utf-8)') };
-    $parser->parse_from_file ("tmp$$.pod", \*OUT);
-    close OUT;
-    my $accents = 0;
-    open (TMP, "out$$.tmp") or die "Cannot open out$$.tmp: $!\n";
-    eval { binmode (\*TMP, ':encoding(utf-8)') };
-    while (<TMP>) {
-        $accents = 1 if /Accent mark definitions/;
-        last if /^\.nh/;
-    }
-    my $output;
-    {
-        local $/;
-        $output = <TMP>;
-    }
-    close TMP;
-    1 while unlink ("tmp$$.pod", "out$$.tmp");
-    if ($options{utf8}) {
-        ok (!$accents, "Saw no accent definitions for test $n");
-    } else {
-        ok ($accents, "Saw accent definitions for test $n");
-    }
-    my $expected = '';
-    while (<DATA>) {
-        last if $_ eq "###\n";
-        $expected .= $_;
-    }
-    is ($output, $expected, "Output correct for test $n");
-    $n++;
-}
-
-# Below the marker are bits of POD and corresponding expected text output.
-# This is used to test specific features or problems with Pod::Man.  The
-# input and output are separated by lines containing only ###.
-
-__DATA__
-
-###
-utf8 1
-###
-=head1 BEYONCÉ
-
-Beyoncé!  Beyoncé!  Beyoncé!!
-
-    Beyoncé!  Beyoncé!
-      Beyoncé!  Beyoncé!
-        Beyoncé!  Beyoncé!
-
-Older versions did not convert Beyoncé in verbatim.
-###
-.SH "BEYONCÉ"
-.IX Header "BEYONCÉ"
-Beyoncé!  Beyoncé!  Beyoncé!!
-.PP
-.Vb 3
-\&    Beyoncé!  Beyoncé!
-\&      Beyoncé!  Beyoncé!
-\&        Beyoncé!  Beyoncé!
-.Ve
-.PP
-Older versions did not convert Beyoncé in verbatim.
-###
-
-###
-utf8 1
-###
-=head1 SE<lt>E<gt> output with UTF-8
-
-This is S<non-breaking output>.
-###
-.SH "S<> output with UTF\-8"
-.IX Header "S<> output with UTF-8"
-This is non-breaking output.
-###
diff --git a/cpan/podlators/t/man-utf8.t b/cpan/podlators/t/man-utf8.t
deleted file mode 100644 (file)
index c0d9ba8..0000000
+++ /dev/null
@@ -1,133 +0,0 @@
-#!/usr/bin/perl -w
-#
-# man-utf8.t -- Test Pod::Man with UTF-8 input.
-#
-# Copyright 2002, 2004, 2006, 2008, 2009, 2012 Russ Allbery <rra@stanford.edu>
-#
-# This program is free software; you may redistribute it and/or modify it
-# under the same terms as Perl itself.
-
-BEGIN {
-    chdir 't' if -d 't';
-    if ($ENV{PERL_CORE}) {
-        @INC = '../lib';
-    }
-    unshift (@INC, '../blib/lib');
-    $| = 1;
-}
-
-use strict;
-
-use Test::More;
-
-# UTF-8 support requires Perl 5.8 or later.
-BEGIN {
-    if ($] < 5.008) {
-        plan skip_all => 'Perl 5.8 required for UTF-8 support';
-    } else {
-        plan tests => 7;
-    }
-}
-BEGIN { use_ok ('Pod::Man') }
-
-# Force UTF-8 on all relevant file handles.  Do this inside eval in case the
-# encoding parameter doesn't work.
-eval { binmode (\*DATA, ':encoding(utf-8)') };
-eval { binmode (\*STDOUT, ':encoding(utf-8)') };
-my $builder = Test::More->builder;
-eval { binmode ($builder->output, ':encoding(utf-8)') };
-eval { binmode ($builder->failure_output, ':encoding(utf-8)') };
-
-my $n = 1;
-while (<DATA>) {
-    my %options;
-    next until $_ eq "###\n";
-    while (<DATA>) {
-        last if $_ eq "###\n";
-        my ($option, $value) = split;
-        $options{$option} = $value;
-    }
-    open (TMP, "> tmp$$.pod") or die "Cannot create tmp$$.pod: $!\n";
-    eval { binmode (\*TMP, ':encoding(utf-8)') };
-    print TMP "=encoding utf-8\n\n";
-    while (<DATA>) {
-        last if $_ eq "###\n";
-        print TMP $_;
-    }
-    close TMP;
-    my $parser = Pod::Man->new (%options);
-    isa_ok ($parser, 'Pod::Man', 'Parser object');
-    open (OUT, "> out$$.tmp") or die "Cannot create out$$.tmp: $!\n";
-    $parser->parse_from_file ("tmp$$.pod", \*OUT);
-    close OUT;
-    my $accents = 0;
-    open (TMP, "out$$.tmp") or die "Cannot open out$$.tmp: $!\n";
-    eval { binmode (\*TMP, ':encoding(utf-8)') };
-    while (<TMP>) {
-        $accents = 1 if /Accent mark definitions/;
-        last if /^\.nh/;
-    }
-    my $output;
-    {
-        local $/;
-        $output = <TMP>;
-    }
-    close TMP;
-    1 while unlink ("tmp$$.pod", "out$$.tmp");
-    if ($options{utf8}) {
-        ok (!$accents, "Saw no accent definitions for test $n");
-    } else {
-        ok ($accents, "Saw accent definitions for test $n");
-    }
-    my $expected = '';
-    while (<DATA>) {
-        last if $_ eq "###\n";
-        $expected .= $_;
-    }
-    is ($output, $expected, "Output correct for test $n");
-    $n++;
-}
-
-# Below the marker are bits of POD and corresponding expected text output.
-# This is used to test specific features or problems with Pod::Man.  The
-# input and output are separated by lines containing only ###.
-
-__DATA__
-
-###
-utf8 1
-###
-=head1 BEYONCÉ
-
-Beyoncé!  Beyoncé!  Beyoncé!!
-
-    Beyoncé!  Beyoncé!
-      Beyoncé!  Beyoncé!
-        Beyoncé!  Beyoncé!
-
-Older versions did not convert Beyoncé in verbatim.
-###
-.SH "BEYONCÉ"
-.IX Header "BEYONCÉ"
-Beyoncé!  Beyoncé!  Beyoncé!!
-.PP
-.Vb 3
-\&    Beyoncé!  Beyoncé!
-\&      Beyoncé!  Beyoncé!
-\&        Beyoncé!  Beyoncé!
-.Ve
-.PP
-Older versions did not convert Beyoncé in verbatim.
-###
-
-###
-utf8 1
-###
-=head1 SE<lt>E<gt> output with UTF-8
-
-This is S<non-breaking output>.
-###
-.SH "S<> output with UTF\-8"
-.IX Header "S<> output with UTF-8"
-This is non-breaking output.
-###
similarity index 97%
rename from cpan/podlators/t/man.t
rename to cpan/podlators/t/man/basic.t
index 0645d93..118f22a 100644 (file)
@@ -2,8 +2,8 @@
 #
 # Additional specialized tests for Pod::Man.
 #
-# Copyright 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2010, 2012, 2013
-#     Russ Allbery <rra@stanford.edu>
+# Copyright 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2010, 2012, 2013, 2014
+#     Russ Allbery <rra@cpan.org>
 #
 # This program is free software; you may redistribute it and/or modify it
 # under the same terms as Perl itself.
@@ -33,9 +33,10 @@ while (<DATA>) {
     open (TMP, "> tmp$$.pod") or die "Cannot create tmp$$.pod: $!\n";
 
     # We have a test in ISO 8859-1 encoding.  Make sure that nothing strange
-    # happens if Perl thinks the world is Unicode.  Wrap this in eval so that
-    # older versions of Perl don't croak.
-    eval { binmode (\*TMP, ':encoding(iso-8859-1)') if $have_encoding };
+    # happens if Perl thinks the world is Unicode.  Hide this in a string eval
+    # so that older versions of Perl don't croak and minimum-version tests
+    # still pass.
+    eval 'binmode (\*TMP, ":encoding(iso-8859-1)")' if $have_encoding;
 
     while (<DATA>) {
         last if $_ eq "###\n";
diff --git a/cpan/podlators/t/man/devise-date.t b/cpan/podlators/t/man/devise-date.t
new file mode 100644 (file)
index 0000000..b05b76f
--- /dev/null
@@ -0,0 +1,56 @@
+#!/usr/bin/perl
+#
+# In order for MakeMaker to build in the core, nothing can use Fcntl which
+# includes POSIX.  devise_date()'s use of strftime() was replaced.  This tests
+# that it's identical.  It also tests special handling of the POD_MAN_DATE
+# environment variable.
+
+use 5.006;
+use strict;
+use warnings;
+
+use Pod::Man;
+use POSIX qw(strftime);
+
+use Test::More tests => 6;
+
+# Start with environment variables affecting the date stripped.
+local $ENV{SOURCE_DATE_EPOCH};
+local $ENV{POD_MAN_DATE};
+
+# Check that the results of device_date matches strftime.  There is no input
+# file name, so this will use the current time.
+my $parser = Pod::Man->new;
+is(
+    $parser->devise_date,
+    strftime('%Y-%m-%d', gmtime()),
+    'devise_date matches strftime'
+);
+
+# Set the override environment variable and ensure that it's honored.
+local $ENV{POD_MAN_DATE} = '2014-01-01';
+is($parser->devise_date, '2014-01-01', 'devise_date honors POD_MAN_DATE');
+
+# Check that an empty environment variable is honored.
+local $ENV{POD_MAN_DATE} = q{};
+is($parser->devise_date, q{}, 'devise_date honors empty POD_MAN_DATE');
+
+# Set another environment variable and ensure that it's honored.
+local $ENV{POD_MAN_DATE};
+local $ENV{SOURCE_DATE_EPOCH} = 1439390140;
+is($parser->devise_date, '2015-08-12', 'devise_date honors SOURCE_DATE_EPOCH');
+
+# Check that POD_MAN_DATE overrides SOURCE_DATE_EPOCH
+local $ENV{POD_MAN_DATE}      = '2013-01-01';
+local $ENV{SOURCE_DATE_EPOCH} = 1482676620;
+is($parser->devise_date, '2013-01-01',
+   'devise_date honors POD_MAN_DATE over SOURCE_DATE_EPOCH');
+
+# Check that an invalid SOURCE_DATE_EPOCH is not accepted
+local $ENV{POD_MAN_DATE};
+local $ENV{SOURCE_DATE_EPOCH} = '1482676620B';
+is(
+    $parser->devise_date,
+    strftime('%Y-%m-%d', gmtime()),
+    'devise_date ignores invalid SOURCE_DATE_EPOCH'
+);
diff --git a/cpan/podlators/t/man/devise-title.t b/cpan/podlators/t/man/devise-title.t
new file mode 100644 (file)
index 0000000..d102aa5
--- /dev/null
@@ -0,0 +1,32 @@
+#!/usr/bin/perl
+#
+# Tests for the automatic determination of the manual page title if not
+# specified via options to pod2man or the Pod::Man constructor.
+
+use 5.006;
+use strict;
+use warnings;
+
+use File::Spec;
+use IO::File;
+use Test::More tests => 3;
+
+BEGIN {
+    use_ok('Pod::Man');
+}
+
+# Create a parser and set it up with an input source.  There isn't a way to do
+# this in Pod::Simple without actually parsing the document, so send the
+# output to a string that we'll ignore.
+my $path = File::Spec->catfile('t', 'data', 'basic.pod');
+my $handle = IO::File->new($path, 'r');
+my $parser = Pod::Man->new(errors => 'pod');
+my $output;
+$parser->output_string(\$output);
+$parser->parse_file($handle);
+
+# Check the results of devise_title for this.  We should get back STDIN, and
+# we should have reported an error.
+my ($name, $section) = $parser->devise_title;
+is($name, 'STDIN', 'devise_title uses STDIN for file handle input');
+ok($parser->errors_seen, '...and errors were seen');
similarity index 97%
rename from cpan/podlators/t/man-empty.t
rename to cpan/podlators/t/man/empty.t
index 1e094c8..613b339 100644 (file)
@@ -2,7 +2,7 @@
 #
 # man-empty.t -- Test Pod::Man with a document that produces only errors.
 #
-# Copyright 2013 Russ Allbery <rra@stanford.edu>
+# Copyright 2013 Russ Allbery <rra@cpan.org>
 #
 # This program is free software; you may redistribute it and/or modify it
 # under the same terms as Perl itself.
diff --git a/cpan/podlators/t/man/heading.t b/cpan/podlators/t/man/heading.t
new file mode 100644 (file)
index 0000000..323fd62
--- /dev/null
@@ -0,0 +1,94 @@
+#!/usr/bin/perl
+#
+# Additional tests for Pod::Man heading generation.
+#
+# Copyright 2002, 2004, 2006, 2008, 2009, 2012, 2015
+#     Russ Allbery <rra@cpan.org>
+#
+# This program is free software; you may redistribute it and/or modify it
+# under the same terms as Perl itself.
+
+use 5.006;
+use strict;
+use warnings;
+
+use lib 't/lib';
+
+use Test::More tests => 9;
+use Test::Podlators qw(read_test_data);
+
+BEGIN {
+    use_ok('Pod::Man');
+}
+
+# Loop through all the test data, generate output, and compare it to the
+# desired output data.
+while (defined(my $data = read_test_data(\*DATA, { options => 1 }))) {
+    my $parser = Pod::Man->new(%{ $data->{options} });
+    isa_ok($parser, 'Pod::Man', 'Parser object');
+
+    # Run the parser, storing the output into a Perl variable.
+    my $got;
+    $parser->output_string(\$got);
+    $parser->parse_string_document($data->{input});
+
+    # Extract just the heading line.
+    my ($heading) = ($got =~ m{^ ([.]TH [^\n]+ \n)}xms);
+
+    # Compare the results.
+    is($heading, $data->{output});
+}
+
+# Below the marker are sets of options, the input data, and the corresponding
+# expected .TH line from the man page.  The options and output are separated
+# by lines containing only ###.
+
+__DATA__
+
+###
+date 2009-01-17
+release 1.0
+###
+=head1 NAME
+
+test - Test man page
+###
+.TH STDIN 1 "2009-01-17" "1.0" "User Contributed Perl Documentation"
+###
+
+###
+date 2009-01-17
+name TEST
+section 8
+release 2.0-beta
+###
+=head1 NAME
+
+test - Test man page
+###
+.TH TEST 8 "2009-01-17" "2.0-beta" "User Contributed Perl Documentation"
+###
+
+###
+date 2009-01-17
+release 1.0
+center Testing Documentation
+###
+=head1 NAME
+
+test - Test man page
+###
+.TH STDIN 1 "2009-01-17" "1.0" "Testing Documentation"
+###
+
+###
+date
+release
+center
+###
+=head1 NAME
+
+test - Test man page
+###
+.TH STDIN 1 "" "" ""
+###
diff --git a/cpan/podlators/t/man/options.t b/cpan/podlators/t/man/options.t
new file mode 100644 (file)
index 0000000..7d48b5a
--- /dev/null
@@ -0,0 +1,273 @@
+#!/usr/bin/perl -w
+#
+# Additional tests for Pod::Man options.
+#
+# Copyright 2002, 2004, 2006, 2008, 2009, 2012, 2013, 2015
+#     Russ Allbery <rra@cpan.org>
+#
+# This program is free software; you may redistribute it and/or modify it
+# under the same terms as Perl itself.
+
+use 5.006;
+use strict;
+use warnings;
+
+use lib 't/lib';
+
+use Test::More tests => 31;
+use Test::Podlators qw(read_test_data slurp);
+
+BEGIN {
+    use_ok ('Pod::Man');
+}
+
+# Redirect stderr to a file.  Return the name of the file that stores standard
+# error.
+sub stderr_save {
+    open(OLDERR, '>&STDERR') or die "Can't dup STDERR: $!\n";
+    open(STDERR, "> out$$.err") or die "Can't redirect STDERR: $!\n";
+    return "out$$.err";
+}
+
+# Restore stderr.
+sub stderr_restore {
+    close(STDERR);
+    open(STDERR, '>&OLDERR') or die "Can't dup STDERR: $!\n";
+    close(OLDERR);
+}
+
+# Loop through all the test data, generate output, and compare it to the
+# desired output data.
+my %options = (options => 1, errors => 1);
+my $n = 1;
+while (defined(my $data_ref = read_test_data(\*DATA, \%options))) {
+    my $parser = Pod::Man->new(%{ $data_ref->{options} }, name => 'TEST');
+    isa_ok($parser, 'Pod::Man', 'Parser object');
+
+    # Save stderr to a temporary file and then run the parser, storing the
+    # output into a Perl variable.
+    my $errors = stderr_save();
+    my $got;
+    $parser->output_string(\$got);
+    eval { $parser->parse_string_document($data_ref->{input}) };
+    my $exception = $@;
+    stderr_restore();
+
+    # Strip off everything prior to .nh from the output so that we aren't
+    # testing the generated header, and then check the output.
+    $got =~ s{ \A .* \n [.]nh \n }{}xms;
+    is($got, $data_ref->{output}, "Output for test $n");
+
+    # Collect the errors and add any exception, marking it with EXCEPTION.
+    # Then, compare that to the expected errors.  The "1 while" construct is
+    # for VMS, in case there are multiple versions of the file.
+    my $got_errors = slurp($errors);
+    1 while unlink($errors);
+    if ($exception) {
+        $exception =~ s{ [ ] at [ ] .* }{}xms;
+        $got_errors .= "EXCEPTION: $exception\n";
+    }
+    is($got_errors, $data_ref->{errors}, "Errors for test $n");
+    $n++;
+}
+
+# Below the marker are bits of POD and corresponding expected text output and
+# error output.  The options, input, output, and errors are separated by lines
+# containing only ###.
+
+__DATA__
+
+###
+fixed CR
+fixedbold CY
+fixeditalic CW
+fixedbolditalic CX
+###
+=head1 FIXED FONTS
+
+C<foo B<bar I<baz>> I<bay>>
+###
+.SH "FIXED FONTS"
+.IX Header "FIXED FONTS"
+\&\f(CR\*(C`foo \f(CYbar \f(CXbaz\f(CY\f(CR \f(CWbay\f(CR\*(C'\fR
+###
+###
+
+###
+###
+=over 4
+
+=item Foo
+
+Bar.
+
+=head1 NEXT
+###
+.IP "Foo" 4
+.IX Item "Foo"
+Bar.
+.SH "NEXT"
+.IX Header "NEXT"
+.SH "POD ERRORS"
+.IX Header "POD ERRORS"
+Hey! \fBThe above document had some coding errors, which are explained below:\fR
+.IP "Around line 7:" 4
+.IX Item "Around line 7:"
+You forgot a '=back' before '=head1'
+###
+###
+
+###
+stderr 1
+###
+=over 4
+
+=item Foo
+
+Bar.
+
+=head1 NEXT
+###
+.IP "Foo" 4
+.IX Item "Foo"
+Bar.
+.SH "NEXT"
+.IX Header "NEXT"
+###
+Pod input around line 7: You forgot a '=back' before '=head1'
+###
+
+###
+nourls 1
+###
+=head1 URL suppression
+
+L<anchor|http://www.example.com/>
+###
+.SH "URL suppression"
+.IX Header "URL suppression"
+anchor
+###
+###
+
+###
+errors stderr
+###
+=over 4
+
+=item Foo
+
+Bar.
+
+=head1 NEXT
+###
+.IP "Foo" 4
+.IX Item "Foo"
+Bar.
+.SH "NEXT"
+.IX Header "NEXT"
+###
+Pod input around line 7: You forgot a '=back' before '=head1'
+###
+
+###
+errors die
+###
+=over 4
+
+=item Foo
+
+Bar.
+
+=head1 NEXT
+###
+.IP "Foo" 4
+.IX Item "Foo"
+Bar.
+.SH "NEXT"
+.IX Header "NEXT"
+###
+Pod input around line 7: You forgot a '=back' before '=head1'
+EXCEPTION: POD document had syntax errors
+###
+
+###
+errors pod
+###
+=over 4
+
+=item Foo
+
+Bar.
+
+=head1 NEXT
+###
+.IP "Foo" 4
+.IX Item "Foo"
+Bar.
+.SH "NEXT"
+.IX Header "NEXT"
+.SH "POD ERRORS"
+.IX Header "POD ERRORS"
+Hey! \fBThe above document had some coding errors, which are explained below:\fR
+.IP "Around line 7:" 4
+.IX Item "Around line 7:"
+You forgot a '=back' before '=head1'
+###
+###
+
+###
+errors none
+###
+=over 4
+
+=item Foo
+
+Bar.
+
+=head1 NEXT
+###
+.IP "Foo" 4
+.IX Item "Foo"
+Bar.
+.SH "NEXT"
+.IX Header "NEXT"
+###
+###
+
+###
+errors none
+###
+=over 4
+
+=item foo
+
+Not a bullet.
+
+=item *
+
+Also not a bullet.
+
+=back
+###
+.IP "foo" 4
+.IX Item "foo"
+Not a bullet.
+.IP "*" 4
+Also not a bullet.
+###
+###
+
+###
+quotes \(lq"\(rq"
+###
+=head1 FOO C<BAR> BAZ
+
+Foo C<bar> baz.
+###
+.ie n .SH "FOO \(lq""BAR\(rq"" BAZ"
+.el .SH "FOO \f(CWBAR\fP BAZ"
+.IX Header "FOO BAR BAZ"
+Foo \f(CW\*(C`bar\*(C'\fR baz.
+###
+###
diff --git a/cpan/podlators/t/man/utf8-io.t b/cpan/podlators/t/man/utf8-io.t
new file mode 100644 (file)
index 0000000..858f8f7
--- /dev/null
@@ -0,0 +1,50 @@
+#!/usr/bin/perl -w
+#
+# Test Pod::Man UTF-8 handling, with and without PerlIO.
+#
+# Copyright 2002, 2004, 2006, 2008, 2009, 2010, 2012, 2014, 2015
+#     Russ Allbery <rra@cpan.org>
+#
+# This program is free software; you may redistribute it and/or modify it
+# under the same terms as Perl itself.
+
+use 5.006;
+use strict;
+use warnings;
+
+use lib 't/lib';
+
+use Test::More;
+use Test::Podlators qw(test_snippet_with_io);
+
+# UTF-8 support requires Perl 5.8 or later.
+BEGIN {
+    if ($] < 5.008) {
+        plan skip_all => 'Perl 5.8 required for UTF-8 support';
+    } else {
+        plan tests => 13;
+    }
+}
+
+# Load the module.
+BEGIN {
+    use_ok('Pod::Man');
+}
+
+# Force UTF-8 on all relevant file handles.  Hide this in a string eval so
+# that older versions of Perl don't croak and minimum-version tests still
+# pass.
+#
+## no critic (BuiltinFunctions::ProhibitStringyEval)
+## no critic (ValuesAndExpressions::RequireInterpolationOfMetachars)
+eval 'binmode(\*STDOUT, ":encoding(utf-8)")';
+my $builder = Test::More->builder;
+eval 'binmode($builder->output, ":encoding(utf-8)")';
+eval 'binmode($builder->failure_output, ":encoding(utf-8)")';
+## use critic
+
+# For each of the UTF-8 snippets, check them with and without PerlIO layers.
+for my $snippet (qw(utf8-nonbreaking utf8-verbatim)) {
+    test_snippet_with_io('Pod::Man', "man/$snippet");
+    test_snippet_with_io('Pod::Man', "man/$snippet", { perlio_utf8 => 1 });
+}
similarity index 98%
rename from cpan/podlators/t/parselink.t
rename to cpan/podlators/t/parselink/basic.t
index 828b2ec..d06a3b5 100644 (file)
@@ -2,7 +2,7 @@
 #
 # parselink.t -- Tests for Pod::ParseLink.
 #
-# Copyright 2001, 2009 by Russ Allbery <rra@stanford.edu>
+# Copyright 2001, 2009 by Russ Allbery <rra@cpan.org>
 #
 # This program is free software; you may redistribute it and/or modify it
 # under the same terms as Perl itself.
diff --git a/cpan/podlators/t/pod-parser.t b/cpan/podlators/t/pod-parser.t
deleted file mode 100644 (file)
index 6394731..0000000
+++ /dev/null
@@ -1,78 +0,0 @@
-#!/usr/bin/perl -w
-#
-# pod-parser.t -- Tests for backward compatibility with Pod::Parser.
-#
-# Copyright 2006, 2008, 2009, 2012 by Russ Allbery <rra@stanford.edu>
-#
-# This program is free software; you may redistribute it and/or modify it
-# under the same terms as Perl itself.
-
-BEGIN {
-    chdir 't' if -d 't';
-    if ($ENV{PERL_CORE}) {
-        @INC = '../lib';
-    }
-    unshift (@INC, '../blib/lib');
-    $| = 1;
-}
-
-use strict;
-
-use Test::More tests => 7;
-BEGIN {
-    use_ok ('Pod::Man');
-    use_ok ('Pod::Text');
-}
-
-my $parser = Pod::Man->new;
-isa_ok ($parser, 'Pod::Man', 'Pod::Man parser object');
-open (TMP, "> tmp$$.pod") or die "Cannot create tmp$$.pod: $!\n";
-print TMP "Some random B<text>.\n";
-close TMP;
-open (OUT, "> out$$.tmp") or die "Cannot create out$$.tmp: $!\n";
-$parser->parse_from_file ({ -cutting => 0 }, "tmp$$.pod", \*OUT);
-close OUT;
-open (OUT, "out$$.tmp") or die "Cannot open out$$.tmp: $!\n";
-while (<OUT>) { last if /^\.nh/ }
-my $output;
-{
-    local $/;
-    $output = <OUT>;
-}
-close OUT;
-is ($output, "Some random \\fBtext\\fR.\n", 'Pod::Man -cutting output');
-
-$parser = Pod::Text->new;
-isa_ok ($parser, 'Pod::Text', 'Pod::Text parser object');
-open (OUT, "> out$$.tmp") or die "Cannot create out$$.tmp: $!\n";
-$parser->parse_from_file ({ -cutting => 0 }, "tmp$$.pod", \*OUT);
-close OUT;
-open (OUT, "out$$.tmp") or die "Cannot open out$$.tmp: $!\n";
-{
-    local $/;
-    $output = <OUT>;
-}
-close OUT;
-is ($output, "    Some random text.\n\n", 'Pod::Text -cutting output');
-
-# Test the pod2text function, particularly with only one argument.
-open (TMP, "> tmp$$.pod") or die "Cannot create tmp$$.pod: $!\n";
-print TMP "=pod\n\nSome random B<text>.\n";
-close TMP;
-open (OUT, "> out$$.tmp") or die "Cannot create out$$.tmp: $!\n";
-open (SAVE, '>&STDOUT') or die "Cannot dup stdout: $!\n";
-open (STDOUT, '>&OUT') or die "Cannot replace stdout: $!\n";
-pod2text ("tmp$$.pod");
-close OUT;
-open (STDOUT, '>&SAVE') or die "Cannot fix stdout: $!\n";
-close SAVE;
-open (OUT, "out$$.tmp") or die "Cannot open out$$.tmp: $!\n";
-{
-    local $/;
-    $output = <OUT>;
-}
-close OUT;
-is ($output, "    Some random text.\n\n", 'Pod::Text pod2text function');
-
-1 while unlink ("tmp$$.pod", "out$$.tmp");
-exit 0;
diff --git a/cpan/podlators/t/pod-spelling.t b/cpan/podlators/t/pod-spelling.t
deleted file mode 100644 (file)
index d3ab858..0000000
+++ /dev/null
@@ -1,75 +0,0 @@
-#!/usr/bin/perl -w
-#
-# Check for spelling errors in POD documentation
-#
-# Checks all POD files in the tree for spelling problems using Pod::Spell and
-# either aspell or ispell.  aspell is preferred.  This test is disabled unless
-# RRA_MAINTAINER_TESTS is set, since spelling dictionaries vary too much
-# between environments.
-#
-# Copyright 2008, 2009 Russ Allbery <rra@stanford.edu>
-#
-# This program is free software; you may redistribute it and/or modify it
-# under the same terms as Perl itself.
-
-use strict;
-use Test::More;
-
-# Skip all spelling tests unless the maintainer environment variable is set.
-plan skip_all => 'Spelling tests only run for maintainer'
-    unless $ENV{RRA_MAINTAINER_TESTS};
-
-# Load required Perl modules.
-eval 'use Test::Pod 1.00';
-plan skip_all => 'Test::Pod 1.00 required for testing POD' if $@;
-eval 'use Pod::Spell';
-plan skip_all => 'Pod::Spell required to test POD spelling' if $@;
-
-# Locate a spell-checker.  hunspell is not currently supported due to its lack
-# of support for contractions (at least in the version in Debian).
-my @spell;
-my %options = (aspell => [ qw(-d en_US --home-dir=./ list) ],
-               ispell => [ qw(-d american -l -p /dev/null) ]);
-SEARCH: for my $program (qw/aspell ispell/) {
-    for my $dir (split ':', $ENV{PATH}) {
-        if (-x "$dir/$program") {
-            @spell = ("$dir/$program", @{ $options{$program} });
-        }
-        last SEARCH if @spell;
-    }
-}
-plan skip_all => 'aspell or ispell required to test POD spelling'
-    unless @spell;
-
-# Prerequisites are satisfied, so we're going to do some testing.  Figure out
-# what POD files we have and from that develop our plan.
-$| = 1;
-my @pod = all_pod_files ();
-plan tests => scalar @pod;
-
-# Finally, do the checks.
-for my $pod (@pod) {
-    my $child = open (CHILD, '-|');
-    if (not defined $child) {
-        die "Cannot fork: $!\n";
-    } elsif ($child == 0) {
-        my $pid = open (SPELL, '|-', @spell) or die "Cannot run @spell: $!\n";
-        open (POD, '<', $pod) or die "Cannot open $pod: $!\n";
-        my $parser = Pod::Spell->new;
-        $parser->parse_from_filehandle (\*POD, \*SPELL);
-        close POD;
-        close SPELL;
-        exit ($? >> 8);
-    } else {
-        my @words = <CHILD>;
-        close CHILD;
-      SKIP: {
-            skip "@spell failed for $pod", 1 unless $? == 0;
-            for (@words) {
-                s/^\s+//;
-                s/\s+$//;
-            }
-            is ("@words", '', $pod);
-        }
-    }
-}
diff --git a/cpan/podlators/t/pod.t b/cpan/podlators/t/pod.t
deleted file mode 100644 (file)
index e570e18..0000000
+++ /dev/null
@@ -1,14 +0,0 @@
-#!/usr/bin/perl -w
-#
-# Test POD formatting.
-#
-# Copyright 2009 Russ Allbery <rra@stanford.edu>
-#
-# This program is free software; you may redistribute it and/or modify it
-# under the same terms as Perl itself.
-
-use strict;
-use Test::More;
-eval 'use Test::Pod 1.00';
-plan skip_all => "Test::Pod 1.00 required for testing POD" if $@;
-all_pod_files_ok ();
diff --git a/cpan/podlators/t/style/minimum-version.t b/cpan/podlators/t/style/minimum-version.t
new file mode 100644 (file)
index 0000000..e4eeafd
--- /dev/null
@@ -0,0 +1,47 @@
+#!/usr/bin/perl
+#
+# Check that too-new features of Perl are not being used.
+#
+# The canonical version of this file is maintained in the rra-c-util package,
+# which can be found at <http://www.eyrie.org/~eagle/software/rra-c-util/>.
+#
+# Written by Russ Allbery <eagle@eyrie.org>
+# Copyright 2013, 2014
+#     The Board of Trustees of the Leland Stanford Junior University
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the "Software"),
+# to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+# DEALINGS IN THE SOFTWARE.
+
+use 5.006;
+use strict;
+use warnings;
+
+use lib 't/lib';
+
+use Test::More;
+use Test::RRA qw(skip_unless_automated use_prereq);
+use Test::RRA::Config qw($MINIMUM_VERSION);
+
+# Skip for normal user installs since this doesn't affect functionality.
+skip_unless_automated('Minimum version tests');
+
+# Load prerequisite modules.
+use_prereq('Test::MinimumVersion');
+
+# Check all files in the Perl distribution.
+all_minimum_version_ok($MINIMUM_VERSION);
diff --git a/cpan/podlators/t/style/module-version.t b/cpan/podlators/t/style/module-version.t
new file mode 100644 (file)
index 0000000..0de70c4
--- /dev/null
@@ -0,0 +1,315 @@
+#!/usr/bin/perl
+#
+# Check or update the version of Perl modules.
+#
+# Examines all module files (*.pm) under the lib directory and verifies that
+# the package is set to the same value as the current version number as
+# determined by the MYMETA.json file at the top of the source distribution.
+#
+# When given the --update option, instead fixes all of the Perl modules found
+# to have the correct version.
+
+use 5.006;
+use strict;
+use warnings;
+
+use lib 't/lib';
+
+use Carp qw(croak);
+use File::Find qw(find);
+use Getopt::Long qw(GetOptions);
+use Test::More;
+use Test::RRA qw(skip_unless_automated use_prereq);
+
+# If we have options, we're being run from the command line and always load
+# our prerequisite modules.  Otherwise, check if we have necessary
+# prerequisites and should run as a test suite.
+if (@ARGV) {
+    require JSON::PP;
+    require Perl6::Slurp;
+    Perl6::Slurp->import;
+} else {
+    skip_unless_automated('Module version tests');
+    use_prereq('JSON::PP');
+    use_prereq('Perl6::Slurp');
+}
+
+# A regular expression matching the version string for a module using the
+# package syntax from Perl 5.12 and later.  $1 will contain all of the line
+# contents prior to the actual version string, $2 will contain the version
+# itself, and $3 will contain the rest of the line.
+our $REGEX_VERSION_PACKAGE = qr{
+    (                           # prefix ($1)
+        \A \s*                  # whitespace
+        package \s+             # package keyword
+        [\w\:\']+ \s+           # package name
+    )
+    ( v? [\d._]+ )              # the version number itself ($2)
+    (                           # suffix ($3)
+        \s* ;
+    )
+}xms;
+
+# A regular expression matching a $VERSION string in a module.  $1 will
+# contain all of the line contents prior to the actual version string, $2 will
+# contain the version itself, and $3 will contain the rest of the line.
+our $REGEX_VERSION_OLD = qr{
+    (                           # prefix ($1)
+        \A .*                   # any prefix, such as "our"
+        [\$*]                   # scalar or typeglob
+        [\w\:\']*\b             # optional package name
+        VERSION\b               # version variable
+        \s* = \s*               # assignment
+    )
+    [\"\']?                     # optional leading quote
+    ( v? [\d._]+ )              # the version number itself ($2)
+    [\"\']?                     # optional trailing quote
+    (                           # suffix ($3)
+        \s*
+        ;
+    )
+}xms;
+
+# Find all the Perl modules shipped in this package, if any, and returns the
+# list of file names.
+#
+# $dir - The root directory to search, lib by default
+#
+# Returns: List of file names
+sub module_files {
+    my ($dir) = @_;
+    $dir ||= 'lib';
+    return if !-d $dir;
+    my @files;
+    my $wanted = sub {
+        if ($_ eq 'blib') {
+            $File::Find::prune = 1;
+            return;
+        }
+        if (m{ [.] pm \z }xms) {
+            push(@files, $File::Find::name);
+        }
+        return;
+    };
+    find($wanted, $dir);
+    return @files;
+}
+
+# Given a module file, read it for the version value and return the value.
+#
+# $file - File to check, which should be a Perl module
+#
+# Returns: The version of the module
+#  Throws: Text exception on I/O failure or inability to find version
+sub module_version {
+    my ($file) = @_;
+    open(my $data, q{<}, $file) or die "$0: cannot open $file: $!\n";
+    while (defined(my $line = <$data>)) {
+        if (   $line =~ $REGEX_VERSION_PACKAGE
+            || $line =~ $REGEX_VERSION_OLD)
+        {
+            my ($prefix, $version, $suffix) = ($1, $2, $3);
+            close($data) or die "$0: error reading from $file: $!\n";
+            return $version;
+        }
+    }
+    close($data) or die "$0: error reading from $file: $!\n";
+    die "$0: cannot find version number in $file\n";
+}
+
+# Return the current version of the distribution from MYMETA.json in the
+# current directory.
+#
+# Returns: The version number of the distribution
+# Throws: Text exception if MYMETA.json is not found or doesn't contain a
+#         version
+sub dist_version {
+    my $json     = JSON::PP->new->utf8(1);
+    my $metadata = $json->decode(scalar(slurp('MYMETA.json')));
+    my $version  = $metadata->{version};
+    if (!defined($version)) {
+        die "$0: cannot find version number in MYMETA.json\n";
+    }
+    return $version;
+}
+
+# Given a module file and the new version for that module, update the version
+# in that module to the new one.
+#
+# $file    - Perl module file whose version should be updated
+# $version - The new version number
+#
+# Returns: undef
+#  Throws: Text exception on I/O failure or inability to find version
+sub update_module_version {
+    my ($file, $version) = @_;
+    open(my $in, q{<}, $file) or die "$0: cannot open $file: $!\n";
+    open(my $out, q{>}, "$file.new")
+      or die "$0: cannot create $file.new: $!\n";
+
+    # If the version starts with v, use it without quotes.  Otherwise, quote
+    # it to prevent removal of trailing zeroes.
+    if ($version !~ m{ \A v }xms) {
+        $version = "'$version'";
+    }
+
+    # Scan for the version and replace it.
+  SCAN:
+    while (defined(my $line = <$in>)) {
+        if (   $line =~ s{ $REGEX_VERSION_PACKAGE }{$1$version$3}xms
+            || $line =~ s{ $REGEX_VERSION_OLD     }{$1$version$3}xms)
+        {
+            print {$out} $line or die "$0: cannot write to $file.new: $!\n";
+            last SCAN;
+        }
+        print {$out} $line or die "$0: cannot write to $file.new: $!\n";
+    }
+
+    # Copy the rest of the input file to the output file.
+    print {$out} <$in> or die "$0: cannot write to $file.new: $!\n";
+    close($out) or die "$0: cannot flush $file.new: $!\n";
+    close($in)  or die "$0: error reading from $file: $!\n";
+
+    # All done.  Rename the new file over top of the old file.
+    rename("$file.new", $file)
+      or die "$0: cannot rename $file.new to $file: $!\n";
+    return;
+}
+
+# Act as a test suite.  Find all of the Perl modules in the package, if any,
+# and check that the version for each module matches the version of the
+# distribution.  Reports results with Test::More and sets up a plan based on
+# the number of modules found.
+#
+# Returns: undef
+#  Throws: Text exception on fatal errors
+sub test_versions {
+    my $dist_version = dist_version();
+    my @modules      = module_files();
+
+    # Output the plan.  Skip the test if there were no modules found.
+    if (@modules) {
+        plan tests => scalar(@modules);
+    } else {
+        plan skip_all => 'No Perl modules found';
+        return;
+    }
+
+    # For each module, get the module version and compare.
+    for my $module (@modules) {
+        my $module_version = module_version($module);
+        is($module_version, $dist_version, "Version for $module");
+    }
+    return;
+}
+
+# Update the versions of all modules to the current distribution version.
+#
+# Returns: undef
+#  Throws: Text exception on fatal errors
+sub update_versions {
+    my $version = dist_version();
+    my @modules = module_files();
+    for my $module (@modules) {
+        update_module_version($module, $version);
+    }
+    return;
+}
+
+# Main routine.  We run as either a test suite or as a script to update all of
+# the module versions, selecting based on whether we got the -u / --update
+# command-line option.
+my $update;
+Getopt::Long::config('bundling', 'no_ignore_case');
+GetOptions('update|u' => \$update) or exit 1;
+if ($update) {
+    update_versions();
+} else {
+    test_versions();
+}
+exit 0;
+__END__
+
+=for stopwords
+Allbery sublicense MERCHANTABILITY NONINFRINGEMENT CPAN
+
+=head1 NAME
+
+module-version.t - Check or update versions of Perl modules
+
+=head1 SYNOPSIS
+
+B<module-version.t> [B<--update>]
+
+=head1 REQUIREMENTS
+
+Perl 5.6.0 or later, the Perl6::Slurp module, and the JSON::PP Perl
+module, both of which are available from CPAN.  JSON::PP is also included
+in Perl core in Perl 5.14 and later.
+
+=head1 DESCRIPTION
+
+This script has a dual purpose as either a test script or a utility
+script.  The intent is to assist with maintaining consistent versions in a
+Perl distribution, supporting both the package keyword syntax introduced
+in Perl 5.12 or the older explicit setting of a $VERSION variable.
+
+As a test, it reads the current version of a package from the
+F<MYMETA.json> file in the current directory (which should be the root of
+the distribution) and then looks for any Perl modules in F<lib>.  If it
+finds any, it checks that the version number of the Perl module matches
+the version number of the package from the F<MYMETA.json> file.  These
+test results are reported with Test::More, suitable for any TAP harness.
+
+As a utility script, when run with the B<--update> option, it similarly
+finds all Perl modules in F<lib> and then rewrites their version setting
+to match the version of the package as determined from the F<MYMETA.json>
+file.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-u>, B<--update>
+
+Rather than test the Perl modules for the correct version, update all
+Perl modules found in the tree under F<lib> to the current version
+from the C<MYMETA.json> file.
+
+=back
+
+=head1 AUTHOR
+
+Russ Allbery <eagle@eyrie.org>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2013, 2014 The Board of Trustees of the Leland Stanford Junior
+University
+
+Copyright 2014, 2015 Russ Allbery <eagle@eyrie.org>
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+
+=head1 SEE ALSO
+
+This module is maintained in the rra-c-util package.  The current version
+is available from L<http://www.eyrie.org/~eagle/software/rra-c-util/>.
+
+=cut
diff --git a/cpan/podlators/t/style/strict.t b/cpan/podlators/t/style/strict.t
new file mode 100644 (file)
index 0000000..7137b15
--- /dev/null
@@ -0,0 +1,56 @@
+#!/usr/bin/perl
+#
+# Test Perl code for strict, warnings, and syntax.
+#
+# The canonical version of this file is maintained in the rra-c-util package,
+# which can be found at <http://www.eyrie.org/~eagle/software/rra-c-util/>.
+#
+# Written by Russ Allbery <eagle@eyrie.org>
+# Copyright 2013, 2014
+#     The Board of Trustees of the Leland Stanford Junior University
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the "Software"),
+# to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+# DEALINGS IN THE SOFTWARE.
+
+use 5.006;
+use strict;
+use warnings;
+
+use lib 't/lib';
+
+use File::Spec;
+use Test::RRA qw(skip_unless_automated use_prereq);
+
+# Skip for normal user installs since this doesn't affect functionality.
+skip_unless_automated('Strictness tests');
+
+# Load prerequisite modules.
+use_prereq('Test::Strict');
+
+# Test everything in the distribution directory except the Build and
+# Makefile.PL scripts generated by Module::Build.  We also want to check use
+# warnings.
+$Test::Strict::TEST_SKIP = ['Build', 'Makefile.PL'];
+$Test::Strict::TEST_WARNINGS = 1;
+all_perl_files_ok(File::Spec->curdir);
+
+# Hack to suppress "used only once" warnings.
+END {
+    $Test::Strict::TEST_SKIP     = [];
+    $Test::Strict::TEST_WARNINGS = 0;
+}
similarity index 98%
rename from cpan/podlators/t/text.t
rename to cpan/podlators/t/text/basic.t
index 223e0b0..1d274c3 100644 (file)
@@ -3,7 +3,7 @@
 # text.t -- Additional specialized tests for Pod::Text.
 #
 # Copyright 2002, 2004, 2006, 2007, 2008, 2009, 2012
-#     Russ Allbery <rra@stanford.edu>
+#     Russ Allbery <rra@cpan.org>
 #
 # This program is free software; you may redistribute it and/or modify it
 # under the same terms as Perl itself.
similarity index 98%
rename from cpan/podlators/t/color.t
rename to cpan/podlators/t/text/color.t
index 4fd1bd1..c2e1333 100644 (file)
@@ -3,7 +3,7 @@
 # color.t -- Additional specialized tests for Pod::Text::Color.
 #
 # Copyright 2002, 2004, 2006, 2009, 2012, 2013
-#     Russ Allbery <rra@stanford.edu>
+#     Russ Allbery <rra@cpan.org>
 #
 # This program is free software; you may redistribute it and/or modify it
 # under the same terms as Perl itself.
similarity index 96%
rename from cpan/podlators/t/text-empty.t
rename to cpan/podlators/t/text/empty.t
index 2164a75..0b8823a 100644 (file)
@@ -2,7 +2,7 @@
 #
 # text-empty.t -- Test Pod::Text with a document that produces only errors.
 #
-# Copyright 2013 Russ Allbery <rra@stanford.edu>
+# Copyright 2013 Russ Allbery <rra@cpan.org>
 #
 # This program is free software; you may redistribute it and/or modify it
 # under the same terms as Perl itself.
similarity index 89%
rename from cpan/podlators/t/text-encoding.t
rename to cpan/podlators/t/text/encoding.t
index d096b37..7fe7401 100644 (file)
@@ -2,8 +2,8 @@
 #
 # text-encoding.t -- Test Pod::Text with various weird encoding combinations.
 #
-# Copyright 2002, 2004, 2006, 2007, 2008, 2009, 2012
-#     Russ Allbery <rra@stanford.edu>
+# Copyright 2002, 2004, 2006, 2007, 2008, 2009, 2012, 2015
+#     Russ Allbery <rra@cpan.org>
 #
 # This program is free software; you may redistribute it and/or modify it
 # under the same terms as Perl itself.
@@ -26,7 +26,7 @@ BEGIN {
     if ($] < 5.008) {
         plan skip_all => 'Perl 5.8 required for encoding support';
     } else {
-        plan tests => 5;
+        plan tests => 7;
     }
 }
 BEGIN { use_ok ('Pod::Text') }
@@ -127,3 +127,30 @@ I can eat glass
     See <http://www.columbia.edu/kermit/utf8.html>
 
 ###
+
+###
+=pod
+
+=head1 NAME
+
+This is the first ascii text
+
+=encoding utf8
+
+=over 4
+
+=item ⇒This is the first non-ascii text⇐
+
+This is the second ascii text
+
+=back
+
+=cut
+###
+NAME
+    This is the first ascii text
+
+    ⇒This is the first non-ascii text⇐
+        This is the second ascii text
+
+###
similarity index 95%
rename from cpan/podlators/t/text-options.t
rename to cpan/podlators/t/text/options.t
index 06bf081..3338aa6 100644 (file)
@@ -2,8 +2,8 @@
 #
 # Additional tests for Pod::Text options.
 #
-# Copyright 2002, 2004, 2006, 2008, 2009, 2012, 2013
-#     Russ Allbery <rra@stanford.edu>
+# Copyright 2002, 2004, 2006, 2008, 2009, 2012, 2013, 2015
+#     Russ Allbery <rra@cpan.org>
 #
 # This program is free software; you may redistribute it and/or modify it
 # under the same terms as Perl itself.
@@ -19,7 +19,7 @@ BEGIN {
 
 use strict;
 
-use Test::More tests => 34;
+use Test::More tests => 37;
 BEGIN { use_ok ('Pod::Text') }
 
 # Redirect stderr to a file.
@@ -351,3 +351,16 @@ Bar.
 NEXT
 ###
 ###
+
+###
+quotes <<<>>>
+###
+=head1 FOO C<BAR> BAZ
+
+Foo C<bar> baz.
+###
+FOO <<<BAR>>> BAZ
+    Foo <<<bar>>> baz.
+
+###
+###
similarity index 98%
rename from cpan/podlators/t/overstrike.t
rename to cpan/podlators/t/text/overstrike.t
index 13ee2c8..c5496bb 100644 (file)
@@ -3,7 +3,7 @@
 # overstrike.t -- Additional specialized tests for Pod::Text::Overstrike.
 #
 # Copyright 2002, 2004, 2006, 2009, 2012, 2013
-#     Russ Allbery <rra@stanford.edu>
+#     Russ Allbery <rra@cpan.org>
 #
 # This program is free software; you may redistribute it and/or modify it
 # under the same terms as Perl itself.
similarity index 81%
rename from cpan/podlators/t/text-perlio.t
rename to cpan/podlators/t/text/perlio.t
index fe50ca1..c95f682 100644 (file)
@@ -2,8 +2,8 @@
 #
 # text-perlio.t -- Test Pod::Text with a PerlIO UTF-8 encoding layer.
 #
-# Copyright 2002, 2004, 2006, 2007, 2008, 2009, 2010, 2012
-#     Russ Allbery <rra@stanford.edu>
+# Copyright 2002, 2004, 2006, 2007, 2008, 2009, 2010, 2012, 2014
+#     Russ Allbery <rra@cpan.org>
 #
 # This program is free software; you may redistribute it and/or modify it
 # under the same terms as Perl itself.
@@ -31,18 +31,22 @@ BEGIN {
 }
 BEGIN { use_ok ('Pod::Text') }
 
+# Force UTF-8 on all relevant file handles.  Hide this in a string eval so
+# that older versions of Perl don't croak and minimum-version tests still
+# pass.
+eval 'binmode (\*DATA, ":encoding(utf-8)")';
+eval 'binmode (\*STDOUT, ":encoding(utf-8)")';
+my $builder = Test::More->builder;
+eval 'binmode ($builder->output, ":encoding(utf-8)")';
+eval 'binmode ($builder->failure_output, ":encoding(utf-8)")';
+
 my $parser = Pod::Text->new (utf8 => 1);
 isa_ok ($parser, 'Pod::Text', 'Parser object');
 my $n = 1;
-eval { binmode (\*DATA, ':encoding(utf-8)') };
-eval { binmode (\*STDOUT, ':encoding(utf-8)') };
-my $builder = Test::More->builder;
-eval { binmode ($builder->output, ':encoding(utf-8)') };
-eval { binmode ($builder->failure_output, ':encoding(utf-8)') };
 while (<DATA>) {
     next until $_ eq "###\n";
     open (TMP, "> tmp$$.pod") or die "Cannot create tmp$$.pod: $!\n";
-    eval { binmode (\*TMP, ':encoding(utf-8)') };
+    eval 'binmode (\*TMP, ":encoding(utf-8)")';
     print TMP "=encoding UTF-8\n\n";
     while (<DATA>) {
         last if $_ eq "###\n";
@@ -50,11 +54,11 @@ while (<DATA>) {
     }
     close TMP;
     open (OUT, "> out$$.tmp") or die "Cannot create out$$.tmp: $!\n";
-    eval { binmode (\*OUT, ':encoding(utf-8)') };
+    eval 'binmode (\*OUT, ":encoding(utf-8)")';
     $parser->parse_from_file ("tmp$$.pod", \*OUT);
     close OUT;
     open (TMP, "out$$.tmp") or die "Cannot open out$$.tmp: $!\n";
-    eval { binmode (\*TMP, ':encoding(utf-8)') };
+    eval 'binmode (\*TMP, ":encoding(utf-8)")';
     my $output;
     {
         local $/;
similarity index 74%
rename from cpan/podlators/t/termcap.t
rename to cpan/podlators/t/text/termcap.t
index d751bad..4b30c62 100644 (file)
@@ -2,8 +2,8 @@
 #
 # termcap.t -- Additional specialized tests for Pod::Text::Termcap.
 #
-# Copyright 2002, 2004, 2006, 2009, 2012, 2013
-#     Russ Allbery <rra@stanford.edu>
+# Copyright 2002, 2004, 2006, 2009, 2012, 2013, 2014
+#     Russ Allbery <rra@cpan.org>
 #
 # This program is free software; you may redistribute it and/or modify it
 # under the same terms as Perl itself.
@@ -19,13 +19,29 @@ BEGIN {
 
 use strict;
 
+use File::Spec;
 use Test::More tests => 4;
+
 BEGIN { use_ok ('Pod::Text::Termcap') }
 
+# Find the path to the test source files.  This requires some fiddling when
+# these tests are run as part of Perl core.
+sub source_path {
+    my $file = shift;
+    if ($ENV{PERL_CORE}) {
+        my $updir = File::Spec->updir;
+        my $dir = File::Spec->catdir ($updir, 'lib', 'Pod', 't', 'data');
+        return File::Spec->catfile ($dir, $file);
+    } else {
+        return File::Spec->catfile ('data', $file);
+    }
+}
+
 # Hard-code a few values to try to get reproducible results.
-$ENV{COLUMNS} = 80;
-$ENV{TERM} = 'xterm';
-$ENV{TERMCAP} = 'xterm:co=80:do=^J:md=\E[1m:us=\E[4m:me=\E[m';
+$ENV{COLUMNS}  = 80;
+$ENV{TERM}     = 'xterm';
+$ENV{TERMPATH} = source_path ('termcap');
+$ENV{TERMCAP}  = 'xterm:co=#80:do=^J:md=\E[1m:us=\E[4m:me=\E[m';
 
 my $parser = Pod::Text::Termcap->new;
 isa_ok ($parser, 'Pod::Text::Termcap', 'Parser module');
similarity index 82%
rename from cpan/podlators/t/text-utf8.t
rename to cpan/podlators/t/text/utf8.t
index 822f1ea..e468c57 100644 (file)
@@ -2,8 +2,8 @@
 #
 # text-utf8.t -- Test Pod::Text with UTF-8 input.
 #
-# Copyright 2002, 2004, 2006, 2007, 2008, 2009, 2012
-#     Russ Allbery <rra@stanford.edu>
+# Copyright 2002, 2004, 2006, 2007, 2008, 2009, 2012, 2014
+#     Russ Allbery <rra@cpan.org>
 #
 # This program is free software; you may redistribute it and/or modify it
 # under the same terms as Perl itself.
@@ -31,18 +31,22 @@ BEGIN {
 }
 BEGIN { use_ok ('Pod::Text') }
 
+# Force UTF-8 on all relevant file handles.  Hide this in a string eval so
+# that older versions of Perl don't croak and minimum-version tests still
+# pass.
+eval 'binmode (\*DATA, ":encoding(utf-8)")';
+eval 'binmode (\*STDOUT, ":encoding(utf-8)")';
+my $builder = Test::More->builder;
+eval 'binmode ($builder->output, ":encoding(utf-8)")';
+eval 'binmode ($builder->failure_output, ":encoding(utf-8)")';
+
 my $parser = Pod::Text->new;
 isa_ok ($parser, 'Pod::Text', 'Parser object');
 my $n = 1;
-eval { binmode (\*DATA, ':encoding(utf-8)') };
-eval { binmode (\*STDOUT, ':encoding(utf-8)') };
-my $builder = Test::More->builder;
-eval { binmode ($builder->output, ':encoding(utf-8)') };
-eval { binmode ($builder->failure_output, ':encoding(utf-8)') };
 while (<DATA>) {
     next until $_ eq "###\n";
     open (TMP, "> tmp$$.pod") or die "Cannot create tmp$$.pod: $!\n";
-    eval { binmode (\*TMP, ':encoding(utf-8)') };
+    eval 'binmode (\*TMP, ":encoding(utf-8)")';
     print TMP "=encoding UTF-8\n\n";
     while (<DATA>) {
         last if $_ eq "###\n";
@@ -53,7 +57,7 @@ while (<DATA>) {
     $parser->parse_from_file ("tmp$$.pod", \*OUT);
     close OUT;
     open (TMP, "out$$.tmp") or die "Cannot open out$$.tmp: $!\n";
-    eval { binmode (\*TMP, ':encoding(utf-8)') };
+    eval 'binmode (\*TMP, ":encoding(utf-8)")';
     my $output;
     {
         local $/;
index c65c16b..22524a9 100644 (file)
@@ -280,16 +280,18 @@ The current version is always available from its web site at
 
 =head1 AUTHOR
 
-Russ Allbery <rra@stanford.edu>, with large portions of this documentation
+Russ Allbery <rra@cpan.org>, with large portions of this documentation
 taken from the documentation of the original B<pod2man> implementation by
 Larry Wall and Tom Christiansen.
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010 Russ Allbery
-<rra@stanford.edu>.
+Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2015 Russ Allbery
+<rra@cpan.org>
 
-This documentation is free software; you may redistribute it and/or modify
-it under the same terms as Perl itself.
+Copying and distribution of this file, with or without modification, are
+permitted in any medium without royalty provided the copyright notice and
+this notice are preserved.  This file is offered as-is, without any
+warranty.
 
 =cut
index 2c733b6..292776a 100644 (file)
@@ -313,4 +313,3 @@ lib/benchmark.pm    Verbatim line length including indents exceeds 79 by    2
 lib/config.pod ? Should you be using L<...> instead of -1
 lib/extutils/embed.pm  Verbatim line length including indents exceeds 79 by    2
 lib/perl5db.pl ? Should you be using L<...> instead of 1
-lib/pod/text/overstrike.pm     Verbatim line length including indents exceeds 79 by    1
index 27c371f..c1dea90 100644 (file)
@@ -35,9 +35,9 @@ print $fh <<'EOT';
 # Files to be built with variable substitution after miniperl is
 # available.  Dependencies handled manually below (for now).
 
-pl = c2ph.PL corelist.PL cpan.PL h2ph.PL h2xs.PL instmodsh.PL json_pp.PL perlbug.PL perldoc.PL perlivp.PL pl2pm.PL prove.PL ptar.PL ptardiff.PL ptargrep.PL shasum.PL splain.PL libnetcfg.PL piconv.PL enc2xs.PL encguess.PL xsubpp.PL pod2html.PL zipdetails.PL
-plextract = c2ph corelist cpan h2ph h2xs instmodsh json_pp perlbug perldoc perlivp pl2pm prove ptar ptardiff ptargrep shasum splain libnetcfg piconv enc2xs encguess xsubpp pod2html zipdetails
-plextractexe = ./c2ph ./corelist ./cpan ./h2ph ./h2xs ./json_pp ./instmodsh ./perlbug ./perldoc ./perlivp ./pl2pm ./prove ./ptar ./ptardiff ./ptargrep ./shasum ./splain ./libnetcfg ./piconv ./enc2xs ./encguess ./xsubpp ./pod2html ./zipdetails
+pl = c2ph.PL corelist.PL cpan.PL h2ph.PL h2xs.PL instmodsh.PL json_pp.PL perlbug.PL perldoc.PL perlivp.PL pl2pm.PL prove.PL ptar.PL ptardiff.PL ptargrep.PL shasum.PL splain.PL libnetcfg.PL piconv.PL enc2xs.PL encguess.PL xsubpp.PL pod2html.PL pod2man.PL pod2text.PL zipdetails.PL
+plextract = c2ph corelist cpan h2ph h2xs instmodsh json_pp perlbug perldoc perlivp pl2pm prove ptar ptardiff ptargrep shasum splain libnetcfg piconv enc2xs encguess xsubpp pod2html pod2man pod2text zipdetails
+plextractexe = ./c2ph ./corelist ./cpan ./h2ph ./h2xs ./json_pp ./instmodsh ./perlbug ./perldoc ./perlivp ./pl2pm ./prove ./ptar ./ptardiff ./ptargrep ./shasum ./splain ./libnetcfg ./piconv ./enc2xs ./encguess ./xsubpp ./pod2html ./pod2man ./pod2man ./zipdetails
 
 all: $(plextract) 
 
diff --git a/utils/pod2man.PL b/utils/pod2man.PL
new file mode 100644 (file)
index 0000000..69172f6
--- /dev/null
@@ -0,0 +1,53 @@
+#!/usr/local/bin/perl
+
+use Config;
+use File::Basename qw(&basename &dirname);
+use Cwd;
+
+# List explicitly here the variables you want Configure to
+# generate.  Metaconfig only looks for shell variables, so you
+# have to mention them as if they were shell variables, not
+# %Config entries.  Thus you write
+#  $startperl
+# to ensure Configure will look for $Config{startperl}.
+
+# This forces PL files to create target in same directory as PL file.
+# This is so that make depend always knows where to find PL derivatives.
+my $origdir = cwd;
+chdir dirname($0);
+my $file = basename($0, '.PL');
+$file .= '.com' if $^O eq 'VMS';
+
+open OUT,">$file" or die "Can't create $file: $!";
+
+print "Extracting $file (with variable substitutions)\n";
+
+# In this section, perl variables will be expanded during extraction.
+# You can use $Config{...} to use Configure variables.
+
+print OUT <<"!GROK!THIS!";
+$Config{startperl}
+    eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}'
+       if \$running_under_some_shell;
+!GROK!THIS!
+
+use File::Spec;
+
+my $script = File::Spec->catfile(
+    File::Spec->catdir(
+        File::Spec->updir, qw(cpan podlators bin),
+    ),
+    'pod2man',
+);
+
+if (open(IN, $script)) {
+    print OUT <IN>;
+    close IN;
+} else {
+    die "$0: cannot find '$script'\n";
+}
+
+close OUT or die "Can't close $file: $!";
+chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
+exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';
+chdir $origdir;
diff --git a/utils/pod2text.PL b/utils/pod2text.PL
new file mode 100644 (file)
index 0000000..7dba4ac
--- /dev/null
@@ -0,0 +1,53 @@
+#!/usr/local/bin/perl
+
+use Config;
+use File::Basename qw(&basename &dirname);
+use Cwd;
+
+# List explicitly here the variables you want Configure to
+# generate.  Metaconfig only looks for shell variables, so you
+# have to mention them as if they were shell variables, not
+# %Config entries.  Thus you write
+#  $startperl
+# to ensure Configure will look for $Config{startperl}.
+
+# This forces PL files to create target in same directory as PL file.
+# This is so that make depend always knows where to find PL derivatives.
+my $origdir = cwd;
+chdir dirname($0);
+my $file = basename($0, '.PL');
+$file .= '.com' if $^O eq 'VMS';
+
+open OUT,">$file" or die "Can't create $file: $!";
+
+print "Extracting $file (with variable substitutions)\n";
+
+# In this section, perl variables will be expanded during extraction.
+# You can use $Config{...} to use Configure variables.
+
+print OUT <<"!GROK!THIS!";
+$Config{startperl}
+    eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}'
+       if \$running_under_some_shell;
+!GROK!THIS!
+
+use File::Spec;
+
+my $script = File::Spec->catfile(
+    File::Spec->catdir(
+        File::Spec->updir, qw(cpan podlators bin),
+    ),
+    'pod2text',
+);
+
+if (open(IN, $script)) {
+    print OUT <IN>;
+    close IN;
+} else {
+    die "$0: cannot find '$script'\n";
+}
+
+close OUT or die "Can't close $file: $!";
+chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
+exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';
+chdir $origdir;