summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3quark.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3quark.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3quark.dtx179
1 files changed, 100 insertions, 79 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3quark.dtx b/Master/texmf-dist/source/latex/l3kernel/l3quark.dtx
index 3cb65a59b33..b85b03440df 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3quark.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3quark.dtx
@@ -35,8 +35,8 @@
%
%<*driver|package>
\RequirePackage{l3names}
-\GetIdInfo$Id: l3quark.dtx 3384 2012-02-12 13:13:11Z will $
- {L3 Experimental quarks}
+\GetIdInfo$Id: l3quark.dtx 3986 2012-07-15 19:23:51Z joseph $
+ {L3 Quarks}
%</driver|package>
%<*driver>
\documentclass[full]{l3doc}
@@ -71,8 +71,9 @@
%
% Two special types of constants in \LaTeX3 are \enquote{quarks} and
% \enquote{scan marks}. By convention all constants of type quark
-% start out with |\q_|, and scan marks start with |\s_|.
-% \emph{Scan marks are an experimental feature.}
+% start out with |\q_|, and scan marks start with |\s_|. Scan marks are
+% for internal use by the kernel: they are not intended for more general
+% use.
%
% \subsection{Quarks}
%
@@ -114,22 +115,6 @@
% An example of the quark testing functions and their use in recursion
% can be seen in the implementation of \cs{clist_map_function:NN}.
%
-%
-% \subsection{Scan marks}
-%
-% Scan marks are control sequences set equal to \cs{scan_stop:},
-% hence will never expand in an expansion context and will be (largely)
-% invisible if they are encountered in a typesetting context.
-%
-% Like quarks, they can be used as delimiters in weird functions
-% and are often safer to use for this purpose.
-% Since they are harmless when executed by \TeX{} in non-expandable
-% contexts, they can be used to mark the end of a set of instructions.
-% This allows to skip to that point if the end of the instructions
-% should not be performed (see \pkg{l3regex}).
-%
-%^^A todo: talk about the use of scan marks in galley and fp.
-%
% \section{Defining quarks}
%
% \begin{function}{\quark_new:N}
@@ -279,63 +264,81 @@
% ended.
% \end{function}
%
+% \section{Clearing quarks away}
+%
+% \begin{function}{\use_none_delimit_by_q_recursion_stop:w}
+% \begin{syntax}
+% \cs{use_none_delimit_by_q_recursion_stop:w} \meta{tokens} \cs{q_recursion_stop}
+% \end{syntax}
+% Used to prematurely terminate a recursion using \cs{q_recursion_stop}
+% as the end marker, removing any remaining \meta{tokens} from the
+% input stream.
+% \end{function}
+%
+% \begin{function}{\use_i_delimit_by_q_recursion_stop:nw}
+% \begin{syntax}
+% \cs{use_i_delimit_by_q_recursion_stop:nw} \Arg{insertion}
+% ~~\meta{tokens} \cs{q_recursion_stop}
+% \end{syntax}
+% Used to prematurely terminate a recursion using \cs{q_recursion_stop}
+% as the end marker, removing any remaining \meta{tokens} from the
+% input stream. The \meta{insertion} is then made into the input
+% stream after the end of the recursion.
+% \end{function}
+%
+% \section{Internal quark functions}
+%
% \begin{function}
% {
-% \quark_if_recursion_tail_break:N,
-% \quark_if_recursion_tail_break:n
+% \__quark_if_recursion_tail_break:NN,
+% \__quark_if_recursion_tail_break:nN
% }
% \begin{syntax}
-% \cs{quark_if_recursion_tail_break:n} \Arg{token list}
+% \cs{__quark_if_recursion_tail_break:nN} \Arg{token list} \cs{\meta{type}_map_break:}
% \end{syntax}
-% Tests if \meta{token list} contains only \cs{q_recursion_tail},
-% and if so terminates the recursion using \cs{prg_map_break:}.
-% The recursion end should be marked by \cs{prg_break_point:n}.
+% Tests if \meta{token list} contains only \cs{q_recursion_tail}, and
+% if so terminates the recursion using \cs{\meta{type}_map_break:}.
+% The recursion end should be marked by \cs{prg_break_point:Nn}
+% \cs{\meta{type}_map_break:}.
% \end{function}
%
% \section{Scan marks}
%
-% \begin{function}{\scan_new:N}
+% Scan marks are control sequences set equal to \cs{scan_stop:},
+% hence will never expand in an expansion context and will be (largely)
+% invisible if they are encountered in a typesetting context.
+%
+% Like quarks, they can be used as delimiters in weird functions
+% and are often safer to use for this purpose.
+% Since they are harmless when executed by \TeX{} in non-expandable
+% contexts, they can be used to mark the end of a set of instructions.
+% This allows to skip to that point if the end of the instructions
+% should not be performed (see \pkg{l3regex}).
+%
+% The scan marks system is only for internal use by the kernel team in
+% a small number of very specific places. These functions should not be
+% used more generally.
+%
+% \begin{function}{\__scan_new:N}
% \begin{syntax}
-% \cs{scan_new:N} \meta{scan mark}
+% \cs{__scan_new:N} \meta{scan mark}
% \end{syntax}
% Creates a new \meta{scan mark} which is set equal to \cs{scan_stop:}.
% The \meta{scan mark} will be defined globally, and an error message
% will be raised if the name was already taken by another scan mark.
% \end{function}
%
-% \begin{variable}{\s_stop}
+% \begin{variable}{\s__stop}
% Used at the end of a set of instructions, as a marker
-% that can be jumped to using \cs{use_none_delimit_by_s_stop:w}.
+% that can be jumped to using \cs{__use_none_delimit_by_s__stop:w}.
% \end{variable}
%
-% \begin{function}{\use_none_delimit_by_s_stop:w}
+% \begin{function}{\__use_none_delimit_by_s__stop:w}
% \begin{syntax}
-% \cs{use_none_delimit_by_s_stop:w} \meta{tokens} \cs{s_stop}
+% \cs{__use_none_delimit_by_s__stop:w} \meta{tokens} \cs{s__stop}
% \end{syntax}
-% Removes the \meta{tokens} and \cs{s_stop} from the input stream.
-% This leads to a low-level \TeX{} error if \cs{s_stop} is absent.
-% \end{function}
-%
-% \section{Internal quark functions}
-%
-% \begin{function}{\use_none_delimit_by_q_recursion_stop:w}
-% \begin{syntax}
-% \cs{use_none_delimit_by_q_recursion_stop:w} \meta{tokens} \cs{q_recursion_stop}
-% \end{syntax}
-% Used to prematurely terminate a recursion using \cs{q_recursion_stop}
-% as the end marker, removing any remaining \meta{tokens} from the
-% input stream.
-% \end{function}
-%
-% \begin{function}{\use_i_delimit_by_q_recursion_stop:nw}
-% \begin{syntax}
-% \cs{use_i_delimit_by_q_recursion_stop:nw} \Arg{insertion}
-% ~~\meta{tokens} \cs{q_recursion_stop}
-% \end{syntax}
-% Used to prematurely terminate a recursion using \cs{q_recursion_stop}
-% as the end marker, removing any remaining \meta{tokens} from the
-% input stream. The \meta{insertion} is then made into the input
-% stream after the end of the recursion.
+% Removes the \meta{tokens} and \cs{s__stop} from the input stream.
+% This leads to a low-level \TeX{} error if \cs{s__stop} is absent.
% \end{function}
%
% \end{documentation}
@@ -354,7 +357,7 @@
%<*package>
\ProvidesExplPackage
{\ExplFileName}{\ExplFileDate}{\ExplFileVersion}{\ExplFileDescription}
-\package_check_loaded_expl:
+\__expl_package_check:
%</package>
% \end{macrocode}
%
@@ -453,22 +456,22 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}{\quark_if_recursion_tail_break:N}
-% \begin{macro}{\quark_if_recursion_tail_break:n}
+% \begin{macro}{\__quark_if_recursion_tail_break:NN}
+% \begin{macro}{\__quark_if_recursion_tail_break:nN}
% Analogs of the \cs{quark_if_recursion_tail_stop\ldots{}} functions.
-% Break the mapping using \cs{prg_map_break:}.
+% Break the mapping using |#2|.
% \begin{macrocode}
-\cs_new:Npn \quark_if_recursion_tail_break:N #1
+\cs_new:Npn \__quark_if_recursion_tail_break:NN #1#2
{
\if_meaning:w \q_recursion_tail #1
- \exp_after:wN \prg_map_break:
+ \exp_after:wN #2
\fi:
}
-\cs_new:Npn \quark_if_recursion_tail_break:n #1
+\cs_new:Npn \__quark_if_recursion_tail_break:nN #1#2
{
\if_int_compare:w \pdftex_strcmp:D
{ \exp_not:N \q_recursion_tail } { \exp_not:n {#1} } = \c_zero
- \exp_after:wN \prg_map_break:
+ \exp_after:wN #2
\fi:
}
% \end{macrocode}
@@ -477,7 +480,7 @@
%
% \begin{macro}[pTF]{\quark_if_nil:N}
% \UnitTested
-% \begin{macro}[pTF]{\quark_if_no_value:N., \quark_if_no_value:c}
+% \begin{macro}[pTF]{\quark_if_no_value:N, \quark_if_no_value:c}
% \UnitTested
% Here we test if we found a special quark as the first argument.
% We better start with \cs{q_no_value} as the first argument since
@@ -541,59 +544,77 @@
% \end{macro}
% \end{macro}
%
-% \begin{variable}{\q_tl_act_mark,\q_tl_act_stop}
+% \begin{variable}{\q__tl_act_mark, \q__tl_act_stop}
% These private quarks are needed by \pkg{l3tl}, but that is loaded
% before the quark module, hence their definition is deferred.
% \begin{macrocode}
-\quark_new:N \q_tl_act_mark
-\quark_new:N \q_tl_act_stop
+\quark_new:N \q__tl_act_mark
+\quark_new:N \q__tl_act_stop
% \end{macrocode}
% \end{variable}
%
% \subsection{Scan marks}
+%
+% \begin{macrocode}
+%<@@=scan>
+% \end{macrocode}
%
-% \begin{variable}{\g_scan_marks_tl}
+% \begin{variable}{\g_@@_marks_tl}
% \UnitTested
% The list of all scan marks currently declared.
% \begin{macrocode}
-\tl_new:N \g_scan_marks_tl
+\tl_new:N \g_@@_marks_tl
% \end{macrocode}
% \end{variable}
%
-% \begin{macro}{\scan_new:N}
+% \begin{macro}[int]{\@@_new:N}
% \UnitTested
% Check whether the variable is already a scan mark,
% then declare it to be equal to \cs{scan_stop:} globally.
% \begin{macrocode}
-\cs_new_protected:Npn \scan_new:N #1
+\cs_new_protected:Npn \@@_new:N #1
{
- \tl_if_in:NnTF \g_scan_marks_tl { #1 }
+ \tl_if_in:NnTF \g_@@_marks_tl { #1 }
{
- \msg_kernel_error:nnx { scan } { already-defined }
+ \__msg_kernel_error:nnx { kernel } { scanmark-already-defined }
{ \token_to_str:N #1 }
}
{
- \tl_gput_right:Nn \g_scan_marks_tl {#1}
+ \tl_gput_right:Nn \g_@@_marks_tl {#1}
\cs_new_eq:NN #1 \scan_stop:
}
}
% \end{macrocode}
% \end{macro}
%
-% \begin{variable}{\s_stop}
+% \begin{variable}{\s__stop}
% \UnitTested
% We only declare one scan mark here, more can be defined
% by specific modules.
% \begin{macrocode}
-\scan_new:N \s_stop
+\@@_new:N \s__stop
% \end{macrocode}
% \end{variable}
%
-% \begin{macro}{\use_none_delimit_by_s_stop:w}
+% \begin{macro}[int]{\__use_none_delimit_by_s__stop:w}
% \UnitTested
% Similar to \cs{use_none_delimit_by_q_stop:w}.
% \begin{macrocode}
-\cs_new:Npn \use_none_delimit_by_s_stop:w #1 \s_stop { }
+\cs_new:Npn \__use_none_delimit_by_s__stop:w #1 \s__stop { }
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{Deprecated quark functions}
+%
+% \begin{macro}
+% {\quark_if_recursion_tail_break:N, \quark_if_recursion_tail_break:n}
+% It's not clear what breaking function we should be using here, so
+% I'm picking one somewhat arbitrarily.
+% \begin{macrocode}
+\cs_new:Npn \quark_if_recursion_tail_break:N #1
+ { \__quark_if_recursion_tail_break:NN #1 \prg_break: }
+\cs_new:Npn \quark_if_recursion_tail_break:n #1
+ { \__quark_if_recursion_tail_break:nN {#1} \prg_break: }
% \end{macrocode}
% \end{macro}
%