Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Update podlators to CPAN version 2.4.0

  The new perlpodstyle.pod has been located to pod/

  Changes were necessary to mkppport because of a new dependency on
  Encode in podlators that stopped it being built before Encode was built.

  [DELTA]

  2010-10-10  Russ Allbery  <rra@stanford.edu>

  * VERSION: podlators 2.4.0 released.

  * scripts/pod2man: Remove the code to generate the #! line and
  supporting code and instead rely on ExtUtils::MakeMaker to handle
  that during package build.
  * scripts/pod2text: Likewise.
  * scripts/pod2man.PL: Renamed to pod2man.
  * scripts/pod2text.PL: Renamed to pod2text.
  * Makefile.PL: Remove PL_FILES section.

  * pod/perlpodstyle.pod: New style guide for POD documentation,
  split mostly from the NOTES section of the pod2man man page.
  * scripts/pod2man.PL: Remove NOTES section, now maintained as the
  separate perlpodstyle document.
  * Makefile.PL: Add perlpodstyle.1 to the generated man pages.

  * lib/Pod/Man.pm (cmd_para): 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.
  * t/man.t: Test S<> at the end of lines.

  * lib/Pod/Man.pm (output): If the utf8 option is given, encode
  output in UTF-8 if there is no encoding layer.  Now requires the
  Encode module.
  (start_document): Rather than forcibly change the PerlIO encoding
  layer, probe the PerlIO layers with protection for Perl versions
  without PerlIO and set a flag indicating whether to encode on the
  fly on output.
  * lib/Pod/Text.pm: Likewise.
  * Makefile.PL: Mark Encode as required.
  * t/man-perlio.t: Test Pod::Man output to a file handle with a
  PerlIO encoding layer already applied.
  * t/text-perlio.t: Likewise for Pod::Text.
  • Loading branch information...
commit 463da0ac9e3d63ff5a2efbc705aad083d4b2b20e 1 parent fb59364
Chris Williams bingos authored
8 MANIFEST
View
@@ -1644,8 +1644,9 @@ cpan/podlators/lib/Pod/Text/Color.pm Convert POD data to color ASCII text
cpan/podlators/lib/Pod/Text/Overstrike.pm Convert POD data to formatted overstrike text
cpan/podlators/lib/Pod/Text.pm Pod-Parser - convert POD data to formatted ASCII text
cpan/podlators/lib/Pod/Text/Termcap.pm Convert POD data to ASCII text with format escapes
-cpan/podlators/scripts/pod2man.PL Precursor for translator to turn pod into manpage
-cpan/podlators/scripts/pod2text.PL Precursor for translator to turn pod into text
+cpan/podlators/Makefile.PL Convert POD data to *roff
+cpan/podlators/scripts/pod2man Precursor for translator to turn pod into manpage
+cpan/podlators/scripts/pod2text Precursor for translator to turn pod into text
cpan/podlators/t/basic.cap podlators test
cpan/podlators/t/basic.clr podlators test
cpan/podlators/t/basic.man podlators test
@@ -1658,6 +1659,7 @@ cpan/podlators/t/devise-date.t podlators test
cpan/podlators/t/filehandle.t podlators test
cpan/podlators/t/man-heading.t podlators test
cpan/podlators/t/man-options.t podlators test
+cpan/podlators/t/man-perlio.t podlators test
cpan/podlators/t/man.t podlators test
cpan/podlators/t/man-utf8.t podlators test
cpan/podlators/t/overstrike.t podlators test
@@ -1668,6 +1670,7 @@ cpan/podlators/t/pod.t podlators test
cpan/podlators/t/termcap.t podlators test
cpan/podlators/t/text-encoding.t podlators test
cpan/podlators/t/text-options.t podlators test
+cpan/podlators/t/text-perlio.t podlators test
cpan/podlators/t/text.t podlators test
cpan/podlators/t/text-utf8.t podlators test
cpan/podlators/VERSION podlators distribution version
@@ -4138,6 +4141,7 @@ pod/perlperf.pod Perl Performance and Optimization Techniques
pod/perl.pod Perl overview (this section)
pod/perlpod.pod Perl plain old documentation
pod/perlpodspec.pod Perl plain old documentation format specification
+pod/perlpodstyle.pod Perl POD style guide
pod/perlpolicy.pod Perl development policies
pod/perlport.pod Perl portability guide
pod/perlpragma.pod Perl modules: writing a user pragma
3  Porting/Maintainers.pl
View
@@ -1201,8 +1201,9 @@ package Maintainers;
'podlators' =>
{
'MAINTAINER' => 'rra',
- 'DISTRIBUTION' => 'RRA/podlators-2.3.1.tar.gz',
+ 'DISTRIBUTION' => 'RRA/podlators-2.4.0.tar.gz',
'FILES' => q[cpan/podlators],
+ 'MAP' => { 'pod/perlpodstyle.pod' => 'pod/perlpodstyle.pod', },
'UPSTREAM' => 'cpan',
},
12 cpan/podlators/Makefile.PL
View
@@ -0,0 +1,12 @@
+use strict;
+use ExtUtils::MakeMaker;
+
+WriteMakefile (
+ NAME => 'Pod',
+ DISTNAME => 'podlators',
+ VERSION_FROM => 'VERSION', # finds $VERSION
+ EXE_FILES => [ 'scripts/pod2man', 'scripts/pod2text' ],
+ INSTALLDIRS => ( $] >= 5.006 ? 'perl' : 'site' ),
+ AUTHOR => 'Russ Allbery (rra@stanford.edu)',
+ ABSTRACT => 'Convert POD data to various other formats'
+);
2  cpan/podlators/VERSION
View
@@ -1 +1 @@
-$VERSION = '2.3.1';
+$VERSION = '2.4.0';
40 cpan/podlators/lib/Pod/Man.pm
View
@@ -1,7 +1,7 @@
# Pod::Man -- Convert POD data to formatted *roff input.
#
-# Copyright 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009
-# Russ Allbery <rra@stanford.edu>
+# Copyright 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
+# 2010 Russ Allbery <rra@stanford.edu>
# Substantial contributions by Sean Burke <sburke@cpan.org>
#
# This program is free software; you may redistribute it and/or modify it
@@ -31,11 +31,12 @@ use subs qw(makespace);
use vars qw(@ISA %ESCAPES $PREAMBLE $VERSION);
use Carp qw(croak);
+use Encode qw(encode);
use Pod::Simple ();
@ISA = qw(Pod::Simple);
-$VERSION = '2.23';
+$VERSION = '2.25';
# Set the debugging level. If someone has inserted a debug function into this
# class already, use that. Otherwise, use any Pod::Simple debug function
@@ -723,7 +724,11 @@ sub outindex {
# Output some text, without any additional changes.
sub output {
my ($self, @text) = @_;
- print { $$self{output_fh} } @text;
+ if ($$self{ENCODE}) {
+ print { $$self{output_fh} } encode ('UTF-8', join ('', @text));
+ } else {
+ print { $$self{output_fh} } @text;
+ }
}
##############################################################################
@@ -740,17 +745,19 @@ sub start_document {
return;
}
- # If we were given the utf8 option, set an output encoding on our file
- # handle. Wrap in an eval in case we're using a version of Perl too old
- # to understand this.
- #
- # This is evil because it changes the global state of a file handle that
- # we may not own. However, we can't just blindly encode all output, since
- # there may be a pre-applied output encoding (such as from PERL_UNICODE)
- # and then we would double-encode. This seems to be the least bad
- # approach.
+ # 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
+ # our output before printing it (handled in the output() sub). Wrap the
+ # check in an eval to handle versions of Perl without PerlIO.
+ $$self{ENCODE} = 0;
if ($$self{utf8}) {
- eval { binmode ($$self{output_fh}, ':encoding(UTF-8)') };
+ $$self{ENCODE} = 1;
+ eval {
+ my @layers = PerlIO::get_layers ($$self{output_fh});
+ if (grep { $_ eq 'utf8' } @layers) {
+ $$self{ENCODE} = 0;
+ }
+ }
}
# Determine information for the preamble and then output it.
@@ -949,8 +956,9 @@ sub cmd_para {
if defined ($line) && DEBUG && !$$self{IN_NAME};
# Force exactly one newline at the end and strip unwanted trailing
- # whitespace at the end.
- $text =~ s/\s*$/\n/;
+ # whitespace at the end, but leave "\ " backslashed space from an S< >
+ # at the end of a line.
+ $text =~ s/((?:\\ )*)\s*$/$1\n/;
# Output the paragraph.
$self->output ($self->protect ($self->textmapfonts ($text)));
34 cpan/podlators/lib/Pod/Text.pm
View
@@ -29,6 +29,7 @@ use strict;
use vars qw(@ISA @EXPORT %ESCAPES $VERSION);
use Carp qw(carp croak);
+use Encode qw(encode);
use Exporter ();
use Pod::Simple ();
@@ -37,7 +38,7 @@ use Pod::Simple ();
# We have to export pod2text for backward compatibility.
@EXPORT = qw(pod2text);
-$VERSION = '3.14';
+$VERSION = '3.15';
##############################################################################
# Initialization
@@ -250,7 +251,8 @@ sub reformat {
# necessary to match the input encoding unless UTF-8 output is forced. This
# preserves the traditional pass-through behavior of Pod::Text.
sub output {
- my ($self, $text) = @_;
+ my ($self, @text) = @_;
+ my $text = join ('', @text);
$text =~ tr/\240\255/ /d;
unless ($$self{opt_utf8} || $$self{CHECKED_ENCODING}) {
my $encoding = $$self{encoding} || '';
@@ -259,7 +261,11 @@ sub output {
}
$$self{CHECKED_ENCODING} = 1;
}
- print { $$self{output_fh} } $text;
+ if ($$self{ENCODE}) {
+ print { $$self{output_fh} } encode ('UTF-8', $text);
+ } else {
+ print { $$self{output_fh} } $text;
+ }
}
# Output a block of code (something that isn't part of the POD text). Called
@@ -284,17 +290,19 @@ sub start_document {
# We have to redo encoding handling for each document.
delete $$self{CHECKED_ENCODING};
- # If we were given the utf8 option, set an output encoding on our file
- # handle. Wrap in an eval in case we're using a version of Perl too old
- # to understand this.
- #
- # This is evil because it changes the global state of a file handle that
- # we may not own. However, we can't just blindly encode all output, since
- # there may be a pre-applied output encoding (such as from PERL_UNICODE)
- # and then we would double-encode. This seems to be the least bad
- # approach.
+ # 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
+ # our output before printing it (handled in the output() sub). Wrap the
+ # check in an eval to handle versions of Perl without PerlIO.
+ $$self{ENCODE} = 0;
if ($$self{opt_utf8}) {
- eval { binmode ($$self{output_fh}, ':encoding(UTF-8)') };
+ $$self{ENCODE} = 1;
+ eval {
+ my @layers = PerlIO::get_layers ($$self{output_fh});
+ if (grep { $_ eq 'utf8' } @layers) {
+ $$self{ENCODE} = 0;
+ }
+ };
}
return '';
303 cpan/podlators/scripts/pod2man
View
@@ -0,0 +1,303 @@
+#!perl
+
+# pod2man -- Convert POD data to formatted *roff input.
+#
+# Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010
+# 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.
+
+require 5.004;
+
+use Getopt::Long qw(GetOptions);
+use Pod::Man ();
+use Pod::Usage qw(pod2usage);
+
+use strict;
+
+# Insert -- into @ARGV before any single dash argument to hide it from
+# Getopt::Long; we want to interpret it as meaning stdin.
+my $stdin;
+@ARGV = map { $_ eq '-' && !$stdin++ ? ('--', $_) : $_ } @ARGV;
+
+# Parse our options, trying to retain backward compatibility with pod2man but
+# allowing short forms as well. --lax is currently ignored.
+my %options;
+$options{errors} = 'pod';
+Getopt::Long::config ('bundling_override');
+GetOptions (\%options, 'center|c=s', 'date|d=s', 'fixed=s', 'fixedbold=s',
+ 'fixeditalic=s', 'fixedbolditalic=s', 'help|h', 'lax|l',
+ 'name|n=s', 'official|o', 'quotes|q=s', 'release|r:s',
+ 'section|s=s', 'stderr', 'verbose|v', 'utf8|u') or exit 1;
+pod2usage (0) if $options{help};
+
+# Official sets --center, but don't override things explicitly set.
+if ($options{official} && !defined $options{center}) {
+ $options{center} = 'Perl Programmers Reference Guide';
+}
+
+# Verbose is only our flag, not a Pod::Man flag.
+my $verbose = $options{verbose};
+delete $options{verbose};
+
+# This isn't a valid Pod::Man option and is only accepted for backward
+# compatibility.
+delete $options{lax};
+
+# Initialize and run the formatter, pulling a pair of input and output off at
+# a time.
+my $parser = Pod::Man->new (%options);
+my @files;
+do {
+ @files = splice (@ARGV, 0, 2);
+ print " $files[1]\n" if $verbose;
+ $parser->parse_from_file (@files);
+} while (@ARGV);
+
+__END__
+
+=head1 NAME
+
+pod2man - Convert POD data to formatted *roff input
+
+=for stopwords
+en em --stderr stderr --utf8 UTF-8 overdo markup MT-LEVEL Allbery Solaris
+URL troff troff-specific formatters uppercased Christiansen
+
+=head1 SYNOPSIS
+
+pod2man [B<--center>=I<string>] [B<--date>=I<string>]
+ [B<--fixed>=I<font>] [B<--fixedbold>=I<font>] [B<--fixeditalic>=I<font>]
+ [B<--fixedbolditalic>=I<font>] [B<--name>=I<name>] [B<--official>]
+ [B<--quotes>=I<quotes>] [B<--release>[=I<version>]]
+ [B<--section>=I<manext>] [B<--stderr>] [B<--utf8>] [B<--verbose>]
+ [I<input> [I<output>] ...]
+
+pod2man B<--help>
+
+=head1 DESCRIPTION
+
+B<pod2man> is a front-end for Pod::Man, using it to generate *roff input
+from POD source. The resulting *roff code is suitable for display on a
+terminal using nroff(1), normally via man(1), or printing using troff(1).
+
+I<input> is the file to read for POD source (the POD can be embedded in
+code). If I<input> isn't given, it defaults to C<STDIN>. I<output>, if
+given, is the file to which to write the formatted output. If I<output>
+isn't given, the formatted output is written to C<STDOUT>. Several POD
+files can be processed in the same B<pod2man> invocation (saving module
+load and compile times) by providing multiple pairs of I<input> and
+I<output> files on the command line.
+
+B<--section>, B<--release>, B<--center>, B<--date>, and B<--official> can
+be used to set the headers and footers to use; if not given, Pod::Man will
+assume various defaults. See below or L<Pod::Man> for details.
+
+B<pod2man> assumes that your *roff formatters have a fixed-width font
+named C<CW>. If yours is called something else (like C<CR>), use
+B<--fixed> to specify it. This generally only matters for troff output
+for printing. Similarly, you can set the fonts used for bold, italic, and
+bold italic fixed-width output.
+
+Besides the obvious pod conversions, Pod::Man, and therefore pod2man also
+takes care of formatting func(), func(n), and simple variable references
+like $foo or @bar so you don't have to use code escapes for them; complex
+expressions like C<$fred{'stuff'}> will still need to be escaped, though.
+It also translates dashes that aren't used as hyphens into en dashes, makes
+long dashes--like this--into proper em dashes, fixes "paired quotes," and
+takes care of several other troff-specific tweaks. See L<Pod::Man> for
+complete information.
+
+=head1 OPTIONS
+
+=over 4
+
+=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.
+
+=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>.
+
+=item B<--fixed>=I<font>
+
+The fixed-width font to use for verbatim text and code. Defaults to
+C<CW>. Some systems may want C<CR> instead. Only matters for troff(1)
+output.
+
+=item B<--fixedbold>=I<font>
+
+Bold version of the fixed-width font. Defaults to C<CB>. Only matters
+for troff(1) output.
+
+=item B<--fixeditalic>=I<font>
+
+Italic version of the fixed-width font (actually, something of a misnomer,
+since most fixed-width fonts only have an oblique version, not an italic
+version). Defaults to C<CI>. Only matters for troff(1) output.
+
+=item B<--fixedbolditalic>=I<font>
+
+Bold italic (probably actually oblique) version of the fixed-width font.
+Pod::Man doesn't assume you have this, and defaults to C<CB>. Some
+systems (such as Solaris) have this font available as C<CX>. Only matters
+for troff(1) output.
+
+=item B<-h>, B<--help>
+
+Print out usage information.
+
+=item B<-l>, B<--lax>
+
+No longer used. B<pod2man> used to check its input for validity as a
+manual page, but this should now be done by L<podchecker(1)> instead.
+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.
+
+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.
+
+=item B<-o>, B<--official>
+
+Set the default header to indicate that this page is part of the standard
+Perl release, if B<--center> is not also given.
+
+=item B<-q> I<quotes>, B<--quotes>=I<quotes>
+
+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.
+
+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>
+
+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.
+
+=item B<-s>, B<--section>
+
+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
+functions, 4 for devices, 5 for file formats, 6 for games, 7 for
+miscellaneous information, and 8 for administrator commands. There is a lot
+of variation here, however; some systems (like Solaris) use 4 for file
+formats, 5 for miscellaneous information, and 7 for devices. Still others
+use 1m instead of 8, or some mix of both. About the only section numbers
+that are reliably consistent are 1, 2, and 3.
+
+By default, section 1 will be used unless the file ends in C<.pm>, in
+which case section 3 will be selected.
+
+=item B<--stderr>
+
+By default, B<pod2man> puts any errors detected in the POD input in a POD
+ERRORS section in the output manual page. If B<--stderr> is given, errors
+are sent to standard error instead and the POD ERRORS section is
+suppressed.
+
+=item B<-u>, B<--utf8>
+
+By default, B<pod2man> produces the most conservative possible *roff
+output to try to ensure that it will work with as many different *roff
+implementations as possible. Many *roff implementations cannot handle
+non-ASCII characters, so this means all non-ASCII characters are converted
+either to a *roff escape sequence that tries to create a properly accented
+character (at least for troff output) or to C<X>.
+
+This option says to instead output literal UTF-8 characters. If your
+*roff implementation can handle it, this is the best output format to use
+and avoids corruption of documents containing non-ASCII characters.
+However, be warned that *roff source with literal UTF-8 characters is not
+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.
+
+=item B<-v>, B<--verbose>
+
+Print out the name of each output file as it is being generated.
+
+=back
+
+=head1 DIAGNOSTICS
+
+If B<pod2man> fails with errors, see L<Pod::Man> and L<Pod::Simple> for
+information about what those errors might mean.
+
+=head1 EXAMPLES
+
+ pod2man program > program.1
+ pod2man SomeModule.pm /usr/perl/man/man3/SomeModule.3
+ pod2man --section=7 note.pod > note.7
+
+If you would like to print out a lot of man page continuously, you probably
+want to set the C and D registers to set contiguous page numbering and
+even/odd paging, at least on some versions of man(7).
+
+ troff -man -rC1 -rD1 perl.1 perldata.1 perlsyn.1 ...
+
+To get index entries on C<STDERR>, turn on the F register, as in:
+
+ troff -man -rF1 perl.1
+
+The indexing merely outputs messages via C<.tm> for each major page,
+section, subsection, item, and any C<XE<lt>E<gt>> directives. See
+L<Pod::Man> for more details.
+
+=head1 BUGS
+
+Lots of this documentation is duplicated from L<Pod::Man>.
+
+=head1 SEE ALSO
+
+L<Pod::Man>, L<Pod::Simple>, L<man(1)>, L<nroff(1)>, L<perlpod(1)>,
+L<podchecker(1)>, L<perlpodstyle(1)>, L<troff(1)>, L<man(7)>
+
+The man page documenting the an macro set may be L<man(5)> instead of
+L<man(7)> on your system.
+
+The current version of this script is always available from its web site at
+L<http://www.eyrie.org/~eagle/software/podlators/>. It is also part of the
+Perl core distribution as of 5.6.0.
+
+=head1 AUTHOR
+
+Russ Allbery <rra@stanford.edu>, 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 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.
+
+=cut
589 cpan/podlators/scripts/pod2man.PL
View
@@ -1,589 +0,0 @@
-#!/usr/local/bin/perl
-
-use Config;
-use File::Basename qw(&basename &dirname);
-use Cwd;
-
-# List explicitly here the variables you want Configure to
-# generate. Metaconfig only looks for shell variables, so you
-# have to mention them as if they were shell variables, not
-# %Config entries. Thus you write
-# $startperl
-# to ensure Configure will look for $Config{startperl}.
-
-# This forces PL files to create target in same directory as PL file.
-# This is so that make depend always knows where to find PL derivatives.
-$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 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.
-
-require 5.004;
-
-use Getopt::Long qw(GetOptions);
-use Pod::Man ();
-use Pod::Usage qw(pod2usage);
-
-use strict;
-
-# Silence -w warnings.
-use vars qw($running_under_some_shell);
-
-# Insert -- into @ARGV before any single dash argument to hide it from
-# Getopt::Long; we want to interpret it as meaning stdin.
-my $stdin;
-@ARGV = map { $_ eq '-' && !$stdin++ ? ('--', $_) : $_ } @ARGV;
-
-# Parse our options, trying to retain backward compatibility with pod2man but
-# allowing short forms as well. --lax is currently ignored.
-my %options;
-$options{errors} = 'pod';
-Getopt::Long::config ('bundling_override');
-GetOptions (\%options, 'center|c=s', 'date|d=s', 'fixed=s', 'fixedbold=s',
- 'fixeditalic=s', 'fixedbolditalic=s', 'help|h', 'lax|l',
- 'name|n=s', 'official|o', 'quotes|q=s', 'release|r:s',
- 'section|s=s', 'stderr', 'verbose|v', 'utf8|u') or exit 1;
-pod2usage (0) if $options{help};
-
-# Official sets --center, but don't override things explicitly set.
-if ($options{official} && !defined $options{center}) {
- $options{center} = 'Perl Programmers Reference Guide';
-}
-
-# Verbose is only our flag, not a Pod::Man flag.
-my $verbose = $options{verbose};
-delete $options{verbose};
-
-# This isn't a valid Pod::Man option and is only accepted for backward
-# compatibility.
-delete $options{lax};
-
-# Initialize and run the formatter, pulling a pair of input and output off at
-# a time.
-my $parser = Pod::Man->new (%options);
-my @files;
-do {
- @files = splice (@ARGV, 0, 2);
- print " $files[1]\n" if $verbose;
- $parser->parse_from_file (@files);
-} while (@ARGV);
-
-__END__
-
-=head1 NAME
-
-pod2man - Convert POD data to formatted *roff input
-
-=for stopwords
-en em --stderr stderr --utf8 UTF-8 overdo markup MT-LEVEL Allbery Solaris
-URL troff troff-specific formatters uppercased Christiansen
-
-=head1 SYNOPSIS
-
-pod2man [B<--center>=I<string>] [B<--date>=I<string>]
- [B<--fixed>=I<font>] [B<--fixedbold>=I<font>] [B<--fixeditalic>=I<font>]
- [B<--fixedbolditalic>=I<font>] [B<--name>=I<name>] [B<--official>]
- [B<--quotes>=I<quotes>] [B<--release>[=I<version>]]
- [B<--section>=I<manext>] [B<--stderr>] [B<--utf8>] [B<--verbose>]
- [I<input> [I<output>] ...]
-
-pod2man B<--help>
-
-=head1 DESCRIPTION
-
-B<pod2man> is a front-end for Pod::Man, using it to generate *roff input
-from POD source. The resulting *roff code is suitable for display on a
-terminal using nroff(1), normally via man(1), or printing using troff(1).
-
-I<input> is the file to read for POD source (the POD can be embedded in
-code). If I<input> isn't given, it defaults to C<STDIN>. I<output>, if
-given, is the file to which to write the formatted output. If I<output>
-isn't given, the formatted output is written to C<STDOUT>. Several POD
-files can be processed in the same B<pod2man> invocation (saving module
-load and compile times) by providing multiple pairs of I<input> and
-I<output> files on the command line.
-
-B<--section>, B<--release>, B<--center>, B<--date>, and B<--official> can
-be used to set the headers and footers to use; if not given, Pod::Man will
-assume various defaults. See below or L<Pod::Man> for details.
-
-B<pod2man> assumes that your *roff formatters have a fixed-width font
-named C<CW>. If yours is called something else (like C<CR>), use
-B<--fixed> to specify it. This generally only matters for troff output
-for printing. Similarly, you can set the fonts used for bold, italic, and
-bold italic fixed-width output.
-
-Besides the obvious pod conversions, Pod::Man, and therefore pod2man also
-takes care of formatting func(), func(n), and simple variable references
-like $foo or @bar so you don't have to use code escapes for them; complex
-expressions like C<$fred{'stuff'}> will still need to be escaped, though.
-It also translates dashes that aren't used as hyphens into en dashes, makes
-long dashes--like this--into proper em dashes, fixes "paired quotes," and
-takes care of several other troff-specific tweaks. See L<Pod::Man> for
-complete information.
-
-=head1 OPTIONS
-
-=over 4
-
-=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.
-
-=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>.
-
-=item B<--fixed>=I<font>
-
-The fixed-width font to use for verbatim text and code. Defaults to
-C<CW>. Some systems may want C<CR> instead. Only matters for troff(1)
-output.
-
-=item B<--fixedbold>=I<font>
-
-Bold version of the fixed-width font. Defaults to C<CB>. Only matters
-for troff(1) output.
-
-=item B<--fixeditalic>=I<font>
-
-Italic version of the fixed-width font (actually, something of a misnomer,
-since most fixed-width fonts only have an oblique version, not an italic
-version). Defaults to C<CI>. Only matters for troff(1) output.
-
-=item B<--fixedbolditalic>=I<font>
-
-Bold italic (probably actually oblique) version of the fixed-width font.
-Pod::Man doesn't assume you have this, and defaults to C<CB>. Some
-systems (such as Solaris) have this font available as C<CX>. Only matters
-for troff(1) output.
-
-=item B<-h>, B<--help>
-
-Print out usage information.
-
-=item B<-l>, B<--lax>
-
-No longer used. B<pod2man> used to check its input for validity as a
-manual page, but this should now be done by L<podchecker(1)> instead.
-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.
-
-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.
-
-=item B<-o>, B<--official>
-
-Set the default header to indicate that this page is part of the standard
-Perl release, if B<--center> is not also given.
-
-=item B<-q> I<quotes>, B<--quotes>=I<quotes>
-
-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.
-
-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>
-
-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.
-
-=item B<-s>, B<--section>
-
-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
-functions, 4 for devices, 5 for file formats, 6 for games, 7 for
-miscellaneous information, and 8 for administrator commands. There is a lot
-of variation here, however; some systems (like Solaris) use 4 for file
-formats, 5 for miscellaneous information, and 7 for devices. Still others
-use 1m instead of 8, or some mix of both. About the only section numbers
-that are reliably consistent are 1, 2, and 3.
-
-By default, section 1 will be used unless the file ends in C<.pm>, in
-which case section 3 will be selected.
-
-=item B<--stderr>
-
-By default, B<pod2man> puts any errors detected in the POD input in a POD
-ERRORS section in the output manual page. If B<--stderr> is given, errors
-are sent to standard error instead and the POD ERRORS section is
-suppressed.
-
-=item B<-u>, B<--utf8>
-
-By default, B<pod2man> produces the most conservative possible *roff
-output to try to ensure that it will work with as many different *roff
-implementations as possible. Many *roff implementations cannot handle
-non-ASCII characters, so this means all non-ASCII characters are converted
-either to a *roff escape sequence that tries to create a properly accented
-character (at least for troff output) or to C<X>.
-
-This option says to instead output literal UTF-8 characters. If your
-*roff implementation can handle it, this is the best output format to use
-and avoids corruption of documents containing non-ASCII characters.
-However, be warned that *roff source with literal UTF-8 characters is not
-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.
-
-=item B<-v>, B<--verbose>
-
-Print out the name of each output file as it is being generated.
-
-=back
-
-=head1 DIAGNOSTICS
-
-If B<pod2man> fails with errors, see L<Pod::Man> and L<Pod::Simple> for
-information about what those errors might mean.
-
-=head1 EXAMPLES
-
- pod2man program > program.1
- pod2man SomeModule.pm /usr/perl/man/man3/SomeModule.3
- pod2man --section=7 note.pod > note.7
-
-If you would like to print out a lot of man page continuously, you probably
-want to set the C and D registers to set contiguous page numbering and
-even/odd paging, at least on some versions of man(7).
-
- troff -man -rC1 -rD1 perl.1 perldata.1 perlsyn.1 ...
-
-To get index entries on C<STDERR>, turn on the F register, as in:
-
- troff -man -rF1 perl.1
-
-The indexing merely outputs messages via C<.tm> for each major page,
-section, subsection, item, and any C<XE<lt>E<gt>> directives. See
-L<Pod::Man> for more details.
-
-=head1 BUGS
-
-Lots of this documentation is duplicated from L<Pod::Man>.
-
-=head1 NOTES
-
-For those not sure of the proper layout of a man page, here are some notes
-on writing a proper man page.
-
-The name of the program being documented is conventionally written in bold
-(using BE<lt>E<gt>) wherever it occurs, as are all program options.
-Arguments should be written in italics (IE<lt>E<gt>). Functions are
-traditionally written in italics; if you write a function as function(),
-Pod::Man will take care of this for you. Literal code or commands should
-be in CE<lt>E<gt>. References to other man pages should be in the form
-C<manpage(section)>, and Pod::Man will automatically format those
-appropriately. As an exception, it's traditional not to use this form when
-referring to module documentation; use C<LE<lt>Module::NameE<gt>> instead.
-
-References to other programs or functions are normally in the form of man
-page references so that cross-referencing tools can provide the user with
-links and the like. It's possible to overdo this, though, so be careful not
-to clutter your documentation with too much markup.
-
-The major headers should be set out using a C<=head1> directive, and are
-historically written in the rather startling ALL UPPER CASE format, although
-this is not mandatory. Minor headers may be included using C<=head2>, and
-are typically in mixed case.
-
-The standard sections of a manual page are:
-
-=over 4
-
-=item NAME
-
-Mandatory section; should be a comma-separated list of programs or functions
-documented by this POD page, such as:
-
- foo, bar - programs to do something
-
-Manual page indexers are often extremely picky about the format of this
-section, so don't put anything in it except this line. A single dash, and
-only a single dash, should separate the list of programs or functions from
-the description. Do not use any markup such as CE<lt>E<gt> or
-BE<lt>E<gt>. Functions should not be qualified with C<()> or the like.
-The description should ideally fit on a single line, even if a man program
-replaces the dash with a few tabs.
-
-=item SYNOPSIS
-
-A short usage summary for programs and functions. This section is mandatory
-for section 3 pages.
-
-=item DESCRIPTION
-
-Extended description and discussion of the program or functions, or the body
-of the documentation for man pages that document something else. If
-particularly long, it's a good idea to break this up into subsections
-C<=head2> directives like:
-
- =head2 Normal Usage
-
- =head2 Advanced Features
-
- =head2 Writing Configuration Files
-
-or whatever is appropriate for your documentation.
-
-=item OPTIONS
-
-Detailed description of each of the command-line options taken by the
-program. This should be separate from the description for the use of things
-like L<Pod::Usage|Pod::Usage>. This is normally presented as a list, with
-each option as a separate C<=item>. The specific option string should be
-enclosed in BE<lt>E<gt>. Any values that the option takes should be
-enclosed in IE<lt>E<gt>. For example, the section for the option
-B<--section>=I<manext> would be introduced with:
-
- =item B<--section>=I<manext>
-
-Synonymous options (like both the short and long forms) are separated by a
-comma and a space on the same C<=item> line, or optionally listed as their
-own item with a reference to the canonical name. For example, since
-B<--section> can also be written as B<-s>, the above would be:
-
- =item B<-s> I<manext>, B<--section>=I<manext>
-
-(Writing the short option first is arguably easier to read, since the long
-option is long enough to draw the eye to it anyway and the short option can
-otherwise get lost in visual noise.)
-
-=item RETURN VALUE
-
-What the program or function returns, if successful. This section can be
-omitted for programs whose precise exit codes aren't important, provided
-they return 0 on success as is standard. It should always be present for
-functions.
-
-=item ERRORS
-
-Exceptions, error return codes, exit statuses, and errno settings.
-Typically used for function documentation; program documentation uses
-DIAGNOSTICS instead. The general rule of thumb is that errors printed to
-C<STDOUT> or C<STDERR> and intended for the end user are documented in
-DIAGNOSTICS while errors passed internal to the calling program and
-intended for other programmers are documented in ERRORS. When documenting
-a function that sets errno, a full list of the possible errno values
-should be given here.
-
-=item DIAGNOSTICS
-
-All possible messages the program can print out--and what they mean. You
-may wish to follow the same documentation style as the Perl documentation;
-see perldiag(1) for more details (and look at the POD source as well).
-
-If applicable, please include details on what the user should do to correct
-the error; documenting an error as indicating "the input buffer is too
-small" without telling the user how to increase the size of the input buffer
-(or at least telling them that it isn't possible) aren't very useful.
-
-=item EXAMPLES
-
-Give some example uses of the program or function. Don't skimp; users often
-find this the most useful part of the documentation. The examples are
-generally given as verbatim paragraphs.
-
-Don't just present an example without explaining what it does. Adding a
-short paragraph saying what the example will do can increase the value of
-the example immensely.
-
-=item ENVIRONMENT
-
-Environment variables that the program cares about, normally presented as a
-list using C<=over>, C<=item>, and C<=back>. For example:
-
- =over 6
-
- =item HOME
-
- Used to determine the user's home directory. F<.foorc> in this
- directory is read for configuration details, if it exists.
-
- =back
-
-Since environment variables are normally in all uppercase, no additional
-special formatting is generally needed; they're glaring enough as it is.
-
-=item FILES
-
-All files used by the program or function, normally presented as a list, and
-what it uses them for. File names should be enclosed in FE<lt>E<gt>. It's
-particularly important to document files that will be potentially modified.
-
-=item CAVEATS
-
-Things to take special care with, sometimes called WARNINGS.
-
-=item BUGS
-
-Things that are broken or just don't work quite right.
-
-=item RESTRICTIONS
-
-Bugs you don't plan to fix. :-)
-
-=item NOTES
-
-Miscellaneous commentary.
-
-=item AUTHOR
-
-Who wrote it (use AUTHORS for multiple people). Including your current
-e-mail address (or some e-mail address to which bug reports should be sent)
-so that users have a way of contacting you is a good idea. Remember that
-program documentation tends to roam the wild for far longer than you expect
-and pick an e-mail address that's likely to last if possible.
-
-=item HISTORY
-
-Programs derived from other sources sometimes have this, or you might keep
-a modification log here. If the log gets overly long or detailed,
-consider maintaining it in a separate file, though.
-
-=item COPYRIGHT AND LICENSE
-
-For copyright
-
- Copyright YEAR(s) by YOUR NAME(s)
-
-(No, (C) is not needed. No, "all rights reserved" is not needed.)
-
-For licensing the easiest way is to use the same licensing as Perl itself:
-
- This library is free software; you may redistribute it and/or modify
- it under the same terms as Perl itself.
-
-This makes it easy for people to use your module with Perl. Note that
-this licensing is neither an endorsement or a requirement, you are of
-course free to choose any licensing.
-
-=item SEE ALSO
-
-Other man pages to check out, like man(1), man(7), makewhatis(8), or
-catman(8). Normally a simple list of man pages separated by commas, or a
-paragraph giving the name of a reference work. Man page references, if they
-use the standard C<name(section)> form, don't have to be enclosed in
-LE<lt>E<gt> (although it's recommended), but other things in this section
-probably should be when appropriate.
-
-If the package has a mailing list, include a URL or subscription
-instructions here.
-
-If the package has a web site, include a URL here.
-
-=back
-
-In addition, some systems use CONFORMING TO to note conformance to relevant
-standards and MT-LEVEL to note safeness for use in threaded programs or
-signal handlers. These headings are primarily useful when documenting parts
-of a C library. Documentation of object-oriented libraries or modules may
-use CONSTRUCTORS and METHODS sections for detailed documentation of the
-parts of the library and save the DESCRIPTION section for an overview; other
-large modules may use FUNCTIONS for similar reasons. Some people use
-OVERVIEW to summarize the description if it's quite long.
-
-Section ordering varies, although NAME should I<always> be the first section
-(you'll break some man page systems otherwise), and NAME, SYNOPSIS,
-DESCRIPTION, and OPTIONS generally always occur first and in that order if
-present. In general, SEE ALSO, AUTHOR, and similar material should be left
-for last. Some systems also move WARNINGS and NOTES to last. The order
-given above should be reasonable for most purposes.
-
-Finally, as a general note, try not to use an excessive amount of markup.
-As documented here and in L<Pod::Man>, you can safely leave Perl variables,
-function names, man page references, and the like unadorned by markup and
-the POD translators will figure it out for you. This makes it much easier
-to later edit the documentation. Note that many existing translators
-(including this one currently) will do the wrong thing with e-mail addresses
-when wrapped in LE<lt>E<gt>, so don't do that.
-
-For additional information that may be more accurate for your specific
-system, see either L<man(5)> or L<man(7)> depending on your system manual
-section numbering conventions.
-
-=head1 SEE ALSO
-
-L<Pod::Man>, L<Pod::Simple>, L<man(1)>, L<nroff(1)>, L<perlpod(1)>,
-L<podchecker(1)>, L<troff(1)>, L<man(7)>
-
-The man page documenting the an macro set may be L<man(5)> instead of
-L<man(7)> on your system.
-
-The current version of this script is always available from its web site at
-L<http://www.eyrie.org/~eagle/software/podlators/>. It is also part of the
-Perl core distribution as of 5.6.0.
-
-=head1 AUTHOR
-
-Russ Allbery <rra@stanford.edu>, based I<very> heavily on the original
-B<pod2man> by Larry Wall and Tom Christiansen. Large portions of this
-documentation, particularly the sections on the anatomy of a proper man
-page, are taken from the B<pod2man> documentation by Tom.
-
-=head1 COPYRIGHT AND LICENSE
-
-Copyright 1999, 2000, 2001, 2004, 2006, 2008 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.
-
-=cut
-!NO!SUBS!
-#'# (cperl-mode)
-
-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;
51 cpan/podlators/scripts/pod2text.PL → cpan/podlators/scripts/pod2text
View
@@ -1,43 +1,9 @@
-#!/usr/local/bin/perl
-
-use Config;
-use File::Basename qw(&basename &dirname);
-use Cwd;
-
-# List explicitly here the variables you want Configure to
-# generate. Metaconfig only looks for shell variables, so you
-# have to mention them as if they were shell variables, not
-# %Config entries. Thus you write
-# $startperl
-# to ensure Configure will look for $Config{startperl}.
-
-# This forces PL files to create target in same directory as PL file.
-# This is so that make depend always knows where to find PL derivatives.
-$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!';
+#!perl
# pod2text -- Convert POD data to formatted ASCII text.
#
-# Copyright 1999, 2000, 2001, 2004, 2006, 2008 Russ Allbery <rra@stanford.edu>
+# Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010
+# 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.
@@ -53,9 +19,6 @@ use Pod::Usage qw(pod2usage);
use strict;
-# Silence -w warnings.
-use vars qw($running_under_some_shell);
-
# Take an initial pass through our options, looking for one of the form
# -<number>. We turn that into -w <number> for compatibility with the
# original pod2text script.
@@ -297,16 +260,10 @@ Russ Allbery <rra@stanford.edu>.
=head1 COPYRIGHT AND LICENSE
-Copyright 1999, 2000, 2001, 2004, 2006, 2008 Russ Allbery
+Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010 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.
=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;
134 cpan/podlators/t/man-perlio.t
View
@@ -0,0 +1,134 @@
+#!/usr/bin/perl -w
+#
+# man-perlio.t -- Test Pod::Man with a PerlIO UTF-8 encoding layer.
+#
+# Copyright 2002, 2004, 2006, 2008, 2009, 2010 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.
+###
2  cpan/podlators/t/man-utf8.t
View
@@ -1,6 +1,6 @@
#!/usr/bin/perl -w
#
-# man-options.t -- Additional tests for Pod::Man options.
+# man-utf8.t -- Test Pod::Man with UTF-8 input.
#
# Copyright 2002, 2004, 2006, 2008, 2009 Russ Allbery <rra@stanford.edu>
#
22 cpan/podlators/t/man.t
View
@@ -2,7 +2,7 @@
#
# man.t -- Additional specialized tests for Pod::Man.
#
-# Copyright 2002, 2003, 2004, 2006, 2007, 2008, 2009
+# Copyright 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2010
# Russ Allbery <rra@stanford.edu>
#
# This program is free software; you may redistribute it and/or modify it
@@ -19,7 +19,7 @@ BEGIN {
use strict;
-use Test::More tests => 30;
+use Test::More tests => 31;
BEGIN { use_ok ('Pod::Man') }
# Test whether we can use binmode to set encoding.
@@ -510,3 +510,21 @@ test - B<test> I<italics> F<file>
.SH "NAME"
test \- test italics file
###
+
+###
+=head1 TRAILING SPACE
+
+HelloS< >
+
+worldS< >
+
+.
+###
+.SH "TRAILING SPACE"
+.IX Header "TRAILING SPACE"
+Hello\
+.PP
+world\ \ \
+.PP
+\&.
+###
123 cpan/podlators/t/text-perlio.t
View
@@ -0,0 +1,123 @@
+#!/usr/bin/perl -w
+#
+# text-perlio.t -- Test Pod::Text with a PerlIO UTF-8 encoding layer.
+#
+# Copyright 2002, 2004, 2006, 2007, 2008, 2009, 2010
+# 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 => 4;
+ }
+}
+BEGIN { use_ok ('Pod::Text') }
+
+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)') };
+ print TMP "=encoding UTF-8\n\n";
+ while (<DATA>) {
+ last if $_ eq "###\n";
+ print TMP $_;
+ }
+ close TMP;
+ 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;
+ open (TMP, 'out.tmp') or die "Cannot open out.tmp: $!\n";
+ eval { binmode (\*TMP, ':encoding(utf-8)') };
+ 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");
+ $n++;
+}
+
+# Below the marker are bits of POD and corresponding expected text output.
+# This is used to test specific features or problems with Pod::Text. The
+# input and output are separated by lines containing only ###.
+
+__DATA__
+
+###
+=head1 Test of SE<lt>E<gt>
+
+This is S<some whitespace>.
+###
+Test of S<>
+ This is some whitespace.
+
+###
+
+###
+=head1 I can eat glass
+
+=over 4
+
+=item Esperanto
+
+Mi povas manĝi vitron, ĝi ne damaĝas min.
+
+=item Braille
+
+⠊⠀⠉⠁⠝⠀⠑⠁⠞⠀⠛⠇⠁⠎⠎⠀⠁⠝⠙⠀⠊⠞⠀⠙⠕⠑⠎⠝⠞⠀⠓⠥⠗⠞⠀⠍⠑
+
+=item Hindi
+
+मैं काँच खा सकता हूँ और मुझे उससे कोई चोट नहीं पहुंचती.
+
+=back
+
+See L<http://www.columbia.edu/kermit/utf8.html>
+###
+I can eat glass
+ Esperanto
+ Mi povas manĝi vitron, ĝi ne damaĝas min.
+
+ Braille
+ ⠊⠀⠉⠁⠝⠀⠑⠁⠞⠀⠛⠇⠁⠎⠎⠀⠁⠝⠙⠀⠊⠞⠀⠙⠕⠑⠎⠝⠞⠀⠓⠥⠗⠞⠀⠍⠑
+
+ Hindi
+ मैं काँच खा सकता हूँ और मुझे उससे कोई चोट नहीं पहुंचती.
+
+ See <http://www.columbia.edu/kermit/utf8.html>
+
+###
6 mkppport
View
@@ -2,7 +2,6 @@ use strict;
use warnings;
use Getopt::Long;
-use Pod::Usage;
use File::Spec;
use File::Compare qw( compare );
use File::Copy qw( copy );
@@ -22,7 +21,10 @@ my %opt = (
clean => 0,
);
-GetOptions(\%opt, qw( clean list=s )) or pod2usage(2);
+unless ( GetOptions(\%opt, qw( clean list=s )) ) {
+ require Pod::Usage;
+ Pod::Usage::pod2usage(2);
+}
my $absroot = File::Spec->rel2abs($rootdir);
my @destdirs = readlist($opt{list});
4 pod/perldelta.pod
View
@@ -338,6 +338,10 @@ C<PathTools> has been upgraded from version 3.31_01 to 3.34.
=item *
+C<podlators> has been upgraded from version 2.3.1 to 2.4.0
+
+=item *
+
C<sigtrap> has been upgraded from version 1.04 to 1.05.
It no longer tries to modify read-only arguments when generating a
295 pod/perlpodstyle.pod
View
@@ -0,0 +1,295 @@
+=head1 NAME
+
+perlpodstyle - Perl POD style guide
+
+=head1 DESCRIPTION
+
+These are general guidelines for how to write POD documentation for Perl
+scripts and modules, based on general guidelines for writing good UNIX man
+pages. All of these guidelines are, of course, optional, but following
+them will make your documentation more consistent with other documentation
+on the system.
+
+The name of the program being documented is conventionally written in bold
+(using BE<lt>E<gt>) wherever it occurs, as are all program options.
+Arguments should be written in italics (IE<lt>E<gt>). Function names are
+traditionally written in italics; if you write a function as function(),
+Pod::Man will take care of this for you. Literal code or commands should
+be in CE<lt>E<gt>. References to other man pages should be in the form
+C<manpage(section)> or C<LE<lt>manpage(section)E<gt>>, and Pod::Man will
+automatically format those appropriately. The second form, with
+LE<lt>E<gt>, is used to request that a POD formatter make a link to the
+man page if possible. As an exception, one normally omits the section
+when referring to module documentation since it's not clear what section
+module documentation will be in; use C<LE<lt>Module::NameE<gt>> for module
+references instead.
+
+References to other programs or functions are normally in the form of man
+page references so that cross-referencing tools can provide the user with
+links and the like. It's possible to overdo this, though, so be careful not
+to clutter your documentation with too much markup. References to other
+programs that are not given as man page references should be enclosed in
+BE<lt>E<gt>.
+
+The major headers should be set out using a C<=head1> directive, and are
+historically written in the rather startling ALL UPPER CASE format; this
+is not mandatory, but it's strongly recommended so that sections have
+consistent naming across different software packages. Minor headers may
+be included using C<=head2>, and are typically in mixed case.
+
+The standard sections of a manual page are:
+
+=over 4
+
+=item NAME
+
+Mandatory section; should be a comma-separated list of programs or
+functions documented by this POD page, such as:
+
+ foo, bar - programs to do something
+
+Manual page indexers are often extremely picky about the format of this
+section, so don't put anything in it except this line. Every program or
+function documented by this POD page should be listed, separated by a
+comma and a space. For a Perl module, just give the module name. A
+single dash, and only a single dash, should separate the list of programs
+or functions from the description. Do not use any markup such as
+CE<lt>E<gt> or BE<lt>E<gt> anywhere in this line. Functions should not be
+qualified with C<()> or the like. The description should ideally fit on a
+single line, even if a man program replaces the dash with a few tabs.
+
+=item SYNOPSIS
+
+A short usage summary for programs and functions. This section is
+mandatory for section 3 pages. For Perl module documentation, it's
+usually convenient to have the contents of this section be a verbatim
+block showing some (brief) examples of typical ways the module is used.
+
+=item DESCRIPTION
+
+Extended description and discussion of the program or functions, or the
+body of the documentation for man pages that document something else. If
+particularly long, it's a good idea to break this up into subsections
+C<=head2> directives like:
+
+ =head2 Normal Usage
+
+ =head2 Advanced Features
+
+ =head2 Writing Configuration Files
+
+or whatever is appropriate for your documentation.
+
+For a module, this is generally where the documentation of the interfaces
+provided by the module goes, usually in the form of a list with an
+C<=item> for each interface. Depending on how many interfaces there are,
+you may want to put that documentation in separate METHODS, FUNCTIONS,
+CLASS METHODS, or INSTANCE METHODS sections instead and save the
+DESCRIPTION section for an overview.
+
+=item OPTIONS
+
+Detailed description of each of the command-line options taken by the
+program. This should be separate from the description for the use of
+parsers like L<Pod::Usage>. This is normally presented as a list, with
+each option as a separate C<=item>. The specific option string should be
+enclosed in BE<lt>E<gt>. Any values that the option takes should be
+enclosed in IE<lt>E<gt>. For example, the section for the option
+B<--section>=I<manext> would be introduced with:
+
+ =item B<--section>=I<manext>
+
+Synonymous options (like both the short and long forms) are separated by a
+comma and a space on the same C<=item> line, or optionally listed as their
+own item with a reference to the canonical name. For example, since
+B<--section> can also be written as B<-s>, the above would be:
+
+ =item B<-s> I<manext>, B<--section>=I<manext>
+
+Writing the short option first is recommended because it's easier to read.
+The long option is long enough to draw the eye to it anyway and the short
+option can otherwise get lost in visual noise.
+
+=item RETURN VALUE
+
+What the program or function returns, if successful. This section can be
+omitted for programs whose precise exit codes aren't important, provided
+they return 0 on success and non-zero on failure as is standard. It
+should always be present for functions. For modules, it may be useful to
+summarize return values from the module interface here, or it may be more
+useful to discuss return values separately in the documentation of each
+function or method the module provides.
+
+=item ERRORS
+
+Exceptions, error return codes, exit statuses, and errno settings.
+Typically used for function or module documentation; program documentation
+uses DIAGNOSTICS instead. The general rule of thumb is that errors
+printed to C<STDOUT> or C<STDERR> and intended for the end user are
+documented in DIAGNOSTICS while errors passed internal to the calling
+program and intended for other programmers are documented in ERRORS. When
+documenting a function that sets errno, a full list of the possible errno
+values should be given here.
+
+=item DIAGNOSTICS
+
+All possible messages the program can print out and what they mean. You
+may wish to follow the same documentation style as the Perl documentation;
+see perldiag(1) for more details (and look at the POD source as well).
+
+If applicable, please include details on what the user should do to
+correct the error; documenting an error as indicating "the input buffer is
+too small" without telling the user how to increase the size of the input
+buffer (or at least telling them that it isn't possible) aren't very
+useful.
+
+=item EXAMPLES
+
+Give some example uses of the program or function. Don't skimp; users
+often find this the most useful part of the documentation. The examples
+are generally given as verbatim paragraphs.
+
+Don't just present an example without explaining what it does. Adding a
+short paragraph saying what the example will do can increase the value of
+the example immensely.
+
+=item ENVIRONMENT
+
+Environment variables that the program cares about, normally presented as
+a list using C<=over>, C<=item>, and C<=back>. For example:
+
+ =over 6
+
+ =item HOME
+
+ Used to determine the user's home directory. F<.foorc> in this
+ directory is read for configuration details, if it exists.
+
+ =back
+
+Since environment variables are normally in all uppercase, no additional
+special formatting is generally needed; they're glaring enough as it is.
+
+=item FILES
+
+All files used by the program or function, normally presented as a list,
+and what it uses them for. File names should be enclosed in FE<lt>E<gt>.
+It's particularly important to document files that will be potentially
+modified.
+
+=item CAVEATS
+
+Things to take special care with, sometimes called WARNINGS.
+
+=item BUGS
+
+Things that are broken or just don't work quite right.
+
+=item RESTRICTIONS
+
+Bugs you don't plan to fix. :-)
+
+=item NOTES
+
+Miscellaneous commentary.
+
+=item AUTHOR
+
+Who wrote it (use AUTHORS for multiple people). It's a good idea to
+include your current e-mail address (or some e-mail address to which bug
+reports should be sent) or some other contact information so that users
+have a way of contacting you. Remember that program documentation tends
+to roam the wild for far longer than you expect and pick a contact method
+that's likely to last.
+
+=item HISTORY
+
+Programs derived from other sources sometimes have this. Some people keep
+a modification log here, but that usually gets long and is normally better
+maintained in a separate file.
+
+=item COPYRIGHT AND LICENSE
+
+For copyright
+
+ Copyright YEAR(s) YOUR NAME(s)
+
+(No, (C) is not needed. No, "all rights reserved" is not needed.)
+
+For licensing the easiest way is to use the same licensing as Perl itself:
+
+ This library is free software; you may redistribute it and/or modify
+ it under the same terms as Perl itself.
+
+This makes it easy for people to use your module with Perl. Note that
+this licensing example is neither an endorsement or a requirement, you are
+of course free to choose any licensing.
+
+=item SEE ALSO
+
+Other man pages to check out, like man(1), man(7), makewhatis(8), or
+catman(8). Normally a simple list of man pages separated by commas, or a
+paragraph giving the name of a reference work. Man page references, if
+they use the standard C<name(section)> form, don't have to be enclosed in
+LE<lt>E<gt> (although it's recommended), but other things in this section
+probably should be when appropriate.
+
+If the package has a mailing list, include a URL or subscription
+instructions here.
+
+If the package has a web site, include a URL here.
+
+=back
+
+Documentation of object-oriented libraries or modules may want to use
+CONSTRUCTORS and METHODS sections, or CLASS METHODS and INSTANCE METHODS
+sections, for detailed documentation of the parts of the library and save
+the DESCRIPTION section for an overview. Large modules with a function
+interface may want to use FUNCTIONS for similar reasons. Some people use
+OVERVIEW to summarize the description if it's quite long.
+
+Section ordering varies, although NAME must always be the first section
+(you'll break some man page systems otherwise), and NAME, SYNOPSIS,
+DESCRIPTION, and OPTIONS generally always occur first and in that order if
+present. In general, SEE ALSO, AUTHOR, and similar material should be
+left for last. Some systems also move WARNINGS and NOTES to last. The
+order given above should be reasonable for most purposes.
+
+Some systems use CONFORMING TO to note conformance to relevant standards
+and MT-LEVEL to note safeness for use in threaded programs or signal
+handlers. These headings are primarily useful when documenting parts of a
+C library.
+
+Finally, as a general note, try not to use an excessive amount of markup.
+As documented here and in L<Pod::Man>, you can safely leave Perl
+variables, function names, man page references, and the like unadorned by
+markup and the POD translators will figure it out for you. This makes it
+much easier to later edit the documentation. Note that many existing
+translators will do the wrong thing with e-mail addresses when wrapped in
+LE<lt>E<gt>, so don't do that.
+
+=head1 SEE ALSO
+
+For additional information that may be more accurate for your specific
+system, see either L<man(5)> or L<man(7)> depending on your system manual
+section numbering conventions.
+
+This documentation is maintained as part of the podlators distribution.
+The current version is always available from its web site at
+<http://www.eyrie.org/~eagle/software/podlators/>.
+
+=head1 AUTHOR
+
+Russ Allbery <rra@stanford.edu>, with large portions of this documentation
+taken from the documentation of the original B<pod2man> implementation by
+Larry Wall and Tom Christiansen.
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010 Russ Allbery
+<rra@stanford.edu>.
+
+This documentation is free software; you may redistribute it and/or modify
+it under the same terms as Perl itself.
+
+=cut
Please sign in to comment.
Something went wrong with that request. Please try again.