summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2022-07-09 20:14:09 +0000
committerKarl Berry <karl@freefriends.org>2022-07-09 20:14:09 +0000
commit2214af530f51d678e1e121ac55c9d635813abea0 (patch)
tree6aa048695f5bf1f403235283ff4d48313230f2b4 /Master/texmf-dist/doc/latex
parent846bdc65a718e70cfba2eb3d87f4eb6d475b8f83 (diff)
rescansync (9jul22)
git-svn-id: svn://tug.org/texlive/trunk@63856 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex')
-rw-r--r--Master/texmf-dist/doc/latex/rescansync/README24
-rw-r--r--Master/texmf-dist/doc/latex/rescansync/rescansync.pdfbin0 -> 378207 bytes
-rw-r--r--Master/texmf-dist/doc/latex/rescansync/rescansync.tex162
3 files changed, 186 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/rescansync/README b/Master/texmf-dist/doc/latex/rescansync/README
new file mode 100644
index 00000000000..27851c5f619
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/rescansync/README
@@ -0,0 +1,24 @@
+rescansync -- Re-scan tokens with synctex information
+Allow users to execute saved code to typeset text while preserving Sync\TeX\ information.
+
+Released under the LaTeX Project Public License v1.3c or later
+See http://www.latex-project.org/lppl.txt
+
+Report bugs at https://github.com/user202729/TeXlib
+
+========
+
+Copyright 2022 user202729
+
+This work may be distributed and/or modified under the conditions of the
+LaTeX Project Public License (LPPL), either version 1.3c of this license or
+(at your option) any later version. The latest version of this license is in
+the file:
+
+ http://www.latex-project.org/lppl.txt
+
+This work has the LPPL maintenance status `maintained'.
+
+The Current Maintainer of this work is user202729.
+
+This work consists of the files rescansync.sty.
diff --git a/Master/texmf-dist/doc/latex/rescansync/rescansync.pdf b/Master/texmf-dist/doc/latex/rescansync/rescansync.pdf
new file mode 100644
index 00000000000..67d2c7c790c
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/rescansync/rescansync.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/rescansync/rescansync.tex b/Master/texmf-dist/doc/latex/rescansync/rescansync.tex
new file mode 100644
index 00000000000..c68dd3e29d5
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/rescansync/rescansync.tex
@@ -0,0 +1,162 @@
+%%! TEX program = lualatex
+\ProvidesFile{rescansync.tex} [2022/07/09 v0.0.0 ]
+\documentclass{l3doc}
+\EnableCrossrefs
+\CodelineIndex
+\RecordChanges
+\fvset{gobble=0,tabsize=4,frame=single,numbers=left,numbersep=3pt}
+\usepackage{hyperref}
+\usepackage{csquotes}
+
+%\MakeOuterQuote{"}
+\begin{document}
+\GetFileInfo{\jobname.tex}
+
+\title{\textsf{rescansync} --- Re-scan tokens with synctex information
+\thanks{This file describes version \fileversion, last revised \filedate.}
+}
+\author{user202729%
+%\thanks{E-mail: (not set)}
+}
+\date{Released \filedate}
+
+\maketitle
+
+\begin{abstract}
+Allow users to execute saved code to typeset text while preserving Sync\TeX\ information.
+\end{abstract}
+
+\section{Simple interface}
+
+\DescribeEnv{rescansyncSaveenvPacked}
+Saves the environment body into the specified macro after the environment name, with additional information required to execute it later.
+
+The macro is stored in some internal format. If the user want to modify the content, use one of the advanced interface described below.
+
+Requires the \pkg{saveenv} and \pkg{currfile} package to be loaded. If you want to save the environment body using some other package, use the advanced interface.
+
+\begin{function}{\rescansyncPacked}
+ \begin{syntax}
+ \tn{rescansyncPacked} \meta{macro}
+ \end{syntax}
+ Execute the stored content in \meta{macro}.
+
+ The content must be stored with \env{rescansyncSaveenvPacked} environment or similar.
+\end{function}
+
+To give an usage example: the following code
+\begin{verbatim}
+% the following line will save the content "123 456"
+% and some auxiliary information into the macro \mycontent.
+\begin{rescansyncSaveenvPacked}{\mycontent}
+123
+
+456
+\end{rescansyncSaveenvPacked}
+
+% the following line will typeset 789 as usual.
+789
+
+% the following line will typeset "123 456".
+\rescansyncPacked{\mycontent}
+\end{verbatim}
+will typeset \enquote{789 123 456} as 3 separate paragraphs, with Sync\TeX\ information preserved.
+
+If the engine is not \LuaTeX, there will still be limited Sync\TeX\ information that points to a temporary file, but the line number is preserved.
+
+\DescribeEnv{rescansyncSaveenvghostPacked}
+The usage of this environment is similar to the \env{rescansyncSaveenvPacked} above, except that the content is still typeset with Sync\TeX\ information preserved while it's stored.
+
+In the example above, if this environment is used instead
+\begin{verbatim}
+\begin{rescansyncSaveenvghostPacked}{\mycontent}
+123
+
+456
+\end{rescansyncSaveenvghostPacked}
+
+789
+
+\rescansyncPacked{\mycontent}
+\end{verbatim}
+the content typeset will be \enquote{123 456 789 123 456}.
+
+As with \env{saveenvghost} environment (read \pkg{saveenv} package documentation for more details), the Sync\TeX\ information of the first section is guaranteed to be preserved, but there might be some performance hit.
+
+\section{Advanced interface}
+
+\begin{function}{\rescansync:nn}
+ \begin{syntax}
+ \cs{rescansync:nn} \Arg{content} \Arg{line offset}
+ \end{syntax}
+ Execute (rescan) the \Arg{content}. Requires \pkg{currfile}.
+
+ Details: \Arg{content} will be detokenized, and characters with char code 10 will be interpreted as a line break
+ (the behavior is inherited from |\iow_now:Nn| function. As a consequence, it's not allowed to write literal character with char code 10 to the file;
+ however this is not very useful regardless because on some operating systems this is equivalent to a real newline)
+
+ \Arg{line offset} is some non-negative number. If it's 0 then the first line of \Arg{content} corresponds to the first line in the target file.
+
+ Remark: If \pkg{newverbs}, \pkg{xparse} or \pkg{filecontentsdef} is used to collect multiline verbatim environment,
+ they have the line separation characters separated by character with char code 13 by default, you need to
+ manually replace them.
+
+ Even though the Sync\TeX\ information points to the correct file, if there's some error the temporary file name (which has the form
+ \texttt{RS\meta{number}-\meta{file name}} will be shown.
+
+ Engines other than \LuaTeX\ has the limitations described above.
+\end{function}
+
+\begin{function}{\rescansync:nnn}
+ \begin{syntax}
+ \cs{rescansync:nnn} \Arg{content} \Arg{line offset} \Arg{file name}
+ \end{syntax}
+
+ Similar to above, but use \Arg{file name} as the temporary file name. (only important in error messages, the Sync\TeX\ information
+ points to the file that the content is scanned.)
+\end{function}
+
+\begin{function}{\rescansync:nnnn}
+ \begin{syntax}
+ \cs{rescansync:nnnn} \Arg{content} \Arg{line offset} \Arg{file name} \Arg{Sync\TeX\ tag}
+ \end{syntax}
+
+ Similar to above, but you're allowed to specify the Sync\TeX\ tag.
+
+ More details: each file ever read has an associated Sync\TeX\ tag value, which is a number. The Sync\TeX\ information will point to that file.
+
+ On engines other than \LuaTeX, this feature is not supported and the function returns empty.
+\end{function}
+
+\begin{function}[EXP]{\rescansync_gettag:}
+ \begin{syntax}
+ \cs{rescansync_gettag:}
+ \end{syntax}
+
+ Function that fully expands to some token list that represents the Sync\TeX\ tag that corresponds to some file.
+
+ Note that if a file is |\input| more than once (or if |\file_get:nnN| \pkg{expl3} function is used on that file, which internally uses the \TeX\ |\input| primitive),
+ the tag value will be different and forward search may fail to work.
+\end{function}
+
+As a full example, assume there's a file named \file{a.tex}:
+\begin{verbatim}
+\tl_set:Nx \mytag {\rescansync_gettag:}
+\end{verbatim}
+After it's executed, a file \file{b.tex} executes:
+\begin{verbatim}
+\rescansync:nnnV {abcdef} {3} {rescanned-a} \mytag
+\end{verbatim}
+then the text |abcdef| will be typesetted, the Sync\TeX\ information points to line $1+3=4$ in the file \file{a.tex}
+(as the code |abcdef| is on the first line of the \Arg{content}, and the line offset is 3).
+
+If there's any error while typesetting |abcdef|, the error file name will be reported as for example, \file{RS1-rescanned-a.tex} (the number |1| might vary) instead of \file{a.tex}.
+
+\StopEventually{%
+ \PrintChanges
+ \PrintIndex
+}
+\Finale
+\end{document}
+
+