lib/Pod/t/htmlview.t pod2html render test
lib/Pod/t/InputObjects.t See if Pod::InputObjects works
lib/Pod/t/man.t podlators test
+lib/Pod/t/man-options.t podlators test
lib/Pod/t/parselink.t podlators test
lib/Pod/t/pod2html-lib.pl pod2html testing library
lib/Pod/t/pod2latex.t See if Pod::LaTeX works
# Pod::Man -- Convert POD data to formatted *roff input.
-# $Id: Man.pm,v 2.16 2007-11-29 01:35:53 eagle Exp $
#
-# Copyright 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007
+# Copyright 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
# Russ Allbery <rra@stanford.edu>
# Substantial contributions by Sean Burke <sburke@cpan.org>
#
# Don't use the CVS revision as the version, since this module is also in Perl
# core and too many things could munge CVS magic revision strings. This
# number should ideally be the same as the CVS revision in podlators, however.
-$VERSION = '2.16';
+$VERSION = '2.17';
# Set the debugging level. If someone has inserted a debug function into this
# class already, use that. Otherwise, use any Pod::Simple debug function
my $convert = $$options{convert};
my $literal = $$options{literal};
- # Normally we do character translation, but we won't even do that in
- # <Data> blocks.
- if ($convert) {
- if (ASCII) {
- $text =~ s/(\\|[^\x00-\x7F])/$ESCAPES{ord ($1)} || "X"/eg;
- } else {
- $text =~ s/(\\)/$ESCAPES{ord ($1)} || "X"/eg;
- }
- }
-
# Cleanup just tidies up a few things, telling *roff that the hyphens are
- # hard and putting a bit of space between consecutive underscores.
+ # hard, putting a bit of space between consecutive underscores, and
+ # escaping backslashes. Be careful not to mangle our character
+ # translations by doing this before processing character translation.
if ($cleanup) {
+ $text =~ s/\\/\\e/g;
$text =~ s/-/\\-/g;
$text =~ s/_(?=_)/_\\|/g;
}
+ # Normally we do character translation, but we won't even do that in
+ # <Data> blocks or if UTF-8 output is desired.
+ if ($convert && !$$self{utf8} && ASCII) {
+ $text =~ s/([^\x00-\x7F])/$ESCAPES{ord ($1)} || "X"/eg;
+ }
+
# Ensure that *roff doesn't convert literal quotes to UTF-8 single quotes,
# but don't mess up our accept escapes.
if ($literal) {
# to Roman rather than the actual previous font when used in headings.
# troff output may still be broken, but at least we can fix nroff by
# just switching the font changes to the non-fixed versions.
- $nroff =~ s/\Q$$self{FONTS}{100}\E(.*)\\f[PR]/$1/g;
- $nroff =~ s/\Q$$self{FONTS}{101}\E(.*)\\f([PR])/\\fI$1\\f$2/g;
- $nroff =~ s/\Q$$self{FONTS}{110}\E(.*)\\f([PR])/\\fB$1\\f$2/g;
- $nroff =~ s/\Q$$self{FONTS}{111}\E(.*)\\f([PR])/\\f\(BI$1\\f$2/g;
+ $nroff =~ s/\Q$$self{FONTS}{100}\E(.*?)\\f[PR]/$1/g;
+ $nroff =~ s/\Q$$self{FONTS}{101}\E(.*?)\\f([PR])/\\fI$1\\f$2/g;
+ $nroff =~ s/\Q$$self{FONTS}{110}\E(.*?)\\f([PR])/\\fB$1\\f$2/g;
+ $nroff =~ s/\Q$$self{FONTS}{111}\E(.*?)\\f([PR])/\\f\(BI$1\\f$2/g;
# Now finally output the command. Bother with .ie only if the nroff
# and troff output aren't the same.
"o\\*/" , "u\\*`", "u\\*'", "u\\*^", "u\\*:", "y\\*'", "\\*(th", "y\\*:",
) if ASCII;
-# Make sure that at least this works even outside of ASCII.
-$ESCAPES{ord("\\")} = "\\e";
-
##############################################################################
# Premable
##############################################################################
.if t .Sp
.ne 5
.PP
-\fB\\$1\fR
+\fB\&\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
By default, section 1 will be used unless the file ends in .pm in which case
section 3 will be selected.
+=item utf8
+
+By default, Pod::Man 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>.
+
+If this option is set, Pod::Man will instead output UTF-8. 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.
+
=back
The standard Pod::Simple method parse_file() takes one argument naming the
=head1 BUGS
-Eight-bit input data isn't handled at all well at present. The correct
-approach would be to map EE<lt>E<gt> escapes to the appropriate UTF-8
-characters and then do a translation pass on the output according to the
-user-specified output character set. Unfortunately, we can't send eight-bit
-data directly to the output unless the user says this is okay, since some
-vendor *roff implementations can't handle eight-bit data. If the *roff
-implementation can, however, that's far superior to the current hacked
-characters that only work under troff.
-
There is currently no way to turn off the guesswork that tries to format
unmarked text appropriately, and sometimes it isn't wanted (particularly
when using POD to document something other than Perl). Most of the work
# Pod::ParseLink -- Parse an L<> formatting code in POD text.
-# $Id: ParseLink.pm,v 1.6 2002/07/15 05:46:00 eagle Exp $
#
# Copyright 2001 by Russ Allbery <rra@stanford.edu>
#
# Pod::Text -- Convert POD data to formatted ASCII text.
-# $Id: Text.pm,v 3.8 2006-09-16 20:55:41 eagle Exp $
#
# Copyright 1999, 2000, 2001, 2002, 2004, 2006
# by Russ Allbery <rra@stanford.edu>
# Pod::Text::Color -- Convert POD data to formatted color ASCII text
-# $Id: Color.pm,v 2.3 2006-01-25 23:56:54 eagle Exp $
#
# Copyright 1999, 2001, 2004, 2006 by Russ Allbery <rra@stanford.edu>
#
# Pod::Text::Overstrike -- Convert POD data to formatted overstrike text
-# $Id: Overstrike.pm,v 2.0 2004/06/09 04:51:20 eagle Exp $
#
# Created by Joe Smith <Joe.Smith@inwap.com> 30-Nov-2000
# (based on Pod::Text::Color by Russ Allbery <rra@stanford.edu>)
# Pod::Text::Termcap -- Convert POD data to ASCII text with format escapes.
-# $Id: Termcap.pm,v 2.3 2006-01-25 23:56:54 eagle Exp $
#
# Copyright 1999, 2001, 2002, 2004, 2006 by Russ Allbery <rra@stanford.edu>
#
#!/usr/bin/perl -w
-# $Id: basic.t,v 1.11 2006-09-16 20:25:25 eagle Exp $
#
# basic.t -- Basic tests for podlators.
#
#!/usr/bin/perl -w
-# $Id: color.t,v 1.3 2006-01-28 22:31:50 eagle Exp $
#
# color.t -- Additional specialized tests for Pod::Text::Color.
#
#!/usr/bin/perl -w
-# $Id: filehandle.t,v 1.2 2006-09-16 20:25:25 eagle Exp $
#
# filehandle.t -- Test the parse_from_filehandle interface.
#
--- /dev/null
+#!/usr/bin/perl -w
+#
+# man-options.t -- Additional tests for Pod::Man options.
+#
+# Copyright 2002, 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.
+
+BEGIN {
+ chdir 't' if -d 't';
+ if ($ENV{PERL_CORE}) {
+ @INC = '../lib';
+ } else {
+ unshift (@INC, '../blib/lib');
+ }
+ unshift (@INC, '../blib/lib');
+ $| = 1;
+ print "1..2\n";
+}
+
+END {
+ print "not ok 1\n" unless $loaded;
+}
+
+use Pod::Man;
+
+$loaded = 1;
+print "ok 1\n";
+
+my $n = 2;
+while (<DATA>) {
+ my %options;
+ next until $_ eq "###\n";
+ while (<DATA>) {
+ last if $_ eq "###\n";
+ my ($option, $value) = split;
+ $options{$option} = $value;
+ }
+ open (TMP, '> tmp.pod') or die "Cannot create tmp.pod: $!\n";
+ while (<DATA>) {
+ last if $_ eq "###\n";
+ print TMP $_;
+ }
+ close TMP;
+ my $parser = Pod::Man->new (%options) or die "Cannot create parser\n";
+ open (OUT, '> out.tmp') or die "Cannot create out.tmp: $!\n";
+ $parser->parse_from_file ('tmp.pod', \*OUT);
+ close OUT;
+ open (TMP, 'out.tmp') or die "Cannot open out.tmp: $!\n";
+ while (<TMP>) { last if /^\.nh/ }
+ my $output;
+ {
+ local $/;
+ $output = <TMP>;
+ }
+ close TMP;
+ unlink ('tmp.pod', 'out.tmp');
+ my $expected = '';
+ while (<DATA>) {
+ last if $_ eq "###\n";
+ $expected .= $_;
+ }
+ if ($output eq $expected) {
+ print "ok $n\n";
+ } else {
+ print "not ok $n\n";
+ print "Expected\n========\n$expected\nOutput\n======\n$output\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.
+###
#!/usr/bin/perl -w
-# $Id: man.t,v 1.12 2007-11-29 01:35:54 eagle Exp $
#
# man.t -- Additional specialized tests for Pod::Man.
#
-# Copyright 2002, 2003, 2004, 2006, 2007 by Russ Allbery <rra@stanford.edu>
+# Copyright 2002, 2003, 2004, 2006, 2007, 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.
}
unshift (@INC, '../blib/lib');
$| = 1;
- print "1..22\n";
+ print "1..24\n";
}
END {
$loaded = 1;
print "ok 1\n";
+# Test whether we can use binmode to set encoding.
+my $have_encoding = (eval { require PerlIO::encoding; 1 } and not $@);
+
my $parser = Pod::Man->new or die "Cannot create parser\n";
my $n = 2;
while (<DATA>) {
# We have a test in ISO 8859-1 encoding. Make sure that nothing strange
# happens if Perl thinks the world is Unicode. Wrap this in eval so that
# older versions of Perl don't croak.
- eval { binmode (\*TMP, ':encoding(iso-8859-1)') };
+ eval { binmode (\*TMP, ':encoding(iso-8859-1)') if $have_encoding };
while (<DATA>) {
last if $_ eq "###\n";
.IX Header "Quote escaping"
Don't escape `this' but do escape \f(CW\`this\*(Aq\fR (and don't surround it in quotes).
###
+
+###
+=pod
+
+E<eth>
+###
+.PP
+\&\*(d-
+###
+
+###
+=head1 C<one> and C<two>
+###
+.ie n .SH """one"" and ""two"""
+.el .SH "\f(CWone\fP and \f(CWtwo\fP"
+.IX Header "one and two"
+###
#!/usr/bin/perl -w
-# $Id: parselink.t,v 1.1 2001/11/23 10:09:06 eagle Exp $
#
# parselink.t -- Tests for Pod::ParseLink.
#
#!/usr/bin/perl -w
-# $Id: pod-parser.t,v 1.2 2006-09-16 21:09:57 eagle Exp $
#
# pod-parser.t -- Tests for backward compatibility with Pod::Parser.
#
#!/usr/bin/perl -w
-# $Id: termcap.t,v 1.4 2006-01-28 22:31:50 eagle Exp $
#
# termcap.t -- Additional specialized tests for Pod::Text::Termcap.
#
#!/usr/bin/perl -w
-# $Id: text-options.t,v 1.6 2006-01-28 22:31:50 eagle Exp $
#
# text-options.t -- Additional tests for Pod::Text options.
#
#!/usr/bin/perl -w
-# $Id: text.t,v 1.6 2007-09-12 00:20:08 eagle Exp $
#
# text.t -- Additional specialized tests for Pod::Text.
#
print OUT <<'!NO!SUBS!';
# pod2man -- Convert POD data to formatted *roff input.
-# $Id: pod2man.PL,v 1.16 2006-01-21 01:53:55 eagle Exp $
#
-# Copyright 1999, 2000, 2001, 2004, 2006 by Russ Allbery <rra@stanford.edu>
+# 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.
GetOptions (\%options, 'section|s=s', 'release|r:s', 'center|c=s',
'date|d=s', 'fixed=s', 'fixedbold=s', 'fixeditalic=s',
'fixedbolditalic=s', 'name|n=s', 'official|o', 'quotes|q=s',
- 'lax|l', 'help|h', 'verbose|v') or exit 1;
+ 'lax|l', 'help|h', 'verbose|v', 'utf8|u') or exit 1;
pod2usage (0) if $options{help};
# Official sets --center, but don't override things explicitly set.
By default, section 1 will be used unless the file ends in .pm in which case
section 3 will be selected.
+=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.
+
=item B<-v>, B<--verbose>
Print out the name of each output file as it is being generated.
=head1 COPYRIGHT AND LICENSE
-Copyright 1999, 2000, 2001, 2004, 2006 by Russ Allbery <rra@stanford.edu>.
+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.
projects / p5sagit/p5-mst-13.2.git / commitdiff