perltex update from ctan 07-12-11

git-svn-id: svn://tug.org/texlive/trunk@5762 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 98 insertions, 82 deletions

diff --git a/Master/texmf-dist/source/latex/perltex/perltex.dtx b/Master/texmf-dist/source/latex/perltex/perltex.dtx
index 84a1a5be833..5c05584776d 100644
--- a/Master/texmf-dist/source/latex/perltex/perltex.dtx
+++ b/Master/texmf-dist/source/latex/perltex/perltex.dtx
@@ -22,7 +22,7 @@
 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
 %<package>\ProvidesPackage{perltex}
 %<*package>
-    [2007/12/08 v1.6 LaTeX macros for use with PerlTeX]
+    [2007/12/10 v1.7 LaTeX macros for use with PerlTeX]
 %</package>
 %
 %<*driver>
@@ -62,7 +62,7 @@
 %</driver>
 % \fi
 %
-% \CheckSum{578}
+% \CheckSum{579}
 %
 % \CharacterTable
 %  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
@@ -112,7 +112,7 @@
 % \newcommand{\perltex}{\texttt{perltex.pl}}  ^^A  Name of the Perl script
 % \newcommand{\perlmac}{\texttt{perltex.sty}} ^^A  Name of the LaTeX package
 % \newcommand{\noperlmac}{\texttt{noperltex.sty}} ^^A  Name of the alternate LaTeX package
-% \newcommand{\XeTeX}{^^A                     ^^A  Used in the documentation
+% \newcommand{\XeTeX}{^^A                     ^^A  Name of the typesetting system
 %   X\lower0.5ex\hbox{\kern-0.15em\reflectbox{E}}\kern-0.1667em\TeX^^A
 % }
 %
@@ -457,7 +457,6 @@
 % [\textbf{--help}]
 % [\textbf{--latex}=\textit{program}]
 % [\textbf{--}[\textbf{no}]\textbf{safe}]
-% [\textbf{--}[\textbf{no}]\textbf{pipe}]
 % [\textbf{--permit}=\textit{feature}]
 % [\textbf{--makesty}]
 % [\textit{latex options}]
@@ -515,18 +514,6 @@
 % blanche} to execute any arbitrary Perl code, including that which can
 % harm the user's files.  See \emph{Safe} for more information.
 %
-% \item[{\textbf{-{}-}[\textbf{no}]\textbf{pipe}}] \mbox{}
-%
-% Enable or disable the named-pipe speed optimization.  By default
-% (\textbf{-{}-pipe}), communication between Perl and \LaTeX\ occurs
-% through a high-speed named pipe on operating systems that support
-% persistent named pipes (e.g.,~Linux).  Operating systems that lack
-% support for persistent named pipes (e.g.,~Windows) will automatically
-% fall back onto using slower, file-based communication.  Specifying
-% \textbf{-{}-nopipe} forces \PerlTeX\ to use the slower, file-based
-% communication on all platforms.  There have been reports of \PerlTeX\
-% failing under \XeTeX\ when run without \textbf{-{}-nopipe}.
-%
 % \item[{\textbf{-{}-permit}=\textit{feature}}] \mbox{}
 %
 % Permit particular Perl operations to be performed.  The
@@ -700,12 +687,15 @@
 %   \label{sec:acknowledgments}
 %
 %   Thanks to Andrew Mertz for writing the first draft of the code that
-%   produces the \PerlTeX-free \noperlmac\ style file and for testing the
-%   final draft; and to Andrei Alexandrescu for providing a few bug fixes.
-%   Also, thanks to the many people who have sent me fan mail or submitted
-%   bug reports, documentation corrections, or feature requests.  (The
-%   \texttt{\string\perldo} macro and the \texttt{--makesty} option were
-%   particularly popular requests.)
+%   produces the \PerlTeX-free \noperlmac\ style file and for testing
+%   the final draft; to Andrei Alexandrescu for providing a few bug
+%   fixes; and to Nick Andrewes for identifying and helping diagnose a
+%   problem running \PerlTeX\ with \XeTeX\ and to Jonathan Kew for
+%   suggesting a workaround.  Also, thanks to the many people who have
+%   sent me fan mail or submitted bug reports, documentation
+%   corrections, or feature requests.  (The \texttt{\string\perldo}
+%   macro and the \texttt{--makesty} option were particularly popular
+%   requests.)
 %
 %   \PrintChanges
 %   \PrintIndex
@@ -1916,26 +1906,30 @@ use strict;
 % \begin{perlmacro}{$latexprog}
 % \begin{perlmacro}{$runsafely}
 % \begin{perlmacro}{@permittedops}
+% \begin{perlmacro}{$usepipe}
 % |$latexprog| is the name of the \LaTeX{} executable
 % (e.g.,~``|latex|'').  If |$runsafely| is~|1| (the default), then the
-% user's Perl code runs in a secure sandbox; if it's |0|, then arbitrary
+% user's Perl code runs in a secure sandbox; if it's~|0|, then arbitrary
 % Perl code is allowed to run.  |@permittedops| is a list of features
 % made available to the user's Perl code.  Valid values are described in
 % Perl's |Opcode| manual page.  \perltex's default is a list containing
-% only |:browse|.
+% only |:browse|.  |$usepipe| is~|1| if \perltex\ should attempt to use
+% a named pipe for communicating with |latex| or~|0| if an ordinary file
+% should be used instead.
 %    \begin{macrocode}
 my $latexprog;
 my $runsafely = 1;
 my @permittedops;
+my $usepipe = 1;
 %    \end{macrocode}
 % \end{perlmacro}
 % \end{perlmacro}
 % \end{perlmacro}
+% \end{perlmacro}
 %
-% \paragraph{Other global variables}
+% \paragraph{Filename variables}
 % \begin{perlmacro}{$progname}
 % \begin{perlmacro}{$jobname}
-% \begin{perlmacro}{@latexcmdline}
 % \begin{perlmacro}{$toperl}
 % \begin{perlmacro}{$fromperl}
 % \begin{perlmacro}{$toflag}
@@ -1943,37 +1937,23 @@ my @permittedops;
 % \begin{perlmacro}{$doneflag}
 % \begin{perlmacro}{$logfile}
 % \begin{perlmacro}{$pipe}
-% \begin{perlmacro}{$usepipe}
-% \begin{perlmacro}{$styfile}
-% \begin{perlmacro}{@macroexpansions}
-% \begin{perlmacro}{$sandbox}
-% \begin{perlmacro}{$sandbox_eval}
-% \begin{perlmacro}{$latexpid}
 % |$progname| is the run-time name of the \perltex{} program.
 % |$jobname| is the base name of the user's |.tex| file, which defaults
-% to the \TeX{} default of |texput|.  |@latexcmdline| is the command
-% line to pass to the \LaTeX{} executable.  |$toperl| defines the
-% filename used for \LaTeX{}$\rightarrow$Perl communication.
-% |$fromperl| defines the filename used for Perl$\rightarrow$\LaTeX{}
-% communication.  |$toflag| is the name of a file that will exist only
-% after \LaTeX{} creates |$tofile|.  |$fromflag| is the name of a file
-% that will exist only after Perl creates |$fromfile|.  |$doneflag| is
-% the name of a file that will exist only after Perl deletes
-% |$fromflag|.  |$logfile| is the name of a log file to which \perltex{}
-% writes verbose execution information.  |$pipe| is the name of a Unix
-% named pipe (or ordinary file on operating systems that lack support
-% for persistent named pipes or in the case that |$usepipe| is set
-% to~|0|) used to convince the |latex| process to yield control of the
-% CPU\@.  |$styfile| is the string \noperlmac\ if \perltex\ is run with
-% \texttt{--makesty}, otherwise undefined.  |$sandbox| is a secure
-% sandbox in which to run code that appeared in the \LaTeX{} document.
-% |$sandbox_eval| is a subroutine that evalutes a string within
-% |$sandbox| (normally) or outside of all sandboxes (if |--nosafe| is
-% specified).  |$latexpid| is the process~ID of the |latex| process.
+% to the \TeX{} default of |texput|.  |$toperl| defines the filename
+% used for \LaTeX-to-Perl communication.  |$fromperl| defines the
+% filename used for Perl-to-\LaTeX{} communication.  |$toflag| is the
+% name of a file that will exist only after \LaTeX{} creates |$tofile|.
+% |$fromflag| is the name of a file that will exist only after Perl
+% creates |$fromfile|.  |$doneflag| is the name of a file that will
+% exist only after Perl deletes |$fromflag|.  |$logfile| is the name of
+% a log file to which \perltex{} writes verbose execution information.
+% |$pipe| is the name of a Unix named pipe (or ordinary file on
+% operating systems that lack support for persistent named pipes or in
+% the case that |$usepipe| is set to~|0|) used to convince the |latex|
+% process to yield control of the CPU\@.
 %    \begin{macrocode}
 my $progname = basename $0;
 my $jobname = "texput";
-my @latexcmdline;
 my $toperl;
 my $fromperl;
 my $toflag;
@@ -1981,12 +1961,6 @@ my $fromflag;
 my $doneflag;
 my $logfile;
 my $pipe;
-my $usepipe = 1;
-my $styfile;
-my @macroexpansions;
-my $sandbox = new Safe;
-my $sandbox_eval;
-my $latexpid;
 %    \end{macrocode}
 % \end{perlmacro}
 % \end{perlmacro}
@@ -1997,12 +1971,57 @@ my $latexpid;
 % \end{perlmacro}
 % \end{perlmacro}
 % \end{perlmacro}
+%
+% \paragraph{Other global variables}
+% \begin{perlmacro}{@latexcmdline}
+% \begin{perlmacro}{$styfile}
+% \begin{perlmacro}{@macroexpansions}
+% \begin{perlmacro}{$sandbox}
+% \begin{perlmacro}{$sandbox_eval}
+% \begin{perlmacro}{$latexpid}
+% |@latexcmdline| is the command line to pass to the \LaTeX{}
+% executable.  |$styfile| is the string \noperlmac{} if \perltex{} is run
+% with \texttt{--makesty}, otherwise undefined.  |@macroexpansions| is a
+% list of \PerlTeX{} macro expansions in the order they were encountered.
+% It is used for creating a \noperlmac{} file when \texttt{--makesty} is
+% specified.  |$sandbox| is a secure sandbox in which to run code that
+% appeared in the \LaTeX{} document.  |$sandbox_eval| is a subroutine
+% that evalutes a string within |$sandbox| (normally) or outside of all
+% sandboxes (if |--nosafe| is specified).  |$latexpid| is the process~ID
+% of the |latex| process.
+%    \begin{macrocode}
+my @latexcmdline;
+my $styfile;
+my @macroexpansions;
+my $sandbox = new Safe;
+my $sandbox_eval;
+my $latexpid;
+%    \end{macrocode}
 % \end{perlmacro}
 % \end{perlmacro}
 % \end{perlmacro}
 % \end{perlmacro}
 % \end{perlmacro}
 % \end{perlmacro}
+%
+% \begin{perlmacro}{$pipestring}
+% |$pipestring| is a constant string to write to the |$pipe| named pipe
+% (or file) at each \LaTeX{} synchronization point.  Its particular
+% definition is really a bug workaround for \XeTeX\@.  The current
+% version of \XeTeX{} reads the first few bytes of a file to determine
+% the character encoding (\mbox{UTF-8} or \mbox{UTF-16}, big-endian or
+% little-endian) then attempts to rewind the file pointer.  Because
+% pipes can't be rewound, the effect is that the first two bytes of
+% |$pipe| are discarded and the rest are input.  Hence, the
+% ``|\endinput|'' used in prior versions of \PerlTeX{} inserted a
+% spurious ``|ndinput|'' into the author's document.  We therefore
+% define |$pipestring| such that it will not interfere with the document
+% even if the first few bytes are discarded.
+% \changes{v1.7}{2007/12/09}{Introduced this variable as a workaround for
+%   \protect\XeTeX's attempt to rewind \texttt{\$pipe}}
+%    \begin{macrocode}
+my $pipestring = "\%\%\%\%\% Generated by $progname\n\\endinput\n";
+%    \end{macrocode}
 % \end{perlmacro}
 %
 % \subsubsection{Command-line conversion}
@@ -2016,17 +2035,27 @@ my $latexpid;
 % specified.  We then use |Getopt::Long| to parse the command line,
 % leaving any parameters we don't recognize in the argument vector
 % (|@ARGV|) because these are presumably |latex| options.
-% \changes{v1.6}{2007/12/07}{Added a \texttt{--nopipe} option
-%   to \protect\perltex\ to help it work with \protect\XeTeX}
+% \changes{v1.6}{2007/12/07}{Added an (undocumented) \texttt{--nopipe}
+%   option to \protect\perltex\ to help it work with \protect\XeTeX}
+% \changes{v1.7}{2007/12/09}{Added an (undocumented) \texttt{--synctext}
+%   option to alter the text written to \texttt{\$pipe}}
 %    \begin{macrocode}
 $latexprog = $ENV{"PERLTEX"} || "latex";
 Getopt::Long::Configure("require_order", "pass_through");
-GetOptions("help"     => sub {pod2usage(-verbose => 1)},
-           "latex=s"  => \$latexprog,
-           "safe!"    => \$runsafely,
-           "pipe!"    => \$usepipe,
-           "makesty"  => sub {$styfile = "noperltex.sty"},
-           "permit=s" => \@permittedops) || pod2usage(2);
+GetOptions("help"       => sub {pod2usage(-verbose => 1)},
+           "latex=s"    => \$latexprog,
+           "safe!"      => \$runsafely,
+%    \end{macrocode}
+% The following two options are undocumented because the defaults should
+% always suffice.  We're not yet removing these options, however, in
+% case they turn out to be useful for diagnostic purposes.
+%    \begin{macrocode}
+           "pipe!"      => \$usepipe,
+           "synctext=s" => \$pipestring,
+%    \end{macrocode}
+%    \begin{macrocode}
+           "makesty"    => sub {$styfile = "noperltex.sty"},
+           "permit=s"   => \@permittedops) || pod2usage(2);
 %    \end{macrocode}
 %
 % \paragraph{Preparing a \LaTeX{} command line}
@@ -2126,7 +2155,7 @@ if (defined $styfile) {
 %    \begin{macrocode}
 if (!$usepipe || !eval {mkfifo($pipe, 0600)}) {
     sysopen PIPE, $pipe, O_WRONLY|O_CREAT, 0755;
-    print PIPE "\\endinput\n";
+    print PIPE $pipestring;
     close PIPE;
     $usepipe = 0;
 }
@@ -2436,7 +2465,7 @@ while (1) {
 %    \end{macrocode}
 %    \begin{macrocode}
     if (open (PIPE, ">$pipe")) {
-        print PIPE "\\endinput\n";
+        print PIPE $pipestring;
         close PIPE;
     }
 %    \end{macrocode}
@@ -2454,7 +2483,7 @@ while (1) {
 % Again, we awaken the |latex| process, which is blocked on |$pipe|.
 %    \begin{macrocode}
     if (open (PIPE, ">$pipe")) {
-        print PIPE "\\endinput\n";
+        print PIPE $pipestring;
         close PIPE;
     }
 }
@@ -2577,7 +2606,6 @@ perltex
 [B<--help>]
 [B<--latex>=I<program>]
 [B<-->[B<no>]B<safe>]
-[B<-->[B<no>]B<pipe>]
 [B<--permit>=I<feature>]
 [B<--makesty>]
 [I<latex options>]
@@ -2630,18 +2658,6 @@ external programs.  Specifying B<--nosafe> gives the LaTeX document
 I<carte blanche> to execute any arbitrary Perl code, including that
 which can harm the user's files.  See L<Safe> for more information.
 
-=item B<-->[B<no>]B<pipe>
-
-Enable or disable the named-pipe speed optimization.  By default
-(B<--pipe>), communication between Perl and LaTeX occurs through a
-high-speed named pipe on operating systems that support persistent
-named pipes (e.g., Linux).  Operating systems that lack support for
-persistent named pipes (e.g., Windows) will automatically fall back
-onto using slower, file-based communication.  Specifying B<--nopipe>
-forces PerlTeX to use the slower, file-based communication on all
-platforms.  There have been reports of PerlTeX failing under XeTeX
-when run without B<--nopipe>.
-
 =item B<--permit>=I<feature>
 
 Permit particular Perl operations to be performed.  The B<--permit>