summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3msg.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2017-07-15 21:27:01 +0000
committerKarl Berry <karl@freefriends.org>2017-07-15 21:27:01 +0000
commitb1ce47fe4d0e1f06d1b019c3c6eb5f1b0ecd5e14 (patch)
tree58362abe4b603bb5f6db898b9b835bc8af730b3e /Master/texmf-dist/source/latex/l3kernel/l3msg.dtx
parent03b8dcfa3435f0265dfad4fd09aaab8f4ff9c617 (diff)
l3 (15jul17)
git-svn-id: svn://tug.org/texlive/trunk@44813 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3msg.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3msg.dtx169
1 files changed, 92 insertions, 77 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3msg.dtx b/Master/texmf-dist/source/latex/l3kernel/l3msg.dtx
index 8e6a6525406..d71000c896d 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3msg.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3msg.dtx
@@ -41,7 +41,7 @@
% }^^A
% }
%
-% \date{Released 2017/05/29}
+% \date{Released 2017/07/15}
%
% \maketitle
%
@@ -72,9 +72,9 @@
% \section{Creating new messages}
%
% All messages have to be created before they can be used.
-% The text of messages will automatically by wrapped to the length
+% The text of messages is automatically wrapped to the length
% available in the console. As a result, formatting is only needed
-% where it will help to show meaning. In particular, |\\| may be
+% where it helps to show meaning. In particular, |\\| may be
% used to force a new line and \verb*|\ | forces an explicit space.
% Additionally, |\{|, |\#|, |\}|, |\%| and |\~| can be used to produce
% the corresponding character.
@@ -87,20 +87,19 @@
% \begin{verbatim}
% \msg_new:nnnn { mymodule } { submodule / message } ...
% \end{verbatim}
-% will allow only those messages from the \texttt{submodule} to be filtered
-% out.
+% will allow to filter out specifically messages from the \texttt{submodule}.
%
% \begin{function}[updated = 2011-08-16]{\msg_new:nnnn, \msg_new:nnn}
% \begin{syntax}
% \cs{msg_new:nnnn} \Arg{module} \Arg{message} \Arg{text} \Arg{more text}
% \end{syntax}
% Creates a \meta{message} for a given \meta{module}.
-% The message will be defined to first give \meta{text} and then
+% The message is defined to first give \meta{text} and then
% \meta{more text} if the user requests it. If no \meta{more text} is
% available then a standard text is given instead. Within \meta{text}
% and \meta{more text} four parameters (|#1| to |#4|) can be used:
% these will be supplied at the time the message is
-% used. An error will be raised if the \meta{message} already exists.
+% used. An error is raised if the \meta{message} already exists.
% \end{function}
%
% \begin{function}{\msg_set:nnnn, \msg_set:nnn, \msg_gset:nnnn, \msg_gset:nnn}
@@ -108,7 +107,7 @@
% \cs{msg_set:nnnn} \Arg{module} \Arg{message} \Arg{text} \Arg{more text}
% \end{syntax}
% Sets up the text for a \meta{message} for a given \meta{module}.
-% The message will be defined to first give \meta{text} and then
+% The message is defined to first give \meta{text} and then
% \meta{more text} if the user requests it. If no \meta{more text} is
% available then a standard text is given instead. Within \meta{text}
% and \meta{more text} four parameters (|#1| to |#4|) can be used:
@@ -232,9 +231,9 @@
% Messages behave differently depending on the message class. In all cases,
% the message may be issued supplying~$0$ to~$4$ arguments. If the number of
% arguments supplied here does not match the number in the definition of the
-% message, extra arguments will be ignored, or empty arguments added (of
-% course the sense of the message may be impaired). The four arguments will
-% be converted to strings before being added to the message text: the
+% message, extra arguments are ignored, or empty arguments added (of
+% course the sense of the message may be impaired). The four arguments are
+% converted to strings before being added to the message text: the
% \texttt{x}-type variants should be used to expand material.
%
% \begin{function}[updated = 2012-08-11]
@@ -254,7 +253,7 @@
% \end{syntax}
% Issues \meta{module} error \meta{message}, passing \meta{arg one} to
% \meta{arg four} to the text-creating functions. After issuing a
-% fatal error the \TeX{} run will halt.
+% fatal error the \TeX{} run halts.
% \end{function}
%
% \begin{function}[updated = 2012-08-11]
@@ -274,7 +273,7 @@
% \end{syntax}
% Issues \meta{module} error \meta{message}, passing \meta{arg one} to
% \meta{arg four} to the text-creating functions. After issuing a
-% critical error, \TeX{} will stop reading the current input file.
+% critical error, \TeX{} stops reading the current input file.
% This may halt the \TeX{} run (if the current file is the main file)
% or may abort reading a sub-file.
% \begin{texnote}
@@ -300,9 +299,9 @@
% \cs{msg_error:nnnnnn} \Arg{module} \Arg{message} \Arg{arg one} \Arg{arg two} \Arg{arg three} \Arg{arg four}
% \end{syntax}
% Issues \meta{module} error \meta{message}, passing \meta{arg one} to
-% \meta{arg four} to the text-creating functions. The error will
-% interrupt processing and issue the text at the terminal. After user
-% input, the run will continue.
+% \meta{arg four} to the text-creating functions. The error
+% interrupts processing and issues the text at the terminal. After user
+% input, the run continues.
% \end{function}
%
% \begin{function}[updated = 2012-08-11]
@@ -322,8 +321,8 @@
% \end{syntax}
% Issues \meta{module} warning \meta{message}, passing \meta{arg one}
% to \meta{arg four} to the text-creating functions. The warning text
-% will be added to the log file and the terminal, but the \TeX{} run
-% will not be interrupted.
+% is added to the log file and the terminal, but the \TeX{} run
+% is not interrupted.
% \end{function}
%
% \begin{function}[updated = 2012-08-11]
@@ -343,7 +342,7 @@
% \end{syntax}
% Issues \meta{module} information \meta{message}, passing
% \meta{arg one} to \meta{arg four} to the text-creating functions.
-% The information text will be added to the log file.
+% The information text is added to the log file.
% \end{function}
%
% \begin{function}[updated = 2012-08-11]
@@ -363,7 +362,7 @@
% \end{syntax}
% Issues \meta{module} information \meta{message}, passing
% \meta{arg one} to \meta{arg four} to the text-creating functions.
-% The information text will be added to the log file: the output
+% The information text is added to the log file: the output
% is briefer than \cs{msg_info:nnnnnn}.
% \end{function}
%
@@ -397,7 +396,7 @@
% \begin{verbatim}
% \msg_error:nn { module } { my-message }
% \end{verbatim}
-% when it is used. With no filtering, this will raise an error. However, we
+% when it is used. With no filtering, this raises an error. However, we
% could alter the behaviour with
% \begin{verbatim}
% \msg_redirect_class:nn { error } { warning }
@@ -417,7 +416,7 @@
%
% Multiple redirections are possible. Redirections can be cancelled by
% providing an empty argument for the target class. Redirection to a
-% missing class will raise errors immediately. Infinite loops are
+% missing class raises an error immediately. Infinite loops are
% prevented by eliminating the redirection starting from the target of
% the redirection that caused the loop to appear. Namely, if
% redirections are requested as $A \to B$, $B \to C$ and $C \to A$ in
@@ -479,16 +478,16 @@
% ! <text>
% !...............................................
% \end{verbatim}
-% where the \meta{text} will be wrapped to fit within the current
+% where the \meta{text} is wrapped to fit within the current
% line length. The user may then request more information, at which
-% stage the \meta{extra text} will be shown in the terminal in the
+% stage the \meta{extra text} is shown in the terminal in the
% format
% \begin{verbatim}
% |'''''''''''''''''''''''''''''''''''''''''''''''
% | <extra text>
% |...............................................
% \end{verbatim}
-% where the \meta{extra text} will be wrapped within the current
+% where the \meta{extra text} is wrapped within the current
% line length. Wrapping of both \meta{text} and \meta{more text} takes place
% using \cs{iow_wrap:nnnN}; the documentation for the latter should be
% consulted for full details.
@@ -504,7 +503,7 @@
% . <text>
% .................................................
% \end{verbatim}
-% where the \meta{text} will be wrapped to fit within the current
+% where the \meta{text} is wrapped to fit within the current
% line length. Wrapping takes place using \cs{iow_wrap:nnnN}; the
% documentation for the latter should be consulted for full details.
% \end{function}
@@ -520,7 +519,7 @@
% * <text>
% *************************************************
% \end{verbatim}
-% where the \meta{text} will be wrapped to fit within the current
+% where the \meta{text} is wrapped to fit within the current
% line length. Wrapping takes place using \cs{iow_wrap:nnnN}; the
% documentation for the latter should be consulted for full details.
% \end{function}
@@ -537,12 +536,12 @@
% \cs{__msg_kernel_new:nnnn} \Arg{module} \Arg{message} \Arg{text} \Arg{more text}
% \end{syntax}
% Creates a kernel \meta{message} for a given \meta{module}.
-% The message will be defined to first give \meta{text} and then
+% The message is defined to first give \meta{text} and then
% \meta{more text} if the user requests it. If no \meta{more text} is
% available then a standard text is given instead. Within \meta{text}
% and \meta{more text} four parameters (|#1| to |#4|) can be used:
% these will be supplied and expanded at the time the message is used.
-% An error will be raised if the \meta{message} already exists.
+% An error is raised if the \meta{message} already exists.
% \end{function}
%
% \begin{function}{\__msg_kernel_set:nnnn, \__msg_kernel_set:nnn}
@@ -550,7 +549,7 @@
% \cs{__msg_kernel_set:nnnn} \Arg{module} \Arg{message} \Arg{text} \Arg{more text}
% \end{syntax}
% Sets up the text for a kernel \meta{message} for a given \meta{module}.
-% The message will be defined to first give \meta{text} and then
+% The message is defined to first give \meta{text} and then
% \meta{more text} if the user requests it. If no \meta{more text} is
% available then a standard text is given instead. Within \meta{text}
% and \meta{more text} four parameters (|#1| to |#4|) can be used:
@@ -574,7 +573,7 @@
% \end{syntax}
% Issues kernel \meta{module} error \meta{message}, passing \meta{arg one}
% to \meta{arg four} to the text-creating functions. After issuing a
-% fatal error the \TeX{} run will halt. Cannot be redirected.
+% fatal error the \TeX{} run halts. Cannot be redirected.
% \end{function}
%
% \begin{function}[updated = 2012-08-11]
@@ -594,9 +593,9 @@
% \end{syntax}
% Issues kernel \meta{module} error \meta{message}, passing \meta{arg one}
% to
-% \meta{arg four} to the text-creating functions. The error will
-% stop processing and issue the text at the terminal. After user input,
-% the run will continue. Cannot be redirected.
+% \meta{arg four} to the text-creating functions. The error
+% stops processing and issues the text at the terminal. After user input,
+% the run continues. Cannot be redirected.
% \end{function}
%
% \begin{function}[updated = 2012-08-11]
@@ -617,8 +616,7 @@
% Issues kernel \meta{module} warning \meta{message}, passing
% \meta{arg one} to
% \meta{arg four} to the text-creating functions. The warning text
-% will be added to the log file, but the \TeX{} run will not be
-% interrupted.
+% is added to the log file, but the \TeX{} run is not interrupted.
% \end{function}
%
% \begin{function}[updated = 2012-08-11]
@@ -638,7 +636,7 @@
% \end{syntax}
% Issues kernel \meta{module} information \meta{message}, passing
% \meta{arg one} to \meta{arg four} to the text-creating functions.
-% The information text will be added to the log file.
+% The information text is added to the log file.
% \end{function}
%
% \section{Expandable errors}
@@ -664,7 +662,7 @@
% \end{syntax}
% Issues an error, passing \meta{arg one} to \meta{arg four}
% to the text-creating functions. The resulting string must
-% be shorter than a line, otherwise it will be cropped.
+% be much shorter than a line, otherwise it is cropped.
% \end{function}
%
% \begin{function}[EXP, added = 2011-08-11, updated = 2011-08-13]
@@ -738,8 +736,8 @@
% Shows or logs the \meta{expression} (turned into a string), an
% equal sign, and the result of applying the \meta{function} to the
% \Arg{expression}. For instance, if the \meta{function} is
-% \cs{int_eval:n} and the \meta{expression} is |1+2| then this will
-% log |> 1+2=3.| The case where the \meta{function} is
+% \cs{int_eval:n} and the \meta{expression} is |1+2| then this
+% logs |> 1+2=3.| The case where the \meta{function} is
% \cs{tl_to_str:n} is special: then the string representation of the
% \meta{expression} is only logged once.
% \end{function}
@@ -833,11 +831,10 @@
%
% \begin{macro}[aux]{\__chk_if_free_msg:nn}
% This auxiliary is similar to \cs{__chk_if_free_cs:N}, and is used when
-% defining messages with \cs{msg_new:nnnn}. It could be inlined in
-% \cs{msg_new:nnnn}, but the experimental \pkg{l3trace} module needs
-% to disable this check when reloading a package with the extra
-% tracing information.
+% defining messages with \cs{msg_new:nnnn}.
% \begin{macrocode}
+\__debug_patch:nnNw { }
+ { \__debug_log:x { Defining~message~ #1 / #2 ~\msg_line_context: } }
\cs_new_protected:Npn \__chk_if_free_msg:nn #1#2
{
\msg_if_exist:nnT {#1} {#2}
@@ -846,19 +843,6 @@
{#1} {#2}
}
}
-%<*package>
-\if_bool:N \l@expl@log@functions@bool
- \cs_gset_protected:Npn \__chk_if_free_msg:nn #1#2
- {
- \msg_if_exist:nnT {#1} {#2}
- {
- \@@_kernel_error:nnxx { kernel } { message-already-defined }
- {#1} {#2}
- }
- \__chk_log:x { Defining~message~ #1 / #2 ~\msg_line_context: }
- }
-\fi:
-%</package>
% \end{macrocode}
% \end{macro}
%
@@ -922,7 +906,7 @@
\tl_const:Nn \c_@@_continue_text_tl
{ Type~<return>~to~continue }
\tl_const:Nn \c_@@_critical_text_tl
- { Reading~the~current~file~'\g_file_current_name_tl'~will~stop. }
+ { Reading~the~current~file~'\g_file_curr_name_str'~will~stop. }
\tl_const:Nn \c_@@_fatal_text_tl
{ This~is~a~fatal~error:~LaTeX~will~abort. }
\tl_const:Nn \c_@@_help_text_tl
@@ -1027,9 +1011,9 @@
% trailing closing braces are turned into spaces to hide them as well.
% The group in which we alter the definition of the active |!| is
% closed before producing the message: this ensures that tokens
-% inserted by typing |I| in the command-line will be inserted after
+% inserted by typing |I| in the command-line are inserted after
% the message is entirely cleaned up.
-
+%
% The \cs{__iow_with:Nnn} auxiliary, defined in \pkg{l3file}, expects
% an \meta{integer variable}, an integer \meta{value}, and some
% \meta{code}. It runs the \meta{code} after ensuring that the
@@ -1489,7 +1473,7 @@
% applies then no further redirection is attempted. Otherwise, split
% the message name into \texttt{module/submodule/message} (with an
% arbitrary number of slashes), and store |{/module/submodule}|,
-% |{/module}| and |{}| into \cs{l_@@_hierarchy_seq}. We will then
+% |{/module}| and |{}| into \cs{l_@@_hierarchy_seq}. We then
% map through this sequence, applying the most specific redirection.
% \begin{macrocode}
\cs_new_protected:Npn \@@_use_redirect_name:n #1
@@ -1556,7 +1540,7 @@
% \end{macro}
%
% \begin{macro}{\msg_redirect_name:nnn}
-% Named message will always use the given class even if that class is
+% Named message always use the given class even if that class is
% redirected further. An empty target class cancels any existing
% redirection for that message.
% \begin{macrocode}
@@ -1928,21 +1912,6 @@
LaTeX~has~been~asked~to~define~the~conditional~form~'#1'~of~
the~function~'#2',~but~only~'TF',~'T',~'F',~and~'p'~forms~exist.
}
-%<*package>
-\bool_if:NT \l@expl@check@declarations@bool
- {
- \@@_kernel_new:nnnn { check } { non-declared-variable }
- { The~variable~#1~has~not~been~declared~\msg_line_context:. }
- {
- Checking~is~active,~and~you~have~tried~do~so~something~like: \\
- \ \ \tl_set:Nn ~ #1 ~ \{ ~ ... ~ \} \\
- without~first~having: \\
- \ \ \tl_new:N ~ #1 \\
- \\
- LaTeX~will~create~the~variable~and~continue.
- }
- }
-%</package>
\@@_kernel_new:nnnn { kernel } { scanmark-already-defined }
{ Scan~mark~#1~already~defined. }
{
@@ -1975,6 +1944,52 @@
}
% \end{macrocode}
%
+% Some errors are only needed in package mode if debugging is enabled by
+% one of the options \texttt{enable-debug}, \texttt{check-declarations},
+% \texttt{log-functions}, or on the contrary if debugging is turned off.
+% In format mode the error is somewhat different.
+% \begin{macrocode}
+%<*package>
+\bool_if:NTF \l@expl@enable@debug@bool
+ {
+ \@@_kernel_new:nnn { kernel } { debug-unpatchable }
+ { Only~some~definitions~can~be~patched;~'#3'~cannot. }
+ \@@_kernel_new:nnnn { check } { non-declared-variable }
+ { The~variable~#1~has~not~been~declared~\msg_line_context:. }
+ {
+ Checking~is~active,~and~you~have~tried~do~so~something~like: \\
+ \ \ \tl_set:Nn ~ #1 ~ \{ ~ ... ~ \} \\
+ without~first~having: \\
+ \ \ \tl_new:N ~ #1 \\
+ \\
+ LaTeX~will~create~the~variable~and~continue.
+ }
+ }
+ {
+ \@@_kernel_new:nnnn { kernel } { enable-debug }
+ { To~use~'#1'~load~expl3~with~the~'enable-debug'~option. }
+ {
+ The~function~'#1'~will~be~ignored~because~it~can~only~work~if~
+ some~internal~functions~in~expl3~have~been~appropriately~
+ defined.~This~only~happens~if~one~of~the~options~
+ 'enable-debug',~'check-declarations'~or~'log-functions'~was~
+ given~when~loading~expl3.
+ }
+ }
+%</package>
+%<*initex>
+\@@_kernel_new:nnnn { kernel } { enable-debug }
+ { '#1'~cannot~be~used~in~format~mode. }
+ {
+ The~function~'#1'~will~be~ignored~because~it~can~only~work~if~
+ some~internal~functions~in~expl3~have~been~appropriately~
+ defined.~This~only~happens~in~package~mode~(and~only~if~one~of~
+ the~options~'enable-debug',~'check-declarations'~or~'log-functions'~
+ was~given~when~loading~expl3.
+ }
+%</initex>
+% \end{macrocode}
+%
% Some errors only appear in expandable settings,
% hence don't need a \enquote{more-text} argument.
% \begin{macrocode}