diff options
Diffstat (limited to 'Master/texmf-dist/source/lualatex/luacode/luacode.dtx')
| -rw-r--r-- | Master/texmf-dist/source/lualatex/luacode/luacode.dtx | 113 |
1 files changed, 85 insertions, 28 deletions
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} |