summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3msg.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3msg.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3msg.dtx549
1 files changed, 308 insertions, 241 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3msg.dtx b/Master/texmf-dist/source/latex/l3kernel/l3msg.dtx
index 472196ac62a..89362b7e7d4 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3msg.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3msg.dtx
@@ -35,7 +35,7 @@
%
%<*driver|package>
\RequirePackage{l3names}
-\GetIdInfo$Id: l3msg.dtx 3470 2012-02-26 19:10:24Z bruno $
+\GetIdInfo$Id: l3msg.dtx 3568 2012-04-23 13:23:58Z joseph $
{L3 Experimental messages}
%</driver|package>
%<*driver>
@@ -91,6 +91,8 @@
%
% \section{Creating new messages}
%
+% ^^A Wrong: "\msg_new:nnnn" is (as it should) global.
+% ^^A However, redirections are indeed local.
% All messages have to be created before they can be used. All message
% setting is local, with the general assumption that messages will
% be managed as part of module set up outside of any \TeX{} grouping.
@@ -99,6 +101,19 @@
% available in the console. As a result, formatting is only needed
% where it will help 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.
+%
+% Messages may be subdivided \emph{by one level} using the~|/|
+% character. This is used within the message filtering system to allow
+% for example the \LaTeX{} kernel messages to belong to the module
+% \texttt{LaTeX} while still being filterable at a more granular level.
+% Thus for example
+% \begin{verbatim}
+% \msg_new:nnnn { mymodule } { submodule / message } ...
+% \end{verbatim}
+% will allow only those messages from the \texttt{submodule} to be filtered
+% out.
%
% \begin{function}[updated = 2011-08-16]{\msg_new:nnnn, \msg_new:nnn}
% \begin{syntax}
@@ -110,9 +125,8 @@
% 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. The
-% parameters will be expanded when the message is used. Within the
-% \meta{text} and \meta{more text} |\\| can be used to start a new
-% line. An error will be raised if the \meta{message} already exists.
+% parameters will be expanded when the message is used. An error will
+% be raised if the \meta{message} already exists.
% \end{function}
%
% \begin{function}{\msg_set:nnnn, \msg_set:nnn, \msg_gset:nnnn, \msg_gset:nnn}
@@ -125,9 +139,16 @@
% 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. The
-% parameters will be expanded when the message is used. Within the
-% \meta{text} and \meta{more text} |\\| can be used to start a new
-% line.
+% parameters will be expanded when the message is used.
+% \end{function}
+%
+% \begin{function}[EXP,pTF, added=2012-03-03]{\msg_if_exist:nn}
+% \begin{syntax}
+% \cs{msg_if_exist_p:nn} \Arg{module} \Arg{message}
+% \cs{msg_if_exist:nnTF} \Arg{module} \Arg{message} \Arg{true code} \Arg{false code}
+% \end{syntax}
+% Tests whether the \meta{message} for the \meta{module} is currently
+% defined.
% \end{function}
%
% \section{Contextual information for messages}
@@ -176,7 +197,7 @@
% Fatal <module> error
% \end{verbatim}
% This function can be redefined to alter the language in which the
-% message is give, using |#1| as the name of the \meta{module} to
+% message is given, using |#1| as the name of the \meta{module} to
% be included.
% \end{function}
%
@@ -189,7 +210,7 @@
% Critical <module> error
% \end{verbatim}
% This function can be redefined to alter the language in which the
-% message is give, using |#1| as the name of the \meta{module} to
+% message is given, using |#1| as the name of the \meta{module} to
% be included.
% \end{function}
%
@@ -202,7 +223,7 @@
% <module> error
% \end{verbatim}
% This function can be redefined to alter the language in which the
-% message is give, using |#1| as the name of the \meta{module} to
+% message is given, using |#1| as the name of the \meta{module} to
% be included.
% \end{function}
%
@@ -215,7 +236,7 @@
% <module> warning
% \end{verbatim}
% This function can be redefined to alter the language in which the
-% message is give, using |#1| as the name of the \meta{module} to
+% message is given, using |#1| as the name of the \meta{module} to
% be included.
% \end{function}
%
@@ -228,7 +249,7 @@
% <module> info
% \end{verbatim}
% This function can be redefined to alter the language in which the
-% message is give, using |#1| as the name of the \meta{module} to
+% message is given, using |#1| as the name of the \meta{module} to
% be included.
% \end{function}
%
@@ -242,22 +263,26 @@
% \cs{tl_to_str:n} or \cs{token_to_str:N} to prevent unwanted expansion
% of the material.
%
-% \begin{function}{\msg_class_set:nn}
+% \begin{function}[updated = 2012-04-12]{\msg_class_set:nn}
% \begin{syntax}
% \cs{msg_class_set:nn} \Arg{class} \Arg{code}
% \end{syntax}
% Sets a \meta{class} to output a message, using \meta{code}
% to process the message text. The \meta{class} should be a text
% value, while the \meta{code} may be any arbitrary material.
-% The \meta{code} will receive $6$ arguments: the module
+% The \meta{code} will receive~$6$ arguments: the module
% name (|#1|), the message name (|#2|) and the four arguments
% taken by the message text (|#3| to |#6|).
+% ^^A Add an example? An application could be that an IDE redirects
+% ^^A classes from 'error' to 'IDEerror', 'warning' to 'IDEwarning',
+% ^^A etc, and defines 'IDEerror' and 'IDEwarning' to produce messages
+% ^^A which are simpler to parse.
% \end{function}
%
% The kernel defines several common message classes. The following
% describes the standard behaviour of each class if no redirection of
% the class or message is active. In all cases, the message may be
-% issued supplying $0$ to $4$ arguments. The code will
+% issued supplying~$0$ to~$4$ arguments. The code will
% ensure that there an no errors if the number of arguments supplied
% here does not match the number in the definition of the message
% (although of course the sense of the message may be impaired).
@@ -271,8 +296,7 @@
% \msg_fatal:nn
% }
% \begin{syntax}
-% \cs{msg_fatal:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one}
-% ~~\Arg{arg two} \Arg{arg three} \Arg{arg four}
+% \cs{msg_fatal:nnxxxx} \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. After issuing a
@@ -281,15 +305,14 @@
%
% \begin{function}
% {
-% \msg_critical:nnxxxx ,
-% \msg_critical:nnxxx ,
-% \msg_critical:nnxx ,
-% \msg_critical:nnx ,
-% \msg_critical:nn
-% }
+% \msg_critical:nnxxxx ,
+% \msg_critical:nnxxx ,
+% \msg_critical:nnxx ,
+% \msg_critical:nnx ,
+% \msg_critical:nn
+% }
% \begin{syntax}
-% \cs{msg_critical:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one}
-% ~~\Arg{arg two} \Arg{arg three} \Arg{arg four}
+% \cs{msg_critical:nnxxxx} \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. After issuing the
@@ -297,6 +320,8 @@
% the \TeX{} run (if the current file is the main file) or
% may abort reading a sub-file.
% \end{function}
+% ^^A Perhaps add detection that we are in the main file to really do
+% ^^A '\tex_end:D' in that case?
%
% \begin{function}
% {
@@ -307,8 +332,7 @@
% \msg_error:nn
% }
% \begin{syntax}
-% \cs{msg_error:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one}
-% ~~\Arg{arg two} \Arg{arg three} \Arg{arg four}
+% \cs{msg_error:nnxxxx} \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
@@ -325,8 +349,7 @@
% \msg_warning:nn
% }
% \begin{syntax}
-% \cs{msg_warning:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one}
-% ~~\Arg{arg two} \Arg{arg three} \Arg{arg four}
+% \cs{msg_warning:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one} \Arg{arg two} \Arg{arg three} \Arg{arg four}
% \end{syntax}
% Issues \meta{module} warning \meta{message}, passing \meta{arg one} to
% \meta{arg four} to the text-creating functions. The warning text
@@ -343,8 +366,7 @@
% \msg_info:nn
% }
% \begin{syntax}
-% \cs{msg_info:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one}
-% ~~\Arg{arg two} \Arg{arg three} \Arg{arg four}
+% \cs{msg_info:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one} \Arg{arg two} \Arg{arg three} \Arg{arg four}
% \end{syntax}
% Issues \meta{module} information \meta{message}, passing
% \meta{arg one} to \meta{arg four} to the text-creating functions.
@@ -360,8 +382,7 @@
% \msg_log:nn
% }
% \begin{syntax}
-% \cs{msg_log:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one}
-% ~~\Arg{arg two} \Arg{arg three} \Arg{arg four}
+% \cs{msg_log:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one} \Arg{arg two} \Arg{arg three} \Arg{arg four}
% \end{syntax}
% Issues \meta{module} information \meta{message}, passing
% \meta{arg one} to \meta{arg four} to the text-creating functions.
@@ -378,8 +399,7 @@
% \msg_none:nn
% }
% \begin{syntax}
-% \cs{msg_none:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one}
-% ~~\Arg{arg two} \Arg{arg three} \Arg{arg four}
+% \cs{msg_none:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one} \Arg{arg two} \Arg{arg three} \Arg{arg four}
% \end{syntax}
% Does nothing: used as a message class to prevent any output at
% all (see the discussion of message redirection).
@@ -405,13 +425,16 @@
% \begin{verbatim}
% \msg_redirect_module:nnn { module } { error } { warning }
% \end{verbatim}
-% to alter just those messages for module, or even
+% to alter only messages from that module, or even
% \begin{verbatim}
% \msg_redirect_name:nnn { module } { my-message } { warning }
% \end{verbatim}
-% to target just one message.
+% to target just one message. Redirection applies first to individual messages,
+% then to messages from one module and finally to messages of one class. Thus
+% it is possible to select out an individual message for special treatment
+% even if the entire class is already redirected.
%
-% \begin{function}{\msg_redirect_class:nn}
+% \begin{function}[updated = 2012-04-12]{\msg_redirect_class:nn}
% \begin{syntax}
% \cs{msg_redirect_class:nn} \Arg{class one} \Arg{class two}
% \end{syntax}
@@ -422,7 +445,7 @@
% rather than at the point of redirection.
% \end{function}
%
-% \begin{function}{\msg_redirect_module:nnn}
+% \begin{function}[updated = 2012-04-12]{\msg_redirect_module:nnn}
% \begin{syntax}
% \cs{msg_redirect_module:nnn} \Arg{module} \Arg{class one} \Arg{class two}
% \end{syntax}
@@ -437,9 +460,9 @@
% \end{verbatim}
% \end{function}
%
-% \begin{function}{\msg_redirect_name:nnn}
+% \begin{function}[updated = 2012-04-12]{\msg_redirect_name:nnn}
% \begin{syntax}
-% \cs{msg_redirect_name:nn} \Arg{module} \Arg{message} \Arg{class}
+% \cs{msg_redirect_name:nnn} \Arg{module} \Arg{message} \Arg{class}
% \end{syntax}
% Redirects a specific \meta{message} from a specific \meta{module}
% to act as a member of \meta{class} of messages. This function can
@@ -538,9 +561,8 @@
% 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. The
-% parameters will be expanded when the message is used. Within the
-% \meta{text} and \meta{more text} |\\| can be used to start a new
-% line. An error will be raised if the \meta{message} already exists.
+% parameters will be expanded when the message is used. An error will
+% be raised if the \meta{message} already exists.
% \end{function}
%
% \begin{function}{\msg_kernel_set:nnnn, \msg_kernel_set:nnn}
@@ -553,9 +575,7 @@
% 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. The
-% parameters will be expanded when the message is used. Within the
-% \meta{text} and \meta{more text} |\\| can be used to start a new
-% line.
+% parameters will be expanded when the message is used.
% \end{function}
%
% \begin{function}
@@ -567,8 +587,7 @@
% \msg_kernel_fatal:nn
% }
% \begin{syntax}
-% \cs{msg_kernel_fatal:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one}
-% ~~\Arg{arg two} \Arg{arg three} \Arg{arg four}
+% \cs{msg_kernel_fatal:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one} \Arg{arg two} \Arg{arg three} \Arg{arg four}
% \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
@@ -584,8 +603,7 @@
% \msg_kernel_error:nn
% }
% \begin{syntax}
-% \cs{msg_kernel_error:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one}
-% ~~\Arg{arg two} \Arg{arg three} \Arg{arg four}
+% \cs{msg_kernel_error:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one} \Arg{arg two} \Arg{arg three} \Arg{arg four}
% \end{syntax}
% Issues kernel \meta{module} error \meta{message}, passing \meta{arg one}
% to
@@ -603,8 +621,7 @@
% \msg_kernel_warning:nn
% }
% \begin{syntax}
-% \cs{msg_kernel_warning:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one}
-% ~~\Arg{arg two} \Arg{arg three} \Arg{arg four}
+% \cs{msg_kernel_warning:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one} \Arg{arg two} \Arg{arg three} \Arg{arg four}
% \end{syntax}
% Issues kernel \meta{module} warning \meta{message}, passing
% \meta{arg one} to
@@ -622,8 +639,7 @@
% \msg_kernel_info:nn
% }
% \begin{syntax}
-% \cs{msg_kernel_info:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one}
-% ~~\Arg{arg two} \Arg{arg three} \Arg{arg four}
+% \cs{msg_kernel_info:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one} \Arg{arg two} \Arg{arg three} \Arg{arg four}
% \end{syntax}
% Issues kernel \meta{module} information \meta{message}, passing
% \meta{arg one} to \meta{arg four} to the text-creating functions.
@@ -636,7 +652,9 @@
% expansion only context. This must be handled internally very
% differently from normal error messages, as none of the tools
% to print to the terminal or the log file are expandable.
-% However, the interface is similar.
+% However, the interface is similar, with the important caveat that the
+% message text and arguments are not expanded, and messages should be
+% very short.
%
% \begin{function}[EXP, added = 2011-11-23]
% {
@@ -647,8 +665,7 @@
% \msg_expandable_kernel_error:nn
% }
% \begin{syntax}
-% \cs{msg_expandable_kernel_error:nnnnnn} \Arg{module} \Arg{message}
-% ~~\Arg{arg one} \Arg{arg two} \Arg{arg three} \Arg{arg four}
+% \cs{msg_expandable_kernel_error:nnnnnn} \Arg{module} \Arg{message} \Arg{arg one} \Arg{arg two} \Arg{arg three} \Arg{arg four}
% \end{syntax}
% Issues an error, passing \meta{arg one} to \meta{arg four}
% to the text-creating functions. The resulting string must
@@ -677,8 +694,7 @@
%
% \begin{function}{\msg_aux_use:nn, \msg_aux_use:nnxxxx}
% \begin{syntax}
-% \cs{msg_aux_use:nnxxxx} \Arg{module} \Arg{message}
-% ~~\Arg{arg one} \Arg{arg two} \Arg{arg three} \Arg{arg four}
+% \cs{msg_aux_use:nnxxxx} \Arg{module} \Arg{message} \Arg{arg one} \Arg{arg two} \Arg{arg three} \Arg{arg four}
% \end{syntax}
% Prints the \meta{message} from \meta{module} in the terminal,
% without formatting.
@@ -733,7 +749,7 @@
% the code here. First, a mechanism for creating message text.
% This is pretty simple, as there is not actually a lot to do.
%
-%\begin{variable}{\c_msg_text_prefix_tl, \c_msg_more_text_prefix_tl}
+% \begin{variable}{\c_msg_text_prefix_tl, \c_msg_more_text_prefix_tl}
% Locations for the text of messages.
% \begin{macrocode}
\tl_const:Nn \c_msg_text_prefix_tl { msg~text~>~ }
@@ -741,6 +757,18 @@
% \end{macrocode}
% \end{variable}
%
+% \begin{macro}[EXP,pTF]{\msg_if_exist:nn}
+% Test whether the control sequence containing the message text exists
+% or not.
+% \begin{macrocode}
+\prg_new_conditional:Npnn \msg_if_exist:nn #1#2 { p , T , F , TF }
+ {
+ \cs_if_exist:cTF { \c_msg_text_prefix_tl #1 / #2 }
+ { \prg_return_true: } { \prg_return_false: }
+ }
+% \end{macrocode}
+% \end{macro}
+%
% \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
@@ -750,7 +778,7 @@
% \begin{macrocode}
\cs_new_protected:Npn \chk_if_free_msg:nn #1#2
{
- \cs_if_free:cF { \c_msg_text_prefix_tl #1 / #2 }
+ \msg_if_exist:nnT {#1} {#2}
{
\msg_kernel_error:nnxx { msg } { message-already-defined }
{#1} {#2}
@@ -760,7 +788,7 @@
\tex_ifodd:D \l@expl@log@functions@bool
\cs_gset_protected:Npn \chk_if_free_msg:nn #1#2
{
- \cs_if_free:cF { \c_msg_text_prefix_tl #1 / #2 }
+ \msg_if_exist:nnT {#1} {#2}
{
\msg_kernel_error:nnxx { msg } { message-already-defined }
{#1} {#2}
@@ -867,12 +895,12 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\msg_line_number:}
-% \begin{macro}{\msg_line_context:}
-% For writing the line number nicely.
+% \begin{macro}{\msg_line_number, \msg_line_context:}
+% For writing the line number nicely. \cs{msg_line_context:} was set up
+% earlier, so this is not \texttt{new}.
% \begin{macrocode}
\cs_new_nopar:Npn \msg_line_number: { \int_use:N \tex_inputlineno:D }
-\cs_set_nopar:Npn \msg_line_context:
+\cs_gset_nopar:Npn \msg_line_context:
{
\c_msg_on_line_text_tl
\c_space_tl
@@ -880,116 +908,87 @@
}
% \end{macrocode}
% \end{macro}
-% \end{macro}
%
% \subsection{Showing messages: low level mechanism}
%
-% \begin{variable}{\c_msg_hide_tl}
-% \begin{variable}{\c_msg_hide_tl<dots>}
-% An empty variable with a number of (category code 11) periods at the
-% end of its name. This is used to push the \TeX{} part of an error
-% message \enquote{off the screen}. Using two variables here means that
-% later life is a little easier.
-% \begin{macrocode}
-\char_set_catcode_letter:N \.
-\tl_new:N
- \c_msg_hide_tl..........................................................
-\tl_const:Nn \c_msg_hide_tl
- { \c_msg_hide_tl.......................................................... }
-\char_set_catcode_other:N \.
-% \end{macrocode}
-% \end{variable}
-% \end{variable}
-%
-% \begin{variable}{\l_msg_text_tl}
-% For wrapping message text.
-% \begin{macrocode}
-\tl_new:N \l_msg_text_tl
-% \end{macrocode}
-%\end{variable}
-%
% \begin{macro}{\msg_interrupt:xxx}
-% \begin{macro}[aux]{\msg_interrupt_no_details:xx}
-% \begin{macro}[aux]{\msg_interrupt_details:xxx}
-% \begin{macro}[aux]{\msg_interrupt_text:n}
-% \begin{macro}[aux]{\msg_interrupt_more_text:n}
-% \begin{macro}[aux]{\msg_interrupt_aux:}
-% The low-level interruption macro is rather opaque, unfortunately. The
-% idea here is to create a a message which hides all of \TeX{}'s own
-% information by filling the output up with dots. To achieve this,
-% dots have to be letters. The odd
-% \cs{c_msg_hide_tl<dots>} actually does the hiding: it is the
-% large run of dots in the name that is important here. The meaning
-% of |\\| is altered so that the explanation text is a simple run
-% whilst the initial error has line-continuation shown.
+% The low-level interruption macro is rather opaque, unfortunately.
+% Depending on the availability of more information there is a choice
+% of how to set up the further help. We feed the extra help text and
+% the message itself to a wrapping auxiliary, in this order because we
+% must first setup \TeX{}'s \tn{errhelp} register before issuing an
+% \tn{errmessage}.
% \begin{macrocode}
\cs_new_protected:Npn \msg_interrupt:xxx #1#2#3
{
- \group_begin:
- \tl_if_empty:nTF {#3}
- { \msg_interrupt_no_details:xx {#1} {#2} }
- { \msg_interrupt_details:xxx {#1} {#2} {#3} }
- \msg_interrupt_aux:
- \group_end:
+ \tl_if_empty:nTF {#3}
+ {
+ \msg_interrupt_wrap:xx { \\ \c_msg_no_info_text_tl }
+ {#1 \\\\ #2 \\\\ \c_msg_continue_text_tl }
+ }
+ {
+ \msg_interrupt_wrap:xx { \\ #3 }
+ {#1 \\\\ #2 \\\\ \c_msg_help_text_tl }
+ }
}
% \end{macrocode}
-% Depending on the availability of more information there is a choice of
-% how to set up the further help. The extra help text has to be set
-% before the message itself can be issued. Everything is done using
-% \texttt{x}-type expansion as the new line markers are different for
-% the two type of text and need to be correctly set up.
+% \end{macro}
+%
+% \begin{macro}[aux]{\msg_interrupt_wrap:xx}
+% \begin{macro}[aux]{\msg_interrupt_more_text:n}
+% First setup \TeX{}'s \tn{errhelp} register with the extra help |#1|,
+% then build a nice-looking error message with |#2|. Everything is
+% done using \texttt{x}-type expansion as the new line markers are
+% different for the two type of text and need to be correctly set up.
+% The auxiliary \cs{msg_interrupt_more_text:n} recieves its argument
+% as a line-wrapped string, which is thus unaffected by expansion.
% \begin{macrocode}
-\cs_new_protected:Npn \msg_interrupt_no_details:xx #1#2
+\cs_new_protected:Npn \msg_interrupt_wrap:xx #1#2
{
- \iow_wrap:xnnnN
- { \\ \c_msg_no_info_text_tl }
- { |~ } { 2 } { } \msg_interrupt_more_text:n
- \iow_wrap:xnnnN { #1 \\ \\ #2 \\ \\ \c_msg_continue_text_tl }
- { ! ~ } { 2 } {} \msg_interrupt_text:n
- }
-\cs_new_protected:Npn \msg_interrupt_details:xxx #1#2#3
- {
- \iow_wrap:xnnnN
- { \\ #3 }
- { |~ } { 2 } { } \msg_interrupt_more_text:n
- \iow_wrap:xnnnN { #1 \\ \\ #2 \\ \\ \c_msg_help_text_tl }
- { ! ~ } { 2 } { } \msg_interrupt_text:n
+ \iow_wrap:xnnnN {#1} { | ~ } { 2 } { } \msg_interrupt_more_text:n
+ \iow_wrap:xnnnN {#2} { ! ~ } { 2 } { } \msg_interrupt_text:n
}
-\cs_new_protected:Npn \msg_interrupt_text:n #1
- { \tl_set:Nn \l_msg_text_tl {#1} }
\cs_new_protected:Npn \msg_interrupt_more_text:n #1
{
-%<*initex>
- \tl_set:Nx \l_msg_internal_tl
-%</initex>
-%<*package>
- \protected@edef \l_msg_internal_tl
-%</package>
- {
- |'''''''''''''''''''''''''''''''''''''''''''''''
- #1
- \msg_newline:
- |...............................................
- }
- \tex_errhelp:D \exp_after:wN { \l_msg_internal_tl }
+ \exp_args:Nx \tex_errhelp:D
+ {
+ |'''''''''''''''''''''''''''''''''''''''''''''''
+ #1 \iow_newline:
+ |...............................................
+ }
}
% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}[aux]{\msg_interrupt_text:n}
+% \begin{variable}{\c_msg_hide_tl<dots>}
% The business end of the process starts by producing some visual
-% separation of the message from the main part of the log. It then
-% adds the hiding text to the message to print. The error message needs
-% to be printed with everything made \enquote{invisible}: this is where
-% the strange business with |&| comes in: this is made into another
-% |!|. There is also a closing brace that will show up in the output,
-% which is turned into a blank space.
+% separation of the message from the main part of the log. The error
+% message needs to be printed with everything made
+% \enquote{invisible}: \TeX{}'s own information involves the macro in
+% which \tn{errmessage} is called, and the end of the argument of the
+% \tn{errmessage}, including the closing brace. We use an active |!|
+% to call the \tn{errmessage} primitive, and end its argument with an
+% odd \cs{c_msg_hide_tl<dots>} which fills the output with dots. The
+% trailing closing brace is turned into a space to hide it 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 bee inserted after
+% the message is entirely cleaned up.
% \begin{macrocode}
-\group_begin: % {
+\group_begin:
+ \char_set_lccode:nn {`\{} {`\ }
\char_set_lccode:nn {`\}} {`\ }
\char_set_lccode:nn {`\&} {`\!}
\char_set_catcode_active:N \&
+ \char_set_catcode_letter:N \.
+ \tl_new:N
+ \c_msg_hide_tl............................................
\tl_to_lowercase:n
{
\group_end:
- \cs_new_protected:Npn \msg_interrupt_aux:
+ \cs_new_protected:Npn \msg_interrupt_text:n #1
{
\iow_term:x
{
@@ -998,18 +997,22 @@
\iow_newline:
!
}
- \tl_put_right:No \l_msg_text_tl { \c_msg_hide_tl }
- \cs_set_protected_nopar:Npx &
- { \tex_errmessage:D { \exp_not:o { \l_msg_text_tl } } }
+ \group_begin:
+ \cs_set_protected_nopar:Npn &
+ {
+ \tex_errmessage:D
+ {
+ #1
+ \c_msg_hide_tl............................................
+ }
+ }
+ \exp_after:wN
+ \group_end:
&
}
}
% \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
+% \end{variable}
% \end{macro}
%
% \begin{macro}{\msg_log:x}
@@ -1034,11 +1037,12 @@
% \end{macrocode}
% \end{macro}
% \end{macro}
+%
% \subsection{Displaying messages}
%
% \LaTeX{} is handling error messages and so the \TeX{} ones are disabled.
% \begin{macrocode}
-\int_set:Nn \tex_errorcontextlines:D { -1 }
+\int_gset:Nn \tex_errorcontextlines:D { -1 }
% \end{macrocode}
%
% \begin{macro}
@@ -1068,15 +1072,6 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{variable}{\l_msg_redirect_classes_prop, \l_msg_redirect_names_prop}
-% For filtering messages, a list of all messages and of those which have
-% to be modified is required.
-% \begin{macrocode}
-\prop_new:N \l_msg_redirect_classes_prop
-\prop_new:N \l_msg_redirect_names_prop
-% \end{macrocode}
-% \end{variable}
-%
% \begin{macro}{\msg_class_set:nn}
% Setting up a message class does two tasks. Any existing redirection
% is cleared, and the various message functions are created
@@ -1103,6 +1098,7 @@
% \begin{macro}[aux]{\msg_no_more_text:xxxx}
% A test to see if any more text is available, using a
% permanently-empty text function.
+% ^^A It would be more efficient to not define the more-text when absent.
% \begin{macrocode}
\prg_new_conditional:Npnn \msg_if_more_text:N #1 { p , T , F , TF }
{
@@ -1278,102 +1274,117 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{variable}
-% {
-% \l_msg_redirect_classes_seq ,
-% \l_msg_class_tl ,
-% \l_msg_current_class_tl ,
-% \l_msg_current_module_tl
-% }
+% \begin{variable}{\l_msg_class_tl, \l_msg_current_class_tl}
% Support variables needed for the redirection system.
% \begin{macrocode}
-\seq_new:N \l_msg_redirect_classes_seq
\tl_new:N \l_msg_class_tl
\tl_new:N \l_msg_current_class_tl
-\tl_new:N \l_msg_current_module_tl
% \end{macrocode}
-%\end{variable}
+% \end{variable}
+%
+% \begin{variable}{\l_msg_redirect_classes_prop, \l_msg_redirect_names_prop}
+% For filtering messages, a list of all messages and of those which have
+% to be modified is required.
+% \begin{macrocode}
+\prop_new:N \l_msg_redirect_classes_prop
+\prop_new:N \l_msg_redirect_names_prop
+% \end{macrocode}
+% \end{variable}
+%
+% \begin{variable}{\l_msg_redirect_prop}
+% For redirection of individually-named messages
+% \begin{macrocode}
+\prop_new:N \l_msg_redirect_prop
+% \end{macrocode}
+% \end{variable}
+%
+% \begin{variable}{\l_msg_use_direct_bool}
+% Used to force redirection when a name is given directly.
+% \begin{macrocode}
+\bool_new:N \l_msg_use_direct_bool
+% \end{macrocode}
+% \end{variable}
%
% \begin{macro}[int]{\msg_use:nnnnxxxx}
-% \begin{macro}[aux]{\msg_use_aux:nnn}
-% \begin{macro}[aux]{\msg_use_aux:nn}
-% \begin{macro}[aux]{\msg_use_loop_check:nn}
-% \begin{macro}[aux]{\msg_use_code:}
-% \begin{macro}[aux]{\msg_use_loop:n, \msg_use_loop:o}
-% The main message-using macro creates two auxiliary functions: one
-% containing the code for the message, and the second a loop function.
-% There is then a hand-off to the system for checking if redirection is
-% needed.
+% \begin{macro}[aux]{\msg_use_code:, \msg_use_or_change_class:}
+% \begin{macro}[aux]{\msg_use_aux_i:nn, \msg_use_aux_ii:nn}
+% \begin{macro}[aux]{\msg_use_aux_iii:w}
+% \begin{macro}[aux]{\msg_use_aux_iv:w}
+% \begin{macro}[aux]{\msg_use_aux_v:}
+% Actually using a message is a multi-step process. First, some safety
+% checks on the message and class requested. The code and arguments are
+% then stored to avoid passing them around.
% \begin{macrocode}
\cs_new_protected:Npn \msg_use:nnnnxxxx #1#2#3#4#5#6#7#8
{
- \cs_set_protected_nopar:Npx \msg_use_code:
- {
- \seq_clear:N \exp_not:N \l_msg_redirect_classes_seq
- \exp_not:n {#2}
- }
- \cs_set_protected:Npx \msg_use_loop:n ##1
+ \msg_if_exist:nnTF {#3} {#4}
{
- \seq_if_in:NnTF \exp_not:n \l_msg_redirect_classes_seq {#1}
- { \msg_kernel_error:nn { msg } { message-loop } {#1} }
+ \cs_if_exist:cTF { msg_ #1 :nnxxxx }
{
- \seq_put_right:Nn \exp_not:N \l_msg_redirect_classes_seq {#1}
- \exp_not:N \cs_if_exist:cTF { msg_ ##1 :nnxxxx }
+ \tl_set:Nn \l_msg_current_class_tl {#1}
+ \cs_set_protected_nopar:Npx \msg_use_code: { \exp_not:n {#2} }
+ \cs_set_protected_nopar:Npn \msg_use_or_change_class:
{
- \exp_not:N \use:c { msg_ ##1 :nnxxxx }
- \exp_not:n { {#3} {#4} {#5} {#6} {#7} {#8} }
+ \tl_if_eq:NNTF \l_msg_current_class_tl \l_msg_class_tl
+ { \msg_use_code: }
+ {
+ \use:c { msg_ \l_msg_class_tl :nnxxxx }
+ {#3} {#4} {#5} {#6} {#7} {#8}
+ }
}
+ \bool_if:NTF \l_msg_use_direct_bool
{
- \msg_kernel_error:nnx { msg } { message-class-unknown } {##1}
+ \bool_set_false:N \l_msg_use_direct_bool
+ \msg_use_code:
}
+ { \msg_use_aux_i:nn {#3} {#4} }
}
+ { \msg_kernel_error:nnx { msg } { message-class-unknown } {#1} }
}
- \cs_if_exist:cTF { \c_msg_text_prefix_tl #3 / #4 }
- { \msg_use_aux:nnn {#1} {#3} {#4} }
{ \msg_kernel_error:nnxx { msg } { message-unknown } {#3} {#4} }
}
+\cs_new_protected_nopar:Npn \msg_use_code: { }
+\cs_new_protected_nopar:Npn \msg_use_or_change_class: { }
% \end{macrocode}
-% The first auxiliary macro looks for a match by name: the most
-% restrictive check.
+% The first check is for a individual message redirection. If this applies
+% then no further redirection is attempted.
% \begin{macrocode}
-\cs_new_protected:Npn \msg_use_aux:nnn #1#2#3
+\cs_new_protected:Npn \msg_use_aux_i:nn #1#2
{
- \tl_set:Nn \l_msg_current_class_tl {#1}
- \tl_set:Nn \l_msg_current_module_tl {#2}
- \prop_if_in:NnTF \l_msg_redirect_names_prop { // #2 / #3 / }
- { \msg_use_loop_check:nn { names } { // #2 / #3 / } }
- { \msg_use_aux:nn {#1} {#2} }
+ \prop_get:NnNTF \l_msg_redirect_prop { #1 / #2 } \l_msg_class_tl
+ {
+ \bool_set_true:N \l_msg_use_direct_bool
+ \msg_use_or_change_class:
+ }
+ { \msg_use_aux_ii:nn {#1} {#2} }
}
% \end{macrocode}
-% The second function checks for general matches by module or for
-% all modules.
+% Next check if there is a redirection by module or by submodule.
% \begin{macrocode}
-\cs_new_protected:Npn \msg_use_aux:nn #1#2
+\cs_new_protected:Npn \msg_use_aux_ii:nn #1#2
{
- \prop_if_in:cnTF { l_msg_redirect_ #1 _prop } {#2}
- { \msg_use_loop_check:nn {#1} {#2} }
+ \prop_get:coNTF { l_msg_redirect_ \l_msg_current_class_tl _ prop }
+ { \msg_use_aux_iii:w #1 / #2 / \q_stop } \l_msg_class_tl
+ { \msg_use_or_change_class: }
{
- \prop_if_in:cnTF { l_msg_redirect_ #1 _prop } { * }
- { \msg_use_loop_check:nn {#1} { * } }
- { \msg_use_code: }
+ \prop_get:coNTF { l_msg_redirect_ \l_msg_current_class_tl _ prop }
+ { \msg_use_aux_iv:w #1 / #2 \q_stop } \l_msg_class_tl
+ { \msg_use_or_change_class: }
+ { \msg_use_aux_v: }
}
}
+\cs_new:Npn \msg_use_aux_iii:w #1 / #2 / #3 \q_stop { #1 / #2 }
+\cs_new:Npn \msg_use_aux_iv:w #1 / #2 \q_stop { #1 }
% \end{macrocode}
-% When checking whether to loop, the same code is needed in a few
-% places.
+% Finally test for redirection of an entire class.
% \begin{macrocode}
-\cs_new_protected:Npn \msg_use_loop_check:nn #1#2
+\cs_new_protected:Npn \msg_use_aux_v:
{
- \prop_get:cnN { l_msg_redirect_ #1 _prop } {#2} \l_msg_class_tl
- \tl_if_eq:NNTF \l_msg_current_class_tl \l_msg_class_tl
- {
- { \msg_use_code: }
- { \msg_use_loop:o \l_msg_class_tl }
- }
+ \prop_get:cnNF { l_msg_redirect_ \l_msg_current_class_tl _ prop }
+ { * } \l_msg_class_tl
+ { \tl_set_eq:NN \l_msg_class_tl \l_msg_current_class_tl }
+ \msg_use_or_change_class:
}
-\cs_new_protected_nopar:Npn \msg_use_code: { }
-\cs_new_protected:Npn \msg_use_loop:n #1 { }
-\cs_generate_variant:Nn \msg_use_loop:n { o }
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -1383,26 +1394,80 @@
% \end{macro}
%
% \begin{macro}{\msg_redirect_class:nn}
+% \begin{macro}[aux]{\msg_redirect_class_aux:nnn, \msg_redirect_class_aux:nVn}
% Converts class one into class two.
% \begin{macrocode}
\cs_new_protected:Npn \msg_redirect_class:nn #1#2
- { \prop_put:cnn { l_msg_redirect_ #1 _prop } { * } {#2} }
+ {
+ \cs_if_exist:cTF { msg_ #1 :nnxxxx }
+ {
+ \cs_if_exist:cTF { msg_ #2 :nnxxxx }
+ {
+ \tl_set:Nn \l_msg_current_class_tl {#1}
+ \msg_redirect_class_aux:nnn {#1} {#2} {#2}
+ }
+ { \msg_kernel_error:nnx { msg } { message-class-unknown } {#2} }
+ }
+ { \msg_kernel_error:nnx { msg } { message-class-unknown } {#1} }
+ }
+\cs_new_protected:Npn \msg_redirect_class_aux:nnn #1#2#3
+ {
+ \prop_get:cnNTF { l_msg_redirect_ #2 _prop } { * } \l_msg_class_tl
+ {
+ \tl_if_eq:NNTF \l_msg_class_tl \l_msg_current_class_tl
+ { \msg_kernel_error:nnxx { msg } { message-loop } {#1} {#3} }
+ { \msg_redirect_class_aux:nVn {#1} \l_msg_class_tl {#3} }
+ }
+ { \prop_put:cnn { l_msg_redirect_ #1 _prop } { * } {#3} }
+ }
+\cs_generate_variant:Nn \msg_redirect_class_aux:nnn { nV }
% \end{macrocode}
% \end{macro}
+% \end{macro}
%
% \begin{macro}{\msg_redirect_module:nnn}
+% \begin{macro}[aux]
+% {\msg_redirect_module_aux:nnnn, \msg_redirect_module_aux:nnVn}
% For when all messages of a class should be altered for a given module.
% \begin{macrocode}
\cs_new_protected:Npn \msg_redirect_module:nnn #1#2#3
- { \prop_put:cnn { l_msg_redirect_ #2 _prop } {#1} {#3} }
+ {
+ \cs_if_exist:cTF { msg_ #2 :nnxxxx }
+ {
+ \cs_if_exist:cTF { msg_ #3 :nnxxxx }
+ {
+ \tl_set:Nn \l_msg_current_class_tl {#1}
+ \msg_redirect_module_aux:nnnn {#1} {#2} {#3} {#3}
+ }
+ { \msg_kernel_error:nnx { msg } { message-class-unknown } {#3} }
+ }
+ { \msg_kernel_error:nnx { msg } { message-class-unknown } {#2} }
+ }
+\cs_new_protected:Npn \msg_redirect_module_aux:nnnn #1#2#3#4
+ {
+ \prop_get:cnNTF { l_msg_redirect_ #3 _prop } {#1} \l_msg_class_tl
+ {
+ \tl_if_eq:NNTF \l_msg_class_tl \l_msg_current_class_tl
+ { \msg_kernel_error:nnxx { msg } { message-loop } {#2} {#4} }
+ { \msg_redirect_moduel_aux:nVn {#1} {#2} \l_msg_class_tl {#4} }
+ }
+ { \prop_put:cnn { l_msg_redirect_ #2 _prop } {#1} {#4} }
+ }
+\cs_generate_variant:Nn \msg_redirect_module_aux:nnnn { nnV }
% \end{macrocode}
% \end{macro}
+% \end{macro}
%
% \begin{macro}{\msg_redirect_name:nnn}
-% Named message will always use the given class.
+% Named message will always use the given class even if that class is
+% redirected further.
% \begin{macrocode}
\cs_new_protected:Npn \msg_redirect_name:nnn #1#2#3
- { \prop_put:Nnn \l_msg_redirect_names_prop { // #1 / #2 / } {#3} }
+ {
+ \cs_if_exist:cTF { msg_ #3 :nnxxxx }
+ { \prop_put:Nnn \l_msg_redirect_prop { #1 / #2 } {#3} }
+ { \msg_kernel_error:nnx { msg } { message-class-unknown } {#3} }
+ }
% \end{macrocode}
% \end{macro}
%
@@ -1469,7 +1534,7 @@
% \begin{macro}{\msg_kernel_error:nnxx}
% \begin{macro}{\msg_kernel_error:nnx}
% \begin{macro}{\msg_kernel_error:nn}
-% Neither can kernel errors.
+% Neither can kernel errors.
% \begin{macrocode}
\cs_new_protected:Npn \msg_kernel_error:nnxxxx #1#2#3#4#5#6
{
@@ -1500,11 +1565,11 @@
}
\cs_new_protected:Npn \msg_kernel_error:nnxxx #1#2#3#4#5
{\msg_kernel_error:nnxxxx {#1} {#2} {#3} {#4} {#5} { } }
-\cs_set_protected:Npn \msg_kernel_error:nnxx #1#2#3#4
+\cs_gset_protected:Npn \msg_kernel_error:nnxx #1#2#3#4
{ \msg_kernel_error:nnxxxx {#1} {#2} {#3} {#4} { } { } }
-\cs_set_protected:Npn \msg_kernel_error:nnx #1#2#3
+\cs_gset_protected:Npn \msg_kernel_error:nnx #1#2#3
{ \msg_kernel_error:nnxxxx {#1} {#2} {#3} { } { } { } }
-\cs_set_protected:Npn \msg_kernel_error:nn #1#2
+\cs_gset_protected:Npn \msg_kernel_error:nn #1#2
{ \msg_kernel_error:nnxxxx {#1} {#2} { } { } { } { } }
% \end{macrocode}
% \end{macro}
@@ -1690,6 +1755,8 @@
{ Zero~step~size~for~stepwise~function~#1. }
\msg_kernel_new:nnn { prg } { replicate-neg }
{ Negative~argument~for~\prg_replicate:nn. }
+\msg_kernel_new:nnn { kernel } { unknown-comparison }
+ { Relation~symbol~'#1'~unknown:~use~=,~<,~>,~==,~!=,~<=,~>=. }
% \end{macrocode}
%
% Messages used by the \enquote{\texttt{show}} functions.