Pod-Readme-0.11/0000755000175000017500000000000011500266072012647 5ustar davidpdavidpPod-Readme-0.11/README0000644000175000017500000000353011500265050013523 0ustar davidpdavidpNAME Pod::Readme - Convert POD to README file REQUIREMENTS This module should run on Perl 5.005 or newer. The following non-core modules (depending on your Perl version) are required: Pod::PlainText Test::More INSTALLATION Installation can be done using the traditional Makefile.PL or the newer Build.PL methods. Using Makefile.PL: perl Makefile.PL make test make install (On Windows platforms you should use `nmake' instead.) Using Build.PL (if you have Module::Build installed): perl Build.PL perl Build test perl Build install SYNOPSIS use Pod::Readme; my $parser = Pod::Readme->new(); # Read POD from STDIN and write to STDOUT $parser->parse_from_filehandle; # Read POD from Module.pm and write to README $parser->parse_from_file('Module.pm', 'README'); DESCRIPTION This module is a subclass of Pod::PlainText which provides additional POD markup for generating README files. Why should one bother with this? One can simply use pod2text Module.pm > README A problem with doing that is that the default pod2text converter will add text to links, so that "L" is translated to "the Module manpage". Another problem is that the README includes the entirety of the module documentation! Most people browsing the README file do not need all of this information. Likewise, including installation and requirement information in the module documentation is not necessary either, since the module is already installed. This module allows authors to mark portions of the POD to be included only in, or to be excluded from the README file. It also allows you to include portions of another file (such as a separate ChangeLog). See the module documentation for more details. Pod-Readme-0.11/t/0000755000175000017500000000000011500266071013111 5ustar davidpdavidpPod-Readme-0.11/t/90-pod.t0000644000175000017500000000043211361427333014312 0ustar davidpdavidp#!/usr/bin/perl use strict; use warnings; use Test::More; plan skip_all => "Enable DEVEL_TESTS environent variable" unless ($ENV{DEVEL_TESTS}); eval "use Test::Pod 1.00"; plan skip_all => "Test::Pod 1.00 required for testing POD" if $@; all_pod_files_ok(); Pod-Readme-0.11/t/90-fileport.t0000644000175000017500000000043111361427333015353 0ustar davidpdavidp#!/usr/bin/perl use Test::More; plan skip_all => "Enable DEVEL_TESTS environent variable" unless ($ENV{DEVEL_TESTS}); eval "use Test::Portability::Files"; plan skip_all => "Test::Portability::Files required for testing filenames portability" if $@; run_tests(); Pod-Readme-0.11/t/90-podcover.t0000644000175000017500000000042311361427333015351 0ustar davidpdavidp#!/usr/bin/perl use strict; use Test::More; plan skip_all => "Enable DEVEL_TESTS environent variable" unless ($ENV{DEVEL_TESTS}); eval "use Test::Pod::Coverage"; plan skip_all => "Test::Pod::Coverage required" if $@; plan tests => 1; pod_coverage_ok("Pod::Readme"); Pod-Readme-0.11/t/10-basic.t0000644000175000017500000000662511361427333014613 0ustar davidpdavidp#!/usr/bin/perl use strict; use Test::More; my %L_ARGS = ( 'http://www.example.com/' => undef, 'https://www.example.com/' => undef, 'http://www.example.com/some/page?query=foo&bar=baz' => undef, 'ftp://ftp.example.com/some/file' => undef, # 'news://news.example.com/group.name' => undef, 'svn://svn.cpan.org/foo/bar' => undef, 'Some::Module' => undef, 'Some::Module/section' => 'Some::Module', 'Module' => undef, 'Module/section' => 'Module', '/Section' => 'Section', 'Text|Module' => 'Text', 'Text|Module/section' => 'Text', 'Text|http://www.cpan.org/' => 'Text', 'Text|ftp://www.cpan.org/' => 'Text', 'Text|news://www.cpan.org/' => 'Text', ); my @TYPES = qw( readme copying install hacking todo license ); my @INVALID = qw( test tests testing html xhtml xml docbook rtf man nroff dsr rno latex tex code ); # These are methods supported by Pod::Text but not Pod::PlainText my @METHODS = qw( cmd_head3 cmd_head4 ); plan tests => 2 + (19 * scalar(@TYPES)) + scalar(keys %L_ARGS) + (2 * scalar(@INVALID)) + (1 * scalar(@METHODS)); use_ok("Pod::Readme", 0.06); foreach my $type (@INVALID) { my $p; $@ = undef; eval { $p = Pod::Readme->new( readme_type => $type ); }; ok($@, "new $type failed"); ok(!defined $p, "undefined invalid type"); } # TODO - test other document types than "readme" foreach my $type (@TYPES) { my $p = Pod::Readme->new( readme_type => $type ); ok(defined $p, "new $type"); ok($p->{readme_type} eq $type, "readme_type"); ok(!$p->{README_SKIP}, "README_SKIP"); # TODO - test output method $p->cmd_for("$type stop"); ok($p->{README_SKIP}, "$type stop"); $p->cmd_for("$type continue"); ok(!$p->{README_SKIP}, "$type continue"); $p->cmd_for("$type stop"); ok($p->{README_SKIP}, "$type stop"); $p->cmd_for("$type"); ok(!$p->{README_SKIP}, "$type"); $p->cmd_for("$type stop"); ok($p->{README_SKIP}, "$type stop"); $p->cmd_begin("$type"); ok(!$p->{README_SKIP}, "begin $type"); $p->cmd_end("$type"); $p->cmd_for("foobar stop"); ok(!$p->{README_SKIP}, "foobar stop"); $p->cmd_for("foobar continue"); ok(!$p->{README_SKIP}, "foobar continue"); $p->cmd_for("foobar stop"); ok(!$p->{README_SKIP}, "foobar stop"); $p->cmd_for("foobar"); ok(!$p->{README_SKIP}, "foobar"); $p->cmd_for("$type,foobar stop"); ok($p->{README_SKIP}, "$type,foobar stop"); $p->cmd_for("$type,foobar continue"); ok(!$p->{README_SKIP}, "$type,foobar continue"); $p->cmd_for("$type,foobar stop"); ok($p->{README_SKIP}, "$type,foobar stop"); $p->cmd_for("$type,foobar"); ok(!$p->{README_SKIP}, "$type,foobar"); $p->cmd_for("$type,foobar stop"); ok($p->{README_SKIP}, "$type,foobar stop"); $p->cmd_begin("$type,foobar"); ok(!$p->{README_SKIP}, "begin $type,foobar"); $p->cmd_end("$type,foobar"); } # TODO - test for readme include { my $p = Pod::Readme->new(); ok(defined $p, "new"); foreach my $arg (sort keys %L_ARGS) { my $exp = $L_ARGS{$arg} || $arg; my $r = $p->seq_l($arg); ok($r eq $exp, "L<$arg>"); # print STDERR "\x23 $r\n"; }; } { local $TODO = "unimplemented methods"; my $p = Pod::Readme->new(); foreach my $method (@METHODS) { ok($p->can($method), "method $method supported"); } } Pod-Readme-0.11/bin/0000755000175000017500000000000011500266071013416 5ustar davidpdavidpPod-Readme-0.11/bin/pod2readme0000644000175000017500000000275211361427333015376 0ustar davidpdavidp#!/usr/bin/perl use strict; use File::Copy qw( copy ); use Pod::Readme; our $VERSION = '0.05'; # TODO # - use Getopts::Long with better options # - allow for stream conversion # - if no input given, parse META.yml and guess my $input = shift||""; unless (-r $input) { print STDERR << "USAGE"; Cannot find input file "$input" Usage: pod2readme inputfile [outputfile] [type] USAGE exit(1); } my $output = shift || "README"; my $type = shift || lc($output); my $parser = Pod::Readme->new( readme_type => $type ); if (-e $output) { copy( $output, $output . ".bak" ); } $parser->parse_from_file( $input, $output ); __END__ =pod =head1 NAME pod2readme - script to convert POD to README file =head1 SYNOPSIS pod2readme lib/Some/Module.pm =head1 DESCRIPTIONS Converts POD in the specified file to a F text file. If a second argument is given, it will use that as the output file and assume that is the type of file to export: pod2readme Module.pm COPYING If need be, this can be overridden in cases where the output file is not the same as the type, using a third argument: pod2readme Module.pm Module-Install.HOWTO install =head1 SEE ALSO L =head1 AUTHOR Robert Rothenberg =head1 LICENSE Copyright (c) 2005 Robert Rothenberg. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =cut Pod-Readme-0.11/META.yml0000644000175000017500000000123311500266072014117 0ustar davidpdavidp--- #YAML:1.0 name: Pod-Readme version: 0.11 abstract: Convert POD to README file author: - David Precious license: perl distribution_type: module configure_requires: ExtUtils::MakeMaker: 0 build_requires: ExtUtils::MakeMaker: 0 requires: Carp: 0 File::Copy: 0 IO::File: 0 Pod::Text: 3.0 Regexp::Common: 0 Test::More: 0 no_index: directory: - t - inc generated_by: ExtUtils::MakeMaker version 6.56 meta-spec: url: http://module-build.sourceforge.net/META-spec-v1.4.html version: 1.4 Pod-Readme-0.11/lib/0000755000175000017500000000000011500266071013414 5ustar davidpdavidpPod-Readme-0.11/lib/Pod/0000755000175000017500000000000011500266071014136 5ustar davidpdavidpPod-Readme-0.11/lib/Pod/Readme.pm0000644000175000017500000002516511500264676015713 0ustar davidpdavidp=head1 NAME Pod::Readme - Convert POD to README file =begin readme =head1 REQUIREMENTS This module should run on Perl 5.005 or newer. The following non-core modules (depending on your Perl version) are required: Pod::PlainText Test::More =head1 INSTALLATION Installation can be done using the traditional Makefile.PL or the newer Build.PL methods. Using Makefile.PL: perl Makefile.PL make test make install (On Windows platforms you should use C instead.) Using Build.PL (if you have Module::Build installed): perl Build.PL perl Build test perl Build install =end readme =head1 SYNOPSIS use Pod::Readme; my $parser = Pod::Readme->new(); # Read POD from STDIN and write to STDOUT $parser->parse_from_filehandle; # Read POD from Module.pm and write to README $parser->parse_from_file('Module.pm', 'README'); =cut package Pod::Readme; use 5.005; use strict; use Carp; use IO::File; use Pod::PlainText; use Regexp::Common qw( URI ); use vars qw( @ISA $VERSION ); @ISA = qw( Pod::PlainText ); $VERSION = '0.11'; =begin internal =over 12 =item initialize Override adds the C and options, and initializes the "README_SKIP" flag. =back =end internal =cut { my %INVALID_TYPES = map { $_ => 1, } (qw( test testing tests html xhtml xml docbook rtf man nroff dsr rno latex tex code )); sub initialize { my $self = shift; $$self{README_SKIP} ||= 0; $$self{readme_type} ||= "readme"; $$self{debug} ||= 0; $self->SUPER::initialize; croak "$$self{readme_type} is an invalid readme_type", if ($INVALID_TYPES{ $$self{readme_type} }); } } =begin internal =over 12 =item output Override does not output anything if the "README_SKIP" flag is enabled. =back =end internal =cut sub output { my $self = shift; return if $$self{README_SKIP}; $self->SUPER::output(@_); } =begin internal =over =item _parse_args Parses destination and name="value" arguments passed for L. =back =end internal =cut sub _parse_args { my $self = shift; my $string = shift; my @values = ( ); my $arg = ""; my $in_quote = 0; my $last; foreach (split //, $string) { if (/\s/) { if ($in_quote) { $arg .= $_; } else { if ($arg ne "") { push @values, $arg; $arg = ""; } } } else { $arg .= $_; if (/\"/) { if ($in_quote) { $in_quote = 0 unless ($last eq "\\"); } else { # croak "expected \"name=\" before quotes" unless ($last eq "="); $in_quote = 1; } } } $last = $_; } push @values, $arg if ($arg ne ""); return @values; } =begin internal =over =item cmd_begin Overrides support for "begin" command. =back =end internal =cut sub cmd_begin { my $self = shift; my $sec = $$self{readme_type} || "readme"; my @fmt = $self->_parse_args($_[0]); my %secs = map { $_ => 1, } split /,/, $fmt[0]; if ($secs{$sec}) { $$self{README_SKIP} = 0; if (($fmt[1]||"pod") eq "pod") { } elsif ($fmt[1] eq "text") { $$self{VERBATIM} = 1; } else { # TODO - return error $$self{EXCLUDE} = 1; } } else { carp "Ignoring document type(s) \"$fmt[0]\" in POD line $_[1]" if ($$self{debug}); $self->SUPER::cmd_begin(@_); } } =begin internal =over =item cmd_for Overrides support for "for" command. =back =end internal =cut sub cmd_for { my $self = shift; my $sec = $$self{readme_type} || "readme"; my @fmt = $self->_parse_args($_[0]); my %secs = map { $_ => 1, } split /,/, $fmt[0]; if ($secs{$sec}) { my $cmd = $fmt[1] || "continue"; if ($cmd eq "stop") { $$self{README_SKIP} = 1; } elsif ($cmd eq "continue") { $$self{README_SKIP} = 0; } elsif ($cmd eq "include") { my %arg = map { s/\"//g; my ($k,$v) = split /\=/; $k => $v; } @fmt[2..$#fmt]; $arg{type} ||= "pod"; my $text = $self->_include_file( map { $arg{$_} } (qw( type file start stop )) ); if ($arg{type} eq "text") { $self->verbatim($text, $_[1], $_[2]); } else { $self->textblock($text, $_[1], $_[2]); } } else { croak "Don\'t know how to \"$cmd\" in POD line $_[1]"; } } else { carp "Ignoring document type(s) \"$fmt[0]\" in POD line $_[1]" if ($$self{debug}); $self->SUPER::cmd_for(@_); } } =begin internal =over =item cmd_encoding Handle =encoding directive. TODO: actually change the encoding of the output file. =back =end internal =cut sub cmd_encoding { my $self = shift; my $encoding = (split /\s+/, shift)[0]; if ($self->{_encoding}) { die "=encoding option must occur only once!"; } $self->{_encoding} = $encoding; # TODO: Need to actually do something with this option # At least recognising it and not dying is a step in the right direction. } =begin internal =over =item _include_file Includes a file. =back =end internal =cut sub _include_file { my $self = shift; my $type = shift || "pod"; my $file = shift; my $mark = shift || ""; my $stop = shift || ""; my $fh = IO::File->new("<$file") || croak "Unable to open file \"$file\""; my $buffer = ""; while (my $line = <$fh>) { next if (($mark ne "") && ($line !~ /$mark/)); $mark = "" if ($mark ne ""); last if (($stop ne "") && ($line =~ /$stop/)); $buffer .= $line; } close $fh; if ($type ne "pod") { my $indent = " " x $$self{MARGIN}; $buffer =~ s/([\r\n]+)(\t)?/$1 . $indent x (1+length($2||""))/ge; $buffer =~ s/($indent)+$//; } return $buffer; } =begin internal =over =item seq_l Overrides support for "L" markup. =back =end internal =cut # This code is based on code from Pod::PlainText 2.02 sub seq_l { my $self = shift; local $_ = shift; # Smash whitespace in case we were split across multiple lines. s/\s+/ /g; # If we were given any explicit text, just output it. if (/^([^|]+)\|/) { return $1 } # Okay, leading and trailing whitespace isn't important; get rid of it. s/^\s+//; s/\s+$//; # Default to using the whole content of the link entry as a section # name. Note that L forces a manpage interpretation, as does # something looking like L. The latter is an # enhancement over the original Pod::Text. my ($manpage, $section) = ('', $_); if (/$RE{URI}/ || /^(?:https?|ftps?|svn):/) { # a URL return $_; } elsif (/^"\s*(.*?)\s*"$/) { $section = '"' . $1 . '"'; } elsif (m/^[-:.\w]+(?:\(\S+\))?$/) { ($manpage, $section) = ($_, ''); } elsif (m%/%) { ($manpage, $section) = split (/\s*\/\s*/, $_, 2); } if (length $manpage) { return $manpage; } else { return $section; } } =head1 DESCRIPTION This module is a subclass of L which provides additional POD markup for generating F files. Why should one bother with this? One can simply use pod2text Module.pm > README A problem with doing that is that the default L converter will add text to links, so that "LZ<>" is translated to "the Module manpage". Another problem is that the F includes the entirety of the module documentation! Most people browsing the F file do not need all of this information. Likewise, including installation and requirement information in the module documentation is not necessary either, since the module is already installed. This module allows authors to mark portions of the POD to be included only in, or to be excluded from the F file. It also allows you to include portions of another file (such as a separate F). =begin readme See the module documentation for more details. =end readme =for readme stop =head2 Markup Special POD markup options are described below: =over =item begin/end =begin readme =head1 README ONLY This section will only show up in the README file. =end readme Delineates a POD section that is only available in README file. If you prefer to include plain text instead, add the C modifier: =begin readme text README ONLY (PLAINTEXT) This section will only show up in the README file. =end readme Note that placing a colon before the section to indicate that it is POD (e.g. C) is not supported in this version. =item stop/continue =for readme stop All POD that follows will not be included in the README, until a C command occurs: =for readme continue =item include =for readme include file=filename type=type start=Regexp stop=Regexp =for readme include file=Changes start=^0.09 stop=^0.081 type=text Includes a plaintext file named F, starting with the line that contains the start C and ending at the line that begins with the stop C. (The start and stop Regexps are optional: one or both may be omitted.) Type may be C or C. If omitted, C will be assumed. Quotes may be used when the filename or marks contains spaces: =for readme include file="another file.pod" =back One can also using maintain multiple file types (such as including F, or F) by using a modified constructor: $parser = Pod::Readme->new( readme_type => "copying" ); In the above L commands replace "readme" with the tag specified instead (such as "copying"): =begin copying As of version 0.03 you can specify multiple sections by separating them with a comma: =begin copying,readme There is also no standard list of type names. Some names might be recognized by other POD processors (such as "testing" or "html"). L will reject the following "known" type names when they are specified in the constructor: testing html xhtml xml docbook rtf man nroff dsr rno latex tex code You can also use a "debug" mode to diagnose any problems, such as mistyped format names: $parser = Pod::Readme->new( debug => 1 ); Warnings will be issued for any ignored formatting commands. =head2 Example For an example, see the F file in this distribution. =head1 SEE ALSO See L, L and L. =head1 AUTHOR Originally by Robert Rothenberg Now maintained by David Precious =head2 Suggestions, Bug Reporting and Contributing This module is developed on GitHub at: http://github.com/bigpresh/Pod-Readme =head1 LICENSE Copyright (c) 2005,2006 Robert Rothenberg. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Some portions are based on L 2.02. =cut Pod-Readme-0.11/MANIFEST0000644000175000017500000000032611500266072014001 0ustar davidpdavidpChanges Makefile.PL MANIFEST README bin/pod2readme t/10-basic.t t/90-fileport.t t/90-pod.t t/90-podcover.t lib/Pod/Readme.pm META.yml Module meta-data (added by MakeMaker) Pod-Readme-0.11/Makefile.PL0000644000175000017500000000152311500265502014617 0ustar davidpdavidpuse strict; use warnings; use ExtUtils::MakeMaker; WriteMakefile( NAME => 'Pod::Readme', AUTHOR => 'David Precious ', VERSION_FROM => 'lib/Pod/Readme.pm', ABSTRACT_FROM => 'lib/Pod/Readme.pm', ($ExtUtils::MakeMaker::VERSION >= 6.3002 ? (LICENSE=> 'perl') : ()), PREREQ_PM => { 'Carp' => '0', 'File::Copy' => '0', 'IO::File' => '0', 'Pod::Text' => '3.0', 'Regexp::Common' => '0', 'Test::More' => '0' }, INSTALLDIRS => 'site', EXE_FILES => [ 'bin/pod2readme' ], PL_FILES => {}, dist => { COMPRESS => 'gzip -9f', SUFFIX => 'gz' }, clean => { FILES => 'Pod-Readme-*' }, ); Pod-Readme-0.11/Changes0000644000175000017500000000364211500265027014146 0ustar davidpdavidpRevision history for Perl extension Pod::Readme. 0.11 2010-12-09 - Recognise the =encoding directive, rather than dying when it's encountered. TODO: actually take heed of it. Thanks to Ivan Bessarabov for bringing this to my attention! 0.10 2010-05-19 - David Precious taking over maintainership - Apply POD fix patch from RT #38328, thanks to David A. Desrosiers 0.09 Sat Nov 25 2006 - uses Regexp::Common for URI parsing for L<> tag - added separate check for https, ftps, and svn URIs (rt.cpan.org bugs 23585 and 23613) 0.081 Sun May 7 2006 - released package without signature, due to Module::Signature issues 0.08 Mon May 1 2006 - head3/4 headings not recognized - went back to using Pod::PlainText 0.07 Sat Feb 11 2006 - added min version to use Pod::Text statement in source - removed multiple plans from the podcover test 0.06 Thu Feb 9 2006 - eliminated a warning about uninitialized values - recognizes =head3 and =head4 headings (from Pod::Text) - uses Pod::Text instead of Pod::PlainText - added internal documentation - added various QA tests - added "test" and "tests" as a rejected format 0.05 Tue Jun 7 2005 - pod2readme will backup an existing README file - minor updates to the documentation 0.04 Wed May 18 2005 - known other formats such as "html" are rejected - added missing prereq IO::File in Build.PL - added debug option - typos and tweaks for documentation 0.03 Sun May 8 2005 - added documentation to pod2readme script - include file start/stop marks are now Regexps - added more tests - multiple readme types can be specified in a command 0.02 Fri May 6 2005 - added tests (much needed!) - fixed issue with links being changed to refer to manpages 0.01 Sat Apr 30 19:22:33 2005 - original version; created by h2xs 1.23 with options -X -v 0.01 -b 5.5.0 -n Pod::Readme -P