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
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
},
'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
/pod2man*
/pod2text*
+/.travis.yml
+/LICENSE
+/MANIFEST
+/MANIFEST.SKIP
+/META.yml
+/META.json
+/NOTES
+/README
+/THANKS
+/TODO
--- /dev/null
+ 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.
--- /dev/null
+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'
+);
#!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 ();
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};
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>] ...]
=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,
=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>
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
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>
=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;
#!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.
# 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%.*/%%;
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,
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.
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.
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>
=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;
# 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);
@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
$$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}"))
}
} 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;
}
$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
}
# 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
.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.
.\" 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
=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
=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
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
=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
=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
=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
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
=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
=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
=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
=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.
# 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
=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
=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.
-# 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
# 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);
# We have to export pod2text for backward compatibility.
@EXPORT = qw(pod2text);
-$VERSION = '3.18';
+$VERSION = '4.03';
##############################################################################
# Initialization
$$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}");
}
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);
$$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
my $flag = (PerlIO::get_layers ($$self{output_fh}, @options))[-1];
if ($flag & PerlIO::F_UTF8 ()) {
$$self{ENCODE} = 0;
+ $$self{ENCODING} = 'UTF-8';
}
};
}
=head1 NAME
-Pod::Text - Convert POD data to formatted ASCII text
+Pod::Text - Convert POD data to formatted text
=head1 SYNOPSIS
=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
=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.
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
=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
=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
=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.
# 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
=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.
# 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
=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.
# 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
# $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).
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
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
=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.
+++ /dev/null
-#!/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");
- }
- }
-}
--- /dev/null
+# Configuration for Perl tests. -*- perl -*-
+
+# Default minimum version requirement.
+$MINIMUM_VERSION = '5.006';
+
+# File must end with this line.
+1;
--- /dev/null
+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.
--- /dev/null
+[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+.
--- /dev/null
+[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.
--- /dev/null
+[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.
--- /dev/null
+[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++.
--- /dev/null
+# 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
+++ /dev/null
-#!/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);
--- /dev/null
+#!/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);
+}
--- /dev/null
+#!/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);
+}
--- /dev/null
+#!/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);
+}
+++ /dev/null
-#!/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++.
-
-###
--- /dev/null
+#!/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");
+ }
+}
--- /dev/null
+#!/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);
--- /dev/null
+#!/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);
--- /dev/null
+# 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
--- /dev/null
+# 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
--- /dev/null
+# 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
+++ /dev/null
-#!/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"
-###
+++ /dev/null
-#!/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.
-###
+++ /dev/null
-#!/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.
-###
+++ /dev/null
-#!/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.
-###
#
# 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.
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";
--- /dev/null
+#!/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'
+);
--- /dev/null
+#!/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');
#
# 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.
--- /dev/null
+#!/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 "" "" ""
+###
--- /dev/null
+#!/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.
+###
+###
--- /dev/null
+#!/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 });
+}
#
# 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.
+++ /dev/null
-#!/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;
+++ /dev/null
-#!/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);
- }
- }
-}
+++ /dev/null
-#!/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 ();
--- /dev/null
+#!/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);
--- /dev/null
+#!/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
--- /dev/null
+#!/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;
+}
# 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.
# 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.
#
# 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.
#
# 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.
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') }
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
+
+###
#
# 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.
use strict;
-use Test::More tests => 34;
+use Test::More tests => 37;
BEGIN { use_ok ('Pod::Text') }
# Redirect stderr to a file.
NEXT
###
###
+
+###
+quotes <<<>>>
+###
+=head1 FOO C<BAR> BAZ
+
+Foo C<bar> baz.
+###
+FOO <<<BAR>>> BAZ
+ Foo <<<bar>>> baz.
+
+###
+###
# 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.
#
# 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.
}
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";
}
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 $/;
#
# 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.
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');
#
# 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.
}
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";
$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 $/;
=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
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
# 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)
--- /dev/null
+#!/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;
--- /dev/null
+#!/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;
https://perl5.git.perl.org / perl5.git / commitdiff