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