diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/perltex')
| -rw-r--r-- | Master/texmf-dist/source/latex/perltex/perltex.dtx | 180 |
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> |