r58127 - in /branches/upstream/libpod-readme-perl/current: Changes META.yml Makefile.PL README lib/Pod/Readme.pm
ansgar-guest at users.alioth.debian.org
ansgar-guest at users.alioth.debian.org
Thu May 20 08:55:49 UTC 2010
Author: ansgar-guest
Date: Thu May 20 08:55:32 2010
New Revision: 58127
URL: http://svn.debian.org/wsvn/pkg-perl/?sc=1&rev=58127
Log:
[svn-upgrade] Integrating new upstream version, libpod-readme-perl (0.10)
Modified:
branches/upstream/libpod-readme-perl/current/Changes
branches/upstream/libpod-readme-perl/current/META.yml
branches/upstream/libpod-readme-perl/current/Makefile.PL
branches/upstream/libpod-readme-perl/current/README
branches/upstream/libpod-readme-perl/current/lib/Pod/Readme.pm
Modified: branches/upstream/libpod-readme-perl/current/Changes
URL: http://svn.debian.org/wsvn/pkg-perl/branches/upstream/libpod-readme-perl/current/Changes?rev=58127&op=diff
==============================================================================
--- branches/upstream/libpod-readme-perl/current/Changes (original)
+++ branches/upstream/libpod-readme-perl/current/Changes Thu May 20 08:55:32 2010
@@ -1,4 +1,8 @@
Revision history for Perl extension Pod::Readme.
+
+0.10 2010-05-19
+ - David Precious <davidp at preshweb.co.uk> 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
Modified: branches/upstream/libpod-readme-perl/current/META.yml
URL: http://svn.debian.org/wsvn/pkg-perl/branches/upstream/libpod-readme-perl/current/META.yml?rev=58127&op=diff
==============================================================================
--- branches/upstream/libpod-readme-perl/current/META.yml (original)
+++ branches/upstream/libpod-readme-perl/current/META.yml Thu May 20 08:55:32 2010
@@ -1,12 +1,25 @@
---
-name: Pod-Readme
-version: 0.09
+abstract: 'Convert POD to README file'
author:
- 'Robert Rothenberg <rrwo at cpan.org>'
-abstract: Convert POD to README file
+build_requires:
+ Test::More: 0
+configure_requires:
+ Module::Build: 0.36
+generated_by: 'Module::Build version 0.3603'
license: perl
-resources:
- license: http://dev.perl.org/licenses/
+meta-spec:
+ url: http://module-build.sourceforge.net/META-spec-v1.4.html
+ version: 1.4
+name: Pod-Readme
+provides:
+ Pod::Readme:
+ file: lib/Pod/Readme.pm
+ version: 0.10
+recommends:
+ Test::Pod: 1.00
+ Test::Pod::Coverage: 0
+ Test::Portability::Files: 0
requires:
Carp: 0
File::Copy: 0
@@ -14,17 +27,6 @@
Pod::Text: 3.0
Regexp::Common: 0
perl: 5.005
-build_requires:
- Test::More: 0
-recommends:
- Test::Pod: 1.00
- Test::Pod::Coverage: 0
- Test::Portability::Files: 0
-provides:
- Pod::Readme:
- file: lib/Pod/Readme.pm
- version: 0.09
-generated_by: Module::Build version 0.2805
-meta-spec:
- url: http://module-build.sourceforge.net/META-spec-v1.2.html
- version: 1.2
+resources:
+ license: http://dev.perl.org/licenses/
+version: 0.10
Modified: branches/upstream/libpod-readme-perl/current/Makefile.PL
URL: http://svn.debian.org/wsvn/pkg-perl/branches/upstream/libpod-readme-perl/current/Makefile.PL?rev=58127&op=diff
==============================================================================
--- branches/upstream/libpod-readme-perl/current/Makefile.PL (original)
+++ branches/upstream/libpod-readme-perl/current/Makefile.PL Thu May 20 08:55:32 2010
@@ -1,16 +1,17 @@
-# Note: this file was auto-generated by Module::Build::Compat version 0.03
+# Note: this file was auto-generated by Module::Build::Compat version 0.3603
+require 5.005;
use ExtUtils::MakeMaker;
WriteMakefile
(
'NAME' => 'Pod::Readme',
'VERSION_FROM' => 'lib/Pod/Readme.pm',
'PREREQ_PM' => {
- 'Carp' => '0',
- 'File::Copy' => '0',
- 'IO::File' => '0',
+ 'Carp' => 0,
+ 'File::Copy' => 0,
+ 'IO::File' => 0,
'Pod::Text' => '3.0',
- 'Regexp::Common' => '0',
- 'Test::More' => '0'
+ 'Regexp::Common' => 0,
+ 'Test::More' => 0
},
'INSTALLDIRS' => 'site',
'EXE_FILES' => [
Modified: branches/upstream/libpod-readme-perl/current/README
URL: http://svn.debian.org/wsvn/pkg-perl/branches/upstream/libpod-readme-perl/current/README?rev=58127&op=diff
==============================================================================
--- branches/upstream/libpod-readme-perl/current/README (original)
+++ branches/upstream/libpod-readme-perl/current/README Thu May 20 08:55:32 2010
@@ -5,45 +5,45 @@
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
-
+ 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
-
+ 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
-
+ 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');
-
+ 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
-
+ pod2text Module.pm > README
+
A problem with doing that is that the default pod2text converter will
add text to links, so that "L<Module>" is translated to "the Module
manpage".
@@ -62,31 +62,3 @@
See the module documentation for more details.
-REVSION HISTORY
- Changes since the last release:
-
- 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)
-
- A detailed history is available in the Changes file.
-
-SEE ALSO
- See perlpod, perlpodspec and podlators.
-
-AUTHOR
- Robert Rothenberg <rrwo at cpan.org>
-
- Suggestions and Bug Reporting
-
- Feedback is always welcome. Please use the CPAN Request Tracker at
- http://rt.cpan.org to submit bug reports.
-
-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 Pod::PlainText 2.02.
-
Modified: branches/upstream/libpod-readme-perl/current/lib/Pod/Readme.pm
URL: http://svn.debian.org/wsvn/pkg-perl/branches/upstream/libpod-readme-perl/current/lib/Pod/Readme.pm?rev=58127&op=diff
==============================================================================
--- branches/upstream/libpod-readme-perl/current/lib/Pod/Readme.pm (original)
+++ branches/upstream/libpod-readme-perl/current/lib/Pod/Readme.pm Thu May 20 08:55:32 2010
@@ -1,498 +1,515 @@
-=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<nmake> 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 );
-
- at ISA = qw( Pod::PlainText );
-
-$VERSION = '0.09';
-
-=begin internal
-
-=item initialize
-
-Override adds the C<readme_type> and <debug> options, and initializes
-the "README_SKIP" flag.
-
-=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
-
-=item output
-
-Override does not output anything if the "README_SKIP" flag is enabled.
-
-=end internal
-
-=cut
-
-sub output {
- my $self = shift;
- return if $$self{README_SKIP};
- $self->SUPER::output(@_);
-}
-
-
-=begin internal
-
-=item _parse_args
-
-Parses destination and name="value" arguments passed for L</cmd_for>.
-
-=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
-
-=item cmd_begin
-
-Overrides support for "begin" command.
-
-=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
-
-=item cmd_for
-
-Overrides support for "for" command.
-
-=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
-
-=item _include_file
-
-Includes a file.
-
-=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
-
-=item seq_l
-
-Overrides support for "L" markup.
-
-=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<manpage/> forces a manpage interpretation, as does
- # something looking like L<manpage(section)>. 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<Pod::PlainText> which provides additional
-POD markup for generating F<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 L<pod2text> converter will
-add text to links, so that "LZ<><Module>" is translated to
-"the Module manpage".
-
-Another problem is that the F<README> includes the entirety of
-the module documentation! Most people browsing the F<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 F<README> file. It also allows you to
-include portions of another file (such as a separate F<ChangeLog>).
-
-=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<text> 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<begin :readme>) 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<continue> 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<filename>, starting with the line
-that contains the start C<Regexp> and ending at the line that begins
-with the stop C<Regexp>. (The start and stop Regexps are optional: one
-or both may be omitted.)
-
-Type may be C<text> or C<pod>. If omitted, C<pod> 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<TODO>,
-or F<COPYING>) by using a modified constructor:
-
- $parser = Pod::Readme->new( readme_type => "copying" );
-
-In the above L</Markup> 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<Pod::Readme> 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<Readme.pm> file in this distribution.
-
-=for readme continue
-
-=begin readme
-
-=head1 REVSION HISTORY
-
-Changes since the last release:
-
-=for readme include file="Changes" start="^0.09" stop="^0.081" type="text"
-
-A detailed history is available in the F<Changes> file.
-
-=end readme
-
-=head1 SEE ALSO
-
-See L<perlpod>, L<perlpodspec> and L<podlators>.
-
-=head1 AUTHOR
-
-Robert Rothenberg <rrwo at cpan.org>
-
-=head2 Suggestions and Bug Reporting
-
-Feedback is always welcome. Please use the CPAN Request Tracker at
-L<http://rt.cpan.org> to submit bug reports.
-
-=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<Pod::PlainText> 2.02.
-
-=cut
+=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<nmake> 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 );
+
+ at ISA = qw( Pod::PlainText );
+
+$VERSION = '0.10';
+
+=begin internal
+
+=over 12
+
+=item initialize
+
+Override adds the C<readme_type> and <debug> 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</cmd_for>.
+
+=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 _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<manpage/> forces a manpage interpretation, as does
+ # something looking like L<manpage(section)>. 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<Pod::PlainText> which provides additional
+POD markup for generating F<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 L<pod2text> converter will
+add text to links, so that "LZ<><Module>" is translated to
+"the Module manpage".
+
+Another problem is that the F<README> includes the entirety of
+the module documentation! Most people browsing the F<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 F<README> file. It also allows you to
+include portions of another file (such as a separate F<ChangeLog>).
+
+=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<text> 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<begin :readme>) 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<continue> 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<filename>, starting with the line
+that contains the start C<Regexp> and ending at the line that begins
+with the stop C<Regexp>. (The start and stop Regexps are optional: one
+or both may be omitted.)
+
+Type may be C<text> or C<pod>. If omitted, C<pod> 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<TODO>,
+or F<COPYING>) by using a modified constructor:
+
+ $parser = Pod::Readme->new( readme_type => "copying" );
+
+In the above L</Markup> 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<Pod::Readme> 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<Readme.pm> file in this distribution.
+
+=head1 SEE ALSO
+
+See L<perlpod>, L<perlpodspec> and L<podlators>.
+
+=head1 AUTHOR
+
+Originally by Robert Rothenberg <rrwo at cpan.org>
+
+Now maintained by David Precious <davidp at preshweb.co.uk>
+
+
+=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<Pod::PlainText> 2.02.
+
+=cut
More information about the Pkg-perl-cvs-commits
mailing list