summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source')
-rw-r--r--Master/texmf-dist/source/latex/perltex/perltex.dtx180
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>