r58129 - in /trunk/libpod-readme-perl: Changes META.yml Makefile.PL README debian/changelog debian/control debian/copyright debian/rules debian/source/ debian/source/format lib/Pod/Readme.pm
ansgar-guest at users.alioth.debian.org
ansgar-guest at users.alioth.debian.org
Thu May 20 09:07:33 UTC 2010
Author: ansgar-guest
Date: Thu May 20 09:07:16 2010
New Revision: 58129
URL: http://svn.debian.org/wsvn/pkg-perl/?sc=1&rev=58129
Log:
* New upstream release.
* Add myself to Uploaders.
* Use tiny debian/rules.
* Use Build.PL instead of Makefile.PL, add build-dep on
perl (>= 5.10) | libmodule-build-perl.
* No longer run author tests, remove build-dep on libtest-pod-perl and
libtest-pod-coverage-perl.
* Bump Standards-Version to 3.8.4.
* debian/copyright: Formatting changes for current DEP-5 proposal.
Added:
trunk/libpod-readme-perl/debian/source/
trunk/libpod-readme-perl/debian/source/format
Modified:
trunk/libpod-readme-perl/Changes
trunk/libpod-readme-perl/META.yml
trunk/libpod-readme-perl/Makefile.PL
trunk/libpod-readme-perl/README
trunk/libpod-readme-perl/debian/changelog
trunk/libpod-readme-perl/debian/control
trunk/libpod-readme-perl/debian/copyright
trunk/libpod-readme-perl/debian/rules
trunk/libpod-readme-perl/lib/Pod/Readme.pm
Modified: trunk/libpod-readme-perl/Changes
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libpod-readme-perl/Changes?rev=58129&op=diff
==============================================================================
--- trunk/libpod-readme-perl/Changes (original)
+++ trunk/libpod-readme-perl/Changes Thu May 20 09:07:16 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: trunk/libpod-readme-perl/META.yml
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libpod-readme-perl/META.yml?rev=58129&op=diff
==============================================================================
--- trunk/libpod-readme-perl/META.yml (original)
+++ trunk/libpod-readme-perl/META.yml Thu May 20 09:07:16 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: trunk/libpod-readme-perl/Makefile.PL
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libpod-readme-perl/Makefile.PL?rev=58129&op=diff
==============================================================================
--- trunk/libpod-readme-perl/Makefile.PL (original)
+++ trunk/libpod-readme-perl/Makefile.PL Thu May 20 09:07:16 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: trunk/libpod-readme-perl/README
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libpod-readme-perl/README?rev=58129&op=diff
==============================================================================
--- trunk/libpod-readme-perl/README (original)
+++ trunk/libpod-readme-perl/README Thu May 20 09:07:16 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: trunk/libpod-readme-perl/debian/changelog
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libpod-readme-perl/debian/changelog?rev=58129&op=diff
==============================================================================
--- trunk/libpod-readme-perl/debian/changelog (original)
+++ trunk/libpod-readme-perl/debian/changelog Thu May 20 09:07:16 2010
@@ -1,4 +1,4 @@
-libpod-readme-perl (0.09-2) UNRELEASED; urgency=low
+libpod-readme-perl (0.10-1) unstable; urgency=low
[ Nathan Handler ]
* debian/watch: Update to ignore development releases.
@@ -12,7 +12,18 @@
* Improve short description, thanks to Jari Aalto for the bug report
(closes: #550287).
- -- Nathan Handler <nhandler at ubuntu.com> Sat, 06 Jun 2009 01:36:58 +0000
+ [ Ansgar Burchardt ]
+ * New upstream release.
+ * Add myself to Uploaders.
+ * Use tiny debian/rules.
+ * Use Build.PL instead of Makefile.PL, add build-dep on
+ perl (>= 5.10) | libmodule-build-perl.
+ * No longer run author tests, remove build-dep on libtest-pod-perl and
+ libtest-pod-coverage-perl.
+ * Bump Standards-Version to 3.8.4.
+ * debian/copyright: Formatting changes for current DEP-5 proposal.
+
+ -- Ansgar Burchardt <ansgar at 43-1.org> Thu, 20 May 2010 18:06:36 +0900
libpod-readme-perl (0.09-1) unstable; urgency=low
Modified: trunk/libpod-readme-perl/debian/control
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libpod-readme-perl/debian/control?rev=58129&op=diff
==============================================================================
--- trunk/libpod-readme-perl/debian/control (original)
+++ trunk/libpod-readme-perl/debian/control Thu May 20 09:07:16 2010
@@ -1,12 +1,12 @@
Source: libpod-readme-perl
Section: perl
Priority: optional
-Build-Depends: debhelper (>= 7)
-Build-Depends-Indep: perl, libtest-pod-perl, libtest-pod-coverage-perl,
- libregexp-common-perl
+Build-Depends: debhelper (>= 7.3.7), perl (>= 5.10) | libmodule-build-perl
+Build-Depends-Indep: perl, libregexp-common-perl
Maintainer: Debian Perl Group <pkg-perl-maintainers at lists.alioth.debian.org>
-Uploaders: Antonio Radici <antonio at dyne.org>
-Standards-Version: 3.8.0
+Uploaders: Antonio Radici <antonio at dyne.org>,
+ Ansgar Burchardt <ansgar at 43-1.org>
+Standards-Version: 3.8.4
Homepage: http://search.cpan.org/dist/Pod-Readme/
Vcs-Svn: svn://svn.debian.org/pkg-perl/trunk/libpod-readme-perl/
Vcs-Browser: http://svn.debian.org/viewsvn/pkg-perl/trunk/libpod-readme-perl/
Modified: trunk/libpod-readme-perl/debian/copyright
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libpod-readme-perl/debian/copyright?rev=58129&op=diff
==============================================================================
--- trunk/libpod-readme-perl/debian/copyright (original)
+++ trunk/libpod-readme-perl/debian/copyright Thu May 20 09:07:16 2010
@@ -1,17 +1,14 @@
-Format-Specification:
- http://wiki.debian.org/Proposals/CopyrightFormat?action=recall&rev=196
-Upstream-Maintainer: Robert Rothenberg <rrwo at cpan.org>
-Upstream-Source: http://search.cpan.org/dist/Pod-Readme/
-Upstream-Name: Pod-Readme
+Format-Specification: http://svn.debian.org/wsvn/dep/web/deps/dep5.mdwn?op=file&rev=135
+Maintainer: Robert Rothenberg <rrwo at cpan.org>
+Source: http://search.cpan.org/dist/Pod-Readme/
+Name: Pod-Readme
-Files: *
Copyright: 2005-2006, Robert Rothenberg <rrwo at cpan.org>
-License-Alias: Perl
-License: Artistic | GPL-1+
+License: Artistic or GPL-1+
-Files: debian/*
+Files: ./debian/*
Copyright: 2009, Antonio Radici <antonio at dyne.org>
-License: Artistic | GPL-1+
+License: Artistic or GPL-1+
License: Artistic
This program is free software; you can redistribute it and/or modify
Modified: trunk/libpod-readme-perl/debian/rules
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libpod-readme-perl/debian/rules?rev=58129&op=diff
==============================================================================
--- trunk/libpod-readme-perl/debian/rules (original)
+++ trunk/libpod-readme-perl/debian/rules Thu May 20 09:07:16 2010
@@ -1,23 +1,4 @@
#!/usr/bin/make -f
-build: build-stamp
-build-stamp:
- DEVEL_TESTS=1 dh build
- touch $@
-
-clean:
- dh $@
-
-install: install-stamp
-install-stamp: build-stamp
- dh install
- touch $@
-
-binary-arch:
-
-binary-indep: install
- dh $@
-
-binary: binary-arch binary-indep
-
-.PHONY: binary binary-arch binary-indep install clean build
+%:
+ dh --buildsystem=perl_build $@
Added: trunk/libpod-readme-perl/debian/source/format
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libpod-readme-perl/debian/source/format?rev=58129&op=file
==============================================================================
--- trunk/libpod-readme-perl/debian/source/format (added)
+++ trunk/libpod-readme-perl/debian/source/format Thu May 20 09:07:16 2010
@@ -1,0 +1,1 @@
+3.0 (quilt)
Modified: trunk/libpod-readme-perl/lib/Pod/Readme.pm
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libpod-readme-perl/lib/Pod/Readme.pm?rev=58129&op=diff
==============================================================================
--- trunk/libpod-readme-perl/lib/Pod/Readme.pm (original)
+++ trunk/libpod-readme-perl/lib/Pod/Readme.pm Thu May 20 09:07:16 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