luacode (23jan12)

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

5 files changed, 93 insertions, 30 deletions

diff --git a/Master/texmf-dist/doc/lualatex/luacode/News b/Master/texmf-dist/doc/lualatex/luacode/News
index fb5dde8675a..74a12418f79 100644
--- a/Master/texmf-dist/doc/lualatex/luacode/News
+++ b/Master/texmf-dist/doc/lualatex/luacode/News
@@ -1,3 +1,7 @@
+2012/01/23 v1.2a
+    * fix spurious space
+    * clarify doc about backslashes and Lua strings (sugg. by Herbert)
+
 2011/12/29 v1.2
     * new helper macros \luastring, \luastringO, \luastringN
     * new debug (logging) feature
diff --git a/Master/texmf-dist/doc/lualatex/luacode/luacode.pdf b/Master/texmf-dist/doc/lualatex/luacode/luacode.pdf
index bdfc949579c..7c3e7b7cecc 100644
--- a/Master/texmf-dist/doc/lualatex/luacode/luacode.pdf
+++ b/Master/texmf-dist/doc/lualatex/luacode/luacode.pdf
diff --git a/Master/texmf-dist/source/lualatex/luacode/Makefile b/Master/texmf-dist/source/lualatex/luacode/Makefile
index 86534b2bad9..dcc90a75a98 100644
--- a/Master/texmf-dist/source/lualatex/luacode/Makefile
+++ b/Master/texmf-dist/source/lualatex/luacode/Makefile
@@ -5,6 +5,7 @@ DTX       = $(NAME).dtx
 DOC       = $(NAME).pdf
 STY       = $(NAME).sty
 TEST      = test-$(NAME).tex
+TESTLOG   = test-$(NAME).log
 
 UNPACKED  = $(STY) $(TEST)
 GENERATED = $(UNPACKED) $(DOC)
@@ -41,6 +42,7 @@ $(UNPACKED): $(DTX)
 
 check: $(UNPACKED)
 	lualatex -interaction=batchmode $(TEST) >/dev/null
+	! grep 'blank space' $(TESTLOG)
 
 $(CTAN_ZIP): $(DOC) $(SOURCES) $(TDS_ZIP)
 	@echo "Making $@ for CTAN upload."
diff --git a/Master/texmf-dist/source/lualatex/luacode/luacode.dtx b/Master/texmf-dist/source/lualatex/luacode/luacode.dtx
index 4b0ca0ecf00..def0572f7cf 100644
--- a/Master/texmf-dist/source/lualatex/luacode/luacode.dtx
+++ b/Master/texmf-dist/source/lualatex/luacode/luacode.dtx
@@ -124,7 +124,7 @@ See the source file for author and licensing information.
 %
 % \title{The \pk{luacode} package}
 % \author{Manuel P\'egouri\'e-Gonnard \email{mpg@elzevir.fr}}
-% \date{v1.2 2011/12/29}
+% \date{v1.2a 2012/01/23}
 %
 % \maketitle
 %
@@ -133,7 +133,8 @@ See the source file for author and licensing information.
 % tricky: there is no easy way to use the percent character, counting
 % backslashes may be hard, and Lua comments don't work the way you expect.
 % This package provides the |\luaexec| command and the |luacode(*)|
-% environments to help with these problems.
+% environments to help with these problems, as well as helper macros and a
+% debugging mode.
 % \end{abstract}
 %
 % \tableofcontents
@@ -161,33 +162,34 @@ See the source file for author and licensing information.
 % The problems with |\directlua| (or |\luadirect|) are mainly with \TeX\
 % special characters. Actually, things are not that bad, since most special
 % characters do work, namely: |_|, |^|, |&|, \verb+$+, |{|, |}|. Three are a
-% bit tricky but they can be managed with |\string|: |\| and |~|. Only |%| is
-% really hard to obtain. Also, \TeX\ macros are expanded, which is good since
-% it allows to pass information from \TeX\ to Lua, but you must be careful
-% and use only purely expandable macros.
+% bit tricky but they can be managed with |\string|: |\|, |#| and |~|. Only
+% |%| is really hard to obtain. Also, \TeX\ macros are expanded, which is good
+% since it allows to pass information from \TeX\ to Lua, but you must be
+% careful and use only purely expandable macros.
 %
 % \DescribeMacro\luaexec
 % The |\luaexec| command is similar to |\luadirect| but with a few additional
 % features:\footnote{And one major drawback: it is not purely expandable. See
-% previous note.} |\\| gives a double backslash (convenient in Lua strings),
-% |\%| a percent character, and |~| just works. If you happen to need a single
-% backslash, you can still use a construct like |\string\n| just as with
-% |\luadirect|. Also, \TeX\ macros are expanded.
+% previous note.} |\\| gives a double backslash (see note below)
+% |\%| a percent character, and |~| just works. For single backslashes,
+% |\string| is still needed.  Also, \TeX\ macros are expanded.
 %
 % \DescribeEnv{luacode}
-% The |luacode| environment is similar, except that you can use |%| and other
-% special characters directly (but |\%| also works). Only the backslash and
-% the braces keep their special meaning, so that macros still work as usual,
-% and you still need to use a |\string| trick to get a single backslash.
-% Technical note: you are supposed to leave a space (or end-of-line) after
-% the |\begin{luacode}|, which is probably a natural thing to do anyway.
+% The |luacode| environment is similar to |\luaexec|, except that you can now
+% use |%| and |#| directly (but |\%| and |\#| also work) and the line breaks
+% are respected, so that you can use line-wise Lua comments in the normal way,
+% without mistakenly commenting the rest of the chunk.
+%
+% Only the backslash and the braces keep their special meaning, so that macros
+% still work as usual, and you still need to use |\string| to get a single
+% backslash.
 %
 % \DescribeEnv{luacode*}
-% A variant |luacode*| goes further and makes even backslash a normal
+% The variant |luacode*| goes further and makes even backslash a normal
 % character, so that you don't need any trick to obtain a single backslash. On
-% the other end, macros don't work any more.  In addition, the line breaks in
-% the environments are respected, so that you can use line-wise Lua comments
-% in the normal way, without mistakenly commenting the rest of the chunk.
+% the other end, macros don't work any more. So, the content of a |luacode*|
+% is interpreted exactly as if it were in a normal Lua file, directly fed to
+% the Lua interpreter without any \TeX\ intervention.
 %
 % \medskip
 %
@@ -200,7 +202,7 @@ See the source file for author and licensing information.
 %                         & |\luadirect|    & |\luaexec|      & |luacode|       & |luacode*|   \\
 %     \midrule
 %     Macros              & Yes             & Yes             & Yes             & No           \\
-%     Single backslash    & Using |\string| & Using |\string| & Using |\string| & Just |\|     \\
+%     Single backslash    & |\string\|      & |\string\|      & |\string\|      & Just |\|     \\
 %     Double backslash    & |\string\\|     & |\\|            & |\\|            & |\\|         \\
 %     Tilde               & |\string~|      & |~|             & |~|             & |~|          \\
 %     Sharp               & |\string#|      & |\#|            & |#| (or |\#|)   & |#|          \\
@@ -211,12 +213,47 @@ See the source file for author and licensing information.
 %   \end{tabular}
 % \end{center}
 %
+% \noindent\textbf{Backslashes and Lua strings.}
+% In the table and descriptions above, ``double backslash'' means that the Lua
+% interpreter will see a double backslash. It may then turn it into a single
+% backslash in the context of a Lua string delimited by single or double quotes
+% as opposed to a Lua string delimited by brackets, see
+% \href{http://www.lua.org/pil/2.4.html}{\emph{Programming in Lua} section
+% 2.4}. Similarly, a single backslash may or may not be interpreted as
+% starting an escape sequence. For example:
+% \begin{verbatim}
+% \begin{luacode}
+% a = "\\"      -- a contains a single backslash
+% b = [[\\]]    -- b contains two backslashes
+% c = "\\\\"    -- c contains two backslashes too
+% d = "line one\nline two"  -- d contains a newline character
+% e = [[single\nline]]      -- e contains no newline character
+% \end{luacode}
+% \end{verbatim}
+% The alert reader may notice that in the case of |\luadirect| and |\luaexec|,
+% single backslashes are a bit weird. For example with
+% \begin{verbatim}
+% \luaexec{texio.write_nl("line one\string\nline two")}
+% \end{verbatim}
+% \TeX\ will see |\nline| as a control sequence which is the ``argument'' of
+% |\string| and the Lua interpreter will consider only |\n| as an escape
+% sequence, and |line| as independent characters. In practice, this should not
+% have any unwanted consequences (except perhaps on the sanity of the reader).
+%
+% \medskip
+%
+% \noindent\textbf{Technical notes on environments.}
 % \DescribeEnv{luacodestar}
-% Note that you cannot use the environments inside the argument of a command
-% (just as with verbatim commands and environments).  If you wish to define
-% derived environments, you'll need to use |\luacode| \dots |\endluacode|
-% instead of the usual |\begin| |\end| pair in your environment's definition.
-% For the stared variant, use |\luacodestar| and |\endluacodestar|.
+% The environments will not work inside the argument of a command (just as
+% with verbatim commands and environments).  Also, you are supposed to leave a
+% space (or end-of-line) after the |\begin{luacode}| or |\begin{luacode*}|,
+% which is probably a natural thing to do anyway.  Finally, if you wish to
+% define derived environments, you'll need to use |\luacode| \dots
+% |\endluacode| instead of the usual |\begin| |\end| pair in your
+% environment's definition.  For the stared variant, use |\luacodestar| and
+% |\endluacodestar|.
+%
+% \medskip
 %
 % The test file (section~\ref{test}, or \file{test-luacode.tex} in the same
 % directory as this document) provides stupid but complete examples.
@@ -317,7 +354,7 @@ See the source file for author and licensing information.
 %    Package declaration.
 %
 %    \begin{macrocode}
-\ProvidesPackage{luacode}[2011/12/29 v1.2 lua-in-tex helpers (mpg)]
+\ProvidesPackage{luacode}[2012/01/23 v1.2a lua-in-tex helpers (mpg)]
 %    \end{macrocode}
 %
 %    Make sure Lua\TeX\ is used.
@@ -441,7 +478,7 @@ See the source file for author and licensing information.
 %    token.
 %
 %    \begin{macrocode}
-\newcommand \luacode@grab@body [1] {
+\newcommand \luacode@grab@body [1] {%
   \luacode@lines{}%
   \endlinechar10
   \luacode@grab@lines}
@@ -556,6 +593,9 @@ See the source file for author and licensing information.
 %
 %    \section{Test file} \label{test}
 %
+%    TODO: this test files requires manual checking that the output (pdf and
+%    log file) is correct; this should be fixed.
+%
 %    \begin{macrocode}
 %<*testlatex>
 \documentclass{minimal}
@@ -657,6 +697,23 @@ stringN: \texttt{\luadirect{myfunc(\luastringN\mac)}}\par
 \LuaCodeDebugOff
 \luadirect{local rem = 'dbg should be disabled here'}
 
+%    \end{macrocode}
+%
+%    Now track spurious spaces. This is the only part that is automatically
+%    checked, using grep in the Makefile.
+%
+%    \begin{macrocode}
+\tracingcommands1
+\luadirect{local foo}%
+\luaexec{local foo}%
+\begin{luacode}
+  local foo
+\end{luacode}
+\begin{luacode*}
+  local foo
+\end{luacode*}
+\tracingcommands0
+
 \end{document}
 %</testlatex>
 %    \end{macrocode}
diff --git a/Master/texmf-dist/tex/lualatex/luacode/luacode.sty b/Master/texmf-dist/tex/lualatex/luacode/luacode.sty
index 6acca9a7149..f8de0e467d3 100644
--- a/Master/texmf-dist/tex/lualatex/luacode/luacode.sty
+++ b/Master/texmf-dist/tex/lualatex/luacode/luacode.sty
@@ -42,7 +42,7 @@
     \noexpand\else \noexpand\expandafter\noexpand\endinput%
     \noexpand\fi}%
 \expandafter\y\csname luacode@sty@endinput\endcsname%
-\ProvidesPackage{luacode}[2011/12/29 v1.2 lua-in-tex helpers (mpg)]
+\ProvidesPackage{luacode}[2012/01/23 v1.2a lua-in-tex helpers (mpg)]
 \RequirePackage{ifluatex}
 \ifluatex\else
   \PackageError{luacode}{LuaTeX is required for this package. Aborting.}{%
@@ -99,7 +99,7 @@
 \newtoks\luacode@lines
 \newcommand*\luacode@addline [1] {%
   \luacode@lines\expandafter{\the\luacode@lines#1^^J}}
-\newcommand \luacode@grab@body [1] {
+\newcommand \luacode@grab@body [1] {%
   \luacode@lines{}%
   \endlinechar10
   \luacode@grab@lines}