summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/l3kernel/l3msg.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/l3kernel/l3msg.dtx')
-rw-r--r--macros/latex/contrib/l3kernel/l3msg.dtx126
1 files changed, 87 insertions, 39 deletions
diff --git a/macros/latex/contrib/l3kernel/l3msg.dtx b/macros/latex/contrib/l3kernel/l3msg.dtx
index ed2169b94f..a46d268a48 100644
--- a/macros/latex/contrib/l3kernel/l3msg.dtx
+++ b/macros/latex/contrib/l3kernel/l3msg.dtx
@@ -43,7 +43,7 @@
% }^^A
% }
%
-% \date{Released 2021-05-11}
+% \date{Released 2021-05-25}
%
% \maketitle
%
@@ -274,6 +274,25 @@
% 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.
+% Note that this expansion takes place with the standard definitions in
+% effect, which means that shorthands such as |\~| or |\\| are
+% \emph{not} available; instead one should use \cs{iow_char:N} |\~| and
+% \cs{iow_newline:}, respectively.
+% The following message classes exist:
+% \begin{itemize}
+% \item \texttt{fatal}, ending the \TeX{} run;
+% \item \texttt{critical}, ending the file being input;
+% \item \texttt{error}, interrupting the \TeX{} run without ending it;
+% \item \texttt{warning}, written to terminal and log file, for
+% important messages that may require corrections by the user;
+% \item \texttt{note} (less common than \texttt{info}) for important
+% information messages written to the terminal and log file;
+% \item \texttt{info} for normal information messages written to the log
+% file only;
+% \item \texttt{term} and \texttt{log} for un-decorated messages written
+% to the terminal and log file, or to the log file only;
+% \item \texttt{none} for suppressed messages.
+% \end{itemize}
%
% \begin{function}[updated = 2012-08-11]
% {
@@ -365,8 +384,17 @@
% is not interrupted.
% \end{function}
%
-% \begin{function}[updated = 2012-08-11]
+% \begin{function}[added = 2021-05-18]
% {
+% \msg_note:nnnnnn ,
+% \msg_note:nnnnn ,
+% \msg_note:nnnn ,
+% \msg_note:nnn ,
+% \msg_note:nn ,
+% \msg_note:nnxxxx ,
+% \msg_note:nnxxx ,
+% \msg_note:nnxx ,
+% \msg_note:nnx ,
% \msg_info:nnnnnn ,
% \msg_info:nnnnn ,
% \msg_info:nnnn ,
@@ -378,15 +406,28 @@
% \msg_info:nnx
% }
% \begin{syntax}
+% \cs{msg_note:nnnnnn} \Arg{module} \Arg{message} \Arg{arg one} \Arg{arg two} \Arg{arg three} \Arg{arg four}
% \cs{msg_info:nnnnnn} \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.
-% The information text is added to the log file.
+% For the more common \cs{msg_info:nnnnnn}, the information text is
+% added to the log file only, while \cs{msg_note:nnnnnn} adds the
+% info text to both the log file and the terminal. The \TeX{} run is
+% not interrupted.
% \end{function}
%
% \begin{function}[updated = 2012-08-11]
% {
+% \msg_term:nnnnnn ,
+% \msg_term:nnnnn ,
+% \msg_term:nnnn ,
+% \msg_term:nnn ,
+% \msg_term:nn ,
+% \msg_term:nnxxxx ,
+% \msg_term:nnxxx ,
+% \msg_term:nnxx ,
+% \msg_term:nnx ,
% \msg_log:nnnnnn ,
% \msg_log:nnnnn ,
% \msg_log:nnnn ,
@@ -398,33 +439,15 @@
% \msg_log:nnx
% }
% \begin{syntax}
-% \cs{msg_log:nnnnnn} \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.
-% The information text is added to the log file: the output
-% is briefer than \cs{msg_info:nnnnnn}.
-% \end{function}
-%
-% \begin{function}[added = 2020-07-16]
-% {
-% \msg_term:nnnnnn ,
-% \msg_term:nnnnn ,
-% \msg_term:nnnn ,
-% \msg_term:nnn ,
-% \msg_term:nn ,
-% \msg_term:nnxxxx ,
-% \msg_term:nnxxx ,
-% \msg_term:nnxx ,
-% \msg_term:nnx
-% }
-% \begin{syntax}
% \cs{msg_term:nnnnnn} \Arg{module} \Arg{message} \Arg{arg one} \Arg{arg two} \Arg{arg three} \Arg{arg four}
+% \cs{msg_log:nnnnnn} \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.
-% The information text is printed on the terminal (and added to the
-% log file): the output is similar to that of \cs{msg_log:nnnnnn}.
+% The output is briefer than \cs{msg_info:nnnnnn}, omitting for
+% instance the module name. It is added to the log file by
+% \cs{msg_log:nnnnnn} while \cs{msg_term:nnnnnn} also prints it on the
+% terminal.
% \end{function}
%
% \begin{function}[updated = 2012-08-11]
@@ -557,6 +580,9 @@
% \end{syntax}
% Changes the behaviour of messages of \meta{class one} so that they
% are processed using the code for those of \meta{class two}.
+% Each \meta{class} can be one of \texttt{fatal}, \texttt{critical},
+% \texttt{error}, \texttt{warning}, \texttt{note}, \texttt{info},
+% \texttt{term}, \texttt{log}, \texttt{none}.
% \end{function}
%
% \begin{function}[updated = 2012-04-27]{\msg_redirect_module:nnn}
@@ -968,7 +994,7 @@
\cs_new:Npn \@@_text:nn #1#2
{
\exp_args:Nf \@@_text:n { \msg_module_type:n {#1} }
- \msg_module_name:n {#1} ~
+ \exp_args:Nf \@@_text:n { \msg_module_name:n {#1} }
#2
}
\cs_new:Npn \@@_text:n #1
@@ -1193,6 +1219,16 @@
%
% \begin{macro}
% {
+% \@@_info_aux:Nnn ,
+% \msg_note:nnnnnn ,
+% \msg_note:nnnnn ,
+% \msg_note:nnnn ,
+% \msg_note:nnn ,
+% \msg_note:nn ,
+% \msg_note:nnxxxx ,
+% \msg_note:nnxxx ,
+% \msg_note:nnxx ,
+% \msg_note:nnx ,
% \msg_info:nnnnnn ,
% \msg_info:nnnnn ,
% \msg_info:nnnn ,
@@ -1203,18 +1239,25 @@
% \msg_info:nnxx ,
% \msg_info:nnx
% }
-% Information only goes into the log.
+% Information has no decoration and goes either to the log or both
+% log and terminal.
% \begin{macrocode}
+ \@@_class_new:nn { note }
+ {
+ \@@_info_aux:Nnn \iow_term:n {#1}
+ { \use:c { \c_@@_text_prefix_tl #1 / #2 } {#3} {#4} {#5} {#6} }
+ }
\@@_class_new:nn { info }
{
- \str_set:Nx \l_@@_text_str { \msg_info_text:n {#1} }
- \str_set:Nx \l_@@_name_str { \msg_module_name:n {#1} }
- \iow_log:n { }
- \iow_wrap:nxnN
- {
- \l_@@_text_str : ~
- \use:c { \c_@@_text_prefix_tl #1 / #2 } {#3} {#4} {#5} {#6}
- }
+ \@@_info_aux:Nnn \iow_log:n {#1}
+ { \use:c { \c_@@_text_prefix_tl #1 / #2 } {#3} {#4} {#5} {#6} }
+ }
+ \cs_new_protected:Npn \@@_info_aux:Nnn #1#2#3
+ {
+ \str_set:Nx \l_@@_text_str { \msg_info_text:n {#2} }
+ \str_set:Nx \l_@@_name_str { \msg_module_name:n {#2} }
+ #1 { }
+ \iow_wrap:nxnN { \l_@@_text_str : ~ #3 }
{
( \l_@@_name_str )
\prg_replicate:nn
@@ -1224,8 +1267,8 @@
}
{ ~ }
}
- { } \iow_log:n
- \iow_log:n { }
+ { } #1
+ #1 { }
}
% \end{macrocode}
% \end{macro}
@@ -1761,6 +1804,7 @@
% \begin{macro}
% {
% \__kernel_msg_log:nnnnnn, \__kernel_msg_log:nnxxxx,
+% \__kernel_msg_term:nnnnnn, \__kernel_msg_term:nnxxxx,
% \__kernel_msg_show:nnnnnn, \__kernel_msg_show:nnxxxx
% }
% For showing messages.
@@ -1768,6 +1812,9 @@
\cs_new_protected:Npn \__kernel_msg_log:nnnnnn #1
{ \msg_log:nnnnnn { LaTeX / #1 } }
\cs_generate_variant:Nn \__kernel_msg_log:nnnnnn { nnxxxx }
+\cs_new_protected:Npn \__kernel_msg_term:nnnnnn #1
+ { \msg_term:nnnnnn { LaTeX / #1 } }
+\cs_generate_variant:Nn \__kernel_msg_term:nnnnnn { nnxxxx }
\cs_new_protected:Npn \__kernel_msg_show:nnnnnn #1
{ \msg_show:nnnnnn { LaTeX / #1 } }
\cs_generate_variant:Nn \__kernel_msg_show:nnnnnn { nnxxxx }
@@ -1865,6 +1912,7 @@
\c_@@_coding_error_text_tl
Functions~defined~through~\iow_char:N\\cs_new:Nn~must~have~
a~signature~consisting~of~only~normal~arguments~'N'~and~'n'.~
+ The~signature~'#2'~of~'#1'~contains~other~arguments~'#3'.~
To~define~variants~use~\iow_char:N\\cs_generate_variant:Nn~
and~to~define~other~functions~use~\iow_char:N\\cs_new:Npn.
}
@@ -1986,7 +2034,7 @@
\__kernel_msg_new:nnnn { quark } { invalid-function }
{ Quark~test~function~'#1'~is~invalid. }
{
- \c__msg_coding_error_text_tl
+ \c_@@_coding_error_text_tl
LaTeX~has~been~asked~to~create~quark~test~function~'#1'~
\tl_if_empty:nTF {#2}
{ but~that~name~ }