perltex 1.8 (28mar09)

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

2 files changed, 303 insertions, 38 deletions

diff --git a/Master/texmf-dist/source/latex/perltex/perltex.dtx b/Master/texmf-dist/source/latex/perltex/perltex.dtx
index 5c05584776d..51d6ae342fa 100644
--- a/Master/texmf-dist/source/latex/perltex/perltex.dtx
+++ b/Master/texmf-dist/source/latex/perltex/perltex.dtx
@@ -1,6 +1,6 @@
 % \iffalse meta-comment
 %
-% Copyright (C) 2007 Scott Pakin <scott+pt@pakin.org>
+% Copyright (C) 2009 Scott Pakin <scott+pt@pakin.org>
 % ---------------------------------------------------
 %
 % This file may be distributed and/or modified under the conditions of
@@ -22,7 +22,7 @@
 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
 %<package>\ProvidesPackage{perltex}
 %<*package>
-    [2007/12/10 v1.7 LaTeX macros for use with PerlTeX]
+    [2009/03/27 v1.8 LaTeX macros for use with PerlTeX]
 %</package>
 %
 %<*driver>
@@ -62,7 +62,7 @@
 %</driver>
 % \fi
 %
-% \CheckSum{579}
+% \CheckSum{594}
 %
 % \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
@@ -90,32 +90,57 @@
 % \DoNotIndex{\$, \', \(, \), \., \\, \{, \}, \^, \", \@}
 % \DoNotIndex{\@empty, \@ifnextchar, \@ifundefined, \@makeother, \@ne}
 % \DoNotIndex{\@permittedops}
-% \DoNotIndex{\active, \advance}
-% \DoNotIndex{\b, \begin, \begingroup, \btrapped}
+% \DoNotIndex{\A, \active, \advance}
+% \DoNotIndex{\b, \begin, \begingroup, \bgroup, \btrapped}
 % \DoNotIndex{\catcode, \csname}
-% \DoNotIndex{\d, \def}
-% \DoNotIndex{\edef, \else, \end, \endcsname, \endgroup, \expandafter}
+% \DoNotIndex{\d, \def, \documentclass}
+% \DoNotIndex{\E, \edef, \egroup, \else, \end, \endcsname, \endgroup}
+% \DoNotIndex{\expandafter}
 % \DoNotIndex{\fi}
 % \DoNotIndex{\gdef, \global}
 % \DoNotIndex{\ifeof, \ifnum, \ifx, \immediate}
 % \DoNotIndex{\let, \loop}
 % \DoNotIndex{\makeatletter, \makeatother, \MessageBreak}
-% \DoNotIndex{\n, \newcount, \newif, \newread, \newtoks, \newwrite}
+% \DoNotIndex{\n, \newcommand, \newcount, \newenvironment, \newif}
+% \DoNotIndex{\newread, \newtoks, \newwrite}
 % \DoNotIndex{\noexpand, \number}
-% \DoNotIndex{\protect}
+% \DoNotIndex{\obeyspaces}
+% \DoNotIndex{\ProcessOptions, \protect}
+% \DoNotIndex{\Q}
 % \DoNotIndex{\r, \relax, \repeat}
 % \DoNotIndex{\s, \space, \string}
 % \DoNotIndex{\TeX, \the}
 % \DoNotIndex{\W}
 %
+% \newcommand{\indexpkg}[1]{^^A               ^^A  Index a package name
+%   \index{#1=\textsf{#1} (package)}^^A
+%   \index{packages>#1=\textsf{#1}}^^A
+% }
+% \newcommand{\pkgname}[1]{^^A                ^^A  Name of an arbitrary package
+%   \textsf{#1}^^A
+%   \indexpkg{#1}^^A
+% }
 % \newcommand{\PerlTeX}{Perl\TeX{}}           ^^A  Name of the complete system
 % \newcommand{\perltex}{\texttt{perltex.pl}}  ^^A  Name of the Perl script
-% \newcommand{\perlmac}{\texttt{perltex.sty}} ^^A  Name of the LaTeX package
+% \newcommand{\perlmac}{^^A                   ^^A  Name of the LaTeX package
+%   \texttt{perltex.sty}^^A
+%   \indexpkg{perltex}^^A
+% }
 % \newcommand{\noperlmac}{\texttt{noperltex.sty}} ^^A  Name of the alternate LaTeX package
 % \newcommand{\XeTeX}{^^A                     ^^A  Name of the typesetting system
 %   X\lower0.5ex\hbox{\kern-0.15em\reflectbox{E}}\kern-0.1667em\TeX^^A
 % }
 %
+% ^^A  Typeset package options.
+% \newcommand{\DescribeOption}[1]{^^A
+%   \marginpar{\raggedleft\PrintDescribeEnv{#1}}}
+% \newcommand{\pkgoption}[1]{^^A
+%   \texttt{#1}^^A
+%   \index{#1=\texttt{#1} (package option)}^^A
+%   \index{package options>#1=\texttt{#1}}^^A
+% }
+%
+%
 % ^^A  Define an environment just like macro but for Perl scalars or lists.
 % \makeatletter
 % \newenvironment{perlmacro}[1]{^^A
@@ -414,6 +439,30 @@
 % well as |\begin| and |\end| are implicitly preceded by |\noexpand|.
 %
 %
+% \subsection{Making \perltex\ optional}
+% \label{sec:perltex-opt}
+%
+% Normally, \perlmac\ issues a \texttt{Document must be compiled using
+%   perltex} error if a document specifies |\usepackage{perltex}| but is
+% not compiled using \perltex.  However, sometimes \PerlTeX\ may be
+% needed merely to enhance a document's formatting without being
+% mandatory for compiling the document.  For such cases, the
+% \DescribeOption{optional}
+% \pkgoption{optional} package option instructs \perlmac\ only to note
+% that \texttt{Document was compiled without using the perltex script}
+% without aborting the compilation.
+% \DescribeMacro{\ifperl}
+% The author can then use the |\ifperl| macro to test if \perltex\ is
+% being used and, if not, provide alternative definitions for macros and
+% environments defined with |\perlnewcommand| and |\perlnewenvironment|.
+%
+% See Section~\ref{sec:complete-example} for a large \PerlTeX\ example
+% that uses \pkgoption{optional} and |\ifperl| to define an environment
+% one way if \perltex\ is detected and another way if not.  The text
+% preceding the example also shows how to enable a document to compile
+% even if \perlmac\ is not even installed.
+%
+%
 % \subsection{Invoking \perltex}
 % \label{sec:perltex-man}
 %
@@ -665,11 +714,191 @@
 % \clearpage
 %
 %
+% \subsection{A large, complete example}
+% \label{sec:complete-example}
+%
+% Suppose we want to define a |linkwords| environment that exhibits the
+% following characteristics:
+%
+% \begin{enumerate}
+%   \item All words that appear within the environment's body are
+%     automatically hyperlinked to a given URL that incorporates the
+%     lowercase version of the word somewhere within that URL\@.
+%
+%   \item The environment accepts an optional list of stop~words that
+%     should not be hyperlinked.
+%
+%   \item Paragraph breaks, nested environments, and other
+%     \LaTeX\ markup are allowed within the environment's body.
+% \end{enumerate}
+%
+% Because of the reliance on text manipulation (parsing the
+% environment's body into words, comparing each word against the list of
+% stop~words, distinguishing between text and \LaTeX\ markup, etc.),
+% these requirements would be difficult to meet without \PerlTeX\@.
+%
+% We use three packages to help define the |linkwords| environment:
+% \pkgname{perltex} for text manipulation, \pkgname{hyperref} for
+% creating hyperlinks, and \pkgname{environ} for gathering up the body
+% of an environment and passing it as an argument to a macro.  Most of
+% the work is performed by the \PerlTeX\ macro |\dolinkwords|, which
+% takes three arguments: a URL template that contains ``|\%s|'' as a
+% placeholder for a word from the text, a mandatory but possibly empty
+% space-separated list of lowercase stop~words, and the input text to
+% process.  |\dolinkwords| first replaces all sequences of the form
+% |\|\meta{letters}, |\begin{|\meta{letters}|}|, or
+% |\end{|\meta{letters}|}| with dummy alphanumerics but remembers which
+% dummy sequence corresponds with each original \LaTeX\ sequence.  The
+% macro then iterates over each word in the input text, formatting each
+% non-stop-word using the URL template.  Contractions (words containing
+% apostrophes) are ignored.  Finally, |\dolinkwords| replaces the dummy
+% sequences with the corresponding \LaTeX\ text and returns the result.
+% 
+% The |linkwords| environment itself is defined using the |\NewEnviron|
+% macro from the \pkgname{environ} package.  With |\NewEnviron|'s help,
+% |linkwords| accumulates its body into a |\BODY| macro and passes that
+% plus the URL template and the optional list of stop~words to
+% |\dolinkwords|.
+%
+% As an added bonus,
+% |\ifperl|\dots\linebreak[0]|\else|\dots\linebreak[0]|\fi| is used to
+% surround the definition of the |\dolinkwords| macro and |linkwords|
+% environment.  If the document is not run through \perltex, |linkwords|
+% is defined as a do-nothing environment that simply typesets its body
+% as~is.  Note that \perlmac\ is loaded with the \pkgoption{optional}
+% option to indicate that the document can compile without \perltex.
+% However, the user still needs \perlmac\ to avoid getting a
+% \texttt{File `perltex.sty' not found} error from \LaTeX\@.  To produce
+% a document that can compile even without \perlmac\ installed, replace
+% the |\usepackage[optional]{perltex}| line with the following
+% \LaTeX\ code:
+% 
+% \begin{samepage}
+% \begin{verbatim}
+%    \IfFileExists{perltex.sty}
+%                 {\usepackage[optional]{perltex}}
+%                 {\newif\ifperl}
+% \end{verbatim}
+% \end{samepage}
+%
+% A complete \LaTeX\ document is presented below.  This document, which
+% includes the definition and a use of the |linkwords| environment, can be
+% extracted from the \PerlTeX\ source code into a file called
+% |example.tex| by running
+%
+% \begin{verbatim}
+%    tex perltex.ins
+% \end{verbatim}
+%
+% In the following listing, line numbers are suffixed with ``X'' to
+% distinguish them from line numbers associated with \PerlTeX's source
+% code.
+%
+% \bigskip
+%
+% ^^A  We want the doc package to number and index the lines in our
+% ^^A  code listing, but we want to keep line numbers and index entries
+% ^^A  distinct from those of the PerlTeX package code.  The following
+% ^^A  machinations temporarily append an "X" to line numbers in the
+% ^^A  code listing and in the index.
+% \makeatletter
+% \let\theOldCodelineNo=\theCodelineNo
+% \def\theCodelineNo{\reset@font\scriptsize \arabic{CodelineNo}X}
+% \def\appendX#1{#1X}
+% \def\codeline@wrindex@ex#1{\if@filesw
+%   \immediate\write\@indexfile
+%   {\string\indexentry{#1\encapchar appendX}^^A
+%   {\number\c@CodelineNo}}\fi}
+% \ifcodeline@index
+%   \let\special@index=\codeline@wrindex@ex
+% \fi
+% \makeatother
+% \iffalse
+%<*example>
+% \fi
+%
+%    \begin{macrocode}
+\documentclass{article}
+\usepackage[optional]{perltex}
+\usepackage{environ}
+\usepackage{hyperref}
+
+\ifperl
+
+  \perlnewcommand{\dolinkwords}[3]{
+      # Preprocess our arguments.
+      $url = $_[0];
+      $url =~ s/\\\%s/\%s/g;
+      %stopwords = map {lc $_ => 1} split " ", $_[1];
+      $stopwords{""} = 1;
+      $text = $_[2];
+
+      # Replace LaTeX code in the text with placeholders.
+      $placeholder = "ABCxyz123";
+      %substs;
+      $replace = sub {$substs{$placeholder} = $_[0]; $placeholder++};
+      $text =~ s/\\(begin|end)\s+\{[a-z]+\}/$replace->($&)/gse;
+      $text =~ s/\\[a-z]+/$replace->($&)/gse;
+
+      # Hyperlink each word that's not in the stop list.
+      $newtext = "";
+      foreach $word (split /((?<=[-\A\s])[\'a-z]+\b)/i, $text) {
+          $lcword = lc $word;
+          if (defined $stopwords{$lcword} || $lcword =~ /[^a-z]/) {
+              $newtext .= $word;
+          }
+          else {
+              $newtext .= sprintf "\\href{$url}{%s}", $lcword, $word;
+          }
+      }
+
+      # Restore original text from placeholders and return the new text.
+      while (($tag, $orig) = each %substs) {
+          $newtext =~ s/\Q$tag\E/$orig/gs;
+      }
+      return $newtext;
+  }
+
+  \NewEnviron{linkwords}[2][]{\dolinkwords{#2}{#1}{\BODY}}{}
+
+\else
+
+  \newenvironment{linkwords}[2][]{}{}
+
+\fi
+
+\begin{document}
+
+\newcommand{\stopwords}{a an the of in am and or but i we me you us them}
+
+\begin{linkwords}[\stopwords]{http://www.google.com/search?q=define:\%s}
+\begin{verse}
+  I'm very good at integral and differential calculus; \\
+  I know the scientific names of beings animalculous:  \\
+  In short, in matters vegetable, animal, and mineral, \\
+  I am the very model of a modern Major-General.
+\end{verse}
+\end{linkwords}
+
+\end{document}
+%    \end{macrocode}
+%
+% \iffalse
+%</example>
+% \fi
+% \makeatletter
+% \ifcodeline@index
+%   \let\special@index=\codeline@wrindex
+% \fi
+% \let\theCodelineNo=\theOldCodelineNo
+% \makeatother
+%
+%
 % \StopEventually{^^A
 %   \section{License agreement}
 %   \label{sec:license}
 %
-%   Copyright \textcopyright{} 2007 Scott Pakin \texttt{<scott+pt@pakin.org>}
+%   Copyright \textcopyright{} 2009 Scott Pakin \texttt{<scott+pt@pakin.org>}
 %
 %   \providecommand{\url}[1]{\texttt{##1}}
 %
@@ -781,6 +1010,28 @@
 % \subsubsection{Package initialization}
 % \label{sec:package-init}
 %
+% \begin{macro}{\ifplmac@required}
+% \begin{macro}{\plmac@requiredtrue}
+% \begin{macro}{\plmac@requiredfalse}
+% The |optional| package option lets an author specify that the document
+% can be built successfully even without \PerlTeX\@.  Typically, this
+% means that the document uses |\ifperl| to help define
+% reduced-functionality equivalents of any document-defined
+% \PerlTeX\ macros and environments.  When |optional| is not specified,
+% \perlmac\ issues an error message if the document is compiled without
+% using \perltex.  When |optional| is specified, \perlmac\ suppresses
+% the error message.
+% \changes{v1.8}{2009/03/26}{Introduced an \texttt{optional} package
+%   option to suppress the ``must be compiled using perltex'' error
+%   message}
+%    \begin{macrocode}
+\newif\ifplmac@required \plmac@requiredtrue
+\DeclareOption{optional}{\plmac@requiredfalse} \ProcessOptions\relax
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
 % \PerlTeX{} defines six macros that are used for communication between
 % Perl and \LaTeX\@.  |\plmac@tag| is a string of characters that should
 % never occur within one of the user's macro names, macro arguments, or
@@ -825,9 +1076,9 @@
 %   \end{tabular}
 % \end{table}
 %
-% \begin{macro}{\ifplmac@have@perltex}
-% \begin{macro}{\plmac@have@perltextrue}
-% \begin{macro}{\plmac@have@perltexfalse}
+% \begin{macro}{\ifperl}
+% \begin{macro}{\perltrue}
+% \begin{macro}{\perlfalse}
 % The following block of code checks the existence of each of the
 % variables listed in Table~\ref{tbl:variables} plus |\plmac@pipe|, a
 % Unix named pipe used for to improve performance.  If any variable is
@@ -835,23 +1086,31 @@
 % on page~\pageref{page:define-dummies}---defines dummy versions of
 % |\perl|[|re|]|newcommand| and |\perl|[|re|]|newenvironment|.
 %    \begin{macrocode}
-\newif\ifplmac@have@perltex
-\plmac@have@perltextrue
-\@ifundefined{plmac@tag}{\plmac@have@perltexfalse}{}
-\@ifundefined{plmac@tofile}{\plmac@have@perltexfalse}{}
-\@ifundefined{plmac@fromfile}{\plmac@have@perltexfalse}{}
-\@ifundefined{plmac@toflag}{\plmac@have@perltexfalse}{}
-\@ifundefined{plmac@fromflag}{\plmac@have@perltexfalse}{}
-\@ifundefined{plmac@doneflag}{\plmac@have@perltexfalse}{}
-\@ifundefined{plmac@pipe}{\plmac@have@perltexfalse}{}
-\ifplmac@have@perltex
+\newif\ifperl
+\perltrue
+\@ifundefined{plmac@tag}{\perlfalse}{}
+\@ifundefined{plmac@tofile}{\perlfalse}{}
+\@ifundefined{plmac@fromfile}{\perlfalse}{}
+\@ifundefined{plmac@toflag}{\perlfalse}{}
+\@ifundefined{plmac@fromflag}{\perlfalse}{}
+\@ifundefined{plmac@doneflag}{\perlfalse}{}
+\@ifundefined{plmac@pipe}{\perlfalse}{}
+\ifperl
 \else
-  \PackageError{perltex}{Document must be compiled using perltex}
-    {Instead of compiling your document directly with latex, you need
-     to\MessageBreak use the perltex script.  \space perltex sets up
-     a variety of macros needed by\MessageBreak the perltex
-     package as well as a listener process needed for\MessageBreak
-     communication between LaTeX and Perl.}
+  \ifplmac@required
+    \PackageError{perltex}{Document must be compiled using perltex}
+      {Instead of compiling your document directly with latex, you need
+       to\MessageBreak use the perltex script.  \space perltex sets up
+       a variety of macros needed by\MessageBreak the perltex
+       package as well as a listener process needed for\MessageBreak
+       communication between LaTeX and Perl.}
+    \else
+      \bgroup
+        \obeyspaces
+        \typeout{perltex: Document was compiled without using the perltex script;}
+        \typeout{         it may not print as desired.}
+      \egroup
+  \fi
 \fi
 %    \end{macrocode}
 % \end{macro}
@@ -1675,8 +1934,12 @@
 % processing is encapsulated within |\plmac@write@perl@i|, this is the
 % only macro that strictly requires \perltex.  Consequently, we wrap the
 % entire macro definition within a check for \perltex.
+% \changes{v1.8}{2009/03/25}{Renamed
+%   \texttt{\string\string\string\ifplmac@have@perltex} to
+%   \texttt{\char`\\ ifperl} to help authors write
+%   mixed \string\LaTeX\string\slash\space \string\PerlTeX\ documents}
 %    \begin{macrocode}
-\ifplmac@have@perltex
+\ifperl
   \newcommand{\plmac@write@perl@i}[1]{%
 %    \end{macrocode}
 % The first step is to write argument |#1| to |\plmac@tofile|:
@@ -1843,7 +2106,7 @@
 #
 # This is a generated file.
 #
-# Copyright (C) 2007 Scott Pakin <scott+pt@pakin.org>
+# Copyright (C) 2009 Scott Pakin <scott+pt@pakin.org>
 #
 # This file may be distributed and/or modified under the conditions
 # of the LaTeX Project Public License, either version 1.3c of this
@@ -2511,8 +2774,8 @@ END {
 % accumulated the output from each \PerlTeX\ macro invocation into
 % |@macroexpansions|, and now we need to produce a
 % \noperlmac\ file.  We start by generating a boilerplate
-% header in which we set up the package and load both \perlmac\ and
-% \texttt{filecontents.sty}.
+% header in which we set up the package and load both \pkgname{perltex}
+% and \pkgname{filecontents}.
 %    \begin{macrocode}
         print STYFILE <<"STYFILEHEADER1";
 \\NeedsTeXFormat{LaTeX2e}[1999/12/01]
diff --git a/Master/texmf-dist/source/latex/perltex/perltex.ins b/Master/texmf-dist/source/latex/perltex/perltex.ins
index 256d0e34ed4..6abc0acbf3e 100644
--- a/Master/texmf-dist/source/latex/perltex/perltex.ins
+++ b/Master/texmf-dist/source/latex/perltex/perltex.ins
@@ -1,5 +1,5 @@
 %%
-%% Copyright (C) 2007 Scott Pakin <scott+pt@pakin.org>
+%% Copyright (C) 2009 Scott Pakin <scott+pt@pakin.org>
 %%
 %% This file may be distributed and/or modified under the conditions of
 %% the LaTeX Project Public License, either version 1.3c of this license
@@ -21,7 +21,7 @@
 
 This is a generated file.
 
-Copyright (C) 2007 Scott Pakin <scott+pt@pakin.org>
+Copyright (C) 2009 Scott Pakin <scott+pt@pakin.org>
 
 This file may be distributed and/or modified under the conditions of
 the LaTeX Project Public License, either version 1.3c of this license
@@ -35,7 +35,8 @@ and version 1.3c or later is part of all distributions of LaTeX version
 
 \endpreamble
 
-\generate{\file{perltex.sty}{\from{perltex.dtx}{package}}}
+\generate{\file{perltex.sty}{\from{perltex.dtx}{package}}
+          \file{example.tex}{\from{perltex.dtx}{example}}}
 \generate{\usepreamble\empty\usepostamble\empty
           \file{perltex.pl}{\from{perltex.dtx}{perltex}}}
 
@@ -57,7 +58,8 @@ and version 1.3c or later is part of all distributions of LaTeX version
 \Msg{* perltex.pl") and install perltex.bat in the same directory as         *}
 \Msg{* perltex.pl.                                                           *}
 \Msg{*                                                                       *}
-\Msg{* To produce the documentation run the file perltex.dtx through LaTeX.  *}
+\Msg{* To produce the documentation and a sample PerlTeX file, example.tex,  *}
+\Msg{* run the file perltex.dtx through LaTeX.                               *}
 \Msg{*                                                                       *}
 \Msg{* Happy TeXing!                                                         *}
 \Msg{*                                                                       *}