summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/saveenv
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2022-12-23 21:04:23 +0000
committerKarl Berry <karl@freefriends.org>2022-12-23 21:04:23 +0000
commit3380912e470b2169b6c54166d32f14d631d63270 (patch)
treee84177a9effa207f76020b4aff5f0d263dd299d3 /Master/texmf-dist/doc/latex/saveenv
parent8d383d484835575910b71ef5e1746d57be9afef3 (diff)
saveenv (23dec22)
git-svn-id: svn://tug.org/texlive/trunk@65340 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/saveenv')
-rw-r--r--Master/texmf-dist/doc/latex/saveenv/saveenv.pdfbin384203 -> 395762 bytes
-rw-r--r--Master/texmf-dist/doc/latex/saveenv/saveenv.tex78
2 files changed, 64 insertions, 14 deletions
diff --git a/Master/texmf-dist/doc/latex/saveenv/saveenv.pdf b/Master/texmf-dist/doc/latex/saveenv/saveenv.pdf
index 20bf11c9fd9..f93c230efa9 100644
--- a/Master/texmf-dist/doc/latex/saveenv/saveenv.pdf
+++ b/Master/texmf-dist/doc/latex/saveenv/saveenv.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/saveenv/saveenv.tex b/Master/texmf-dist/doc/latex/saveenv/saveenv.tex
index c6d4ba87bb8..5a5f741a250 100644
--- a/Master/texmf-dist/doc/latex/saveenv/saveenv.tex
+++ b/Master/texmf-dist/doc/latex/saveenv/saveenv.tex
@@ -1,5 +1,5 @@
%%! TEX program = lualatex
-\ProvidesFile{saveenv.tex} [2022/07/08 v0.0.0 ]
+\ProvidesFile{saveenv.tex} [2022/12/23 v0.0.1 ]
\documentclass{l3doc}
\EnableCrossrefs
\CodelineIndex
@@ -41,8 +41,8 @@ This package provides tools to create your own verbatim environments, and works
\begin{itemize}
\item \pkg{scontents} package is similar; however it does not allow programmer to programmatically retrieve the macro content, only do a limited number of actions with them (execute, typeset as verbatim code, etc.).
- \item \pkg{fancyvrb} and \pkg{verbatimcopy} provides some internal macro for defining similar environments, however they're internal.
- \item \pkg{filecontentsdef} and \pkg{newverbs} provides very similar facilities (\env{filecontentsdefmacro} environment and \tn{Collectverbenv} command respectively); however it requires \verb+\endlinechar=13+ and does not support \cs{ExplSyntaxOn} environment.
+ \item \pkg{fancyvrb}, \pkg{xsimverb} and \pkg{verbatimcopy} provides some internal macro for defining similar environments, however they're internal and/or too specialized (writes to file etc.).
+ \item \pkg{filecontentsdef} and \pkg{newverbs} provides very similar facilities (\env{filecontentsdefmacro} environment and |\Collectverbenv| command respectively); however it requires |\endlinechar=13| and does not support |\ExplSyntaxOn| environment.
\item \pkg{verbatim} provides facilities to define custom verbatim environment that processes the content line-by-line, however the interface is more complicated.
For comparison, the following code
@@ -80,7 +80,7 @@ This package provides tools to create your own verbatim environments, and works
\end{verbatim}
defines an environment that saves the data similar to \env{saveenv} environment described below (with the overhead of |\tl_build_*| functions),
-but inside \cs{ExplSyntaxOn} environment it generates a spurious space at the beginning of the string.
+but inside |\ExplSyntaxOn| environment it generates a spurious space at the beginning of the string.
\end{itemize}
@@ -91,17 +91,28 @@ but inside \cs{ExplSyntaxOn} environment it generates a spurious space at the be
Environment that saves its body.
For example, the following code
-
\begin{verbatim}
\begin{saveenv}{\data}
123
456
\end{saveenv}
\end{verbatim}
+will save the string \texttt{123\meta{newline}456\meta{newline}} globally into |\data|.
+
+Remark: it is consistent to keep the trailing newline, as
+\begin{verbatim}
+\begin{saveenv}{\data}
+\end{saveenv}
+\end{verbatim}
+will make |\data| empty, and
+\begin{verbatim}
+\begin{saveenv}{\data}
-will save the string \texttt{123\meta{newline}456} globally into \cs{data}.
+\end{saveenv}
+\end{verbatim}
+will make |\data| consist of a single \meta{newline}.
-The braces around \verb+{\data}+ is optional; however, in the unlikely case if \cs{endlinechar} has the \enquote{letter} catcode, it might be absorbed and gives unexpected result.
+The braces around |{\data}| is optional; however, in the unlikely case if \cs{endlinechar} has the \enquote{letter} catcode, it might be absorbed and gives unexpected result.
A newline is represented as a token with charcode 10 (|^^J|) and catcode other.
@@ -116,7 +127,7 @@ The assignment is global, and done before the macro \cs{endsaveenv} is executed.
The data is represented as an \pkg{expl3}-string, that is, a sequence of tokens with catcode 12 (for non-space characters) or 10 (for space character).
-In other words, the token list is equal to its own \cs{detokenize}.
+In other words, the token list is equal to its own |\detokenize|.
\DescribeEnv{saveenvghost}
Similar to above; however the content inside is still typesetted/executed, and the Sync\TeX\ information is preserved.
@@ -127,7 +138,43 @@ Note that this environment is implemented by reading the whole file from the beg
Similar to above; however the final newline and the space characters before \texttt{\cs{end}\{\meta{environment name}\}} are preserved.
For example, the example above with \texttt{saveenv} replaced with \texttt{saveenvkeeplast}
-will save the string \texttt{123\meta{newline}456\meta{newline}} into \cs{data} instead.
+will save the string \texttt{123\meta{newline}456\meta{newline}} into |\data| instead.
+
+\section{Reinsert environments}
+
+Sometimes it's desirable to execute something (e.g. do some local assignments) after the group ends.
+
+There are a few options:
+\begin{itemize}
+ \item use |\aftergroup|,
+ \item close the group, execute the code and open a new one (remember to preserve the value of |\@currenvir|),
+ \item use one of the environments below.
+\end{itemize}
+
+\DescribeEnv{saveenvreinsert}
+Environment that takes two arguments, the \meta{str var} to be set and the code to be put after the group end.
+
+Usage example: If the following code is executed
+\begin{verbatim}
+\begin{saveenvreinsert}{\data}{\myfunction {args etc.}}
+123
+456
+\end{saveenvreinsert}
+some other content
+\end{verbatim}
+the effect would be identical to as if |\data| is set to \texttt{123\meta{newline}456\meta{newline}},
+then the following code is executed
+\begin{verbatim}
+\myfunction {args etc.}some other content
+\end{verbatim}
+If the second argument is empty, this environment is identical to the \env{saveenv} environment.
+
+Note that in the example above |\myfunction| is executed after the group ends,
+while any code in the second block of the |\NewDocumentEnvironment| definition
+would be executed before the group ends (such as in the example below), thus any local assignment will not persist.
+
+\DescribeEnv{saveenvkeeplastreinsert}
+Same as above, but the trailing whitespaces (after the last newline) are preserved.
\section{Extending the environments}
@@ -148,6 +195,8 @@ For example, the following definition
\end{verbatim}
will define an environment \env{custom} that prints out the content inside the environment using |\tl_show:N|.
+Note that in this case |\tl_show:N \data| is executed before the group ends.
+
\section{Limitation}
\begin{itemize}
@@ -157,13 +206,15 @@ will define an environment \env{custom} that prints out the content inside the e
Nevertheless, in modern computers, the overhead is negligible.
\item In case it's desired to typeset the content afterwards, it's difficult to preserve the Sync\TeX\ data.
+
+ (although with Lua\LaTeX\ it's possible, see \pkg{rescansync} package)
\end{itemize}
\item Currently nested environments with the same name are not supported (unlike \pkg{scontents} package).
- \item Note that there must be nothing after the \texttt{\cs{begin}\{\meta{environment name}\}} or the \texttt{\cs{end}\{\meta{environment name}\}} line.
+ \item Note that there must be nothing after the |\begin|\texttt{\{\meta{environment name}\}} or the |\end|\texttt{\{\meta{environment name}\}} line.
- \item Note that \texttt{\cs{end}\{\meta{environment name}\}} must not be in the middle of any line.
+ \item Note that |\end|\texttt{\{\meta{environment name}\}} must not be in the middle of any line.
\item The \cs{endlinechar} must not be tokenized in advance (or if it is, its catcode must be 12/other).
This might happen when for example your environment looks ahead for optional argument.
@@ -172,10 +223,9 @@ will define an environment \env{custom} that prints out the content inside the e
Alternatively, you can
\begin{itemize}
\item manually remove the end line token,
- \item set \verb+\endlinechar=-1\relax+ before calling \cs{saveenv}
- \item (optional) reset the value of \cs{endlinechar} afterwards.
-
+ \item set |\endlinechar=-1\relax| inside the environment before calling \cs{saveenv}.
\end{itemize}
+ The value of |\endlinechar| will automatically be reset after the group of the environment is closed.
\end{itemize}