summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Pod')
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/Escapes.pm61
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/Find.pm6
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/Functions.pm30
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/Html.pm21
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/InputObjects.pm8
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/LaTeX.pm1883
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/Man.pm161
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/ParseUtils.pm8
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/Parser.pm28
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/Perldoc.pm236
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/Perldoc/BaseTo.pm3
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/Perldoc/GetOptsOO.pm2
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/Perldoc/ToANSI.pm2
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/Perldoc/ToChecker.pm2
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/Perldoc/ToMan.pm37
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/Perldoc/ToNroff.pm2
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/Perldoc/ToPod.pm2
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/Perldoc/ToRtf.pm2
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/Perldoc/ToTerm.pm49
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/Perldoc/ToText.pm2
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/Perldoc/ToTk.pm2
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/Perldoc/ToXml.pm2
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/PlainText.pm6
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/Select.pm32
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/Simple.pod430
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/Simple/Subclassing.pod1071
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/Text.pm48
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/Text/Termcap.pm6
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/Usage.pm76
29 files changed, 2069 insertions, 2149 deletions
diff --git a/Master/tlpkg/tlperl/lib/Pod/Escapes.pm b/Master/tlpkg/tlperl/lib/Pod/Escapes.pm
index de4d75a7b83..52b52724fce 100644
--- a/Master/tlpkg/tlperl/lib/Pod/Escapes.pm
+++ b/Master/tlpkg/tlperl/lib/Pod/Escapes.pm
@@ -1,11 +1,23 @@
-
-require 5;
-# The documentation is at the end.
-# Time-stamp: "2004-05-07 15:31:25 ADT"
package Pod::Escapes;
+use strict;
+use warnings;
+use 5.006;
+
+use vars qw(
+ %Code2USASCII
+ %Name2character
+ %Name2character_number
+ %Latin1Code_to_fallback
+ %Latin1Char_to_fallback
+ $FAR_CHAR
+ $FAR_CHAR_NUMBER
+ $NOT_ASCII
+ @ISA $VERSION @EXPORT_OK %EXPORT_TAGS
+);
+
require Exporter;
@ISA = ('Exporter');
-$VERSION = '1.04';
+$VERSION = '1.06';
@EXPORT_OK = qw(
%Code2USASCII
%Name2character
@@ -19,18 +31,6 @@ $VERSION = '1.04';
#==========================================================================
-use strict;
-use vars qw(
- %Code2USASCII
- %Name2character
- %Name2character_number
- %Latin1Code_to_fallback
- %Latin1Char_to_fallback
- $FAR_CHAR
- $FAR_CHAR_NUMBER
- $NOT_ASCII
-);
-
$FAR_CHAR = "?" unless defined $FAR_CHAR;
$FAR_CHAR_NUMBER = ord($FAR_CHAR) unless defined $FAR_CHAR_NUMBER;
@@ -90,7 +90,7 @@ sub e2charnum {
$in = hex $1;
} # else it's decimal, or named
- if($in =~ m/^\d+$/s) {
+ if($in =~ m/^[0-9]+$/s) {
return 0 + $in;
} else {
return $Name2character_number{$in}; # returns undef if unknown
@@ -529,7 +529,7 @@ __END__
=head1 NAME
-Pod::Escapes -- for resolving Pod EE<lt>...E<gt> sequences
+Pod::Escapes - for resolving Pod EE<lt>...E<gt> sequences
=head1 SYNOPSIS
@@ -567,7 +567,7 @@ C<e2char('0x2F')>, and C<e2char('057')> all return "/",
because C<EE<lt>solE<gt>>, C<EE<lt>47E<gt>>, C<EE<lt>0x2fE<gt>>,
and C<EE<lt>057E<gt>>, all mean "/". If
the name has no known value (as with a name of "qacute") or is
-syntactally invalid (as with a name of "1/4"), this returns undef.
+syntactically invalid (as with a name of "1/4"), this returns undef.
=item e2charnum($e_content)
@@ -579,7 +579,7 @@ C<e2char('0x2F')>, and C<e2char('057')> all return 47,
because C<EE<lt>solE<gt>>, C<EE<lt>47E<gt>>, C<EE<lt>0x2fE<gt>>,
and C<EE<lt>057E<gt>>, all mean "/", whose Unicode number is 47. If
the name has no known value (as with a name of "qacute") or is
-syntactally invalid (as with a name of "1/4"), this returns undef.
+syntactically invalid (as with a name of "1/4"), this returns undef.
=item $Name2character{I<name>}
@@ -641,11 +641,21 @@ C<chr($Name2character_number{$name})>.
=head1 SEE ALSO
-L<perlpod|perlpod>
+L<Pod::Browser> - a pod web server based on L<Catalyst>.
+
+L<Pod::Checker> - check pod documents for syntax errors.
+
+L<Pod::Coverage> - check if the documentation for a module is comprehensive.
+
+L<perlpod> - description of pod format (for people documenting with pod).
-L<perlpodspec|perlpodspec>
+L<perlpodspec> - specification of pod format (for people processing it).
-L<Text::Unidecode|Text::Unidecode>
+L<Text::Unidecode> - ASCII transliteration of Unicode text.
+
+=head1 REPOSITORY
+
+L<https://github.com/neilbowers/Pod-Escapes>
=head1 COPYRIGHT AND DISCLAIMERS
@@ -671,12 +681,13 @@ Currently (October 2001), that's these three:
Sean M. Burke C<sburke@cpan.org>
+Now being maintained by Neil Bowers E<lt>neilb@cpan.orgE<gt>
+
=cut
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# What I used for reading the XHTML .ent files:
-use strict;
my(@norms, @good, @bad);
my $dir = 'c:/sgml/docbook/';
my %escapes;
diff --git a/Master/tlpkg/tlperl/lib/Pod/Find.pm b/Master/tlpkg/tlperl/lib/Pod/Find.pm
index 157caf23a31..6149e7940ae 100644
--- a/Master/tlpkg/tlperl/lib/Pod/Find.pm
+++ b/Master/tlpkg/tlperl/lib/Pod/Find.pm
@@ -14,7 +14,7 @@ package Pod::Find;
use strict;
use vars qw($VERSION);
-$VERSION = '1.60'; ## Current version of this package
+$VERSION = '1.62'; ## Current version of this package
require 5.005; ## requires this Perl version or later
use Carp;
@@ -45,6 +45,10 @@ Pod::Find - find POD documents in directory trees
=head1 DESCRIPTION
+B<NOTE: This module is considered legacy; modern Perl releases (5.18 and
+higher) are going to remove Pod-Parser from core and use L<Pod-Simple>
+for all things POD.>
+
B<Pod::Find> provides a set of functions to locate POD files. Note that
no function is exported by default to avoid pollution of your namespace,
so be sure to specify them in the B<use> statement if you need them:
diff --git a/Master/tlpkg/tlperl/lib/Pod/Functions.pm b/Master/tlpkg/tlperl/lib/Pod/Functions.pm
index 6ae7ae4bfe5..9e09beee929 100644
--- a/Master/tlpkg/tlperl/lib/Pod/Functions.pm
+++ b/Master/tlpkg/tlperl/lib/Pod/Functions.pm
@@ -54,7 +54,7 @@ L<perlfunc/"Perl Functions by Category"> section.
=cut
-our $VERSION = '1.06';
+our $VERSION = '1.08';
require Exporter;
@@ -134,7 +134,7 @@ bind Socket binds an address to a socket
binmode I/O prepare binary files for I/O
bless Objects create an object
break Flow break out of a C<given> block
-caller Namespace Flow get context of the current subroutine call
+caller Flow Namespace get context of the current subroutine call
chdir File change your current working directory
chmod File changes the permissions on a list of files
chomp String remove a trailing record separator from a string
@@ -148,14 +148,14 @@ connect Socket connect to a remote socket
continue Flow optional trailing block in a while or foreach
cos Math cosine function
crypt String one-way passwd-style encryption
-dbmclose Objects I/O breaks binding on a tied dbm file
-dbmopen Objects I/O create binding on a tied dbm file
+dbmclose I/O Objects breaks binding on a tied dbm file
+dbmopen I/O Objects create binding on a tied dbm file
defined Misc test whether a value, variable, or function is defined
delete HASH deletes a value from a hash
die Flow I/O raise an exception or bail out
-do Modules Flow turn a BLOCK into a TERM
+do Flow Modules turn a BLOCK into a TERM
dump Flow create an immediate core dump
-each HASH ARRAY retrieve the next key/value pair from a hash
+each ARRAY HASH retrieve the next key/value pair from a hash
endgrent User be done using group file
endhostent User be done using hosts file
endnetent User be done using networks file
@@ -207,13 +207,13 @@ glob File expand filenames using wildcards
gmtime Time convert UNIX time into record or string using Greenwich time
goto Flow create spaghetti code
grep LIST locate elements in a list test true against a given criterion
-hex String Math convert a string to a hexadecimal number
+hex Math String convert a string to a hexadecimal number
import Modules Namespace patch a module's namespace into your own
index String find a substring within a string
int Math get the integer portion of a number
ioctl File system-dependent device control system call
join LIST join a list into a string using a separator
-keys HASH ARRAY retrieve list of indices from a hash
+keys ARRAY HASH retrieve list of indices from a hash
kill Process send a signal to a process or process group
last Flow exit a block prematurely
lc String return lower-case version of a string
@@ -237,13 +237,13 @@ msgsnd SysV send a SysV IPC message to a message queue
my Namespace declare and assign a local variable (lexical scoping)
next Flow iterate a block prematurely
no Modules unimport some module symbols or semantics at compile time
-oct String Math convert a string to an octal number
+oct Math String convert a string to an octal number
open File open a file, pipe, or descriptor
opendir File open a directory
ord String find a character's numeric representation
our Namespace declare and assign a package variable (lexical scoping)
-pack String Binary convert a list into a binary representation
-package Modules Objects Namespace declare a separate global namespace
+pack Binary String convert a list into a binary representation
+package Modules Namespace Objects declare a separate global namespace
__PACKAGE__ Flow the current package
pipe Process open a pair of connected filehandles
pop ARRAY remove the last element from an array and return it
@@ -271,7 +271,7 @@ rename File change a filename
require Modules load in external functions from a library at runtime
reset Misc clear all variables of a given name
return Flow get out of a function early
-reverse String LIST flip a string or a list
+reverse LIST String flip a string or a list
rewinddir I/O reset directory handle
rindex String right-to-left substring search
rmdir File remove a directory
@@ -328,7 +328,7 @@ telldir I/O get current seekpointer on a directory handle
tie Objects bind a variable to an object class
tied Objects get a reference to the object underlying a tied variable
time Time return number of seconds since 1970
-times Time Process return elapsed time for self and child processes
+times Process Time return elapsed time for self and child processes
tr/// String transliterate a string
truncate I/O shorten a file
uc String return upper-case version of a string
@@ -339,9 +339,9 @@ unlink File remove one link to a file
unpack Binary LIST convert binary structure into normal perl variables
unshift ARRAY prepend more elements to the beginning of a list
untie Objects break a tie binding to a variable
-use Modules Objects Namespace load in a module at compile time and import its namespace
+use Modules Namespace Objects load in a module at compile time and import its namespace
utime File set a file's last access and modify times
-values HASH ARRAY return a list of the values in a hash
+values ARRAY HASH return a list of the values in a hash
vec Binary test or set particular bits in a string
wait Process wait for any child process to die
waitpid Process wait for a particular child process to die
diff --git a/Master/tlpkg/tlperl/lib/Pod/Html.pm b/Master/tlpkg/tlperl/lib/Pod/Html.pm
index 72b37c249dd..f9f05b358eb 100644
--- a/Master/tlpkg/tlperl/lib/Pod/Html.pm
+++ b/Master/tlpkg/tlperl/lib/Pod/Html.pm
@@ -3,7 +3,7 @@ use strict;
require Exporter;
use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
-$VERSION = 1.18;
+$VERSION = 1.21;
@ISA = qw(Exporter);
@EXPORT = qw(pod2html htmlify);
@EXPORT_OK = qw(anchorify);
@@ -369,14 +369,12 @@ sub pod2html {
my $bodyid = $Backlink ? ' id="_podtop_"' : '';
my $csslink = '';
- my $bodystyle = ' style="background-color: white"';
- my $tdstyle = ' style="background-color: #cccccc"';
+ my $tdstyle = ' style="background-color: #cccccc; color: #000"';
if ($Css) {
$csslink = qq(\n<link rel="stylesheet" href="$Css" type="text/css" />);
$csslink =~ s,\\,/,g;
$csslink =~ s,(/.):,$1|,;
- $bodystyle = '';
$tdstyle= '';
}
@@ -400,7 +398,7 @@ END_OF_BLOCK
<link rev="made" href="mailto:$Config{perladmin}" />
</head>
-<body$bodyid$bodystyle>
+<body$bodyid>
$block
HTMLHEAD
@@ -447,9 +445,14 @@ sub usage {
my $podfile = shift;
warn "$0: $podfile: @_\n" if @_;
die <<END_OF_USAGE;
-Usage: $0 --help --htmlroot=<name> --infile=<name> --outfile=<name>
- --podpath=<name>:...:<name> --podroot=<name> --cachedir=<name>
- --recurse --verbose --index --norecurse --noindex
+Usage: $0 --help --htmldir=<name> --htmlroot=<URL>
+ --infile=<name> --outfile=<name>
+ --podpath=<name>:...:<name> --podroot=<name>
+ --cachedir=<name> --flush --recurse --norecurse
+ --quiet --noquiet --verbose --noverbose
+ --index --noindex --backlink --nobacklink
+ --header --noheader --poderrors --nopoderrors
+ --css=<URL> --title=<name>
--[no]backlink - turn =head1 directives into links pointing to the top of
the page (off by default).
@@ -706,7 +709,7 @@ sub _unixify {
package Pod::Simple::XHTML::LocalPodLinks;
use strict;
use warnings;
-use base 'Pod::Simple::XHTML';
+use parent 'Pod::Simple::XHTML';
use File::Spec;
use File::Spec::Unix;
diff --git a/Master/tlpkg/tlperl/lib/Pod/InputObjects.pm b/Master/tlpkg/tlperl/lib/Pod/InputObjects.pm
index d72865037c8..87ce2478f63 100644
--- a/Master/tlpkg/tlperl/lib/Pod/InputObjects.pm
+++ b/Master/tlpkg/tlperl/lib/Pod/InputObjects.pm
@@ -12,7 +12,7 @@ package Pod::InputObjects;
use strict;
use vars qw($VERSION);
-$VERSION = '1.60'; ## Current version of this package
+$VERSION = '1.62'; ## Current version of this package
require 5.005; ## requires this Perl version or later
#############################################################################
@@ -35,6 +35,10 @@ Nothing.
=head1 DESCRIPTION
+B<NOTE: This module is considered legacy; modern Perl releases (5.18 and
+higher) are going to remove Pod-Parser from core and use L<Pod-Simple>
+for all things POD.>
+
This module defines some basic input objects used by B<Pod::Parser> when
reading and parsing POD text from an input source. The following objects
are defined:
@@ -480,7 +484,7 @@ sub new {
@_
};
- ## Initialize contents if they havent been already
+ ## Initialize contents if they haven't been already
my $ptree = $self->{'-ptree'} || new Pod::ParseTree();
if ( ref $ptree =~ /^(ARRAY)?$/ ) {
## We have an array-ref, or a normal scalar. Pass it as an
diff --git a/Master/tlpkg/tlperl/lib/Pod/LaTeX.pm b/Master/tlpkg/tlperl/lib/Pod/LaTeX.pm
deleted file mode 100644
index fc6d99dd979..00000000000
--- a/Master/tlpkg/tlperl/lib/Pod/LaTeX.pm
+++ /dev/null
@@ -1,1883 +0,0 @@
-package Pod::LaTeX;
-
-=head1 NAME
-
-Pod::LaTeX - Convert Pod data to formatted Latex
-
-=head1 SYNOPSIS
-
- use Pod::LaTeX;
- my $parser = Pod::LaTeX->new ( );
-
- $parser->parse_from_filehandle;
-
- $parser->parse_from_file ('file.pod', 'file.tex');
-
-=head1 DESCRIPTION
-
-C<Pod::LaTeX> is a module to convert documentation in the Pod format
-into Latex. The L<B<pod2latex>|pod2latex> X<pod2latex> command uses
-this module for translation.
-
-C<Pod::LaTeX> is a derived class from L<Pod::Select|Pod::Select>.
-
-=cut
-
-
-use strict;
-require Pod::ParseUtils;
-use base qw/ Pod::Select /;
-
-use if $] > 5.017, 'deprecate';
-
-# use Data::Dumper; # for debugging
-use Carp;
-
-use vars qw/ $VERSION %HTML_Escapes @LatexSections /;
-
-$VERSION = '0.61';
-
-# Definitions of =headN -> latex mapping
-@LatexSections = (qw/
- chapter
- section
- subsection
- subsubsection
- paragraph
- subparagraph
- /);
-
-# Standard escape sequences converted to Latex.
-# The Unicode name of each character is given in the comments.
-# Complete LaTeX set added by Peter Acklam.
-
-%HTML_Escapes = (
- 'sol' => '\textfractionsolidus{}', # xxx - or should it be just '/'
- 'verbar' => '|',
-
- # The stuff below is based on the information available at
- # http://www.w3.org/TR/html401/sgml/entities.html
-
- # All characters in the range 0xA0-0xFF of the ISO 8859-1 character set.
- # Several of these characters require the `textcomp' LaTeX package.
- 'nbsp' => q|~|, # 0xA0 - no-break space = non-breaking space
- 'iexcl' => q|\textexclamdown{}|, # 0xA1 - inverted exclamation mark
- 'cent' => q|\textcent{}|, # 0xA2 - cent sign
- 'pound' => q|\textsterling{}|, # 0xA3 - pound sign
- 'curren' => q|\textcurrency{}|, # 0xA4 - currency sign
- 'yen' => q|\textyen{}|, # 0xA5 - yen sign = yuan sign
- 'brvbar' => q|\textbrokenbar{}|, # 0xA6 - broken bar = broken vertical bar
- 'sect' => q|\textsection{}|, # 0xA7 - section sign
- 'uml' => q|\textasciidieresis{}|, # 0xA8 - diaeresis = spacing diaeresis
- 'copy' => q|\textcopyright{}|, # 0xA9 - copyright sign
- 'ordf' => q|\textordfeminine{}|, # 0xAA - feminine ordinal indicator
- 'laquo' => q|\guillemotleft{}|, # 0xAB - left-pointing double angle quotation mark = left pointing guillemet
- 'not' => q|\textlnot{}|, # 0xAC - not sign
- 'shy' => q|\-|, # 0xAD - soft hyphen = discretionary hyphen
- 'reg' => q|\textregistered{}|, # 0xAE - registered sign = registered trade mark sign
- 'macr' => q|\textasciimacron{}|, # 0xAF - macron = spacing macron = overline = APL overbar
- 'deg' => q|\textdegree{}|, # 0xB0 - degree sign
- 'plusmn' => q|\textpm{}|, # 0xB1 - plus-minus sign = plus-or-minus sign
- 'sup2' => q|\texttwosuperior{}|, # 0xB2 - superscript two = superscript digit two = squared
- 'sup3' => q|\textthreesuperior{}|, # 0xB3 - superscript three = superscript digit three = cubed
- 'acute' => q|\textasciiacute{}|, # 0xB4 - acute accent = spacing acute
- 'micro' => q|\textmu{}|, # 0xB5 - micro sign
- 'para' => q|\textparagraph{}|, # 0xB6 - pilcrow sign = paragraph sign
- 'middot' => q|\textperiodcentered{}|, # 0xB7 - middle dot = Georgian comma = Greek middle dot
- 'cedil' => q|\c{}|, # 0xB8 - cedilla = spacing cedilla
- 'sup1' => q|\textonesuperior{}|, # 0xB9 - superscript one = superscript digit one
- 'ordm' => q|\textordmasculine{}|, # 0xBA - masculine ordinal indicator
- 'raquo' => q|\guillemotright{}|, # 0xBB - right-pointing double angle quotation mark = right pointing guillemet
- 'frac14' => q|\textonequarter{}|, # 0xBC - vulgar fraction one quarter = fraction one quarter
- 'frac12' => q|\textonehalf{}|, # 0xBD - vulgar fraction one half = fraction one half
- 'frac34' => q|\textthreequarters{}|, # 0xBE - vulgar fraction three quarters = fraction three quarters
- 'iquest' => q|\textquestiondown{}|, # 0xBF - inverted question mark = turned question mark
- 'Agrave' => q|\`A|, # 0xC0 - latin capital letter A with grave = latin capital letter A grave
- 'Aacute' => q|\'A|, # 0xC1 - latin capital letter A with acute
- 'Acirc' => q|\^A|, # 0xC2 - latin capital letter A with circumflex
- 'Atilde' => q|\~A|, # 0xC3 - latin capital letter A with tilde
- 'Auml' => q|\"A|, # 0xC4 - latin capital letter A with diaeresis
- 'Aring' => q|\AA{}|, # 0xC5 - latin capital letter A with ring above = latin capital letter A ring
- 'AElig' => q|\AE{}|, # 0xC6 - latin capital letter AE = latin capital ligature AE
- 'Ccedil' => q|\c{C}|, # 0xC7 - latin capital letter C with cedilla
- 'Egrave' => q|\`E|, # 0xC8 - latin capital letter E with grave
- 'Eacute' => q|\'E|, # 0xC9 - latin capital letter E with acute
- 'Ecirc' => q|\^E|, # 0xCA - latin capital letter E with circumflex
- 'Euml' => q|\"E|, # 0xCB - latin capital letter E with diaeresis
- 'Igrave' => q|\`I|, # 0xCC - latin capital letter I with grave
- 'Iacute' => q|\'I|, # 0xCD - latin capital letter I with acute
- 'Icirc' => q|\^I|, # 0xCE - latin capital letter I with circumflex
- 'Iuml' => q|\"I|, # 0xCF - latin capital letter I with diaeresis
- 'ETH' => q|\DH{}|, # 0xD0 - latin capital letter ETH
- 'Ntilde' => q|\~N|, # 0xD1 - latin capital letter N with tilde
- 'Ograve' => q|\`O|, # 0xD2 - latin capital letter O with grave
- 'Oacute' => q|\'O|, # 0xD3 - latin capital letter O with acute
- 'Ocirc' => q|\^O|, # 0xD4 - latin capital letter O with circumflex
- 'Otilde' => q|\~O|, # 0xD5 - latin capital letter O with tilde
- 'Ouml' => q|\"O|, # 0xD6 - latin capital letter O with diaeresis
- 'times' => q|\texttimes{}|, # 0xD7 - multiplication sign
- 'Oslash' => q|\O{}|, # 0xD8 - latin capital letter O with stroke = latin capital letter O slash
- 'Ugrave' => q|\`U|, # 0xD9 - latin capital letter U with grave
- 'Uacute' => q|\'U|, # 0xDA - latin capital letter U with acute
- 'Ucirc' => q|\^U|, # 0xDB - latin capital letter U with circumflex
- 'Uuml' => q|\"U|, # 0xDC - latin capital letter U with diaeresis
- 'Yacute' => q|\'Y|, # 0xDD - latin capital letter Y with acute
- 'THORN' => q|\TH{}|, # 0xDE - latin capital letter THORN
- 'szlig' => q|\ss{}|, # 0xDF - latin small letter sharp s = ess-zed
- 'agrave' => q|\`a|, # 0xE0 - latin small letter a with grave = latin small letter a grave
- 'aacute' => q|\'a|, # 0xE1 - latin small letter a with acute
- 'acirc' => q|\^a|, # 0xE2 - latin small letter a with circumflex
- 'atilde' => q|\~a|, # 0xE3 - latin small letter a with tilde
- 'auml' => q|\"a|, # 0xE4 - latin small letter a with diaeresis
- 'aring' => q|\aa{}|, # 0xE5 - latin small letter a with ring above = latin small letter a ring
- 'aelig' => q|\ae{}|, # 0xE6 - latin small letter ae = latin small ligature ae
- 'ccedil' => q|\c{c}|, # 0xE7 - latin small letter c with cedilla
- 'egrave' => q|\`e|, # 0xE8 - latin small letter e with grave
- 'eacute' => q|\'e|, # 0xE9 - latin small letter e with acute
- 'ecirc' => q|\^e|, # 0xEA - latin small letter e with circumflex
- 'euml' => q|\"e|, # 0xEB - latin small letter e with diaeresis
- 'igrave' => q|\`i|, # 0xEC - latin small letter i with grave
- 'iacute' => q|\'i|, # 0xED - latin small letter i with acute
- 'icirc' => q|\^i|, # 0xEE - latin small letter i with circumflex
- 'iuml' => q|\"i|, # 0xEF - latin small letter i with diaeresis
- 'eth' => q|\dh{}|, # 0xF0 - latin small letter eth
- 'ntilde' => q|\~n|, # 0xF1 - latin small letter n with tilde
- 'ograve' => q|\`o|, # 0xF2 - latin small letter o with grave
- 'oacute' => q|\'o|, # 0xF3 - latin small letter o with acute
- 'ocirc' => q|\^o|, # 0xF4 - latin small letter o with circumflex
- 'otilde' => q|\~o|, # 0xF5 - latin small letter o with tilde
- 'ouml' => q|\"o|, # 0xF6 - latin small letter o with diaeresis
- 'divide' => q|\textdiv{}|, # 0xF7 - division sign
- 'oslash' => q|\o{}|, # 0xF8 - latin small letter o with stroke, = latin small letter o slash
- 'ugrave' => q|\`u|, # 0xF9 - latin small letter u with grave
- 'uacute' => q|\'u|, # 0xFA - latin small letter u with acute
- 'ucirc' => q|\^u|, # 0xFB - latin small letter u with circumflex
- 'uuml' => q|\"u|, # 0xFC - latin small letter u with diaeresis
- 'yacute' => q|\'y|, # 0xFD - latin small letter y with acute
- 'thorn' => q|\th{}|, # 0xFE - latin small letter thorn
- 'yuml' => q|\"y|, # 0xFF - latin small letter y with diaeresis
-
- # Latin Extended-B
- 'fnof' => q|\textflorin{}|, # latin small f with hook = function = florin
-
- # Greek
- 'Alpha' => q|$\mathrm{A}$|, # greek capital letter alpha
- 'Beta' => q|$\mathrm{B}$|, # greek capital letter beta
- 'Gamma' => q|$\Gamma$|, # greek capital letter gamma
- 'Delta' => q|$\Delta$|, # greek capital letter delta
- 'Epsilon' => q|$\mathrm{E}$|, # greek capital letter epsilon
- 'Zeta' => q|$\mathrm{Z}$|, # greek capital letter zeta
- 'Eta' => q|$\mathrm{H}$|, # greek capital letter eta
- 'Theta' => q|$\Theta$|, # greek capital letter theta
- 'Iota' => q|$\mathrm{I}$|, # greek capital letter iota
- 'Kappa' => q|$\mathrm{K}$|, # greek capital letter kappa
- 'Lambda' => q|$\Lambda$|, # greek capital letter lambda
- 'Mu' => q|$\mathrm{M}$|, # greek capital letter mu
- 'Nu' => q|$\mathrm{N}$|, # greek capital letter nu
- 'Xi' => q|$\Xi$|, # greek capital letter xi
- 'Omicron' => q|$\mathrm{O}$|, # greek capital letter omicron
- 'Pi' => q|$\Pi$|, # greek capital letter pi
- 'Rho' => q|$\mathrm{R}$|, # greek capital letter rho
- 'Sigma' => q|$\Sigma$|, # greek capital letter sigma
- 'Tau' => q|$\mathrm{T}$|, # greek capital letter tau
- 'Upsilon' => q|$\Upsilon$|, # greek capital letter upsilon
- 'Phi' => q|$\Phi$|, # greek capital letter phi
- 'Chi' => q|$\mathrm{X}$|, # greek capital letter chi
- 'Psi' => q|$\Psi$|, # greek capital letter psi
- 'Omega' => q|$\Omega$|, # greek capital letter omega
-
- 'alpha' => q|$\alpha$|, # greek small letter alpha
- 'beta' => q|$\beta$|, # greek small letter beta
- 'gamma' => q|$\gamma$|, # greek small letter gamma
- 'delta' => q|$\delta$|, # greek small letter delta
- 'epsilon' => q|$\epsilon$|, # greek small letter epsilon
- 'zeta' => q|$\zeta$|, # greek small letter zeta
- 'eta' => q|$\eta$|, # greek small letter eta
- 'theta' => q|$\theta$|, # greek small letter theta
- 'iota' => q|$\iota$|, # greek small letter iota
- 'kappa' => q|$\kappa$|, # greek small letter kappa
- 'lambda' => q|$\lambda$|, # greek small letter lambda
- 'mu' => q|$\mu$|, # greek small letter mu
- 'nu' => q|$\nu$|, # greek small letter nu
- 'xi' => q|$\xi$|, # greek small letter xi
- 'omicron' => q|$o$|, # greek small letter omicron
- 'pi' => q|$\pi$|, # greek small letter pi
- 'rho' => q|$\rho$|, # greek small letter rho
-# 'sigmaf' => q||, # greek small letter final sigma
- 'sigma' => q|$\sigma$|, # greek small letter sigma
- 'tau' => q|$\tau$|, # greek small letter tau
- 'upsilon' => q|$\upsilon$|, # greek small letter upsilon
- 'phi' => q|$\phi$|, # greek small letter phi
- 'chi' => q|$\chi$|, # greek small letter chi
- 'psi' => q|$\psi$|, # greek small letter psi
- 'omega' => q|$\omega$|, # greek small letter omega
-# 'thetasym' => q||, # greek small letter theta symbol
-# 'upsih' => q||, # greek upsilon with hook symbol
-# 'piv' => q||, # greek pi symbol
-
- # General Punctuation
- 'bull' => q|\textbullet{}|, # bullet = black small circle
- # bullet is NOT the same as bullet operator
- 'hellip' => q|\textellipsis{}|, # horizontal ellipsis = three dot leader
- 'prime' => q|\textquotesingle{}|, # prime = minutes = feet
- 'Prime' => q|\textquotedbl{}|, # double prime = seconds = inches
- 'oline' => q|\textasciimacron{}|, # overline = spacing overscore
- 'frasl' => q|\textfractionsolidus{}|, # fraction slash
-
- # Letterlike Symbols
- 'weierp' => q|$\wp$|, # script capital P = power set = Weierstrass p
- 'image' => q|$\Re$|, # blackletter capital I = imaginary part
- 'real' => q|$\Im$|, # blackletter capital R = real part symbol
- 'trade' => q|\texttrademark{}|, # trade mark sign
-# 'alefsym' => q||, # alef symbol = first transfinite cardinal
- # alef symbol is NOT the same as hebrew letter alef, although the same
- # glyph could be used to depict both characters
-
- # Arrows
- 'larr' => q|\textleftarrow{}|, # leftwards arrow
- 'uarr' => q|\textuparrow{}|, # upwards arrow
- 'rarr' => q|\textrightarrow{}|, # rightwards arrow
- 'darr' => q|\textdownarrow{}|, # downwards arrow
- 'harr' => q|$\leftrightarrow$|, # left right arrow
-# 'crarr' => q||, # downwards arrow with corner leftwards = carriage return
- 'lArr' => q|$\Leftarrow$|, # leftwards double arrow
- # ISO 10646 does not say that lArr is the same as the 'is implied by'
- # arrow but also does not have any other character for that function. So
- # lArr can be used for 'is implied by' as ISOtech suggests
- 'uArr' => q|$\Uparrow$|, # upwards double arrow
- 'rArr' => q|$\Rightarrow$|, # rightwards double arrow
- # ISO 10646 does not say this is the 'implies' character but does not
- # have another character with this function so ? rArr can be used for
- # 'implies' as ISOtech suggests
- 'dArr' => q|$\Downarrow$|, # downwards double arrow
- 'hArr' => q|$\Leftrightarrow$|, # left right double arrow
-
- # Mathematical Operators.
- # Some of these require the `amssymb' package.
- 'forall' => q|$\forall$|, # for all
- 'part' => q|$\partial$|, # partial differential
- 'exist' => q|$\exists$|, # there exists
- 'empty' => q|$\emptyset$|, # empty set = null set = diameter
- 'nabla' => q|$\nabla$|, # nabla = backward difference
- 'isin' => q|$\in$|, # element of
- 'notin' => q|$\notin$|, # not an element of
- 'ni' => q|$\ni$|, # contains as member
- 'prod' => q|$\prod$|, # n-ary product = product sign
- # prod is NOT the same character as 'greek capital letter pi' though the
- # same glyph might be used for both
- 'sum' => q|$\sum$|, # n-ary summation
- # sum is NOT the same character as 'greek capital letter sigma' though
- # the same glyph might be used for both
- 'minus' => q|$-$|, # minus sign
- 'lowast' => q|$\ast$|, # asterisk operator
- 'radic' => q|$\surd$|, # square root = radical sign
- 'prop' => q|$\propto$|, # proportional to
- 'infin' => q|$\infty$|, # infinity
- 'ang' => q|$\angle$|, # angle
- 'and' => q|$\wedge$|, # logical and = wedge
- 'or' => q|$\vee$|, # logical or = vee
- 'cap' => q|$\cap$|, # intersection = cap
- 'cup' => q|$\cup$|, # union = cup
- 'int' => q|$\int$|, # integral
- 'there4' => q|$\therefore$|, # therefore
- 'sim' => q|$\sim$|, # tilde operator = varies with = similar to
- # tilde operator is NOT the same character as the tilde
- 'cong' => q|$\cong$|, # approximately equal to
- 'asymp' => q|$\asymp$|, # almost equal to = asymptotic to
- 'ne' => q|$\neq$|, # not equal to
- 'equiv' => q|$\equiv$|, # identical to
- 'le' => q|$\leq$|, # less-than or equal to
- 'ge' => q|$\geq$|, # greater-than or equal to
- 'sub' => q|$\subset$|, # subset of
- 'sup' => q|$\supset$|, # superset of
- # note that nsup, 'not a superset of' is not covered by the Symbol font
- # encoding and is not included.
- 'nsub' => q|$\not\subset$|, # not a subset of
- 'sube' => q|$\subseteq$|, # subset of or equal to
- 'supe' => q|$\supseteq$|, # superset of or equal to
- 'oplus' => q|$\oplus$|, # circled plus = direct sum
- 'otimes' => q|$\otimes$|, # circled times = vector product
- 'perp' => q|$\perp$|, # up tack = orthogonal to = perpendicular
- 'sdot' => q|$\cdot$|, # dot operator
- # dot operator is NOT the same character as middle dot
-
- # Miscellaneous Technical
- 'lceil' => q|$\lceil$|, # left ceiling = apl upstile
- 'rceil' => q|$\rceil$|, # right ceiling
- 'lfloor' => q|$\lfloor$|, # left floor = apl downstile
- 'rfloor' => q|$\rfloor$|, # right floor
- 'lang' => q|$\langle$|, # left-pointing angle bracket = bra
- # lang is NOT the same character as 'less than' or 'single left-pointing
- # angle quotation mark'
- 'rang' => q|$\rangle$|, # right-pointing angle bracket = ket
- # rang is NOT the same character as 'greater than' or 'single
- # right-pointing angle quotation mark'
-
- # Geometric Shapes
- 'loz' => q|$\lozenge$|, # lozenge
-
- # Miscellaneous Symbols
- 'spades' => q|$\spadesuit$|, # black spade suit
- 'clubs' => q|$\clubsuit$|, # black club suit = shamrock
- 'hearts' => q|$\heartsuit$|, # black heart suit = valentine
- 'diams' => q|$\diamondsuit$|, # black diamond suit
-
- # C0 Controls and Basic Latin
- 'quot' => q|"|, # quotation mark = APL quote ["]
- 'amp' => q|\&|, # ampersand
- 'lt' => q|<|, # less-than sign
- 'gt' => q|>|, # greater-than sign
- 'OElig' => q|\OE{}|, # latin capital ligature OE
- 'oelig' => q|\oe{}|, # latin small ligature oe
- 'Scaron' => q|\v{S}|, # latin capital letter S with caron
- 'scaron' => q|\v{s}|, # latin small letter s with caron
- 'Yuml' => q|\"Y|, # latin capital letter Y with diaeresis
- 'circ' => q|\textasciicircum{}|, # modifier letter circumflex accent
- 'tilde' => q|\textasciitilde{}|, # small tilde
- 'ensp' => q|\phantom{n}|, # en space
- 'emsp' => q|\hspace{1em}|, # em space
- 'thinsp' => q|\,|, # thin space
- 'zwnj' => q|{}|, # zero width non-joiner
-# 'zwj' => q||, # zero width joiner
-# 'lrm' => q||, # left-to-right mark
-# 'rlm' => q||, # right-to-left mark
- 'ndash' => q|--|, # en dash
- 'mdash' => q|---|, # em dash
- 'lsquo' => q|\textquoteleft{}|, # left single quotation mark
- 'rsquo' => q|\textquoteright{}|, # right single quotation mark
- 'sbquo' => q|\quotesinglbase{}|, # single low-9 quotation mark
- 'ldquo' => q|\textquotedblleft{}|, # left double quotation mark
- 'rdquo' => q|\textquotedblright{}|, # right double quotation mark
- 'bdquo' => q|\quotedblbase{}|, # double low-9 quotation mark
- 'dagger' => q|\textdagger{}|, # dagger
- 'Dagger' => q|\textdaggerdbl{}|, # double dagger
- 'permil' => q|\textperthousand{}|, # per mille sign
- 'lsaquo' => q|\guilsinglleft{}|, # single left-pointing angle quotation mark
- 'rsaquo' => q|\guilsinglright{}|, # single right-pointing angle quotation mark
- 'euro' => q|\texteuro{}|, # euro sign
-);
-
-=head1 OBJECT METHODS
-
-The following methods are provided in this module. Methods inherited
-from C<Pod::Select> are not described in the public interface.
-
-=over 4
-
-=begin __PRIVATE__
-
-=item C<initialize>
-
-Initialise the object. This method is subclassed from C<Pod::Parser>.
-The base class method is invoked. This method defines the default
-behaviour of the object unless overridden by supplying arguments to
-the constructor.
-
-Internal settings are defaulted as well as the public instance data.
-Internal hash values are accessed directly (rather than through
-a method) and start with an underscore.
-
-This method should not be invoked by the user directly.
-
-=end __PRIVATE__
-
-=cut
-
-
-
-# - An array for nested lists
-
-# Arguments have already been read by this point
-
-sub initialize {
- my $self = shift;
-
- # print Dumper($self);
-
- # Internals
- $self->{_Lists} = []; # For nested lists
- $self->{_suppress_all_para} = 0; # For =begin blocks
- $self->{_dont_modify_any_para}=0; # For =begin blocks
- $self->{_CURRENT_HEAD1} = ''; # Name of current HEAD1 section
-
- # Options - only initialise if not already set
-
- # Cause the '=head1 NAME' field to be treated specially
- # The contents of the NAME paragraph will be converted
- # to a section title. All subsequent =head1 will be converted
- # to =head2 and down. Will not affect =head1's prior to NAME
- # Assumes: 'Module - purpose' format
- # Also creates a purpose field
- # The name is used for Labeling of the subsequent subsections
- $self->{ReplaceNAMEwithSection} = 0
- unless exists $self->{ReplaceNAMEwithSection};
- $self->{AddPreamble} = 1 # make full latex document
- unless exists $self->{AddPreamble};
- $self->{StartWithNewPage} = 0 # Start new page for pod section
- unless exists $self->{StartWithNewPage};
- $self->{TableOfContents} = 0 # Add table of contents
- unless exists $self->{TableOfContents}; # only relevant if AddPreamble=1
- $self->{AddPostamble} = 1 # Add closing latex code at end
- unless exists $self->{AddPostamble}; # effectively end{document} and index
- $self->{MakeIndex} = 1 # Add index (only relevant AddPostamble
- unless exists $self->{MakeIndex}; # and AddPreamble)
-
- $self->{UniqueLabels} = 1 # Use label unique for each pod
- unless exists $self->{UniqueLabels}; # either based on the filename
- # or supplied
-
- # Control the level of =head1. default is \section
- #
- $self->{Head1Level} = 1 # Offset in latex sections
- unless exists $self->{Head1Level}; # 0 is chapter, 2 is subsection
-
- # Control at which level numbering of sections is turned off
- # ie subsection becomes subsection*
- # The numbering is relative to the latex sectioning commands
- # and is independent of Pod heading level
- # default is to number \section but not \subsection
- $self->{LevelNoNum} = 2
- unless exists $self->{LevelNoNum};
-
- # Label to be used as prefix to all internal section names
- # If not defined will attempt to derive it from the filename
- # This can not happen when running parse_from_filehandle though
- # hence the ability to set the label externally
- # The label could then be Pod::Parser_DESCRIPTION or somesuch
-
- $self->{Label} = undef # label to be used as prefix
- unless exists $self->{Label}; # to all internal section names
-
- # These allow the caller to add arbitrary latex code to
- # start and end of document. AddPreamble and AddPostamble are ignored
- # if these are set.
- # Also MakeIndex and TableOfContents are also ignored.
- $self->{UserPreamble} = undef # User supplied start (AddPreamble =1)
- unless exists $self->{Label};
- $self->{UserPostamble} = undef # Use supplied end (AddPostamble=1)
- unless exists $self->{Label};
-
- # Run base initialize
- $self->SUPER::initialize;
-
-}
-
-=back
-
-=head2 Data Accessors
-
-The following methods are provided for accessing instance data. These
-methods should be used for accessing configuration parameters rather
-than assuming the object is a hash.
-
-Default values can be supplied by using these names as keys to a hash
-of arguments when using the C<new()> constructor.
-
-=over 4
-
-=item B<AddPreamble>
-
-Logical to control whether a C<latex> preamble is to be written.
-If true, a valid C<latex> preamble is written before the pod data is written.
-This is similar to:
-
- \documentclass{article}
- \usepackage[T1]{fontenc}
- \usepackage{textcomp}
- \begin{document}
-
-but will be more complicated if table of contents and indexing are required.
-Can be used to set or retrieve the current value.
-
- $add = $parser->AddPreamble();
- $parser->AddPreamble(1);
-
-If used in conjunction with C<AddPostamble> a full latex document will
-be written that could be immediately processed by C<latex>.
-
-For some pod escapes it may be necessary to include the amsmath
-package. This is not yet added to the preamble automatically.
-
-=cut
-
-sub AddPreamble {
- my $self = shift;
- if (@_) {
- $self->{AddPreamble} = shift;
- }
- return $self->{AddPreamble};
-}
-
-=item B<AddPostamble>
-
-Logical to control whether a standard C<latex> ending is written to the output
-file after the document has been processed.
-In its simplest form this is simply:
-
- \end{document}
-
-but can be more complicated if a index is required.
-Can be used to set or retrieve the current value.
-
- $add = $parser->AddPostamble();
- $parser->AddPostamble(1);
-
-If used in conjunction with C<AddPreaamble> a full latex document will
-be written that could be immediately processed by C<latex>.
-
-=cut
-
-sub AddPostamble {
- my $self = shift;
- if (@_) {
- $self->{AddPostamble} = shift;
- }
- return $self->{AddPostamble};
-}
-
-=item B<Head1Level>
-
-The C<latex> sectioning level that should be used to correspond to
-a pod C<=head1> directive. This can be used, for example, to turn
-a C<=head1> into a C<latex> C<subsection>. This should hold a number
-corresponding to the required position in an array containing the
-following elements:
-
- [0] chapter
- [1] section
- [2] subsection
- [3] subsubsection
- [4] paragraph
- [5] subparagraph
-
-Can be used to set or retrieve the current value:
-
- $parser->Head1Level(2);
- $sect = $parser->Head1Level;
-
-Setting this number too high can result in sections that may not be reproducible
-in the expected way. For example, setting this to 4 would imply that C<=head3>
-do not have a corresponding C<latex> section (C<=head1> would correspond to
-a C<paragraph>).
-
-A check is made to ensure that the supplied value is an integer in the
-range 0 to 5.
-
-Default is for a value of 1 (i.e. a C<section>).
-
-=cut
-
-sub Head1Level {
- my $self = shift;
- if (@_) {
- my $arg = shift;
- if ($arg =~ /^\d$/ && $arg <= $#LatexSections) {
- $self->{Head1Level} = $arg;
- } else {
- carp "Head1Level supplied ($arg) must be integer in range 0 to ".$#LatexSections . "- Ignoring\n";
- }
- }
- return $self->{Head1Level};
-}
-
-=item B<Label>
-
-This is the label that is prefixed to all C<latex> label and index
-entries to make them unique. In general, pods have similarly titled
-sections (NAME, DESCRIPTION etc) and a C<latex> label will be multiply
-defined if more than one pod document is to be included in a single
-C<latex> file. To overcome this, this label is prefixed to a label
-whenever a label is required (joined with an underscore) or to an
-index entry (joined by an exclamation mark which is the normal index
-separator). For example, C<\label{text}> becomes C<\label{Label_text}>.
-
-Can be used to set or retrieve the current value:
-
- $label = $parser->Label;
- $parser->Label($label);
-
-This label is only used if C<UniqueLabels> is true.
-Its value is set automatically from the C<NAME> field
-if C<ReplaceNAMEwithSection> is true. If this is not the case
-it must be set manually before starting the parse.
-
-Default value is C<undef>.
-
-=cut
-
-sub Label {
- my $self = shift;
- if (@_) {
- $self->{Label} = shift;
- }
- return $self->{Label};
-}
-
-=item B<LevelNoNum>
-
-Control the point at which C<latex> section numbering is turned off.
-For example, this can be used to make sure that C<latex> sections
-are numbered but subsections are not.
-
-Can be used to set or retrieve the current value:
-
- $lev = $parser->LevelNoNum;
- $parser->LevelNoNum(2);
-
-The argument must be an integer between 0 and 5 and is the same as the
-number described in C<Head1Level> method description. The number has
-nothing to do with the pod heading number, only the C<latex> sectioning.
-
-Default is 2. (i.e. C<latex> subsections are written as C<subsection*>
-but sections are numbered).
-
-=cut
-
-sub LevelNoNum {
- my $self = shift;
- if (@_) {
- $self->{LevelNoNum} = shift;
- }
- return $self->{LevelNoNum};
-}
-
-=item B<MakeIndex>
-
-Controls whether C<latex> commands for creating an index are to be inserted
-into the preamble and postamble
-
- $makeindex = $parser->MakeIndex;
- $parser->MakeIndex(0);
-
-Irrelevant if both C<AddPreamble> and C<AddPostamble> are false (or equivalently,
-C<UserPreamble> and C<UserPostamble> are set).
-
-Default is for an index to be created.
-
-=cut
-
-sub MakeIndex {
- my $self = shift;
- if (@_) {
- $self->{MakeIndex} = shift;
- }
- return $self->{MakeIndex};
-}
-
-=item B<ReplaceNAMEwithSection>
-
-This controls whether the C<NAME> section in the pod is to be translated
-literally or converted to a slightly modified output where the section
-name is the pod name rather than "NAME".
-
-If true, the pod segment
-
- =head1 NAME
-
- pod::name - purpose
-
- =head1 SYNOPSIS
-
-is converted to the C<latex>
-
- \section{pod::name\label{pod_name}\index{pod::name}}
-
- Purpose
-
- \subsection*{SYNOPSIS\label{pod_name_SYNOPSIS}%
- \index{pod::name!SYNOPSIS}}
-
-(dependent on the value of C<Head1Level> and C<LevelNoNum>). Note that
-subsequent C<head1> directives translate to subsections rather than
-sections and that the labels and index now include the pod name (dependent
-on the value of C<UniqueLabels>).
-
-The C<Label> is set from the pod name regardless of any current value
-of C<Label>.
-
- $mod = $parser->ReplaceNAMEwithSection;
- $parser->ReplaceNAMEwithSection(0);
-
-Default is to translate the pod literally.
-
-=cut
-
-sub ReplaceNAMEwithSection {
- my $self = shift;
- if (@_) {
- $self->{ReplaceNAMEwithSection} = shift;
- }
- return $self->{ReplaceNAMEwithSection};
-}
-
-=item B<StartWithNewPage>
-
-If true, each pod translation will begin with a C<latex>
-C<\clearpage>.
-
- $parser->StartWithNewPage(1);
- $newpage = $parser->StartWithNewPage;
-
-Default is false.
-
-=cut
-
-sub StartWithNewPage {
- my $self = shift;
- if (@_) {
- $self->{StartWithNewPage} = shift;
- }
- return $self->{StartWithNewPage};
-}
-
-=item B<TableOfContents>
-
-If true, a table of contents will be created.
-Irrelevant if C<AddPreamble> is false or C<UserPreamble>
-is set.
-
- $toc = $parser->TableOfContents;
- $parser->TableOfContents(1);
-
-Default is false.
-
-=cut
-
-sub TableOfContents {
- my $self = shift;
- if (@_) {
- $self->{TableOfContents} = shift;
- }
- return $self->{TableOfContents};
-}
-
-=item B<UniqueLabels>
-
-If true, the translator will attempt to make sure that
-each C<latex> label or index entry will be uniquely identified
-by prefixing the contents of C<Label>. This allows
-multiple documents to be combined without clashing
-common labels such as C<DESCRIPTION> and C<SYNOPSIS>
-
- $parser->UniqueLabels(1);
- $unq = $parser->UniqueLabels;
-
-Default is true.
-
-=cut
-
-sub UniqueLabels {
- my $self = shift;
- if (@_) {
- $self->{UniqueLabels} = shift;
- }
- return $self->{UniqueLabels};
-}
-
-=item B<UserPreamble>
-
-User supplied C<latex> preamble. Added before the pod translation
-data.
-
-If set, the contents will be prepended to the output file before the translated
-data regardless of the value of C<AddPreamble>.
-C<MakeIndex> and C<TableOfContents> will also be ignored.
-
-=cut
-
-sub UserPreamble {
- my $self = shift;
- if (@_) {
- $self->{UserPreamble} = shift;
- }
- return $self->{UserPreamble};
-}
-
-=item B<UserPostamble>
-
-User supplied C<latex> postamble. Added after the pod translation
-data.
-
-If set, the contents will be prepended to the output file after the translated
-data regardless of the value of C<AddPostamble>.
-C<MakeIndex> will also be ignored.
-
-=cut
-
-sub UserPostamble {
- my $self = shift;
- if (@_) {
- $self->{UserPostamble} = shift;
- }
- return $self->{UserPostamble};
-}
-
-=begin __PRIVATE__
-
-=item B<Lists>
-
-Contains details of the currently active lists.
- The array contains C<Pod::List> objects. A new C<Pod::List>
-object is created each time a list is encountered and it is
-pushed onto this stack. When the list context ends, it
-is popped from the stack. The array will be empty if no
-lists are active.
-
-Returns array of list information in list context
-Returns array ref in scalar context
-
-=cut
-
-
-
-sub lists {
- my $self = shift;
- return @{ $self->{_Lists} } if wantarray();
- return $self->{_Lists};
-}
-
-=end __PRIVATE__
-
-=back
-
-=begin __PRIVATE__
-
-=head2 Subclassed methods
-
-The following methods override methods provided in the C<Pod::Select>
-base class. See C<Pod::Parser> and C<Pod::Select> for more information
-on what these methods require.
-
-=over 4
-
-=cut
-
-######### END ACCESSORS ###################
-
-# Opening pod
-
-=item B<begin_pod>
-
-Writes the C<latex> preamble if requested. Only writes something
-if AddPreamble is true. Writes a standard header unless a UserPreamble
-is defined.
-
-=cut
-
-sub begin_pod {
- my $self = shift;
-
- # Get the pod identification
- # This should really come from the '=head1 NAME' paragraph
-
- my $infile = $self->input_file;
- my $class = ref($self);
- my $date = gmtime(time);
-
- # Comment message to say where this came from
- my $comment = << "__TEX_COMMENT__";
-%% Latex generated from POD in document $infile
-%% Using the perl module $class
-%% Converted on $date
-__TEX_COMMENT__
-
- # Write the preamble
- # If the caller has supplied one then we just use that
-
- my $preamble = '';
-
- if ($self->AddPreamble) {
-
- if (defined $self->UserPreamble) {
-
- $preamble = $self->UserPreamble;
-
- # Add the description of where this came from
- $preamble .= "\n$comment\n%% Preamble supplied by user.\n\n";
-
- } else {
-
- # Write our own preamble
-
- # Code to initialise index making
- # Use an array so that we can prepend comment if required
- my @makeidx = (
- '\usepackage{makeidx}',
- '\makeindex',
- );
-
- unless ($self->MakeIndex) {
- foreach (@makeidx) {
- $_ = '%% ' . $_;
- }
- }
- my $makeindex = join("\n",@makeidx) . "\n";
-
- # Table of contents
- my $tableofcontents = '\tableofcontents';
-
- $tableofcontents = '%% ' . $tableofcontents
- unless $self->TableOfContents;
-
- # Roll our own
- $preamble = << "__TEX_HEADER__";
-\\documentclass{article}
-\\usepackage[T1]{fontenc}
-\\usepackage{textcomp}
-
-$comment
-
-$makeindex
-
-\\begin{document}
-
-$tableofcontents
-
-__TEX_HEADER__
-
- }
- }
-
- # Write the header (blank if none)
- $self->_output($preamble);
-
- # Start on new page if requested
- $self->_output("\\clearpage\n") if $self->StartWithNewPage;
-
-}
-
-
-=item B<end_pod>
-
-Write the closing C<latex> code. Only writes something if AddPostamble
-is true. Writes a standard header unless a UserPostamble is defined.
-
-=cut
-
-sub end_pod {
- my $self = shift;
-
- # End string
- my $end = '';
-
- # Use the user version of the postamble if defined
- if ($self->AddPostamble) {
-
- if (defined $self->UserPostamble) {
- $end = $self->UserPostamble;
-
- } else {
-
- # Check for index
- my $makeindex = '\printindex';
-
- $makeindex = '%% '. $makeindex unless $self->MakeIndex;
-
- $end = "$makeindex\n\n\\end{document}\n";
- }
- }
-
- $self->_output($end);
-
-}
-
-=item B<command>
-
-Process basic pod commands.
-
-=cut
-
-sub command {
- my $self = shift;
- my ($command, $paragraph, $line_num, $parobj) = @_;
-
- # return if we dont care
- return if $command eq 'pod';
-
- # Store a copy of the raw text in case we are in a =for
- # block and need to preserve the existing latex
- my $rawpara = $paragraph;
-
- # Do the latex escapes
- $paragraph = $self->_replace_special_chars($paragraph);
-
- # Interpolate pod sequences in paragraph
- $paragraph = $self->interpolate($paragraph, $line_num);
- $paragraph =~ s/\s+$//;
-
- # Replace characters that can only be done after
- # interpolation of interior sequences
- $paragraph = $self->_replace_special_chars_late($paragraph);
-
- # Now run the command
- if ($command eq 'over') {
-
- $self->begin_list($paragraph, $line_num);
-
- } elsif ($command eq 'item') {
-
- $self->add_item($paragraph, $line_num);
-
- } elsif ($command eq 'back') {
-
- $self->end_list($line_num);
-
- } elsif ($command eq 'head1') {
-
- # Store the name of the section
- $self->{_CURRENT_HEAD1} = $paragraph;
-
- # Print it
- $self->head(1, $paragraph, $parobj);
-
- } elsif ($command eq 'head2') {
-
- $self->head(2, $paragraph, $parobj);
-
- } elsif ($command eq 'head3') {
-
- $self->head(3, $paragraph, $parobj);
-
- } elsif ($command eq 'head4') {
-
- $self->head(4, $paragraph, $parobj);
-
- } elsif ($command eq 'head5') {
-
- $self->head(5, $paragraph, $parobj);
-
- } elsif ($command eq 'head6') {
-
- $self->head(6, $paragraph, $parobj);
-
- } elsif ($command eq 'begin') {
-
- # pass through if latex
- if ($paragraph =~ /^latex/i) {
- # Make sure that subsequent paragraphs are not modfied before printing
- $self->{_dont_modify_any_para} = 1;
-
- } else {
- # Suppress all subsequent paragraphs unless
- # it is explicitly intended for latex
- $self->{_suppress_all_para} = 1;
- }
-
- } elsif ($command eq 'for') {
-
- # =for latex
- # some latex
-
- # With =for we will get the text for the full paragraph
- # as well as the format name.
- # We do not get an additional paragraph later on. The next
- # paragraph is not governed by the =for
-
- # The first line contains the format and the rest is the
- # raw code.
- my ($format, $chunk) = split(/\n/, $rawpara, 2);
-
- # If we have got some latex code print it out immediately
- # unmodified. Else do nothing.
- if ($format =~ /^latex/i) {
- # Make sure that next paragraph is not modfied before printing
- $self->_output( $chunk );
-
- }
-
- } elsif ($command eq 'end') {
-
- # Reset suppression
- $self->{_suppress_all_para} = 0;
- $self->{_dont_modify_any_para} = 0;
-
- } elsif ($command eq 'pod') {
-
- # Do nothing
-
- } else {
- carp "Command $command not recognised at line $line_num\n";
- }
-
-}
-
-=item B<verbatim>
-
-Verbatim text
-
-=cut
-
-sub verbatim {
- my $self = shift;
- my ($paragraph, $line_num, $parobj) = @_;
-
- # Expand paragraph unless in =begin block
- if ($self->{_dont_modify_any_para}) {
- # Just print as is
- $self->_output($paragraph);
-
- } else {
-
- return if $paragraph =~ /^\s+$/;
-
- # Clean trailing space
- $paragraph =~ s/\s+$//;
-
- # Clean tabs. Routine taken from Tabs.pm
- # by David Muir Sharnoff muir@idiom.com,
- # slightly modified by hsmyers@sdragons.com 10/22/01
- my @l = split("\n",$paragraph);
- foreach (@l) {
- 1 while s/(^|\n)([^\t\n]*)(\t+)/
- $1. $2 . (" " x
- (8 * length($3)
- - (length($2) % 8)))
- /sex;
- }
- $paragraph = join("\n",@l);
- # End of change.
-
-
-
- $self->_output('\begin{verbatim}' . "\n$paragraph\n". '\end{verbatim}'."\n");
- }
-}
-
-=item B<textblock>
-
-Plain text paragraph.
-
-=cut
-
-sub textblock {
- my $self = shift;
- my ($paragraph, $line_num, $parobj) = @_;
-
- # print Dumper($self);
-
- # Expand paragraph unless in =begin block
- if ($self->{_dont_modify_any_para}) {
- # Just print as is
- $self->_output($paragraph);
-
- return;
- }
-
-
- # Escape latex special characters
- $paragraph = $self->_replace_special_chars($paragraph);
-
- # Interpolate interior sequences
- my $expansion = $self->interpolate($paragraph, $line_num);
- $expansion =~ s/\s+$//;
-
- # Escape special characters that can not be done earlier
- $expansion = $self->_replace_special_chars_late($expansion);
-
- # If we are replacing 'head1 NAME' with a section
- # we need to look in the paragraph and rewrite things
- # Need to make sure this is called only on the first paragraph
- # following 'head1 NAME' and not on subsequent paragraphs that may be
- # present.
- if ($self->{_CURRENT_HEAD1} =~ /^NAME/i && $self->ReplaceNAMEwithSection()) {
-
- # Strip white space from start and end
- $paragraph =~ s/^\s+//;
- $paragraph =~ s/\s$//;
-
- # Split the string into 2 parts
- my ($name, $purpose) = split(/\s+-\s+/, $expansion,2);
-
- # Now prevent this from triggering until a new head1 NAME is set
- $self->{_CURRENT_HEAD1} = '_NAME';
-
- # Might want to clear the Label() before doing this (CHECK)
-
- # Print the heading
- $self->head(1, $name, $parobj);
-
- # Set the labeling in case we want unique names later
- $self->Label( $self->_create_label( $name, 1 ) );
-
- # Raise the Head1Level by one so that subsequent =head1 appear
- # as subsections of the main name section unless we are already
- # at maximum [Head1Level() could check this itself - CHECK]
- $self->Head1Level( $self->Head1Level() + 1)
- unless $self->Head1Level == $#LatexSections;
-
- # Now write out the new latex paragraph
- $purpose = ucfirst($purpose);
- $self->_output("\n\n$purpose\n\n");
-
- } else {
- # Just write the output
- $self->_output("\n\n$expansion\n\n");
- }
-
-}
-
-=item B<interior_sequence>
-
-Interior sequence expansion
-
-=cut
-
-sub interior_sequence {
- my $self = shift;
-
- my ($seq_command, $seq_argument, $pod_seq) = @_;
-
- if ($seq_command eq 'B') {
- return "\\textbf{$seq_argument}";
-
- } elsif ($seq_command eq 'I') {
- return "\\textit{$seq_argument}";
-
- } elsif ($seq_command eq 'E') {
-
- # If it is simply a number
- if ($seq_argument =~ /^\d+$/) {
- return chr($seq_argument);
- # Look up escape in hash table
- } elsif (exists $HTML_Escapes{$seq_argument}) {
- return $HTML_Escapes{$seq_argument};
-
- } else {
- my ($file, $line) = $pod_seq->file_line();
- warn "Escape sequence $seq_argument not recognised at line $line of file $file\n";
- return;
- }
-
- } elsif ($seq_command eq 'Z') {
-
- # Zero width space
- return '{}';
-
- } elsif ($seq_command eq 'C') {
- return "\\texttt{$seq_argument}";
-
- } elsif ($seq_command eq 'F') {
- return "\\emph{$seq_argument}";
-
- } elsif ($seq_command eq 'S') {
- # non breakable spaces
- my $nbsp = '~';
-
- $seq_argument =~ s/\s/$nbsp/g;
- return $seq_argument;
-
- } elsif ($seq_command eq 'L') {
- my $link = new Pod::Hyperlink($seq_argument);
-
- # undef on failure
- unless (defined $link) {
- carp $@;
- return;
- }
-
- # Handle internal links differently
- my $type = $link->type;
- my $page = $link->page;
-
- if ($type eq 'section' && $page eq '') {
- # Use internal latex reference
- my $node = $link->node;
-
- # Convert to a label
- $node = $self->_create_label($node);
-
- return "\\S\\ref{$node}";
-
- } else {
- # Use default markup for external references
- # (although Starlink would use \xlabel)
- my $markup = $link->markup;
- my ($file, $line) = $pod_seq->file_line();
-
- return $self->interpolate($link->markup, $line);
- }
-
-
-
- } elsif ($seq_command eq 'P') {
- # Special markup for Pod::Hyperlink
- # Replace :: with / - but not sure if I want to do this
- # any more.
- my $link = $seq_argument;
- $link =~ s|::|/|g;
-
- my $ref = "\\emph{$seq_argument}";
- return $ref;
-
- } elsif ($seq_command eq 'Q') {
- # Special markup for Pod::Hyperlink
- return "\\textsf{$seq_argument}";
-
- } elsif ($seq_command eq 'X') {
- # Index entries
-
- # use \index command
- # I will let '!' go through for now
- # not sure how sub categories are handled in X<>
- my $index = $self->_create_index($seq_argument);
- return "\\index{$index}\n";
-
- } else {
- carp "Unknown sequence $seq_command<$seq_argument>";
- }
-
-}
-
-=back
-
-=head2 List Methods
-
-Methods used to handle lists.
-
-=over 4
-
-=item B<begin_list>
-
-Called when a new list is found (via the C<over> directive).
-Creates a new C<Pod::List> object and stores it on the
-list stack.
-
- $parser->begin_list($indent, $line_num);
-
-=cut
-
-sub begin_list {
- my $self = shift;
- my $indent = shift;
- my $line_num = shift;
-
- # Indicate that a list should be started for the next item
- # need to do this to work out the type of list
- push ( @{$self->lists}, new Pod::List(-indent => $indent,
- -start => $line_num,
- -file => $self->input_file,
- )
- );
-
-}
-
-=item B<end_list>
-
-Called when the end of a list is found (the C<back> directive).
-Pops the C<Pod::List> object off the stack of lists and writes
-the C<latex> code required to close a list.
-
- $parser->end_list($line_num);
-
-=cut
-
-sub end_list {
- my $self = shift;
- my $line_num = shift;
-
- unless (defined $self->lists->[-1]) {
- my $file = $self->input_file;
- warn "No list is active at line $line_num (file=$file). Missing =over?\n";
- return;
- }
-
- # What to write depends on list type
- my $type = $self->lists->[-1]->type;
-
- # Don't write anything if the list type is not set
- # iomplying that a list was created but no entries were
- # placed in it (eg because of a =begin/=end combination)
- $self->_output("\\end{$type}\n")
- if (defined $type && length($type) > 0);
-
- # Clear list
- pop(@{ $self->lists});
-
-}
-
-=item B<add_item>
-
-Add items to the list. The first time an item is encountered
-(determined from the state of the current C<Pod::List> object)
-the type of list is determined (ordered, unnumbered or description)
-and the relevant latex code issued.
-
- $parser->add_item($paragraph, $line_num);
-
-=cut
-
-sub add_item {
- my $self = shift;
- my $paragraph = shift;
- my $line_num = shift;
-
- unless (defined $self->lists->[-1]) {
- my $file = $self->input_file;
- warn "List has already ended by line $line_num of file $file. Missing =over?\n";
- # Replace special chars
-# $paragraph = $self->_replace_special_chars($paragraph);
- $self->_output("$paragraph\n\n");
- return;
- }
-
- # If paragraphs printing is turned off via =begin/=end or whatever
- # simply return immediately
- return if $self->{_suppress_all_para};
-
- # Check to see whether we are starting a new lists
- if (scalar($self->lists->[-1]->item) == 0) {
-
- # Examine the paragraph to determine what type of list
- # we have
- $paragraph =~ s/\s+$//;
- $paragraph =~ s/^\s+//;
-
- my $type;
- if (substr($paragraph, 0,1) eq '*') {
- $type = 'itemize';
- } elsif ($paragraph =~ /^\d/) {
- $type = 'enumerate';
- } else {
- $type = 'description';
- }
- $self->lists->[-1]->type($type);
-
- $self->_output("\\begin{$type}\n");
-
- }
-
- my $type = $self->lists->[-1]->type;
-
- if ($type eq 'description') {
- # Handle long items - long items do not wrap
- # If the string is longer than 40 characters we split
- # it into a real item header and some bold text.
- my $maxlen = 40;
- my ($hunk1, $hunk2) = $self->_split_delimited( $paragraph, $maxlen );
-
- # Print the first hunk
- $self->_output("\n\\item[{$hunk1}] ");
-
- # and the second hunk if it is defined
- if ($hunk2) {
- $self->_output("\\textbf{$hunk2}");
- } else {
- # Not there so make sure we have a new line
- $self->_output("\\mbox{}");
- }
-
- } else {
- # If the item was '* Something' or '\d+ something' we still need to write
- # out the something. Also allow 1) and 1.
- my $extra_info = $paragraph;
- $extra_info =~ s/^(\*|\d+[\.\)]?)\s*//;
- $self->_output("\n\\item $extra_info");
- }
-
- # Store the item name in the object. Required so that
- # we can tell if the list is new or not
- $self->lists->[-1]->item($paragraph);
-
-}
-
-=back
-
-=head2 Methods for headings
-
-=over 4
-
-=item B<head>
-
-Print a heading of the required level.
-
- $parser->head($level, $paragraph, $parobj);
-
-The first argument is the pod heading level. The second argument
-is the contents of the heading. The 3rd argument is a Pod::Paragraph
-object so that the line number can be extracted.
-
-=cut
-
-sub head {
- my $self = shift;
- my $num = shift;
- my $paragraph = shift;
- my $parobj = shift;
-
- # If we are replace 'head1 NAME' with a section
- # we return immediately if we get it
- return
- if ($self->{_CURRENT_HEAD1} =~ /^NAME/i && $self->ReplaceNAMEwithSection());
-
- # Create a label
- my $label = $self->_create_label($paragraph);
-
- # Create an index entry
- my $index = $self->_create_index($paragraph);
-
- # Work out position in the above array taking into account
- # that =head1 is equivalent to $self->Head1Level
-
- my $level = $self->Head1Level() - 1 + $num;
-
- # Warn if heading to large
- if ($num > $#LatexSections) {
- my $line = $parobj->file_line;
- my $file = $self->input_file;
- warn "Heading level too large ($level) for LaTeX at line $line of file $file\n";
- $level = $#LatexSections;
- }
-
- # Check to see whether section should be unnumbered
- my $star = ($level >= $self->LevelNoNum ? '*' : '');
-
- # Section
- $self->_output("\\" .$LatexSections[$level] .$star ."{$paragraph\\label{".$label ."}\\index{".$index."}}\n");
-
-}
-
-
-=back
-
-=end __PRIVATE__
-
-=begin __PRIVATE__
-
-=head2 Internal methods
-
-Internal routines are described in this section. They do not form part of the
-public interface. All private methods start with an underscore.
-
-=over 4
-
-=item B<_output>
-
-Output text to the output filehandle. This method must be always be called
-to output parsed text.
-
- $parser->_output($text);
-
-Does not write anything if a =begin is active that should be
-ignored.
-
-=cut
-
-sub _output {
- my $self = shift;
- my $text = shift;
-
- print { $self->output_handle } $text
- unless $self->{_suppress_all_para};
-
-}
-
-
-=item B<_replace_special_chars>
-
-Subroutine to replace characters that are special in C<latex>
-with the escaped forms
-
- $escaped = $parser->_replace_special_chars($paragraph);
-
-Need to call this routine before interior_sequences are munged but not
-if verbatim. It must be called before interpolation of interior
-sequences so that curly brackets and special latex characters inserted
-during interpolation are not themselves escaped. This means that < and
-> can not be modified here since the text still contains interior
-sequences.
-
-Special characters and the C<latex> equivalents are:
-
- } \}
- { \{
- _ \_
- $ \$
- % \%
- & \&
- \ $\backslash$
- ^ \^{}
- ~ \~{}
- # \#
-
-=cut
-
-sub _replace_special_chars {
- my $self = shift;
- my $paragraph = shift;
-
- # Replace a \ with $\backslash$
- # This is made more complicated because the dollars will be escaped
- # by the subsequent replacement. Easiest to add \backslash
- # now and then add the dollars
- $paragraph =~ s/\\/\\backslash/g;
-
- # Must be done after escape of \ since this command adds latex escapes
- # Replace characters that can be escaped
- $paragraph =~ s/([\$\#&%_{}])/\\$1/g;
-
- # Replace ^ characters with \^{} so that $^F works okay
- $paragraph =~ s/(\^)/\\$1\{\}/g;
-
- # Replace tilde (~) with \texttt{\~{}}
- $paragraph =~ s/~/\\texttt\{\\~\{\}\}/g;
-
- # Now add the dollars around each \backslash
- $paragraph =~ s/(\\backslash)/\$$1\$/g;
-
- # Convert ------ to -{}-{}-{}-{}-{}-
- $paragraph =~ s/-(?=-)/-{}/g;
-
- return $paragraph;
-}
-
-=item B<_replace_special_chars_late>
-
-Replace special characters that can not be replaced before interior
-sequence interpolation. See C<_replace_special_chars> for a routine
-to replace special characters prior to interpolation of interior
-sequences.
-
-Does the following transformation:
-
- < $<$
- > $>$
- | $|$
-
-
-=cut
-
-sub _replace_special_chars_late {
- my $self = shift;
- my $paragraph = shift;
-
- # < and >
- $paragraph =~ s/(<|>)/\$$1\$/g;
-
- # Replace | with $|$
- $paragraph =~ s'\|'$|$'g;
-
-
- return $paragraph;
-}
-
-
-=item B<_create_label>
-
-Return a string that can be used as an internal reference
-in a C<latex> document (i.e. accepted by the C<\label> command)
-
- $label = $parser->_create_label($string)
-
-If UniqueLabels is true returns a label prefixed by Label()
-This can be suppressed with an optional second argument.
-
- $label = $parser->_create_label($string, $suppress);
-
-If a second argument is supplied (of any value including undef)
-the Label() is never prefixed. This means that this routine can
-be called to create a Label() without prefixing a previous setting.
-
-=cut
-
-sub _create_label {
- my $self = shift;
- my $paragraph = shift;
- my $suppress = (@_ ? 1 : 0 );
-
- # Remove latex commands
- $paragraph = $self->_clean_latex_commands($paragraph);
-
- # Remove non alphanumerics from the label and replace with underscores
- # want to protect '-' though so use negated character classes
- $paragraph =~ s/[^-:\w]/_/g;
-
- # Multiple underscores will look unsightly so remove repeats
- # This will also have the advantage of tidying up the end and
- # start of string
- $paragraph =~ s/_+/_/g;
-
- # If required need to make sure that the label is unique
- # since it is possible to have multiple pods in a single
- # document
- if (!$suppress && $self->UniqueLabels() && defined $self->Label) {
- $paragraph = $self->Label() .'_'. $paragraph;
- }
-
- return $paragraph;
-}
-
-
-=item B<_create_index>
-
-Similar to C<_create_label> except an index entry is created.
-If C<UniqueLabels> is true, the index entry is prefixed by
-the current C<Label> and an exclamation mark.
-
- $ind = $parser->_create_index($paragraph);
-
-An exclamation mark is used by C<makeindex> to generate
-sub-entries in an index.
-
-=cut
-
-sub _create_index {
- my $self = shift;
- my $paragraph = shift;
- my $suppress = (@_ ? 1 : 0 );
-
- # Remove latex commands
- $paragraph = $self->_clean_latex_commands($paragraph);
-
- # If required need to make sure that the index entry is unique
- # since it is possible to have multiple pods in a single
- # document
- if (!$suppress && $self->UniqueLabels() && defined $self->Label) {
- $paragraph = $self->Label() .'!'. $paragraph;
- }
-
- # Need to replace _ with space
- $paragraph =~ s/_/ /g;
-
- return $paragraph;
-
-}
-
-=item B<_clean_latex_commands>
-
-Removes latex commands from text. The latex command is assumed to be of the
-form C<\command{ text }>. "C<text>" is retained
-
- $clean = $parser->_clean_latex_commands($text);
-
-=cut
-
-sub _clean_latex_commands {
- my $self = shift;
- my $paragraph = shift;
-
- # Remove latex commands of the form \text{ }
- # and replace with the contents of the { }
- # need to make this non-greedy so that it can handle
- # "\text{a} and \text2{b}"
- # without converting it to
- # "a} and \text2{b"
- # This match will still get into trouble if \} is present
- # This is not vital since the subsequent replacement of non-alphanumeric
- # characters will tidy it up anyway
- $paragraph =~ s/\\\w+{(.*?)}/$1/g;
-
- return $paragraph
-}
-
-=item B<_split_delimited>
-
-Split the supplied string into two parts at approximately the
-specified word boundary. Special care is made to make sure that it
-does not split in the middle of some curly brackets.
-
-e.g. "this text is \textbf{very bold}" would not be split into
-"this text is \textbf{very" and " bold".
-
- ($hunk1, $hunk2) = $self->_split_delimited( $para, $length);
-
-The length indicates the maximum length of hunk1.
-
-=cut
-
-# initially Supplied by hsmyers@sdragons.com
-# 10/25/01, utility to split \hbox
-# busting lines. Reformatted by TimJ to match module style.
-sub _split_delimited {
- my $self = shift;
- my $input = shift;
- my $limit = shift;
-
- # Return immediately if already small
- return ($input, '') if length($input) < $limit;
-
- my @output;
- my $s = '';
- my $t = '';
- my $depth = 0;
- my $token;
-
- $input =~ s/\n/ /gm;
- $input .= ' ';
- foreach ( split ( //, $input ) ) {
- $token .= $_;
- if (/\{/) {
- $depth++;
- } elsif ( /}/ ) {
- $depth--;
- } elsif ( / / and $depth == 0) {
- push @output, $token if ( $token and $token ne ' ' );
- $token = '';
- }
- }
-
- foreach (@output) {
- if (length($s) < $limit) {
- $s .= $_;
- } else {
- $t .= $_;
- }
- }
-
- # Tidy up
- $s =~ s/\s+$//;
- $t =~ s/\s+$//;
- return ($s,$t);
-}
-
-=back
-
-=end __PRIVATE__
-
-=head1 NOTES
-
-Compatible with C<latex2e> only. Can not be used with C<latex> v2.09
-or earlier.
-
-A subclass of C<Pod::Select> so that specific pod sections can be
-converted to C<latex> by using the C<select> method.
-
-Some HTML escapes are missing and many have not been tested.
-
-=head1 SEE ALSO
-
-L<Pod::Parser>, L<Pod::Select>, L<pod2latex>, L<Pod::Simple>.
-
-=head1 AUTHORS
-
-Tim Jenness E<lt>tjenness@cpan.orgE<gt>
-
-Bug fixes and improvements have been received from: Simon Cozens
-E<lt>simon@cozens.netE<gt>, Mark A. Hershberger
-E<lt>mah@everybody.orgE<gt>, Marcel Grunauer
-E<lt>marcel@codewerk.comE<gt>, Hugh S Myers
-E<lt>hsmyers@sdragons.comE<gt>, Peter J Acklam
-E<lt>jacklam@math.uio.noE<gt>, Sudhi Herle E<lt>sudhi@herle.netE<gt>,
-Ariel Scolnicov E<lt>ariels@compugen.co.ilE<gt>,
-Adriano Rodrigues Ferreira E<lt>ferreira@triang.com.brE<gt>,
-R. de Vries E<lt>r.de.vries@dutchspace.nlE<gt> and
-Dave Mitchell E<lt>davem@iabyn.comE<gt>.
-
-=head1 COPYRIGHT
-
-Copyright (C) 2011 Tim Jenness.
-Copyright (C) 2000-2004 Tim Jenness. All Rights Reserved.
-
-This program is free software; you can redistribute it and/or modify
-it under the same terms as Perl itself.
-
-=begin __PRIVATE__
-
-=head1 REVISION
-
-$Id$
-
-=end __PRIVATE__
-
-=cut
-
-1;
diff --git a/Master/tlpkg/tlperl/lib/Pod/Man.pm b/Master/tlpkg/tlperl/lib/Pod/Man.pm
index 5e5f4dc4de2..72ca9ff1da9 100644
--- a/Master/tlpkg/tlperl/lib/Pod/Man.pm
+++ b/Master/tlpkg/tlperl/lib/Pod/Man.pm
@@ -36,7 +36,7 @@ use Pod::Simple ();
@ISA = qw(Pod::Simple);
-$VERSION = '2.27';
+$VERSION = '2.28';
# Set the debugging level. If someone has inserted a debug function into this
# class already, use that. Otherwise, use any Pod::Simple debug function
@@ -56,6 +56,27 @@ BEGIN { *ASCII = \&Pod::Simple::ASCII }
# Pretty-print a data structure. Only used for debugging.
BEGIN { *pretty = \&Pod::Simple::pretty }
+# Formatting instructions for various types of blocks. cleanup makes hyphens
+# hard, adds spaces between consecutive underscores, and escapes backslashes.
+# convert translates characters into escapes. guesswork means to apply the
+# transformations done by the guesswork sub. literal says to protect literal
+# quotes from being turned into UTF-8 quotes. By default, all transformations
+# are on except literal, but some elements override.
+#
+# DEFAULT specifies the default settings. All other elements should list only
+# those settings that they are overriding. Data indicates =for roff blocks,
+# which should be passed along completely verbatim.
+#
+# Formatting inherits negatively, in the sense that if the parent has turned
+# off guesswork, all child elements should leave it off.
+my %FORMATTING = (
+ DEFAULT => { cleanup => 1, convert => 1, guesswork => 1, literal => 0 },
+ Data => { cleanup => 0, convert => 0, guesswork => 0, literal => 0 },
+ Verbatim => { guesswork => 0, literal => 1 },
+ C => { guesswork => 0, literal => 1 },
+ X => { cleanup => 0, guesswork => 0 },
+);
+
##############################################################################
# Object initialization
##############################################################################
@@ -73,8 +94,8 @@ sub new {
$self->nbsp_for_S (1);
# Tell Pod::Simple to keep whitespace whenever possible.
- if ($self->can ('preserve_whitespace')) {
- $self->preserve_whitespace (1);
+ if (my $preserve_whitespace = $self->can ('preserve_whitespace')) {
+ $self->$preserve_whitespace (1);
} else {
$self->fullstop_space_harden (1);
}
@@ -257,8 +278,7 @@ sub _handle_text {
# Given an element name, get the corresponding method name.
sub method_for_element {
my ($self, $element) = @_;
- $element =~ tr/-/_/;
- $element =~ tr/A-Z/a-z/;
+ $element =~ tr/A-Z-/a-z_/;
$element =~ tr/_a-z0-9//cd;
return $element;
}
@@ -284,13 +304,14 @@ sub _handle_element_start {
# and also depends on our parent tags. Thankfully, inside tags that
# turn off guesswork and reformatting, nothing else can turn it back
# on, so this can be strictly inherited.
- my $formatting = $$self{PENDING}[-1][1];
- $formatting = $self->formatting ($formatting, $element);
+ my $formatting = {
+ %{ $$self{PENDING}[-1][1] || $FORMATTING{DEFAULT} },
+ %{ $FORMATTING{$element} || {} },
+ };
push (@{ $$self{PENDING} }, [ $attrs, $formatting, '' ]);
DEBUG > 4 and print "Pending: [", pretty ($$self{PENDING}), "]\n";
- } elsif ($self->can ("start_$method")) {
- my $method = 'start_' . $method;
- $self->$method ($attrs, '');
+ } elsif (my $start_method = $self->can ("start_$method")) {
+ $self->$start_method ($attrs, '');
} else {
DEBUG > 2 and print "No $method start method, skipping\n";
}
@@ -306,13 +327,12 @@ sub _handle_element_end {
# If we have a command handler, pull off the pending text and pass it to
# the handler along with the saved attribute hash.
- if ($self->can ("cmd_$method")) {
+ if (my $cmd_method = $self->can ("cmd_$method")) {
DEBUG > 2 and print "</$element> stops saving a tag\n";
my $tag = pop @{ $$self{PENDING} };
DEBUG > 4 and print "Popped: [", pretty ($tag), "]\n";
DEBUG > 4 and print "Pending: [", pretty ($$self{PENDING}), "]\n";
- my $method = 'cmd_' . $method;
- my $text = $self->$method ($$tag[0], $$tag[2]);
+ my $text = $self->$cmd_method ($$tag[0], $$tag[2]);
if (defined $text) {
if (@{ $$self{PENDING} } > 1) {
$$self{PENDING}[-1][2] .= $text;
@@ -320,9 +340,8 @@ sub _handle_element_end {
$self->output ($text);
}
}
- } elsif ($self->can ("end_$method")) {
- my $method = 'end_' . $method;
- $self->$method ();
+ } elsif (my $end_method = $self->can ("end_$method")) {
+ $self->$end_method ();
} else {
DEBUG > 2 and print "No $method end method, skipping\n";
}
@@ -332,34 +351,6 @@ sub _handle_element_end {
# General formatting
##############################################################################
-# Return formatting instructions for a new block. Takes the current
-# formatting and the new element. Formatting inherits negatively, in the
-# sense that if the parent has turned off guesswork, all child elements should
-# leave it off. We therefore return a copy of the same formatting
-# instructions but possibly with more things turned off depending on the
-# element.
-sub formatting {
- my ($self, $current, $element) = @_;
- my %options;
- if ($current) {
- %options = %$current;
- } else {
- %options = (guesswork => 1, cleanup => 1, convert => 1);
- }
- if ($element eq 'Data') {
- $options{guesswork} = 0;
- $options{cleanup} = 0;
- $options{convert} = 0;
- } elsif ($element eq 'X') {
- $options{guesswork} = 0;
- $options{cleanup} = 0;
- } elsif ($element eq 'Verbatim' || $element eq 'C') {
- $options{guesswork} = 0;
- $options{literal} = 1;
- }
- return \%options;
-}
-
# Format a text block. Takes a hash of formatting options and the text to
# format. Currently, the only formatting options are guesswork, cleanup, and
# convert, all of which are boolean.
@@ -456,7 +447,7 @@ sub guesswork {
local $_ = shift;
DEBUG > 5 and print " Guesswork called on [$_]\n";
- # By the time we reach this point, all hypens will be escaped by adding a
+ # By the time we reach this point, all hyphens will be escaped by adding a
# backslash. We want to undo that escaping if they're part of regular
# words and there's only a single dash, since that's a real hyphen that
# *roff gets to consider a possible break point. Make sure that a dash
@@ -512,7 +503,7 @@ sub guesswork {
# strings inserted around things that we've made small-caps if later
# transforms should work on those strings.
- # Italize functions in the form func(), including functions that are in
+ # Italicize functions in the form func(), including functions that are in
# all capitals, but don't italize if there's anything between the parens.
# The function must start with an alphabetic character or underscore and
# then consist of word characters or colons.
@@ -767,7 +758,6 @@ sub start_document {
if ($$attrs{contentless} && !$$self{ALWAYS_EMIT_SOMETHING}) {
DEBUG and print "Document is contentless\n";
$$self{CONTENTLESS} = 1;
- return;
} else {
delete $$self{CONTENTLESS};
}
@@ -788,17 +778,20 @@ sub start_document {
}
}
- # Determine information for the preamble and then output it.
- my ($name, $section);
- if (defined $$self{name}) {
- $name = $$self{name};
- $section = $$self{section} || 1;
- } else {
- ($name, $section) = $self->devise_title;
+ # Determine information for the preamble and then output it unless the
+ # document was content-free.
+ if (!$$self{CONTENTLESS}) {
+ my ($name, $section);
+ if (defined $$self{name}) {
+ $name = $$self{name};
+ $section = $$self{section} || 1;
+ } else {
+ ($name, $section) = $self->devise_title;
+ }
+ my $date = $$self{date} || $self->devise_date;
+ $self->preamble ($name, $section, $date)
+ unless $self->bare_output or DEBUG > 9;
}
- my $date = $$self{date} || $self->devise_date;
- $self->preamble ($name, $section, $date)
- unless $self->bare_output or DEBUG > 9;
# Initialize a few per-document variables.
$$self{INDENT} = 0; # Current indentation level.
@@ -988,9 +981,12 @@ 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, but leave "\ " backslashed space from an S< >
- # at the end of a line.
- $text =~ s/((?:\\ )*)\s*$/$1\n/;
+ # whitespace at the end, but leave "\ " backslashed space from an S< > at
+ # the end of a line. Reverse the text first, to avoid having to scan the
+ # entire paragraph.
+ $text = reverse $text;
+ $text =~ s/\A\s*?(?= \\|\S|\z)/\n/;
+ $text = reverse $text;
# Output the paragraph.
$self->output ($self->protect ($self->textmapfonts ($text)));
@@ -1009,8 +1005,11 @@ sub cmd_verbatim {
return unless $text =~ /\S/;
# Force exactly one newline at the end and strip unwanted trailing
- # whitespace at the end.
- $text =~ s/\s*$/\n/;
+ # whitespace at the end. Reverse the text first, to avoid having to scan
+ # the entire paragraph.
+ $text = reverse $text;
+ $text =~ s/\A\s*/\n/;
+ $text = reverse $text;
# Get a count of the number of lines before the first blank line, which
# we'll pass to .Vb as its parameter. This tells *roff to keep that many
@@ -1354,6 +1353,26 @@ sub parse_file {
return $self->SUPER::parse_file ($in);
}
+# Do the same for parse_lines, just to be polite. Pod::Simple's man page
+# implies that the caller is responsible for setting this, but I don't see any
+# reason not to set a default.
+sub parse_lines {
+ my ($self, @lines) = @_;
+ unless (defined $$self{output_fh}) {
+ $self->output_fh (\*STDOUT);
+ }
+ return $self->SUPER::parse_lines (@lines);
+}
+
+# Likewise for parse_string_document.
+sub parse_string_document {
+ my ($self, $doc) = @_;
+ unless (defined $$self{output_fh}) {
+ $self->output_fh (\*STDOUT);
+ }
+ return $self->SUPER::parse_string_document ($doc);
+}
+
##############################################################################
# Translation tables
##############################################################################
@@ -1547,7 +1566,7 @@ __END__
=for stopwords
en em ALLCAPS teeny fixedbold fixeditalic fixedbolditalic stderr utf8
UTF-8 Allbery Sean Burke Ossanna Solaris formatters troff uppercased
-Christiansen nourls
+Christiansen nourls parsers
=head1 NAME
@@ -1621,7 +1640,7 @@ not to throw an exception. C<pod> says to include a POD ERRORS section
in the resulting documentation summarizing the errors. C<none> ignores
POD errors entirely, as much as possible.
-The default is C<output>.
+The default is C<pod>.
=item date
@@ -1746,16 +1765,22 @@ L<perlpod(1)> for more information on the C<=encoding> command.
The standard Pod::Simple method parse_file() takes one argument naming the
POD file to read from. By default, the output is sent to C<STDOUT>, but
-this can be changed with the output_fd() method.
+this can be changed with the output_fh() method.
The standard Pod::Simple method parse_from_file() takes up to two
arguments, the first being the input file to read POD from and the second
being the file to write the formatted output to.
You can also call parse_lines() to parse an array of lines or
-parse_string_document() to parse a document already in memory. To put the
-output into a string instead of a file handle, call the output_string()
-method. See L<Pod::Simple> for the specific details.
+parse_string_document() to parse a document already in memory. As with
+parse_file(), parse_lines() and parse_string_document() default to sending
+their output to C<STDOUT> unless changed with the output_fh() method.
+
+To put the output from any parse method into a string instead of a file
+handle, call the output_string() method instead of output_fh().
+
+See L<Pod::Simple> for more specific details on the methods available to
+all derived parsers.
=head1 DIAGNOSTICS
diff --git a/Master/tlpkg/tlperl/lib/Pod/ParseUtils.pm b/Master/tlpkg/tlperl/lib/Pod/ParseUtils.pm
index e41c6e023bc..e1ff2aeb19b 100644
--- a/Master/tlpkg/tlperl/lib/Pod/ParseUtils.pm
+++ b/Master/tlpkg/tlperl/lib/Pod/ParseUtils.pm
@@ -11,7 +11,7 @@ package Pod::ParseUtils;
use strict;
use vars qw($VERSION);
-$VERSION = '1.60'; ## Current version of this package
+$VERSION = '1.62'; ## Current version of this package
require 5.005; ## requires this Perl version or later
=head1 NAME
@@ -27,6 +27,10 @@ Pod::ParseUtils - helpers for POD parsing and conversion
=head1 DESCRIPTION
+B<NOTE: This module is considered legacy; modern Perl releases (5.18 and
+higher) are going to remove Pod-Parser from core and use L<Pod-Simple>
+for all things POD.>
+
B<Pod::ParseUtils> contains a few object-oriented helper packages for
POD parsing and processing (i.e. in POD formatters and translators).
@@ -311,7 +315,7 @@ sub parse {
# only page
# problem: a lot of people use (), or (1) or the like to indicate
# man page sections. But this collides with L<func()> that is supposed
- # to point to an internal funtion...
+ # to point to an internal function...
my $page_rx = '[\w.-]+(?:::[\w.-]+)*(?:[(](?:\d\w*|)[)]|)';
# page name only
if(/^($page_rx)$/o) {
diff --git a/Master/tlpkg/tlperl/lib/Pod/Parser.pm b/Master/tlpkg/tlperl/lib/Pod/Parser.pm
index 4f9e20abb11..f3a861982ba 100644
--- a/Master/tlpkg/tlperl/lib/Pod/Parser.pm
+++ b/Master/tlpkg/tlperl/lib/Pod/Parser.pm
@@ -12,7 +12,7 @@ use strict;
## These "variables" are used as local "glob aliases" for performance
use vars qw($VERSION @ISA %myData %myOpts @input_stack);
-$VERSION = '1.60'; ## Current version of this package
+$VERSION = '1.62'; ## Current version of this package
require 5.005; ## requires this Perl version or later
#############################################################################
@@ -81,6 +81,10 @@ Nothing.
=head1 DESCRIPTION
+B<NOTE: This module is considered legacy; modern Perl releases (5.18 and
+higher) are going to remove Pod-Parser from core and use L<Pod-Simple>
+for all things POD.>
+
B<Pod::Parser> is a base class for creating POD filters and translators.
It handles most of the effort involved with parsing the POD sections
from an input stream, leaving subclasses free to be concerned only with
@@ -90,10 +94,6 @@ B<Pod::Parser> parses PODs, and makes method calls to handle the various
components of the POD. Subclasses of B<Pod::Parser> override these methods
to translate the POD into whatever output format they desire.
-Note: This module is considered as legacy; modern Perl releases (5.18 and
-higher) are going to remove Pod::Parser from core and use L<Pod::Simple>
-for all things POD.
-
=head1 QUICK OVERVIEW
To create a POD filter for translating POD documentation into some other
@@ -816,7 +816,7 @@ sub parse_text {
}
if (length) {
## In the middle of a sequence, append this text to it, and
- ## dont forget to "expand" it if that's what the caller wanted
+ ## don't forget to "expand" it if that's what the caller wanted
$seq->append($expand_text ? &$xtext_sub($self,$_,$seq) : $_);
$_ .= $seq_end;
}
@@ -840,7 +840,7 @@ sub parse_text {
}
elsif (length) {
## In the middle of a sequence, append this text to it, and
- ## dont forget to "expand" it if that's what the caller wanted
+ ## don't forget to "expand" it if that's what the caller wanted
$seq->append($expand_text ? &$xtext_sub($self,$_,$seq) : $_);
}
## Keep track of line count
@@ -944,12 +944,12 @@ sub parse_paragraph {
## but that is more overhead than I want to incur)
##-----------------------------------------------------------------
- ## Ignore this block if it isnt in one of the selected sections
+ ## Ignore this block if it isn't in one of the selected sections
if (exists $myData{_SELECTED_SECTIONS}) {
$self->is_selected($text) or return ($myData{_CUTTING} = 1);
}
- ## If we havent already, perform any desired preprocessing and
+ ## If we haven't already, perform any desired preprocessing and
## then re-check the "cutting" state
unless ($wantNonPods) {
$text = $self->preprocess_paragraph($text, $line_num);
@@ -969,7 +969,7 @@ sub parse_paragraph {
($cmd, $sep, $text) = split /(\s+)/, $_, 2;
$sep = '' unless defined $sep;
$text = '' unless defined $text;
- ## If this is a "cut" directive then we dont need to do anything
+ ## If this is a "cut" directive then we don't need to do anything
## except return to "cutting" mode.
if ($cmd eq 'cut') {
$myData{_CUTTING} = 1;
@@ -1102,7 +1102,7 @@ sub parse_from_filehandle {
}
## See if this line is blank and ends the current paragraph.
- ## If it isnt, then keep iterating until it is.
+ ## If it isn't, then keep iterating until it is.
next unless (($textline =~ /^[^\S\r\n]*[\r\n]*$/)
&& (length $paragraph));
@@ -1111,7 +1111,7 @@ sub parse_from_filehandle {
$paragraph = '';
$plines = 0;
}
- ## Dont forget about the last paragraph in the file
+ ## Don't forget about the last paragraph in the file
if (length $paragraph) {
parse_paragraph($self, $paragraph, ($nlines - $plines) + 1)
}
@@ -1146,7 +1146,7 @@ closes the input and output files.
=back
-If the special input filename "-" or "<&STDIN" is given then the STDIN
+If the special input filename "", "-" or "<&STDIN" is given then the STDIN
filehandle is used for input (and no open or close is performed). If no
input filename is specified then "-" is implied. Filehandle references,
or objects that support the regular IO operations (like C<E<lt>$fhE<gt>>
@@ -1611,7 +1611,7 @@ sub _pop_input_stream {
my $old_top = pop(@input_stack);
$myData{_CUTTING} = $old_top->was_cutting();
- ## Dont forget to reset the input indicators
+ ## Don't forget to reset the input indicators
my $input_top = undef;
if (@input_stack > 0) {
$input_top = $myData{_TOP_STREAM} = $input_stack[-1];
diff --git a/Master/tlpkg/tlperl/lib/Pod/Perldoc.pm b/Master/tlpkg/tlperl/lib/Pod/Perldoc.pm
index 8c841e833e8..6ddd21d95d4 100644
--- a/Master/tlpkg/tlperl/lib/Pod/Perldoc.pm
+++ b/Master/tlpkg/tlperl/lib/Pod/Perldoc.pm
@@ -12,7 +12,7 @@ use File::Spec::Functions qw(catfile catdir splitdir);
use vars qw($VERSION @Pagers $Bindir $Pod2man
$Temp_Files_Created $Temp_File_Lifetime
);
-$VERSION = '3.19';
+$VERSION = '3.23';
#..........................................................................
@@ -90,12 +90,13 @@ $Pod2man = "pod2man" . ( $Config{'versiononly'} ? $Config{'version'} : '' );
#
# Option accessors...
-foreach my $subname (map "opt_$_", split '', q{mhlDriFfXqnTdULv}) {
+foreach my $subname (map "opt_$_", split '', q{mhlDriFfXqnTdULva}) {
no strict 'refs';
*$subname = do{ use strict 'refs'; sub () { shift->_elem($subname, @_) } };
}
# And these are so that GetOptsOO knows they take options:
+sub opt_a_with { shift->_elem('opt_a', @_) }
sub opt_f_with { shift->_elem('opt_f', @_) }
sub opt_q_with { shift->_elem('opt_q', @_) }
sub opt_d_with { shift->_elem('opt_d', @_) }
@@ -293,6 +294,7 @@ Options:
-X Use index if present (looks for pod.idx at $Config{archlib})
-q Search the text of questions (not answers) in perlfaq[1-9]
-f Search Perl built-in functions
+ -a Search Perl API
-v Search predefined Perl variables
PageName|ModuleName|ProgramName|URL...
@@ -399,6 +401,7 @@ Examples:
$program_name -f PerlFunc
$program_name -q FAQKeywords
$program_name -v PerlVar
+ $program_name -a PerlAPI
The -h option prints more help. Also try "$program_name perldoc" to get
acquainted with the system. [Perldoc v$VERSION]
@@ -441,6 +444,7 @@ sub init {
$self->{'pagers' } = [@Pagers] unless exists $self->{'pagers'};
$self->{'bindir' } = $Bindir unless exists $self->{'bindir'};
$self->{'pod2man'} = $Pod2man unless exists $self->{'pod2man'};
+ $self->{'search_path'} = [ ] unless exists $self->{'search_path'};
push @{ $self->{'formatter_switches'} = [] }, (
# Yeah, we could use a hashref, but maybe there's some class where options
@@ -470,7 +474,7 @@ sub init_formatter_class_list {
$self->opt_M_with('Pod::Perldoc::ToPod'); # the always-there fallthru
$self->opt_o_with('text');
- $self->opt_o_with('man') unless $self->is_mswin32 || $self->is_dos
+ $self->opt_o_with('term') unless $self->is_mswin32 || $self->is_dos
|| !($ENV{TERM} && (
($ENV{TERM} || '') !~ /dumb|emacs|none|unknown/i
));
@@ -502,10 +506,10 @@ sub process {
# such as perlfaq".
return $self->usage_brief unless @{ $self->{'args'} };
- $self->pagers_guessing;
$self->options_reading;
+ $self->pagers_guessing;
$self->aside(sprintf "$0 => %s v%s\n", ref($self), $self->VERSION);
- $self->drop_privs_maybe;
+ $self->drop_privs_maybe unless $self->opt_U;
$self->options_processing;
# Hm, we have @pages and @found, but we only really act on one
@@ -519,6 +523,7 @@ sub process {
if( $self->opt_f) { @pages = qw(perlfunc perlop) }
elsif( $self->opt_q) { @pages = ("perlfaq1" .. "perlfaq9") }
elsif( $self->opt_v) { @pages = ("perlvar") }
+ elsif( $self->opt_a) { @pages = ("perlapi") }
else { @pages = @{$self->{'args'}};
# @pages = __FILE__
# if @pages == 1 and $pages[0] eq 'perldoc';
@@ -529,7 +534,7 @@ sub process {
$self->find_good_formatter_class();
$self->formatter_sanity_check();
- $self->maybe_diddle_INC();
+ $self->maybe_extend_searchpath();
# for when we're apparently in a module or extension directory
my @found = $self->grand_search_init(\@pages);
@@ -596,7 +601,7 @@ sub find_good_formatter_class {
} else {
$^W = 0;
# The average user just has no reason to be seeing
- # $^W-suppressible warnings from the the require!
+ # $^W-suppressible warnings from the require!
}
eval "require $c";
@@ -795,8 +800,12 @@ sub options_sanity {
# Any sanity-checking need doing here?
# But does not make sense to set either -f or -q in $ENV{"PERLDOC"}
- if( $self->opt_f or $self->opt_q ) {
- $self->usage("Only one of -f -or -q") if $self->opt_f and $self->opt_q;
+ if( $self->opt_f or $self->opt_q or $self->opt_a) {
+ my $count;
+ $count++ if $self->opt_f;
+ $count++ if $self->opt_q;
+ $count++ if $self->opt_a;
+ $self->usage("Only one of -f or -q or -a") if $count > 1;
$self->warn(
"Perldoc is meant for reading one file at a time.\n",
"So these parameters are being ignored: ",
@@ -858,7 +867,7 @@ sub grand_search_init {
# We must look both in @INC for library modules and in $bindir
# for executables, like h2xs or perldoc itself.
- push @searchdirs, ($self->{'bindir'}, @INC);
+ push @searchdirs, ($self->{'bindir'}, @{$self->{search_path}}, @INC);
unless ($self->opt_m) {
if ($self->is_vms) {
my($i,$trn);
@@ -916,22 +925,28 @@ sub maybe_generate_dynamic_pod {
my($self, $found_things) = @_;
my @dynamic_pod;
+ $self->search_perlapi($found_things, \@dynamic_pod) if $self->opt_a;
+
$self->search_perlfunc($found_things, \@dynamic_pod) if $self->opt_f;
$self->search_perlvar($found_things, \@dynamic_pod) if $self->opt_v;
$self->search_perlfaqs($found_things, \@dynamic_pod) if $self->opt_q;
- if( ! $self->opt_f and ! $self->opt_q and ! $self->opt_v ) {
+ if( ! $self->opt_f and ! $self->opt_q and ! $self->opt_v and ! $self->opt_a) {
DEBUG > 4 and print "That's a non-dynamic pod search.\n";
} elsif ( @dynamic_pod ) {
$self->aside("Hm, I found some Pod from that search!\n");
my ($buffd, $buffer) = $self->new_tempfile('pod', 'dyn');
+ if ( $] >= 5.008 && $self->opt_L ) {
+ binmode($buffd, ":utf8");
+ print $buffd "=encoding utf8\n\n";
+ }
push @{ $self->{'temp_file_list'} }, $buffer;
# I.e., it MIGHT be deleted at the end.
- my $in_list = !$self->not_dynamic && $self->opt_f || $self->opt_v;
+ my $in_list = !$self->not_dynamic && $self->opt_f || $self->opt_v || $self->opt_a;
print $buffd "=over 8\n\n" if $in_list;
print $buffd @dynamic_pod or $self->die( "Can't print $buffer: $!" );
@@ -1093,46 +1108,72 @@ sub search_perlop {
$self->not_dynamic( 1 );
my $perlop = shift @$found_things;
+ # XXX FIXME: getting filehandles should probably be done in a single place
+ # especially since we need to support UTF8 or other encoding when dealing
+ # with perlop, perlfunc, perlapi, perlfaq[1-9]
open( PERLOP, '<', $perlop ) or $self->die( "Can't open $perlop: $!" );
- my $paragraph = "";
- my $has_text_seen = 0;
my $thing = $self->opt_f;
- my $list = 0;
- while( my $line = <PERLOP> ){
- if( $paragraph and $line =~ m!^=(?:head|item)! and $paragraph =~ m!X<+\s*\Q$thing\E\s*>+! ){
- if( $list ){
- $paragraph =~ s!=back.*?\z!!s;
- }
-
- if( $paragraph =~ m!^=item! ){
- $paragraph = "=over 8\n\n" . $paragraph . "=back\n";
- }
+ my $previous_line;
+ my $push = 0;
+ my $seen_item = 0;
+ my $skip = 1;
- push @$pod, $paragraph;
- $paragraph = "";
- $has_text_seen = 0;
- $list = 0;
+ while( my $line = <PERLOP> ) {
+ # only start search after we hit the operator section
+ if ($line =~ m!^X<operator, regexp>!) {
+ $skip = 0;
}
- if( $line =~ m!^=over! ){
- $list++;
+ next if $skip;
+
+ # strategy is to capture the previous line until we get a match on X<$thingy>
+ # if the current line contains X<$thingy>, then we push "=over", the previous line,
+ # the current line and keep pushing current line until we see a ^X<some-other-thing>,
+ # then we chop off final line from @$pod and add =back
+ #
+ # At that point, Bob's your uncle.
+
+ if ( $line =~ m!X<+\s*\Q$thing\E\s*>+!) {
+ if ( $previous_line ) {
+ push @$pod, "=over 8\n\n", $previous_line;
+ $previous_line = "";
+ }
+ push @$pod, $line;
+ $push = 1;
+
}
- elsif( $line =~ m!^=back! ){
- $list--;
+ elsif ( $push and $line =~ m!^=item\s*.*$! ) {
+ $seen_item = 1;
}
-
- if( $line =~ m!^=(?:head|item)! and $has_text_seen ){
- $paragraph = "";
+ elsif ( $push and $seen_item and $line =~ m!^X<+\s*[ a-z,?-]+\s*>+!) {
+ $push = 0;
+ $seen_item = 0;
+ last;
}
- elsif( $line !~ m!^=(?:head|item)! and $line !~ m!^\s*$! and $line !~ m!^\s*X<! ){
- $has_text_seen = 1;
+ elsif ( $push ) {
+ push @$pod, $line;
}
- $paragraph .= $line;
+ else {
+ $previous_line = $line;
}
+ } #end while
+
+ # we overfilled by 1 line, so pop off final array element if we have any
+ if ( scalar @$pod ) {
+ pop @$pod;
+
+ # and add the =back
+ push @$pod, "\n\n=back\n";
+ DEBUG > 8 and print "PERLOP POD --->" . (join "", @$pod) . "<---\n";
+ }
+ else {
+ DEBUG > 4 and print "No pod from perlop\n";
+ }
+
close PERLOP;
return;
@@ -1140,6 +1181,83 @@ sub search_perlop {
#..........................................................................
+sub search_perlapi {
+ my($self, $found_things, $pod) = @_;
+
+ DEBUG > 2 and print "Search: @$found_things\n";
+
+ my $perlapi = shift @$found_things;
+ open(PAPI, "<", $perlapi) # "Funk is its own reward"
+ or $self->die("Can't open $perlapi: $!");
+
+ my $search_re = quotemeta($self->opt_a);
+
+ DEBUG > 2 and
+ print "Going to perlapi-scan for $search_re in $perlapi\n";
+
+ # Check available translator or backup to default (english)
+ if ( $self->opt_L && defined $self->{'translators'}->[0] ) {
+ my $tr = $self->{'translators'}->[0];
+ if ( $] < 5.008 ) {
+ $self->aside("Your old perl doesn't really have proper unicode support.");
+ }
+ else {
+ binmode(PAPI, ":utf8");
+ }
+ }
+
+ local $_;
+
+ # Look for our function
+ my $found = 0;
+ my $inlist = 0;
+
+ my @related;
+ my $related_re;
+ while (<PAPI>) { # "The Mothership Connection is here!"
+ if ( m/^=item\s+$search_re\b/ ) {
+ $found = 1;
+ }
+ elsif (@related > 1 and /^=item/) {
+ $related_re ||= join "|", @related;
+ if (m/^=item\s+(?:$related_re)\b/) {
+ $found = 1;
+ }
+ else {
+ last;
+ }
+ }
+ elsif (/^=item/) {
+ last if $found > 1 and not $inlist;
+ }
+ elsif ($found and /^X<[^>]+>/) {
+ push @related, m/X<([^>]+)>/g;
+ }
+ next unless $found;
+ if (/^=over/) {
+ ++$inlist;
+ }
+ elsif (/^=back/) {
+ last if $found > 1 and not $inlist;
+ --$inlist;
+ }
+ push @$pod, $_;
+ ++$found if /^\w/; # found descriptive text
+ }
+
+ if (!@$pod) {
+ CORE::die( sprintf
+ "No documentation for perl api function '%s' found\n",
+ $self->opt_a )
+ ;
+ }
+ close PAPI or $self->die( "Can't open $perlapi: $!" );
+
+ return;
+}
+
+#..........................................................................
+
sub search_perlfunc {
my($self, $found_things, $pod) = @_;
@@ -1162,6 +1280,12 @@ sub search_perlfunc {
if ( $self->opt_L && defined $self->{'translators'}->[0] ) {
my $tr = $self->{'translators'}->[0];
$re = $tr->search_perlfunc_re if $tr->can('search_perlfunc_re');
+ if ( $] < 5.008 ) {
+ $self->aside("Your old perl doesn't really have proper unicode support.");
+ }
+ else {
+ binmode(PFUNC, ":utf8");
+ }
}
# Skip introduction
@@ -1180,7 +1304,16 @@ sub search_perlfunc {
my $related_re;
while (<PFUNC>) { # "The Mothership Connection is here!"
last if( grep{ $self->opt_f eq $_ }@perlops );
- if ( m/^=item\s+$search_re\b/ ) {
+
+ if ( /^=over/ and not $found ) {
+ ++$inlist;
+ }
+ elsif ( /^=back/ and not $found and $inlist ) {
+ --$inlist;
+ }
+
+
+ if ( m/^=item\s+$search_re\b/ and $inlist < 2 ) {
$found = 1;
}
elsif (@related > 1 and /^=item/) {
@@ -1189,11 +1322,11 @@ sub search_perlfunc {
$found = 1;
}
else {
- last;
+ last if $found > 1 and $inlist < 2;
}
}
elsif (/^=item/) {
- last if $found > 1 and not $inlist;
+ last if $found > 1 and $inlist < 2;
}
elsif ($found and /^X<[^>]+>/) {
push @related, m/X<([^>]+)>/g;
@@ -1203,7 +1336,6 @@ sub search_perlfunc {
++$inlist;
}
elsif (/^=back/) {
- last if $found > 1 and not $inlist;
--$inlist;
}
push @$pod, $_;
@@ -1220,7 +1352,7 @@ sub search_perlfunc {
$self->opt_f )
;
}
- close PFUNC or $self->die( "Can't open $perlfunc: $!" );
+ close PFUNC or $self->die( "Can't close $perlfunc: $!" );
return;
}
@@ -1514,7 +1646,14 @@ sub pagers_guessing {
}
}
- unshift @pagers, "$ENV{PERLDOC_PAGER} <" if $ENV{PERLDOC_PAGER};
+ if ( $self->opt_m ) {
+ unshift @pagers, "$ENV{PERLDOC_SRC_PAGER}" if $ENV{PERLDOC_SRC_PAGER}
+ }
+ else {
+ unshift @pagers, "$ENV{PERLDOC_PAGER} <" if $ENV{PERLDOC_PAGER};
+ }
+
+ $self->aside("Pagers: ", @pagers);
return;
}
@@ -1638,19 +1777,18 @@ sub containspod {
#..........................................................................
-sub maybe_diddle_INC {
+sub maybe_extend_searchpath {
my $self = shift;
# Does this look like a module or extension directory?
if (-f "Makefile.PL" || -f "Build.PL") {
- # Add "." and "lib" to @INC (if they exist)
- eval q{ use lib qw(. lib); 1; } or $self->die;
+ push @{$self->{search_path} }, '.','lib';
# don't add if superuser
if ($< && $> && -d "blib") { # don't be looking too hard now!
- eval q{ use blib; 1 };
+ push @{ $self->{search_path} }, 'blib';
$self->warn( $@ ) if $@ && $self->opt_D;
}
}
@@ -1867,6 +2005,8 @@ sub is_tainted { # just a function
sub drop_privs_maybe {
my $self = shift;
+ DEBUG and print "Attempting to drop privs...\n";
+
# Attempt to drop privs if we should be tainting and aren't
if (!( $self->is_vms || $self->is_mswin32 || $self->is_dos
|| $self->is_os2
diff --git a/Master/tlpkg/tlperl/lib/Pod/Perldoc/BaseTo.pm b/Master/tlpkg/tlperl/lib/Pod/Perldoc/BaseTo.pm
index 5bf8a936a78..b216d426114 100644
--- a/Master/tlpkg/tlperl/lib/Pod/Perldoc/BaseTo.pm
+++ b/Master/tlpkg/tlperl/lib/Pod/Perldoc/BaseTo.pm
@@ -3,7 +3,7 @@ use strict;
use warnings;
use vars qw($VERSION);
-$VERSION = '3.19';
+$VERSION = '3.23';
use Carp qw(croak carp);
use Config qw(%Config);
@@ -33,6 +33,7 @@ BEGIN {
*is_linux = $^O eq 'linux' ? \&TRUE : \&FALSE unless defined &is_linux;
*is_hpux = $^O =~ m/hpux/ ? \&TRUE : \&FALSE unless defined &is_hpux;
*is_openbsd = $^O =~ m/openbsd/ ? \&TRUE : \&FALSE unless defined &is_openbsd;
+ *is_bitrig = $^O =~ m/bitrig/ ? \&TRUE : \&FALSE unless defined &is_bitrig;
}
sub _perldoc_elem {
diff --git a/Master/tlpkg/tlperl/lib/Pod/Perldoc/GetOptsOO.pm b/Master/tlpkg/tlperl/lib/Pod/Perldoc/GetOptsOO.pm
index 0355f8f3ca2..3f4e218a946 100644
--- a/Master/tlpkg/tlperl/lib/Pod/Perldoc/GetOptsOO.pm
+++ b/Master/tlpkg/tlperl/lib/Pod/Perldoc/GetOptsOO.pm
@@ -2,7 +2,7 @@ package Pod::Perldoc::GetOptsOO;
use strict;
use vars qw($VERSION);
-$VERSION = '3.19';
+$VERSION = '3.23';
BEGIN { # Make a DEBUG constant ASAP
*DEBUG = defined( &Pod::Perldoc::DEBUG )
diff --git a/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToANSI.pm b/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToANSI.pm
index c6534bd4cf6..f0ecbced987 100644
--- a/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToANSI.pm
+++ b/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToANSI.pm
@@ -4,7 +4,7 @@ use warnings;
use parent qw(Pod::Perldoc::BaseTo);
use vars qw($VERSION);
-$VERSION = '3.19';
+$VERSION = '3.23';
sub is_pageable { 1 }
sub write_with_binmode { 0 }
diff --git a/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToChecker.pm b/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToChecker.pm
index 6f8d12c1120..8bff3381201 100644
--- a/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToChecker.pm
+++ b/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToChecker.pm
@@ -4,7 +4,7 @@ use warnings;
use vars qw(@ISA);
use vars qw($VERSION);
-$VERSION = '3.19';
+$VERSION = '3.23';
# Pick our superclass...
#
diff --git a/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToMan.pm b/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToMan.pm
index 225a78618d5..1080dbd93e0 100644
--- a/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToMan.pm
+++ b/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToMan.pm
@@ -5,7 +5,7 @@ use warnings;
use parent qw(Pod::Perldoc::BaseTo);
use vars qw($VERSION);
-$VERSION = '3.19';
+$VERSION = '3.23';
use File::Spec::Functions qw(catfile);
use Pod::Man 2.18;
@@ -63,7 +63,7 @@ sub init {
sub _roffer_candidates {
my( $self ) = @_;
- if( $self->is_openbsd ) { qw( mandoc groff nroff ) }
+ if( $self->is_openbsd || $self->is_bitrig ) { qw( mandoc groff nroff ) }
else { qw( groff nroff mandoc ) }
}
@@ -136,7 +136,7 @@ sub _get_columns {
sub _get_podman_switches {
my( $self ) = @_;
- my @switches = grep !m/^_/s, keys %$self;
+ my @switches = map { $_, $self->{$_} } grep !m/^_/s, keys %$self;
# There needs to be a cleaner way to handle setting
# the UTF-8 flag, but for now, comment out this
@@ -212,37 +212,16 @@ sub _have_groff_with_utf8 {
sub _have_mandoc_with_utf8 {
my( $self ) = @_;
- return 0 unless $self->_is_mandoc;
- my $roffer = $self->__nroffer;
-
- my $minimum_mandoc_version = '1.11';
-
- my $version_string = `$roffer -V`;
- my( $version ) = $version_string =~ /mandoc ((\d+)\.(\d+))/;
- $self->debug( "Found mandoc $version\n" );
-
- # is a string comparison good enough?
- if( $version lt $minimum_mandoc_version ) {
- $self->warn(
- "You have an older mandoc." .
- " Update to version $minimum_mandoc_version for better Unicode support.\n" .
- "If you don't upgrade, wide characters may come out oddly.\n" .
- "Your results still might be odd. If you have groff, that's even better.\n"
- );
- }
-
- $version ge $minimum_mandoc_version;
+ $self->_is_mandoc and not system 'mandoc -Tlocale -V > /dev/null 2>&1';
}
sub _collect_nroff_switches {
my( $self ) = shift;
- my @render_switches = $self->_is_mandoc ? qw(-mandoc) : qw(-man);
-
- push @render_switches, $self->_get_device_switches;
+ my @render_switches = ('-man', $self->_get_device_switches);
# Thanks to Brendan O'Dea for contributing the following block
- if( $self->_is_roff and $self->is_linux and -t STDOUT and my ($cols) = $self->_get_columns ) {
+ if( $self->_is_roff and -t STDOUT and my ($cols) = $self->_get_columns ) {
my $c = $cols * 39 / 40;
$cols = $c > $cols - 2 ? $c : $cols -2;
push @render_switches, '-rLL=' . (int $c) . 'n' if $cols > 80;
@@ -263,7 +242,7 @@ sub _get_device_switches {
if( $self->_is_nroff ) { qw() }
elsif( $self->_have_groff_with_utf8 ) { qw(-Kutf8 -Tutf8) }
elsif( $self->_is_ebcdic ) { qw(-Tcp1047) }
- elsif( $self->_have_mandoc_with_utf8 ) { qw(-Tutf8) }
+ elsif( $self->_have_mandoc_with_utf8 ) { qw(-Tlocale) }
elsif( $self->_is_mandoc ) { qw() }
else { qw(-Tlatin1) }
}
@@ -314,7 +293,7 @@ sub _filter_through_nroff {
# Eliminate whitespace
$switches =~ s/\s//g;
- # Then seperate the switches with a zero-width positive
+ # Then separate the switches with a zero-width positive
# lookahead on the dash.
#
# See:
diff --git a/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToNroff.pm b/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToNroff.pm
index 4f720e7f0e6..9777581db23 100644
--- a/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToNroff.pm
+++ b/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToNroff.pm
@@ -4,7 +4,7 @@ use warnings;
use parent qw(Pod::Perldoc::BaseTo);
use vars qw($VERSION);
-$VERSION = '3.19';
+$VERSION = '3.23';
# This is unlike ToMan.pm in that it emits the raw nroff source!
diff --git a/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToPod.pm b/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToPod.pm
index 7083ae67b36..97185bbb42d 100644
--- a/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToPod.pm
+++ b/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToPod.pm
@@ -4,7 +4,7 @@ use warnings;
use parent qw(Pod::Perldoc::BaseTo);
use vars qw($VERSION);
-$VERSION = '3.19';
+$VERSION = '3.23';
sub is_pageable { 1 }
sub write_with_binmode { 0 }
diff --git a/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToRtf.pm b/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToRtf.pm
index 6e190f73a27..588405715bb 100644
--- a/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToRtf.pm
+++ b/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToRtf.pm
@@ -4,7 +4,7 @@ use warnings;
use parent qw( Pod::Simple::RTF );
use vars qw($VERSION);
-$VERSION = '3.19';
+$VERSION = '3.23';
sub is_pageable { 0 }
sub write_with_binmode { 0 }
diff --git a/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToTerm.pm b/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToTerm.pm
index f8d9349d10a..693b52a9059 100644
--- a/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToTerm.pm
+++ b/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToTerm.pm
@@ -3,7 +3,7 @@ use strict;
use warnings;
use vars qw($VERSION);
-$VERSION = '3.19';
+$VERSION = '3.23';
use parent qw(Pod::Perldoc::BaseTo);
@@ -18,13 +18,56 @@ sub indent { shift->_perldoc_elem('indent' , @_) }
sub loose { shift->_perldoc_elem('loose' , @_) }
sub quotes { shift->_perldoc_elem('quotes' , @_) }
sub sentence { shift->_perldoc_elem('sentence', @_) }
-sub width { shift->_perldoc_elem('width' , @_) }
+sub width {
+ my $self = shift;
+ $self->_perldoc_elem('width' , @_) ||
+ $self->_get_columns_from_manwidth ||
+ $self->_get_columns_from_stty ||
+ $self->_get_default_width;
+}
+
+sub _get_stty { `stty -a` }
+
+sub _get_columns_from_stty {
+ my $output = $_[0]->_get_stty;
+
+ if( $output =~ /\bcolumns\s+(\d+)/ ) { return $1; }
+ elsif( $output =~ /;\s*(\d+)\s+columns;/ ) { return $1; }
+ else { return 0 }
+ }
+
+sub _get_columns_from_manwidth {
+ my( $self ) = @_;
+
+ return 0 unless defined $ENV{MANWIDTH};
+
+ unless( $ENV{MANWIDTH} =~ m/\A\d+\z/ ) {
+ $self->warn( "Ignoring non-numeric MANWIDTH ($ENV{MANWIDTH})\n" );
+ return 0;
+ }
+
+ if( $ENV{MANWIDTH} == 0 ) {
+ $self->warn( "Ignoring MANWIDTH of 0. Really? Why even run the program? :)\n" );
+ return 0;
+ }
+
+ if( $ENV{MANWIDTH} =~ m/\A(\d+)\z/ ) { return $1 }
+
+ return 0;
+ }
+
+sub _get_default_width {
+ 76
+ }
+
sub new { return bless {}, ref($_[0]) || $_[0] }
sub parse_from_file {
my $self = shift;
+ $self->{width} = $self->width();
+
my @options =
map {; $_, $self->{$_} }
grep !m/^_/s,
@@ -34,7 +77,7 @@ sub parse_from_file {
defined(&Pod::Perldoc::DEBUG)
and Pod::Perldoc::DEBUG()
and print "About to call new Pod::Text::Termcap ",
- $Pod::Text::VERSION ? "(v$Pod::Text::VERSION) " : '',
+ $Pod::Text::VERSION ? "(v$Pod::Text::Termcap::VERSION) " : '',
"with options: ",
@options ? "[@options]" : "(nil)", "\n";
;
diff --git a/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToText.pm b/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToText.pm
index 530bdee7ad0..07f44cd5630 100644
--- a/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToText.pm
+++ b/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToText.pm
@@ -3,7 +3,7 @@ use strict;
use warnings;
use vars qw($VERSION);
-$VERSION = '3.19';
+$VERSION = '3.23';
use parent qw(Pod::Perldoc::BaseTo);
diff --git a/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToTk.pm b/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToTk.pm
index deed6b3ff15..627289e88a1 100644
--- a/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToTk.pm
+++ b/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToTk.pm
@@ -3,7 +3,7 @@ use strict;
use warnings;
use vars qw($VERSION);
-$VERSION = '3.19';
+$VERSION = '3.23';
use parent qw(Pod::Perldoc::BaseTo);
diff --git a/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToXml.pm b/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToXml.pm
index f85f01eb7bd..5c86b3ebda1 100644
--- a/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToXml.pm
+++ b/Master/tlpkg/tlperl/lib/Pod/Perldoc/ToXml.pm
@@ -6,7 +6,7 @@ use vars qw($VERSION);
use parent qw( Pod::Simple::XMLOutStream );
use vars qw($VERSION);
-$VERSION = '3.19';
+$VERSION = '3.23';
sub is_pageable { 0 }
sub write_with_binmode { 0 }
diff --git a/Master/tlpkg/tlperl/lib/Pod/PlainText.pm b/Master/tlpkg/tlperl/lib/Pod/PlainText.pm
index 81fee052903..3db4d903cd6 100644
--- a/Master/tlpkg/tlperl/lib/Pod/PlainText.pm
+++ b/Master/tlpkg/tlperl/lib/Pod/PlainText.pm
@@ -29,7 +29,7 @@ use vars qw(@ISA %ESCAPES $VERSION);
# by Pod::Usage.
@ISA = qw(Pod::Select);
-$VERSION = '2.06';
+$VERSION = '2.07';
BEGIN {
if ($] < 5.006) {
@@ -621,6 +621,10 @@ Pod::PlainText - Convert POD data to formatted ASCII text
=head1 DESCRIPTION
+B<NOTE: This module is considered legacy; modern Perl releases (5.18 and
+higher) are going to remove Pod-Parser from core and use L<Pod-Simple>
+for all things POD.>
+
Pod::PlainText is a module that can convert documentation in the POD format (the
preferred language for documenting Perl) into formatted ASCII. It uses no
special formatting controls or codes whatsoever, and its output is therefore
diff --git a/Master/tlpkg/tlperl/lib/Pod/Select.pm b/Master/tlpkg/tlperl/lib/Pod/Select.pm
index f822d211b65..6657def58fd 100644
--- a/Master/tlpkg/tlperl/lib/Pod/Select.pm
+++ b/Master/tlpkg/tlperl/lib/Pod/Select.pm
@@ -11,7 +11,7 @@ package Pod::Select;
use strict;
use vars qw($VERSION @ISA @EXPORT $MAX_HEADING_LEVEL %myData @section_headings @selected_sections);
-$VERSION = '1.60'; ## Current version of this package
+$VERSION = '1.62'; ## Current version of this package
require 5.005; ## requires this Perl version or later
#############################################################################
@@ -71,6 +71,10 @@ podselect()
=head1 DESCRIPTION
+B<NOTE: This module is considered legacy; modern Perl releases (5.18 and
+higher) are going to remove Pod-Parser from core and use L<Pod-Simple>
+for all things POD.>
+
B<podselect()> is a function which will extract specified sections of
pod documentation from an input stream. This ability is provided by the
B<Pod::Select> module which is a subclass of B<Pod::Parser>.
@@ -531,7 +535,7 @@ implicit first argument.
B<podselect> will print the raw (untranslated) POD paragraphs of all
POD sections in the given input files specified by C<@filelist>
-according to the given options.
+according to the options given in C<\%options>.
If any argument to B<podselect> is a reference to a hash
(associative array) then the values with the following keys are
@@ -542,7 +546,8 @@ processed as follows:
=item B<-output>
A string corresponding to the desired output file (or ">&STDOUT"
-or ">&STDERR"). The default is to use standard output.
+or ">&STDERR"), or a filehandle to write on. The default is to use
+standard output.
=item B<-sections>
@@ -565,10 +570,10 @@ are used.
=back
-All other arguments should correspond to the names of input files
-containing POD sections. A file name of "-" or "<&STDIN" will
-be interpreted to mean standard input (which is the default if no
-filenames are given).
+All other arguments are optional and should correspond to filehandles to
+read from or the names of input files containing POD sections. A file name
+of "", "-" or "<&STDIN" will be interpreted to mean standard input (which
+is the default if no arguments are given).
=cut
@@ -581,8 +586,8 @@ sub podselect {
my %opts;
local $_;
for (@argv) {
- if (ref($_)) {
- next unless (ref($_) eq 'HASH');
+ my $ref = ref($_);
+ if ($ref && $ref eq 'HASH') {
%opts = (%defaults, %{$_});
##-------------------------------------------------------------
@@ -612,12 +617,15 @@ sub podselect {
#! if ( (defined $opts{'-ranges'})
#! && ((ref $opts{'-ranges'}) eq 'ARRAY') );
}
- else {
+ elsif(!$ref || $ref eq 'GLOB') {
$pod_parser->parse_from_file($_, $output);
++$num_inputs;
}
+ else {
+ croak "Input from $ref reference not supported!\n";
+ }
}
- $pod_parser->parse_from_file('-') unless ($num_inputs > 0);
+ $pod_parser->parse_from_file('-') unless ($num_inputs > 0);
}
#############################################################################
@@ -669,7 +677,7 @@ sub _compile_section_spec {
## Parse the regexs for the heading titles
@regexs = split(/\//, $_, $MAX_HEADING_LEVEL);
- ## Set default regex for ommitted levels
+ ## Set default regex for omitted levels
for (my $i = 0; $i < $MAX_HEADING_LEVEL; ++$i) {
$regexs[$i] = '.*' unless ((defined $regexs[$i])
&& (length $regexs[$i]));
diff --git a/Master/tlpkg/tlperl/lib/Pod/Simple.pod b/Master/tlpkg/tlperl/lib/Pod/Simple.pod
new file mode 100644
index 00000000000..4edc08ed677
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/Pod/Simple.pod
@@ -0,0 +1,430 @@
+
+=head1 NAME
+
+Pod::Simple - framework for parsing Pod
+
+=head1 SYNOPSIS
+
+ TODO
+
+=head1 DESCRIPTION
+
+Pod::Simple is a Perl library for parsing text in the Pod ("plain old
+documentation") markup language that is typically used for writing
+documentation for Perl and for Perl modules. The Pod format is explained
+L<perlpod>; the most common formatter is called C<perldoc>.
+
+Be sure to read L</ENCODING> if your Pod contains non-ASCII characters.
+
+Pod formatters can use Pod::Simple to parse Pod documents and render them into
+plain text, HTML, or any number of other formats. Typically, such formatters
+will be subclasses of Pod::Simple, and so they will inherit its methods, like
+C<parse_file>.
+
+If you're reading this document just because you have a Pod-processing
+subclass that you want to use, this document (plus the documentation for the
+subclass) is probably all you need to read.
+
+If you're reading this document because you want to write a formatter
+subclass, continue reading it and then read L<Pod::Simple::Subclassing>, and
+then possibly even read L<perlpodspec> (some of which is for parser-writers,
+but much of which is notes to formatter-writers).
+
+=head1 MAIN METHODS
+
+=over
+
+=item C<< $parser = I<SomeClass>->new(); >>
+
+This returns a new parser object, where I<C<SomeClass>> is a subclass
+of Pod::Simple.
+
+=item C<< $parser->output_fh( *OUT ); >>
+
+This sets the filehandle that C<$parser>'s output will be written to.
+You can pass C<*STDOUT>, otherwise you should probably do something
+like this:
+
+ my $outfile = "output.txt";
+ open TXTOUT, ">$outfile" or die "Can't write to $outfile: $!";
+ $parser->output_fh(*TXTOUT);
+
+...before you call one of the C<< $parser->parse_I<whatever> >> methods.
+
+=item C<< $parser->output_string( \$somestring ); >>
+
+This sets the string that C<$parser>'s output will be sent to,
+instead of any filehandle.
+
+
+=item C<< $parser->parse_file( I<$some_filename> ); >>
+
+=item C<< $parser->parse_file( *INPUT_FH ); >>
+
+This reads the Pod content of the file (or filehandle) that you specify,
+and processes it with that C<$parser> object, according to however
+C<$parser>'s class works, and according to whatever parser options you
+have set up for this C<$parser> object.
+
+=item C<< $parser->parse_string_document( I<$all_content> ); >>
+
+This works just like C<parse_file> except that it reads the Pod
+content not from a file, but from a string that you have already
+in memory.
+
+=item C<< $parser->parse_lines( I<...@lines...>, undef ); >>
+
+This processes the lines in C<@lines> (where each list item must be a
+defined value, and must contain exactly one line of content -- so no
+items like C<"foo\nbar"> are allowed). The final C<undef> is used to
+indicate the end of document being parsed.
+
+The other C<parser_I<whatever>> methods are meant to be called only once
+per C<$parser> object; but C<parse_lines> can be called as many times per
+C<$parser> object as you want, as long as the last call (and only
+the last call) ends with an C<undef> value.
+
+
+=item C<< $parser->content_seen >>
+
+This returns true only if there has been any real content seen for this
+document. Returns false in cases where the document contains content,
+but does not make use of any Pod markup.
+
+=item C<< I<SomeClass>->filter( I<$filename> ); >>
+
+=item C<< I<SomeClass>->filter( I<*INPUT_FH> ); >>
+
+=item C<< I<SomeClass>->filter( I<\$document_content> ); >>
+
+This is a shortcut method for creating a new parser object, setting the
+output handle to STDOUT, and then processing the specified file (or
+filehandle, or in-memory document). This is handy for one-liners like
+this:
+
+ perl -MPod::Simple::Text -e "Pod::Simple::Text->filter('thingy.pod')"
+
+=back
+
+
+
+=head1 SECONDARY METHODS
+
+Some of these methods might be of interest to general users, as
+well as of interest to formatter-writers.
+
+Note that the general pattern here is that the accessor-methods
+read the attribute's value with C<< $value = $parser->I<attribute> >>
+and set the attribute's value with
+C<< $parser->I<attribute>(I<newvalue>) >>. For each accessor, I typically
+only mention one syntax or another, based on which I think you are actually
+most likely to use.
+
+
+=over
+
+=item C<< $parser->parse_characters( I<SOMEVALUE> ) >>
+
+The Pod parser normally expects to read octets and to convert those octets
+to characters based on the C<=encoding> declaration in the Pod source. Set
+this option to a true value to indicate that the Pod source is already a Perl
+character stream. This tells the parser to ignore any C<=encoding> command
+and to skip all the code paths involving decoding octets.
+
+=item C<< $parser->no_whining( I<SOMEVALUE> ) >>
+
+If you set this attribute to a true value, you will suppress the
+parser's complaints about irregularities in the Pod coding. By default,
+this attribute's value is false, meaning that irregularities will
+be reported.
+
+Note that turning this attribute to true won't suppress one or two kinds
+of complaints about rarely occurring unrecoverable errors.
+
+
+=item C<< $parser->no_errata_section( I<SOMEVALUE> ) >>
+
+If you set this attribute to a true value, you will stop the parser from
+generating a "POD ERRORS" section at the end of the document. By
+default, this attribute's value is false, meaning that an errata section
+will be generated, as necessary.
+
+
+=item C<< $parser->complain_stderr( I<SOMEVALUE> ) >>
+
+If you set this attribute to a true value, it will send reports of
+parsing errors to STDERR. By default, this attribute's value is false,
+meaning that no output is sent to STDERR.
+
+Setting C<complain_stderr> also sets C<no_errata_section>.
+
+
+=item C<< $parser->source_filename >>
+
+This returns the filename that this parser object was set to read from.
+
+
+=item C<< $parser->doc_has_started >>
+
+This returns true if C<$parser> has read from a source, and has seen
+Pod content in it.
+
+
+=item C<< $parser->source_dead >>
+
+This returns true if C<$parser> has read from a source, and come to the
+end of that source.
+
+=item C<< $parser->strip_verbatim_indent( I<SOMEVALUE> ) >>
+
+The perlpod spec for a Verbatim paragraph is "It should be reproduced
+exactly...", which means that the whitespace you've used to indent your
+verbatim blocks will be preserved in the output. This can be annoying for
+outputs such as HTML, where that whitespace will remain in front of every
+line. It's an unfortunate case where syntax is turned into semantics.
+
+If the POD your parsing adheres to a consistent indentation policy, you can
+have such indentation stripped from the beginning of every line of your
+verbatim blocks. This method tells Pod::Simple what to strip. For two-space
+indents, you'd use:
+
+ $parser->strip_verbatim_indent(' ');
+
+For tab indents, you'd use a tab character:
+
+ $parser->strip_verbatim_indent("\t");
+
+If the POD is inconsistent about the indentation of verbatim blocks, but you
+have figured out a heuristic to determine how much a particular verbatim block
+is indented, you can pass a code reference instead. The code reference will be
+executed with one argument, an array reference of all the lines in the
+verbatim block, and should return the value to be stripped from each line. For
+example, if you decide that you're fine to use the first line of the verbatim
+block to set the standard for indentation of the rest of the block, you can
+look at the first line and return the appropriate value, like so:
+
+ $new->strip_verbatim_indent(sub {
+ my $lines = shift;
+ (my $indent = $lines->[0]) =~ s/\S.*//;
+ return $indent;
+ });
+
+If you'd rather treat each line individually, you can do that, too, by just
+transforming them in-place in the code reference and returning C<undef>. Say
+that you don't want I<any> lines indented. You can do something like this:
+
+ $new->strip_verbatim_indent(sub {
+ my $lines = shift;
+ sub { s/^\s+// for @{ $lines },
+ return undef;
+ });
+
+=back
+
+=head1 TERTIARY METHODS
+
+=over
+
+=item C<< $parser->abandon_output_fh() >>X<abandon_output_fh>
+
+Cancel output to the file handle. Any POD read by the C<$parser> is not
+effected.
+
+=item C<< $parser->abandon_output_string() >>X<abandon_output_string>
+
+Cancel output to the output string. Any POD read by the C<$parser> is not
+effected.
+
+=item C<< $parser->accept_code( @codes ) >>X<accept_code>
+
+Alias for L<< accept_codes >>.
+
+=item C<< $parser->accept_codes( @codes ) >>X<accept_codes>
+
+Allows C<$parser> to accept a list of L<perlpod/Formatting Codes>. This can be
+used to implement user-defined codes.
+
+=item C<< $parser->accept_directive_as_data( @directives ) >>X<accept_directive_as_data>
+
+Allows C<$parser> to accept a list of directives for data paragraphs. A
+directive is the label of a L<perlpod/Command Paragraph>. A data paragraph is
+one delimited by C<< =begin/=for/=end >> directives. This can be used to
+implement user-defined directives.
+
+=item C<< $parser->accept_directive_as_processed( @directives ) >>X<accept_directive_as_processed>
+
+Allows C<$parser> to accept a list of directives for processed paragraphs. A
+directive is the label of a L<perlpod/Command Paragraph>. A processed
+paragraph is also known as L<perlpod/Ordinary Paragraph>. This can be used to
+implement user-defined directives.
+
+=item C<< $parser->accept_directive_as_verbatim( @directives ) >>X<accept_directive_as_verbatim>
+
+Allows C<$parser> to accept a list of directives for L<perlpod/Verbatim
+Paragraph>. A directive is the label of a L<perlpod/Command Paragraph>. This
+can be used to implement user-defined directives.
+
+=item C<< $parser->accept_target( @targets ) >>X<accept_target>
+
+Alias for L<< accept_targets >>.
+
+=item C<< $parser->accept_target_as_text( @targets ) >>X<accept_target_as_text>
+
+Alias for L<< accept_targets_as_text >>.
+
+=item C<< $parser->accept_targets( @targets ) >>X<accept_targets>
+
+Accepts targets for C<< =begin/=for/=end >> sections of the POD.
+
+=item C<< $parser->accept_targets_as_text( @targets ) >>X<accept_targets_as_text>
+
+Accepts targets for C<< =begin/=for/=end >> sections that should be parsed as
+POD. For details, see L<< perlpodspec/About Data Paragraphs >>.
+
+=item C<< $parser->any_errata_seen() >>X<any_errata_seen>
+
+Used to check if any errata was seen.
+
+I<Example:>
+
+ die "too many errors\n" if $parser->any_errata_seen();
+
+=item C<< $parser->detected_encoding() >>X<detected_encoding>
+
+Return the encoding corresponding to C<< =encoding >>, but only if the
+encoding was recognized and handled.
+
+=item C<< $parser->encoding() >>X<encoding>
+
+Return encoding of the document, even if the encoding is not correctly
+handled.
+
+=item C<< $parser->parse_from_file( $source, $to ) >>X<parse_from_file>
+
+Parses from C<$source> file to C<$to> file. Similar to L<<
+Pod::Parser/parse_from_file >>.
+
+=item C<< $parser->scream( @error_messages ) >>X<scream>
+
+Log an error that can't be ignored.
+
+=item C<< $parser->unaccept_code( @codes ) >>X<unaccept_code>
+
+Alias for L<< unaccept_codes >>.
+
+=item C<< $parser->unaccept_codes( @codes ) >>X<unaccept_codes>
+
+Removes C<< @codes >> as valid codes for the parse.
+
+=item C<< $parser->unaccept_directive( @directives ) >>X<unaccept_directive>
+
+Alias for L<< unaccept_directives >>.
+
+=item C<< $parser->unaccept_directives( @directives ) >>X<unaccept_directives>
+
+Removes C<< @directives >> as valid directives for the parse.
+
+=item C<< $parser->unaccept_target( @targets ) >>X<unaccept_target>
+
+Alias for L<< unaccept_targets >>.
+
+=item C<< $parser->unaccept_targets( @targets ) >>X<unaccept_targets>
+
+Removes C<< @targets >> as valid targets for the parse.
+
+=item C<< $parser->version_report() >>X<version_report>
+
+Returns a string describing the version.
+
+=item C<< $parser->whine( @error_messages ) >>X<whine>
+
+Log an error unless C<< $parser->no_whining( TRUE ); >>.
+
+=back
+
+=head1 ENCODING
+
+The Pod::Simple parser expects to read B<octets>. The parser will decode the
+octets into Perl's internal character string representation using the value of
+the C<=encoding> declaration in the POD source.
+
+If the POD source does not include an C<=encoding> declaration, the parser will
+attempt to guess the encoding (selecting one of UTF-8 or Latin-1) by examining
+the first non-ASCII bytes and applying the heuristic described in
+L<perlpodspec>.
+
+If you set the C<parse_characters> option to a true value the parser will
+expect characters rather than octets; will ignore any C<=encoding>; and will
+make no attempt to decode the input.
+
+=head1 CAVEATS
+
+This is just a beta release -- there are a good number of things still
+left to do. Notably, support for EBCDIC platforms is still half-done,
+an untested.
+
+
+=head1 SEE ALSO
+
+L<Pod::Simple::Subclassing>
+
+L<perlpod|perlpod>
+
+L<perlpodspec|perlpodspec>
+
+L<Pod::Escapes|Pod::Escapes>
+
+L<perldoc>
+
+=head1 SUPPORT
+
+Questions or discussion about POD and Pod::Simple should be sent to the
+pod-people@perl.org mail list. Send an empty email to
+pod-people-subscribe@perl.org to subscribe.
+
+This module is managed in an open GitHub repository,
+L<https://github.com/theory/pod-simple/>. Feel free to fork and contribute, or
+to clone L<git://github.com/theory/pod-simple.git> and send patches!
+
+Patches against Pod::Simple are welcome. Please send bug reports to
+<bug-pod-simple@rt.cpan.org>.
+
+=head1 COPYRIGHT AND DISCLAIMERS
+
+Copyright (c) 2002 Sean M. Burke.
+
+This library is free software; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+
+This program is distributed in the hope that it will be useful, but
+without any warranty; without even the implied warranty of
+merchantability or fitness for a particular purpose.
+
+=head1 AUTHOR
+
+Pod::Simple was created by Sean M. Burke <sburke@cpan.org>.
+But don't bother him, he's retired.
+
+Pod::Simple is maintained by:
+
+=over
+
+=item * Allison Randal C<allison@perl.org>
+
+=item * Hans Dieter Pearcey C<hdp@cpan.org>
+
+=item * David E. Wheeler C<dwheeler@cpan.org>
+
+=back
+
+Documentation has been contributed by:
+
+=over
+
+=item * Gabor Szabo C<szabgab@gmail.com>
+
+=item * Shawn H Corey C<SHCOREY at cpan.org>
+
+=back
+
+=cut
diff --git a/Master/tlpkg/tlperl/lib/Pod/Simple/Subclassing.pod b/Master/tlpkg/tlperl/lib/Pod/Simple/Subclassing.pod
new file mode 100644
index 00000000000..7a7976bdc47
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/Pod/Simple/Subclassing.pod
@@ -0,0 +1,1071 @@
+
+=head1 NAME
+
+Pod::Simple::Subclassing -- write a formatter as a Pod::Simple subclass
+
+=head1 SYNOPSIS
+
+ package Pod::SomeFormatter;
+ use Pod::Simple;
+ @ISA = qw(Pod::Simple);
+ $VERSION = '1.01';
+ use strict;
+
+ sub _handle_element_start {
+ my($parser, $element_name, $attr_hash_r) = @_;
+ ...
+ }
+
+ sub _handle_element_end {
+ my($parser, $element_name, $attr_hash_r) = @_;
+ # NOTE: $attr_hash_r is only present when $element_name is "over" or "begin"
+ # The remaining code excerpts will mostly ignore this $attr_hash_r, as it is
+ # mostly useless. It is documented where "over-*" and "begin" events are
+ # documented.
+ ...
+ }
+
+ sub _handle_text {
+ my($parser, $text) = @_;
+ ...
+ }
+ 1;
+
+=head1 DESCRIPTION
+
+This document is about using Pod::Simple to write a Pod processor,
+generally a Pod formatter. If you just want to know about using an
+existing Pod formatter, instead see its documentation and see also the
+docs in L<Pod::Simple>.
+
+The zeroeth step in writing a Pod formatter is to make sure that there
+isn't already a decent one in CPAN. See L<http://search.cpan.org/>, and
+run a search on the name of the format you want to render to. Also
+consider joining the Pod People list
+L<http://lists.perl.org/showlist.cgi?name=pod-people> and asking whether
+anyone has a formatter for that format -- maybe someone cobbled one
+together but just hasn't released it.
+
+The first step in writing a Pod processor is to read L<perlpodspec>,
+which contains notes information on writing a Pod parser (which has been
+largely taken care of by Pod::Simple), but also a lot of requirements
+and recommendations for writing a formatter.
+
+The second step is to actually learn the format you're planning to
+format to -- or at least as much as you need to know to represent Pod,
+which probably isn't much.
+
+The third step is to pick which of Pod::Simple's interfaces you want to
+use -- the basic interface via Pod::Simple or L<Pod::Simple::Methody> is
+event-based, sort of like L<HTML::Parser>'s interface, or sort of like
+L<XML::Parser>'s "Handlers" interface), but L<Pod::Simple::PullParser>
+provides a token-stream interface, sort of like L<HTML::TokeParser>'s
+interface; L<Pod::Simple::SimpleTree> provides a simple tree interface,
+rather like XML::Parser's "Tree" interface. Users familiar with
+XML-handling will find one of these styles relatively familiar; but if
+you would be even more at home with XML, there are classes that produce
+an XML representation of the Pod stream, notably
+L<Pod::Simple::XMLOutStream>; you can feed the output of such a class to
+whatever XML parsing system you are most at home with.
+
+The last step is to write your code based on how the events (or tokens,
+or tree-nodes, or the XML, or however you're parsing) will map to
+constructs in the output format. Also sure to consider how to escape
+text nodes containing arbitrary text, and also what to do with text
+nodes that represent preformatted text (from verbatim sections).
+
+
+
+=head1 Events
+
+TODO intro... mention that events are supplied for implicits, like for
+missing >'s
+
+
+In the following section, we use XML to represent the event structure
+associated with a particular construct. That is, TODO
+
+=over
+
+=item C<< $parser->_handle_element_start( I<element_name>, I<attr_hashref> ) >>
+
+=item C<< $parser->_handle_element_end( I<element_name> ) >>
+
+=item C<< $parser->_handle_text( I<text_string> ) >>
+
+=back
+
+TODO describe
+
+
+=over
+
+=item events with an element_name of Document
+
+Parsing a document produces this event structure:
+
+ <Document start_line="543">
+ ...all events...
+ </Document>
+
+The value of the I<start_line> attribute will be the line number of the first
+Pod directive in the document.
+
+If there is no Pod in the given document, then the
+event structure will be this:
+
+ <Document contentless="1" start_line="543">
+ </Document>
+
+In that case, the value of the I<start_line> attribute will not be meaningful;
+under current implementations, it will probably be the line number of the
+last line in the file.
+
+=item events with an element_name of Para
+
+Parsing a plain (non-verbatim, non-directive, non-data) paragraph in
+a Pod document produces this event structure:
+
+ <Para start_line="543">
+ ...all events in this paragraph...
+ </Para>
+
+The value of the I<start_line> attribute will be the line number of the start
+of the paragraph.
+
+For example, parsing this paragraph of Pod:
+
+ The value of the I<start_line> attribute will be the
+ line number of the start of the paragraph.
+
+produces this event structure:
+
+ <Para start_line="129">
+ The value of the
+ <I>
+ start_line
+ </I>
+ attribute will be the line number of the first Pod directive
+ in the document.
+ </Para>
+
+=item events with an element_name of B, C, F, or I.
+
+Parsing a BE<lt>...E<gt> formatting code (or of course any of its
+semantically identical syntactic variants
+S<BE<lt>E<lt> ... E<gt>E<gt>>,
+or S<BE<lt>E<lt>E<lt>E<lt> ... E<gt>E<gt>E<gt>E<gt>>, etc.)
+produces this event structure:
+
+ <B>
+ ...stuff...
+ </B>
+
+Currently, there are no attributes conveyed.
+
+Parsing C, F, or I codes produce the same structure, with only a
+different element name.
+
+If your parser object has been set to accept other formatting codes,
+then they will be presented like these B/C/F/I codes -- i.e., without
+any attributes.
+
+=item events with an element_name of S
+
+Normally, parsing an SE<lt>...E<gt> sequence produces this event
+structure, just as if it were a B/C/F/I code:
+
+ <S>
+ ...stuff...
+ </S>
+
+However, Pod::Simple (and presumably all derived parsers) offers the
+C<nbsp_for_S> option which, if enabled, will suppress all S events, and
+instead change all spaces in the content to non-breaking spaces. This is
+intended for formatters that output to a format that has no code that
+means the same as SE<lt>...E<gt>, but which has a code/character that
+means non-breaking space.
+
+=item events with an element_name of X
+
+Normally, parsing an XE<lt>...E<gt> sequence produces this event
+structure, just as if it were a B/C/F/I code:
+
+ <X>
+ ...stuff...
+ </X>
+
+However, Pod::Simple (and presumably all derived parsers) offers the
+C<nix_X_codes> option which, if enabled, will suppress all X events
+and ignore their content. For formatters/processors that don't use
+X events, this is presumably quite useful.
+
+
+=item events with an element_name of L
+
+Because the LE<lt>...E<gt> is the most complex construct in the
+language, it should not surprise you that the events it generates are
+the most complex in the language. Most of complexity is hidden away in
+the attribute values, so for those of you writing a Pod formatter that
+produces a non-hypertextual format, you can just ignore the attributes
+and treat an L event structure like a formatting element that
+(presumably) doesn't actually produce a change in formatting. That is,
+the content of the L event structure (as opposed to its
+attributes) is always what text should be displayed.
+
+There are, at first glance, three kinds of L links: URL, man, and pod.
+
+When a LE<lt>I<some_url>E<gt> code is parsed, it produces this event
+structure:
+
+ <L content-implicit="yes" raw="that_url" to="that_url" type="url">
+ that_url
+ </L>
+
+The C<type="url"> attribute is always specified for this type of
+L code.
+
+For example, this Pod source:
+
+ L<http://www.perl.com/CPAN/authors/>
+
+produces this event structure:
+
+ <L content-implicit="yes" raw="http://www.perl.com/CPAN/authors/" to="http://www.perl.com/CPAN/authors/" type="url">
+ http://www.perl.com/CPAN/authors/
+ </L>
+
+When a LE<lt>I<manpage(section)>E<gt> code is parsed (and these are
+fairly rare and not terribly useful), it produces this event structure:
+
+ <L content-implicit="yes" raw="manpage(section)" to="manpage(section)" type="man">
+ manpage(section)
+ </L>
+
+The C<type="man"> attribute is always specified for this type of
+L code.
+
+For example, this Pod source:
+
+ L<crontab(5)>
+
+produces this event structure:
+
+ <L content-implicit="yes" raw="crontab(5)" to="crontab(5)" type="man">
+ crontab(5)
+ </L>
+
+In the rare cases where a man page link has a specified, that text appears
+in a I<section> attribute. For example, this Pod source:
+
+ L<crontab(5)/"ENVIRONMENT">
+
+will produce this event structure:
+
+ <L content-implicit="yes" raw="crontab(5)/&quot;ENVIRONMENT&quot;" section="ENVIRONMENT" to="crontab(5)" type="man">
+ "ENVIRONMENT" in crontab(5)
+ </L>
+
+In the rare case where the Pod document has code like
+LE<lt>I<sometext>|I<manpage(section)>E<gt>, then the I<sometext> will appear
+as the content of the element, the I<manpage(section)> text will appear
+only as the value of the I<to> attribute, and there will be no
+C<content-implicit="yes"> attribute (whose presence means that the Pod parser
+had to infer what text should appear as the link text -- as opposed to
+cases where that attribute is absent, which means that the Pod parser did
+I<not> have to infer the link text, because that L code explicitly specified
+some link text.)
+
+For example, this Pod source:
+
+ L<hell itself!|crontab(5)>
+
+will produce this event structure:
+
+ <L raw="hell itself!|crontab(5)" to="crontab(5)" type="man">
+ hell itself!
+ </L>
+
+The last type of L structure is for links to/within Pod documents. It is
+the most complex because it can have a I<to> attribute, I<or> a
+I<section> attribute, or both. The C<type="pod"> attribute is always
+specified for this type of L code.
+
+In the most common case, the simple case of a LE<lt>podpageE<gt> code
+produces this event structure:
+
+ <L content-implicit="yes" raw="podpage" to="podpage" type="pod">
+ podpage
+ </L>
+
+For example, this Pod source:
+
+ L<Net::Ping>
+
+produces this event structure:
+
+ <L content-implicit="yes" raw="Net::Ping" to="Net::Ping" type="pod">
+ Net::Ping
+ </L>
+
+In cases where there is link-text explicitly specified, it
+is to be found in the content of the element (and not the
+attributes), just as with the LE<lt>I<sometext>|I<manpage(section)>E<gt>
+case discussed above. For example, this Pod source:
+
+ L<Perl Error Messages|perldiag>
+
+produces this event structure:
+
+ <L raw="Perl Error Messages|perldiag" to="perldiag" type="pod">
+ Perl Error Messages
+ </L>
+
+In cases of links to a section in the current Pod document,
+there is a I<section> attribute instead of a I<to> attribute.
+For example, this Pod source:
+
+ L</"Member Data">
+
+produces this event structure:
+
+ <L content-implicit="yes" raw="/&quot;Member Data&quot;" section="Member Data" type="pod">
+ "Member Data"
+ </L>
+
+As another example, this Pod source:
+
+ L<the various attributes|/"Member Data">
+
+produces this event structure:
+
+ <L raw="the various attributes|/&quot;Member Data&quot;" section="Member Data" type="pod">
+ the various attributes
+ </L>
+
+In cases of links to a section in a different Pod document,
+there are both a I<section> attribute and a L<to> attribute.
+For example, this Pod source:
+
+ L<perlsyn/"Basic BLOCKs and Switch Statements">
+
+produces this event structure:
+
+ <L content-implicit="yes" raw="perlsyn/&quot;Basic BLOCKs and Switch Statements&quot;" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod">
+ "Basic BLOCKs and Switch Statements" in perlsyn
+ </L>
+
+As another example, this Pod source:
+
+ L<SWITCH statements|perlsyn/"Basic BLOCKs and Switch Statements">
+
+produces this event structure:
+
+ <L raw="SWITCH statements|perlsyn/&quot;Basic BLOCKs and Switch Statements&quot;" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod">
+ SWITCH statements
+ </L>
+
+Incidentally, note that we do not distinguish between these syntaxes:
+
+ L</"Member Data">
+ L<"Member Data">
+ L</Member Data>
+ L<Member Data> [deprecated syntax]
+
+That is, they all produce the same event structure (for the most part), namely:
+
+ <L content-implicit="yes" raw="$depends_on_syntax" section="Member Data" type="pod">
+ &#34;Member Data&#34;
+ </L>
+
+The I<raw> attribute depends on what the raw content of the C<LE<lt>E<gt>> is,
+so that is why the event structure is the same "for the most part".
+
+If you have not guessed it yet, the I<raw> attribute contains the raw,
+original, unescaped content of the C<LE<lt>E<gt>> formatting code. In addition
+to the examples above, take notice of the following event structure produced
+by the following C<LE<lt>E<gt>> formatting code.
+
+ L<click B<here>|page/About the C<-M> switch>
+
+ <L raw="click B<here>|page/About the C<-M> switch" section="About the -M switch" to="page" type="pod">
+ click B<here>
+ </L>
+
+Specifically, notice that the formatting codes are present and unescaped
+in I<raw>.
+
+There is a known bug in the I<raw> attribute where any surrounding whitespace
+is condensed into a single ' '. For example, given LE<60> linkE<62>, I<raw>
+will be " link".
+
+=item events with an element_name of E or Z
+
+While there are Pod codes EE<lt>...E<gt> and ZE<lt>E<gt>, these
+I<do not> produce any E or Z events -- that is, there are no such
+events as E or Z.
+
+=item events with an element_name of Verbatim
+
+When a Pod verbatim paragraph (AKA "codeblock") is parsed, it
+produces this event structure:
+
+ <Verbatim start_line="543" xml:space="preserve">
+ ...text...
+ </Verbatim>
+
+The value of the I<start_line> attribute will be the line number of the
+first line of this verbatim block. The I<xml:space> attribute is always
+present, and always has the value "preserve".
+
+The text content will have tabs already expanded.
+
+
+=item events with an element_name of head1 .. head4
+
+When a "=head1 ..." directive is parsed, it produces this event
+structure:
+
+ <head1>
+ ...stuff...
+ </head1>
+
+For example, a directive consisting of this:
+
+ =head1 Options to C<new> et al.
+
+will produce this event structure:
+
+ <head1 start_line="543">
+ Options to
+ <C>
+ new
+ </C>
+ et al.
+ </head1>
+
+"=head2" thru "=head4" directives are the same, except for the element
+names in the event structure.
+
+=item events with an element_name of encoding
+
+In the default case, the events corresponding to C<=encoding> directives
+are not emitted. They are emitted if C<keep_encoding_directive> is true.
+In that case they produce event structures like
+L</"events with an element_name of head1 .. head4"> above.
+
+=item events with an element_name of over-bullet
+
+When an "=over ... Z<>=back" block is parsed where the items are
+a bulleted list, it will produce this event structure:
+
+ <over-bullet indent="4" start_line="543">
+ <item-bullet start_line="545">
+ ...Stuff...
+ </item-bullet>
+ ...more item-bullets...
+ </over-bullet fake-closer="1">
+
+The attribute I<fake-closer> is only present if it is a true value; it is not
+present if it is a false value. It is shown in the above example to illustrate
+where the attribute is (in the B<closing> tag). It signifies that the C<=over>
+did not have a matching C<=back>, and thus Pod::Simple had to create a fake
+closer.
+
+For example, this Pod source:
+
+ =over
+
+ =item *
+
+ Something
+
+ =back
+
+Would produce an event structure that does B<not> have the I<fake-closer>
+attribute, whereas this Pod source:
+
+ =over
+
+ =item *
+
+ Gasp! An unclosed =over block!
+
+would. The rest of the over-* examples will not demonstrate this attribute,
+but they all can have it. See L<Pod::Checker>'s source for an example of this
+attribute being used.
+
+The value of the I<indent> attribute is whatever value is after the
+"=over" directive, as in "=over 8". If no such value is specified
+in the directive, then the I<indent> attribute has the value "4".
+
+For example, this Pod source:
+
+ =over
+
+ =item *
+
+ Stuff
+
+ =item *
+
+ Bar I<baz>!
+
+ =back
+
+produces this event structure:
+
+ <over-bullet indent="4" start_line="10">
+ <item-bullet start_line="12">
+ Stuff
+ </item-bullet>
+ <item-bullet start_line="14">
+ Bar <I>baz</I>!
+ </item-bullet>
+ </over-bullet>
+
+=item events with an element_name of over-number
+
+When an "=over ... Z<>=back" block is parsed where the items are
+a numbered list, it will produce this event structure:
+
+ <over-number indent="4" start_line="543">
+ <item-number number="1" start_line="545">
+ ...Stuff...
+ </item-number>
+ ...more item-number...
+ </over-bullet>
+
+This is like the "over-bullet" event structure; but note that the contents
+are "item-number" instead of "item-bullet", and note that they will have
+a "number" attribute, which some formatters/processors may ignore
+(since, for example, there's no need for it in HTML when producing
+an "<UL><LI>...</LI>...</UL>" structure), but which any processor may use.
+
+Note that the values for the I<number> attributes of "item-number"
+elements in a given "over-number" area I<will> start at 1 and go up by
+one each time. If the Pod source doesn't follow that order (even though
+it really should should!), whatever numbers it has will be ignored (with
+the correct values being put in the I<number> attributes), and an error
+message might be issued to the user.
+
+=item events with an element_name of over-text
+
+These events are somewhat unlike the other over-*
+structures, as far as what their contents are. When
+an "=over ... Z<>=back" block is parsed where the items are
+a list of text "subheadings", it will produce this event structure:
+
+ <over-text indent="4" start_line="543">
+ <item-text>
+ ...stuff...
+ </item-text>
+ ...stuff (generally Para or Verbatim elements)...
+ <item-text>
+ ...more item-text and/or stuff...
+ </over-text>
+
+The I<indent> and I<fake-closer> attributes are as with the other over-* events.
+
+For example, this Pod source:
+
+ =over
+
+ =item Foo
+
+ Stuff
+
+ =item Bar I<baz>!
+
+ Quux
+
+ =back
+
+produces this event structure:
+
+ <over-text indent="4" start_line="20">
+ <item-text start_line="22">
+ Foo
+ </item-text>
+ <Para start_line="24">
+ Stuff
+ </Para>
+ <item-text start_line="26">
+ Bar
+ <I>
+ baz
+ </I>
+ !
+ </item-text>
+ <Para start_line="28">
+ Quux
+ </Para>
+ </over-text>
+
+
+
+=item events with an element_name of over-block
+
+These events are somewhat unlike the other over-*
+structures, as far as what their contents are. When
+an "=over ... Z<>=back" block is parsed where there are no items,
+it will produce this event structure:
+
+ <over-block indent="4" start_line="543">
+ ...stuff (generally Para or Verbatim elements)...
+ </over-block>
+
+The I<indent> and I<fake-closer> attributes are as with the other over-* events.
+
+For example, this Pod source:
+
+ =over
+
+ For cutting off our trade with all parts of the world
+
+ For transporting us beyond seas to be tried for pretended offenses
+
+ He is at this time transporting large armies of foreign mercenaries to
+ complete the works of death, desolation and tyranny, already begun with
+ circumstances of cruelty and perfidy scarcely paralleled in the most
+ barbarous ages, and totally unworthy the head of a civilized nation.
+
+ =back
+
+will produce this event structure:
+
+ <over-block indent="4" start_line="2">
+ <Para start_line="4">
+ For cutting off our trade with all parts of the world
+ </Para>
+ <Para start_line="6">
+ For transporting us beyond seas to be tried for pretended offenses
+ </Para>
+ <Para start_line="8">
+ He is at this time transporting large armies of [...more text...]
+ </Para>
+ </over-block>
+
+=item events with an element_name of over-empty
+
+B<Note: These events are only triggered if C<parse_empty_lists()> is set to a
+true value.>
+
+These events are somewhat unlike the other over-* structures, as far as what
+their contents are. When an "=over ... Z<>=back" block is parsed where there
+is no content, it will produce this event structure:
+
+ <over-empty indent="4" start_line="543">
+ </over-empty>
+
+The I<indent> and I<fake-closer> attributes are as with the other over-* events.
+
+For example, this Pod source:
+
+ =over
+
+ =over
+
+ =back
+
+ =back
+
+will produce this event structure:
+
+ <over-block indent="4" start_line="1">
+ <over-empty indent="4" start_line="3">
+ </over-empty>
+ </over-block>
+
+Note that the outer C<=over> is a block because it has no C<=item>s but still
+has content: the inner C<=over>. The inner C<=over>, in turn, is completely
+empty, and is treated as such.
+
+=item events with an element_name of item-bullet
+
+See L</"events with an element_name of over-bullet">, above.
+
+=item events with an element_name of item-number
+
+See L</"events with an element_name of over-number">, above.
+
+=item events with an element_name of item-text
+
+See L</"events with an element_name of over-text">, above.
+
+=item events with an element_name of for
+
+TODO...
+
+=item events with an element_name of Data
+
+TODO...
+
+=back
+
+
+
+=head1 More Pod::Simple Methods
+
+Pod::Simple provides a lot of methods that aren't generally interesting
+to the end user of an existing Pod formatter, but some of which you
+might find useful in writing a Pod formatter. They are listed below. The
+first several methods (the accept_* methods) are for declaring the
+capabilities of your parser, notably what C<=for I<targetname>> sections
+it's interested in, what extra NE<lt>...E<gt> codes it accepts beyond
+the ones described in the I<perlpod>.
+
+=over
+
+=item C<< $parser->accept_targets( I<SOMEVALUE> ) >>
+
+As the parser sees sections like:
+
+ =for html <img src="fig1.jpg">
+
+or
+
+ =begin html
+
+ <img src="fig1.jpg">
+
+ =end html
+
+...the parser will ignore these sections unless your subclass has
+specified that it wants to see sections targeted to "html" (or whatever
+the formatter name is).
+
+If you want to process all sections, even if they're not targeted for you,
+call this before you start parsing:
+
+ $parser->accept_targets('*');
+
+=item C<< $parser->accept_targets_as_text( I<SOMEVALUE> ) >>
+
+This is like accept_targets, except that it specifies also that the
+content of sections for this target should be treated as Pod text even
+if the target name in "=for I<targetname>" doesn't start with a ":".
+
+At time of writing, I don't think you'll need to use this.
+
+
+=item C<< $parser->accept_codes( I<Codename>, I<Codename>... ) >>
+
+This tells the parser that you accept additional formatting codes,
+beyond just the standard ones (I B C L F S X, plus the two weird ones
+you don't actually see in the parse tree, Z and E). For example, to also
+accept codes "N", "R", and "W":
+
+ $parser->accept_codes( qw( N R W ) );
+
+B<TODO: document how this interacts with =extend, and long element names>
+
+
+=item C<< $parser->accept_directive_as_data( I<directive_name> ) >>
+
+=item C<< $parser->accept_directive_as_verbatim( I<directive_name> ) >>
+
+=item C<< $parser->accept_directive_as_processed( I<directive_name> ) >>
+
+In the unlikely situation that you need to tell the parser that you will
+accept additional directives ("=foo" things), you need to first set the
+parser to treat its content as data (i.e., not really processed at
+all), or as verbatim (mostly just expanding tabs), or as processed text
+(parsing formatting codes like BE<lt>...E<gt>).
+
+For example, to accept a new directive "=method", you'd presumably
+use:
+
+ $parser->accept_directive_as_processed("method");
+
+so that you could have Pod lines like:
+
+ =method I<$whatever> thing B<um>
+
+Making up your own directives breaks compatibility with other Pod
+formatters, in a way that using "=for I<target> ..." lines doesn't;
+however, you may find this useful if you're making a Pod superset
+format where you don't need to worry about compatibility.
+
+
+=item C<< $parser->nbsp_for_S( I<BOOLEAN> ); >>
+
+Setting this attribute to a true value (and by default it is false) will
+turn "SE<lt>...E<gt>" sequences into sequences of words separated by
+C<\xA0> (non-breaking space) characters. For example, it will take this:
+
+ I like S<Dutch apple pie>, don't you?
+
+and treat it as if it were:
+
+ I like DutchE<nbsp>appleE<nbsp>pie, don't you?
+
+This is handy for output formats that don't have anything quite like an
+"SE<lt>...E<gt>" code, but which do have a code for non-breaking space.
+
+There is currently no method for going the other way; but I can
+probably provide one upon request.
+
+
+=item C<< $parser->version_report() >>
+
+This returns a string reporting the $VERSION value from your module (and
+its classname) as well as the $VERSION value of Pod::Simple. Note that
+L<perlpodspec> requires output formats (wherever possible) to note
+this detail in a comment in the output format. For example, for
+some kind of SGML output format:
+
+ print OUT "<!-- \n", $parser->version_report, "\n -->";
+
+
+=item C<< $parser->pod_para_count() >>
+
+This returns the count of Pod paragraphs seen so far.
+
+
+=item C<< $parser->line_count() >>
+
+This is the current line number being parsed. But you might find the
+"line_number" event attribute more accurate, when it is present.
+
+
+=item C<< $parser->nix_X_codes( I<SOMEVALUE> ) >>
+
+This attribute, when set to a true value (and it is false by default)
+ignores any "XE<lt>...E<gt>" sequences in the document being parsed.
+Many formats don't actually use the content of these codes, so have
+no reason to process them.
+
+=item C<< $parser->keep_encoding_directive( I<SOMEVALUE> ) >>
+
+This attribute, when set to a true value (it is false by default)
+will keep C<=encoding> and its content in the event structure. Most
+formats don't actually need to process the content of an C<=encoding>
+directive, even when this directive sets the encoding and the
+processor makes use of the encoding information. Indeed, it is
+possible to know the encoding without processing the directive
+content.
+
+=item C<< $parser->merge_text( I<SOMEVALUE> ) >>
+
+This attribute, when set to a true value (and it is false by default)
+makes sure that only one event (or token, or node) will be created
+for any single contiguous sequence of text. For example, consider
+this somewhat contrived example:
+
+ I just LOVE Z<>hotE<32>apple pie!
+
+When that is parsed and events are about to be called on it, it may
+actually seem to be four different text events, one right after another:
+one event for "I just LOVE ", one for "hot", one for " ", and one for
+"apple pie!". But if you have merge_text on, then you're guaranteed
+that it will be fired as one text event: "I just LOVE hot apple pie!".
+
+
+=item C<< $parser->code_handler( I<CODE_REF> ) >>
+
+This specifies code that should be called when a code line is seen
+(i.e., a line outside of the Pod). Normally this is undef, meaning
+that no code should be called. If you provide a routine, it should
+start out like this:
+
+ sub get_code_line { # or whatever you'll call it
+ my($line, $line_number, $parser) = @_;
+ ...
+ }
+
+Note, however, that sometimes the Pod events aren't processed in exactly
+the same order as the code lines are -- i.e., if you have a file with
+Pod, then code, then more Pod, sometimes the code will be processed (via
+whatever you have code_handler call) before the all of the preceding Pod
+has been processed.
+
+
+=item C<< $parser->cut_handler( I<CODE_REF> ) >>
+
+This is just like the code_handler attribute, except that it's for
+"=cut" lines, not code lines. The same caveats apply. "=cut" lines are
+unlikely to be interesting, but this is included for completeness.
+
+
+=item C<< $parser->pod_handler( I<CODE_REF> ) >>
+
+This is just like the code_handler attribute, except that it's for
+"=pod" lines, not code lines. The same caveats apply. "=pod" lines are
+unlikely to be interesting, but this is included for completeness.
+
+
+=item C<< $parser->whiteline_handler( I<CODE_REF> ) >>
+
+This is just like the code_handler attribute, except that it's for
+lines that are seemingly blank but have whitespace (" " and/or "\t") on them,
+not code lines. The same caveats apply. These lines are unlikely to be
+interesting, but this is included for completeness.
+
+
+=item C<< $parser->whine( I<linenumber>, I<complaint string> ) >>
+
+This notes a problem in the Pod, which will be reported to in the "Pod
+Errors" section of the document and/or send to STDERR, depending on the
+values of the attributes C<no_whining>, C<no_errata_section>, and
+C<complain_stderr>.
+
+=item C<< $parser->scream( I<linenumber>, I<complaint string> ) >>
+
+This notes an error like C<whine> does, except that it is not
+suppressible with C<no_whining>. This should be used only for very
+serious errors.
+
+
+=item C<< $parser->source_dead(1) >>
+
+This aborts parsing of the current document, by switching on the flag
+that indicates that EOF has been seen. In particularly drastic cases,
+you might want to do this. It's rather nicer than just calling
+C<die>!
+
+=item C<< $parser->hide_line_numbers( I<SOMEVALUE> ) >>
+
+Some subclasses that indiscriminately dump event attributes (well,
+except for ones beginning with "~") can use this object attribute for
+refraining to dump the "start_line" attribute.
+
+=item C<< $parser->no_whining( I<SOMEVALUE> ) >>
+
+This attribute, if set to true, will suppress reports of non-fatal
+error messages. The default value is false, meaning that complaints
+I<are> reported. How they get reported depends on the values of
+the attributes C<no_errata_section> and C<complain_stderr>.
+
+=item C<< $parser->no_errata_section( I<SOMEVALUE> ) >>
+
+This attribute, if set to true, will suppress generation of an errata
+section. The default value is false -- i.e., an errata section will be
+generated.
+
+=item C<< $parser->complain_stderr( I<SOMEVALUE> ) >>
+
+This attribute, if set to true will send complaints to STDERR. The
+default value is false -- i.e., complaints do not go to STDERR.
+
+=item C<< $parser->bare_output( I<SOMEVALUE> ) >>
+
+Some formatter subclasses use this as a flag for whether output should
+have prologue and epilogue code omitted. For example, setting this to
+true for an HTML formatter class should omit the
+"<html><head><title>...</title><body>..." prologue and the
+"</body></html>" epilogue.
+
+If you want to set this to true, you should probably also set
+C<no_whining> or at least C<no_errata_section> to true.
+
+=item C<< $parser->preserve_whitespace( I<SOMEVALUE> ) >>
+
+If you set this attribute to a true value, the parser will try to
+preserve whitespace in the output. This means that such formatting
+conventions as two spaces after periods will be preserved by the parser.
+This is primarily useful for output formats that treat whitespace as
+significant (such as text or *roff, but not HTML).
+
+=item C<< $parser->parse_empty_lists( I<SOMEVALUE> ) >>
+
+If this attribute is set to true, the parser will not ignore empty
+C<=over>/C<=back> blocks. The type of C<=over> will be I<empty>, documented
+above, L<events with an element_name of over-empty>.
+
+=back
+
+=head1 SEE ALSO
+
+L<Pod::Simple> -- event-based Pod-parsing framework
+
+L<Pod::Simple::Methody> -- like Pod::Simple, but each sort of event
+calls its own method (like C<start_head3>)
+
+L<Pod::Simple::PullParser> -- a Pod-parsing framework like Pod::Simple,
+but with a token-stream interface
+
+L<Pod::Simple::SimpleTree> -- a Pod-parsing framework like Pod::Simple,
+but with a tree interface
+
+L<Pod::Simple::Checker> -- a simple Pod::Simple subclass that reads
+documents, and then makes a plaintext report of any errors found in the
+document
+
+L<Pod::Simple::DumpAsXML> -- for dumping Pod documents as tidily
+indented XML, showing each event on its own line
+
+L<Pod::Simple::XMLOutStream> -- dumps a Pod document as XML (without
+introducing extra whitespace as Pod::Simple::DumpAsXML does).
+
+L<Pod::Simple::DumpAsText> -- for dumping Pod documents as tidily
+indented text, showing each event on its own line
+
+L<Pod::Simple::LinkSection> -- class for objects representing the values
+of the TODO and TODO attributes of LE<lt>...E<gt> elements
+
+L<Pod::Escapes> -- the module the Pod::Simple uses for evaluating
+EE<lt>...E<gt> content
+
+L<Pod::Simple::Text> -- a simple plaintext formatter for Pod
+
+L<Pod::Simple::TextContent> -- like Pod::Simple::Text, but
+makes no effort for indent or wrap the text being formatted
+
+L<Pod::Simple::HTML> -- a simple HTML formatter for Pod
+
+L<perlpod|perlpod>
+
+L<perlpodspec|perlpodspec>
+
+L<perldoc>
+
+=head1 SUPPORT
+
+Questions or discussion about POD and Pod::Simple should be sent to the
+pod-people@perl.org mail list. Send an empty email to
+pod-people-subscribe@perl.org to subscribe.
+
+This module is managed in an open GitHub repository,
+L<https://github.com/theory/pod-simple/>. Feel free to fork and contribute, or
+to clone L<git://github.com/theory/pod-simple.git> and send patches!
+
+Patches against Pod::Simple are welcome. Please send bug reports to
+<bug-pod-simple@rt.cpan.org>.
+
+=head1 COPYRIGHT AND DISCLAIMERS
+
+Copyright (c) 2002 Sean M. Burke.
+
+This library is free software; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+
+This program is distributed in the hope that it will be useful, but
+without any warranty; without even the implied warranty of
+merchantability or fitness for a particular purpose.
+
+=head1 AUTHOR
+
+Pod::Simple was created by Sean M. Burke <sburke@cpan.org>.
+But don't bother him, he's retired.
+
+Pod::Simple is maintained by:
+
+=over
+
+=item * Allison Randal C<allison@perl.org>
+
+=item * Hans Dieter Pearcey C<hdp@cpan.org>
+
+=item * David E. Wheeler C<dwheeler@cpan.org>
+
+=back
+
+=for notes
+Hm, my old podchecker version (1.2) says:
+ *** WARNING: node 'http://search.cpan.org/' contains non-escaped | or / at line 38 in file Subclassing.pod
+ *** WARNING: node 'http://lists.perl.org/showlist.cgi?name=pod-people' contains non-escaped | or / at line 41 in file Subclassing.pod
+Yes, L<...> is hard.
+
+
+=cut
diff --git a/Master/tlpkg/tlperl/lib/Pod/Text.pm b/Master/tlpkg/tlperl/lib/Pod/Text.pm
index f57256f2d93..87f9e816d00 100644
--- a/Master/tlpkg/tlperl/lib/Pod/Text.pm
+++ b/Master/tlpkg/tlperl/lib/Pod/Text.pm
@@ -38,7 +38,7 @@ use Pod::Simple ();
# We have to export pod2text for backward compatibility.
@EXPORT = qw(pod2text);
-$VERSION = '3.17';
+$VERSION = '3.18';
##############################################################################
# Initialization
@@ -301,7 +301,6 @@ sub start_document {
my ($self, $attrs) = @_;
if ($$attrs{contentless} && !$$self{ALWAYS_EMIT_SOMETHING}) {
$$self{CONTENTLESS} = 1;
- return;
} else {
delete $$self{CONTENTLESS};
}
@@ -727,6 +726,26 @@ sub parse_file {
return $self->SUPER::parse_file ($in);
}
+# Do the same for parse_lines, just to be polite. Pod::Simple's man page
+# implies that the caller is responsible for setting this, but I don't see any
+# reason not to set a default.
+sub parse_lines {
+ my ($self, @lines) = @_;
+ unless (defined $$self{output_fh}) {
+ $self->output_fh (\*STDOUT);
+ }
+ return $self->SUPER::parse_lines (@lines);
+}
+
+# Likewise for parse_string_document.
+sub parse_string_document {
+ my ($self, $doc) = @_;
+ unless (defined $$self{output_fh}) {
+ $self->output_fh (\*STDOUT);
+ }
+ return $self->SUPER::parse_string_document ($doc);
+}
+
##############################################################################
# Module return value and documentation
##############################################################################
@@ -736,6 +755,7 @@ __END__
=for stopwords
alt stderr Allbery Sean Burke's Christiansen UTF-8 pre-Unicode utf8 nourls
+parsers
=head1 NAME
@@ -788,7 +808,7 @@ not to throw an exception. C<pod> says to include a POD ERRORS section
in the resulting documentation summarizing the errors. C<none> ignores
POD errors entirely, as much as possible.
-The default is C<output>.
+The default is C<pod>.
=item indent
@@ -871,10 +891,24 @@ The column at which to wrap text on the right-hand side. Defaults to 76.
=back
-The standard Pod::Simple method parse_file() takes one argument, the file or
-file handle to read from, and writes output to standard output unless that
-has been changed with the output_fh() method. See L<Pod::Simple> for the
-specific details and for other alternative interfaces.
+The standard Pod::Simple method parse_file() takes one argument naming the
+POD file to read from. By default, the output is sent to C<STDOUT>, but
+this can be changed with the output_fh() method.
+
+The standard Pod::Simple method parse_from_file() takes up to two
+arguments, the first being the input file to read POD from and the second
+being the file to write the formatted output to.
+
+You can also call parse_lines() to parse an array of lines or
+parse_string_document() to parse a document already in memory. As with
+parse_file(), parse_lines() and parse_string_document() default to sending
+their output to C<STDOUT> unless changed with the output_fh() method.
+
+To put the output from any parse method into a string instead of a file
+handle, call the output_string() method instead of output_fh().
+
+See L<Pod::Simple> for more specific details on the methods available to
+all derived parsers.
=head1 DIAGNOSTICS
diff --git a/Master/tlpkg/tlperl/lib/Pod/Text/Termcap.pm b/Master/tlpkg/tlperl/lib/Pod/Text/Termcap.pm
index 86380606d8e..18ba7b20ff5 100644
--- a/Master/tlpkg/tlperl/lib/Pod/Text/Termcap.pm
+++ b/Master/tlpkg/tlperl/lib/Pod/Text/Termcap.pm
@@ -27,7 +27,7 @@ use vars qw(@ISA $VERSION);
@ISA = qw(Pod::Text);
-$VERSION = '2.07';
+$VERSION = '2.08';
##############################################################################
# Overrides
@@ -104,7 +104,7 @@ sub strip_format {
return $text;
}
-# Override the wrapping code to igore the special sequences.
+# Override the wrapping code to ignore the special sequences.
sub wrap {
my $self = shift;
local $_ = shift;
@@ -113,7 +113,7 @@ sub wrap {
my $width = $$self{opt_width} - $$self{MARGIN};
# $codes matches a single special sequence. $char matches any number of
- # special sequences preceeding a single character other than a newline.
+ # special sequences preceding a single character other than a newline.
# We have to do $shortchar and $longchar in variables because the
# construct ${char}{0,$width} didn't do the right thing until Perl 5.8.x.
my $codes = "(?:\Q$$self{BOLD}\E|\Q$$self{UNDL}\E|\Q$$self{NORM}\E)";
diff --git a/Master/tlpkg/tlperl/lib/Pod/Usage.pm b/Master/tlpkg/tlperl/lib/Pod/Usage.pm
index 73802bb28ce..f0dd8350f12 100644
--- a/Master/tlpkg/tlperl/lib/Pod/Usage.pm
+++ b/Master/tlpkg/tlperl/lib/Pod/Usage.pm
@@ -11,8 +11,8 @@ package Pod::Usage;
use strict;
use vars qw($VERSION @ISA @EXPORT);
-$VERSION = '1.61'; ## Current version of this package
-require 5.005; ## requires this Perl version or later
+$VERSION = '1.63'; ## Current version of this package
+require 5.006; ## requires this Perl version or later
#use diagnostics;
use Carp;
@@ -22,14 +22,13 @@ use File::Spec;
@EXPORT = qw(&pod2usage);
BEGIN {
- $Pod::Usage::Formatter ||=
- ( $] >= 5.005_58 ? 'Pod::Text' : 'Pod::PlainText');
+ $Pod::Usage::Formatter ||= 'Pod::Text';
eval "require $Pod::Usage::Formatter";
die $@ if $@;
@ISA = ( $Pod::Usage::Formatter );
}
-require Pod::Select;
+our $MAX_HEADING_LEVEL = 3;
##---------------------------------------------------------------------------
@@ -94,7 +93,7 @@ sub pod2usage {
## Default the input file
$opts{'-input'} = $0 unless (defined $opts{'-input'});
- ## Look up input file in path if it doesnt exist.
+ ## Look up input file in path if it doesn't exist.
unless ((ref $opts{'-input'}) || (-e $opts{'-input'})) {
my $basename = $opts{'-input'};
my $pathsep = ($^O =~ /^(?:dos|os2|MSWin32)$/i) ? ';'
@@ -192,6 +191,48 @@ sub new {
return $self;
}
+# This subroutine was copied in whole-cloth from Pod::Select 1.60 in order to
+# allow the ejection of Pod::Select from the core without breaking Pod::Usage.
+# -- rjbs, 2013-03-18
+sub _compile_section_spec {
+ my ($section_spec) = @_;
+ my (@regexs, $negated);
+
+ ## Compile the spec into a list of regexs
+ local $_ = $section_spec;
+ s{\\\\}{\001}g; ## handle escaped backward slashes
+ s{\\/}{\002}g; ## handle escaped forward slashes
+
+ ## Parse the regexs for the heading titles
+ @regexs = split(/\//, $_, $MAX_HEADING_LEVEL);
+
+ ## Set default regex for ommitted levels
+ for (my $i = 0; $i < $MAX_HEADING_LEVEL; ++$i) {
+ $regexs[$i] = '.*' unless ((defined $regexs[$i])
+ && (length $regexs[$i]));
+ }
+ ## Modify the regexs as needed and validate their syntax
+ my $bad_regexs = 0;
+ for (@regexs) {
+ $_ .= '.+' if ($_ eq '!');
+ s{\001}{\\\\}g; ## restore escaped backward slashes
+ s{\002}{\\/}g; ## restore escaped forward slashes
+ $negated = s/^\!//; ## check for negation
+ eval "m{$_}"; ## check regex syntax
+ if ($@) {
+ ++$bad_regexs;
+ carp qq{Bad regular expression /$_/ in "$section_spec": $@\n};
+ }
+ else {
+ ## Add the forward and rear anchors (and put the negator back)
+ $_ = '^' . $_ unless (/^\^/);
+ $_ = $_ . '$' unless (/\$$/);
+ $_ = '!' . $_ if ($negated);
+ }
+ }
+ return (! $bad_regexs) ? [ @regexs ] : undef;
+}
+
sub select {
my ($self, @sections) = @_;
if ($ISA[0]->can('select')) {
@@ -209,7 +250,7 @@ sub select {
my $sref = $self->{USAGE_SELECT};
## Compile each spec
for my $spec (@sections) {
- my $cs = Pod::Select::_compile_section_spec($spec);
+ my $cs = _compile_section_spec($spec);
if ( defined $cs ) {
## Store them in our sections array
push(@$sref, $cs);
@@ -246,7 +287,7 @@ sub _handle_element_end {
my @headings = @{$$self{USAGE_HEADINGS}};
for my $section_spec ( @{$$self{USAGE_SELECT}} ) {
my $match = 1;
- for (my $i = 0; $i < $Pod::Select::MAX_HEADING_LEVEL; ++$i) {
+ for (my $i = 0; $i < $MAX_HEADING_LEVEL; ++$i) {
$headings[$i] = '' unless defined $headings[$i];
my $regex = $section_spec->[$i];
my $negated = ($regex =~ s/^\!//);
@@ -300,7 +341,7 @@ sub preprocess_paragraph {
my $self = shift;
local $_ = shift;
my $line = shift;
- ## See if this is a heading and we arent printing the entire manpage.
+ ## See if this is a heading and we aren't printing the entire manpage.
if (($self->{USAGE_OPTIONS}->{-verbose} < 2) && /^=head/) {
## Change the title of the SYNOPSIS section to USAGE
s/^=head1\s+SYNOPSIS\s*$/=head1 USAGE/;
@@ -401,8 +442,7 @@ is 1, then the "SYNOPSIS" section, along with any section entitled
corresponding value is 2 or more then the entire manpage is printed.
The special verbosity level 99 requires to also specify the -sections
-parameter; then these sections are extracted (see L<Pod::Select>)
-and printed.
+parameter; then these sections are extracted and printed.
=item C<-sections>
@@ -454,9 +494,8 @@ output the POD.
=head2 Formatting base class
-The default text formatter depends on the Perl version (L<Pod::Text> or
-L<Pod::PlainText> for Perl versions E<lt> 5.005_58). The base class for
-Pod::Usage can be defined by pre-setting C<$Pod::Usage::Formatter> I<before>
+The default text formatter is L<Pod::Text>. The base class for Pod::Usage can
+be defined by pre-setting C<$Pod::Usage::Formatter> I<before>
loading Pod::Usage, e.g.:
BEGIN { $Pod::Usage::Formatter = 'Pod::Text::Termcap'; }
@@ -753,15 +792,18 @@ Tom Christiansen E<lt>tchrist@mox.perl.comE<gt>
=head1 ACKNOWLEDGMENTS
+rjbs for refactoring Pod::Usage to not use Pod::Parser any more.
+
Steven McDougall E<lt>swmcd@world.std.comE<gt> for his help and patience
with re-writing this manpage.
=head1 SEE ALSO
-B<Pod::Usage> is now a standalone distribution.
+B<Pod::Usage> is now a standalone distribution, depending on
+L<Pod::Text> which in turn depends on L<Pod::Simple>.
-L<Pod::Parser>, L<Pod::Perldoc>, L<Getopt::Long>, L<Pod::Find>, L<FindBin>,
-L<Pod::Text>, L<Pod::PlainText>, L<Pod::Text::Termcap>
+L<Pod::Perldoc>, L<Getopt::Long>, L<Pod::Find>, L<FindBin>,
+L<Pod::Text>, L<Pod::Text::Termcap>, L<Pod::Simple>
=cut