l3kernel 3036 (11dec11)

git-svn-id: svn://tug.org/texlive/trunk@24822 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 278 insertions, 36 deletions

diff --git a/Master/texmf-dist/source/latex/l3kernel/l3msg.dtx b/Master/texmf-dist/source/latex/l3kernel/l3msg.dtx
index 0e1eb8e072e..36d9e6d9d48 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 2896 2011-10-09 20:36:50Z joseph $
+\GetIdInfo$Id: l3msg.dtx 3029 2011-12-06 22:47:30Z joseph $
   {L3 Experimental messages}
 %</driver|package>
 %<*driver>
@@ -115,7 +115,7 @@
 %   line. An error will be raised if the \meta{message} already exists.
 % \end{function}
 %
-% \begin{function}{\msg_set:nnnn, \msg_set:nnn}
+% \begin{function}{\msg_set:nnnn, \msg_set:nnn, \msg_gset:nnnn, \msg_gset:nnn}
 %   \begin{syntax}
 %     \cs{msg_set:nnnn} \Arg{module} \Arg{message} \Arg{text} \Arg{more text}
 %   \end{syntax}
@@ -633,11 +633,29 @@
 % \section{Expandable errors}
 %
 % In a few places, the \LaTeX3 kernel needs to produce errors in an
-% expansion only context. This must be handled very differently from
-% normal error messages, as none of the tools to print to the terminal
-% or the log file are expandable.
+% 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.
 %
-% \begin{function}[added = 2011-08-11, updated = 2011-08-13]
+% \begin{function}[EXP, added = 2011-11-23]
+%   {
+%     \msg_expandable_kernel_error:nnnnnn,
+%     \msg_expandable_kernel_error:nnnnn,
+%     \msg_expandable_kernel_error:nnnn,
+%     \msg_expandable_kernel_error:nnn,
+%     \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}
+%   \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.
+% \end{function}
+%
+% \begin{function}[EXP, added = 2011-08-11, updated = 2011-08-13]
 %   {\msg_expandable_error:n}
 %   \begin{syntax}
 %     \cs{msg_expandable_error:n} \Arg{error message}
@@ -653,6 +671,36 @@
 %   \end{texnote}
 % \end{function}
 %
+% \section{Internal \pkg{l3msg} functions}
+%
+% The following functions are used in several kernel modules.
+%
+% \begin{function}{\msg_aux_use:nn, \msg_aux_use:nnxxxx}
+%   \begin{syntax}
+%     \cs{msg_aux_use:nnxx} \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.
+% \end{function}
+%
+% \begin{function}{\msg_aux_show:x}
+%   \begin{syntax}
+%     \cs{msg_aux_show:x} \Arg{formatted string}
+%   \end{syntax}
+%   Shows the \meta{formatted string} on the terminal.
+%   The \meta{formatted string} must start with |^^J>|,
+%   failure to do so causes low-level \TeX{} errors.
+% \end{function}
+%
+% \begin{function}{\msg_aux_show:Nnx}
+%   \begin{syntax}
+%     \cs{msg_aux_show:Nnx} \meta{variable} \Arg{module} \Arg{token list}
+%   \end{syntax}
+%   Auxiliary common to \pkg{l3clist}, \pkg{l3prop} and \pkg{seq},
+%   which displays an appropriate message and the contents of the variable.
+% \end{function}
+%
 % \end{documentation}
 %
 % \begin{implementation}
@@ -678,7 +726,7 @@
 %    \end{macrocode}
 % \end{variable}
 %
-%\section{Creating messages}
+% \subsection{Creating messages}
 %
 % Messages are created and used separately, so there two parts to
 % the code here. First, a mechanism for creating message text.
@@ -702,7 +750,7 @@
   {
     \cs_if_exist:cT { \c_msg_text_prefix_tl #1 / #2 }
       {
-        \msg_kernel_error:nn { msg } { message-already-defined }
+        \msg_kernel_error:nnxx { msg } { message-already-defined }
           {#1} {#2}
       }
     \msg_gset:nnnn {#1} {#2}
@@ -857,7 +905,6 @@
     \group_end:
   }
 %    \end{macrocode}
-%    \begin{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
@@ -1044,7 +1091,7 @@
 % \end{macro}
 % \end{macro}
 %
-%\begin{macro}
+% \begin{macro}
 %  {
 %    \msg_fatal:nnxxxx ,
 %    \msg_fatal:nnxxx  ,
@@ -1329,7 +1376,7 @@
 \cs_new_protected_nopar:Npn \msg_redirect_name:nnn #1#2#3
   { \prop_put:Nnn \l_msg_redirect_names_prop { // #1 / #2 / } {#3} }
 %    \end{macrocode}
-%\end{macro}
+% \end{macro}
 %
 % \subsection{Kernel-specific functions}
 %
@@ -1513,9 +1560,8 @@
   { Message~'#2'~for~module~'#1'~already~defined. }
   {
     \c_msg_coding_error_text_tl
-    LaTeX~was~asked~to~define~a~new~message~called~'#2'
-    by~the~module~'#1'~module:\\
-    this~message~already~exists.
+    LaTeX~was~asked~to~define~a~new~message~called~'#2'\
+    by~the~module~'#1':~this~message~already~exists.
     \c_msg_return_text_tl
   }
 \msg_kernel_new:nnnn { msg } { message-unknown }
@@ -1591,34 +1637,54 @@
   }
 %    \end{macrocode}
 %
-% \begin{macro}{\msg_kernel_bug:x}
-% \begin{variable}{\c_msg_kernel_bug_text_tl, \c_msg_kernel_bug_more_text_tl}
-% The \LaTeX{} coding bug error gets re-visited here.
+% Some errors only appear in expandable settings,
+% hence don't need a \enquote{more-text} argument.
 %    \begin{macrocode}
-\cs_set_protected:Npn \msg_kernel_bug:x #1
+\msg_kernel_new:nnn { seq } { misused }
+  { A~sequence~was~misused. }
+\msg_kernel_new:nnn { kernel } { bad-var }
+  { Erroneous~variable~#1 used! }
+\msg_kernel_new:nnn { prg } { zero-step }
+  { Zero~step~size~for~stepwise~function~#1. }
+%    \end{macrocode}
+%
+% Messages used by the \enquote{\texttt{show}} functions.
+%    \begin{macrocode}
+\msg_kernel_new:nnn { seq } { show }
   {
-    \msg_interrupt:xxx { \c_msg_kernel_bug_text_tl }
-      {
-        #1
-       \msg_see_documentation_text:n { LaTeX3 }
-      }
-      { \c_msg_kernel_bug_more_text_tl }
+    Sequence~\token_to_str:N #1~
+    \seq_if_empty:NTF #1
+      { is~empty }
+      { contains~the~items~(without~outer~braces): }
   }
-\tl_const:Nn \c_msg_kernel_bug_text_tl
-  { This~is~a~LaTeX~bug:~check~coding! }
-\tl_const:Nn \c_msg_kernel_bug_more_text_tl
+\msg_kernel_new:nnn { prop } { show }
   {
-    There~is~a~coding~bug~somewhere~around~here. \\
-    This~probably~needs~examining~by~an~expert.
-    \c_msg_return_text_tl
+    Property~list~\token_to_str:N #1~
+    \prop_if_empty:NTF #1
+      { is~empty }
+      { contains~the~pairs~(without~outer~braces): }
   }
+\msg_kernel_new:nnn { clist } { show }
+  {
+    Comma~list~
+    \str_if_eq:nnF {#1} { \l_clist_tmpa_clist } { \token_to_str:N #1~}
+    \clist_if_empty:NTF #1
+      { is~empty }
+      { contains~the~items~(without~outer~braces): }
+  }
+\msg_kernel_new:nnn { ior } { show-no-stream }
+  { No~input~streams~are~open }
+\msg_kernel_new:nnn { ior } { show-open-streams }
+  { The~following~input~streams~are~in~use: }
+\msg_kernel_new:nnn { iow } { show-no-stream }
+  { No~output~streams~are~open }
+\msg_kernel_new:nnn { iow } { show-open-streams }
+  { The~following~output~streams~are~in~use: }
 %    \end{macrocode}
-% \end{variable}
-% \end{macro}
 %
 % \subsection{Expandable errors}
 %
-% \begin{macro}{\msg_expandable_error:n}
+% \begin{macro}[int]{\msg_expandable_error:n}
 %   In expansion only context, we cannot use the normal means of
 %   reporting errors. Instead, we feed \TeX{} an undefined control
 %   sequence, \cs{LaTeX3 error:}. It is thus interrupted, and shows
@@ -1655,15 +1721,165 @@
             \exp_after:wN \exp_after:wN
             \exp_after:wN \c_zero
           }
-        \exp_not:N \use:n { \exp_not:c { LaTeX3~error: } ^ #1 }
-        \exp_not:N \q_stop
+        \exp_not:N \use:n { \exp_not:c { LaTeX3~error: } ^ #1 } ^
       }
-    \cs_new:Npn \msg_expandable_error_aux:w #1 ^ #2 \q_stop { #1 }
+    \cs_new:Npn \msg_expandable_error_aux:w #1 ^ #2 ^ { #1 }
   }
 \group_end:
 %    \end{macrocode}
 % \end{macro}
 %
+% \begin{macro}
+%   {
+%     \msg_expandable_kernel_error:nnnnnn,
+%     \msg_expandable_kernel_error:nnnnn,
+%     \msg_expandable_kernel_error:nnnn,
+%     \msg_expandable_kernel_error:nnn,
+%     \msg_expandable_kernel_error:nn
+%   }
+%   The command built from the csname
+%   |\c_msg_text_prefix_tl LaTeX / #1 / #2|
+%   takes four arguments and builds the error text, which is fed to
+%   \cs{msg_expandable_error:n}.
+%    \begin{macrocode}
+\cs_new:Npn \msg_expandable_kernel_error:nnnnnn #1#2#3#4#5#6
+  {
+    \exp_args:Nf \msg_expandable_error:n
+      {
+        \exp_args:NNc \exp_after:wN \exp_stop_f:
+          { \c_msg_text_prefix_tl LaTeX / #1 / #2 }
+          {#3} {#4} {#5} {#6}
+      }
+  }
+\cs_new:Npn \msg_expandable_kernel_error:nnnnn #1#2#3#4#5
+  {
+    \msg_expandable_kernel_error:nnnnnn
+      {#1} {#2} {#3} {#4} {#5} { }
+  }
+\cs_new:Npn \msg_expandable_kernel_error:nnnn #1#2#3#4
+  {
+    \msg_expandable_kernel_error:nnnnnn
+      {#1} {#2} {#3} {#4} { } { }
+  }
+\cs_new:Npn \msg_expandable_kernel_error:nnn #1#2#3
+  {
+    \msg_expandable_kernel_error:nnnnnn
+      {#1} {#2} {#3} { } { } { }
+  }
+\cs_new:Npn \msg_expandable_kernel_error:nn #1#2
+  {
+    \msg_expandable_kernel_error:nnnnnn
+      {#1} {#2} { } { } { } { }
+  }
+%    \end{macrocode}
+% \end{macro}
+%
+% \subsection{Showing variables}
+%
+% Functions defined in this section are used for diagnostic functions
+% in \pkg{l3clist}, \pkg{l3io}, \pkg{l3prop}, \pkg{l3seq}, \pkg{xtemplate}
+%
+% \begin{variable}{\l_msg_show_tl}
+%   Used to store the material for the diagnostic functions
+%   of various modules.
+%    \begin{macrocode}
+\tl_new:N \l_msg_show_tl
+%    \end{macrocode}
+% \end{variable}
+%
+% \begin{macro}[aux]{\msg_aux_use:nn}
+% \begin{macro}[aux]{\msg_aux_use:nnxxxx}
+%   Print the text of a message to the terminal, without formatting.
+%    \begin{macrocode}
+\cs_new_protected:Npn \msg_aux_use:nn #1#2
+  { \msg_aux_use:nnxxxx {#1} {#2} { } { } { } { } }
+\cs_new_protected:Npn \msg_aux_use:nnxxxx #1#2#3#4#5#6
+  {
+    \iow_term:x
+      {
+        \use:c { \c_msg_text_prefix_tl #1 / #2 }
+          {#3} {#4} {#5} {#6}
+      }
+  }
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}[int]{\msg_aux_show:Nnx}
+% \begin{macro}[aux]{\msg_aux_show:x}
+% \begin{macro}[aux,EXP]{\msg_aux_show:w}
+%   The arguments of \cs{msg_aux_show:Nnx} are
+%   \begin{itemize}
+%   \item The \meta{variable} to be shown.
+%   \item The \texttt{TF} emptyness conditional for that type of variables.
+%   \item The type of the variable.
+%   \item A mapping of the form \cs{seq_map_function:NN} \meta{variable}
+%     \cs{msg_aux_show:n}, which produces the formatted string.
+%   \end{itemize}
+%   We remove a new line and \verb*|> | from the first item using
+%   a \texttt{w}-type auxiliary, and the fact that \texttt{f}-expansion
+%   removes a space. To avoid a low-level \TeX{} error if there is
+%   an empty argument, a simple test is used to keep the output
+%   \enquote{clean}. The odd \cs{exp_after:wN} and trailing
+%   \cs{prg_do_nothing:} improve the output slightly.
+%    \begin{macrocode}
+\cs_new_protected:Npn \msg_aux_show:Nnx #1#2#3
+  {
+    \cs_if_exist:NTF #1
+      {
+        \msg_aux_use:nnxxxx { LaTeX / #2 } { show } {#1} { } { } { }
+        \msg_aux_show:x {#3}
+      }
+      {
+        \msg_kernel_error:nnx { kernel } { variable-not-defined }
+          { \token_to_str:N #1 }
+      }
+  }
+\cs_new_protected:Npn \msg_aux_show:x #1
+  {
+    \tl_set:Nx \l_msg_show_tl {#1}
+    \tl_if_empty:NT \l_msg_show_tl
+      { \tl_set:Nx \l_msg_show_tl { > } }
+    \exp_args:Nf \etex_showtokens:D
+      {
+        \exp_after:wN \exp_after:wN
+        \exp_after:wN \msg_aux_show:w
+        \exp_after:wN \l_msg_show_tl
+        \exp_after:wN
+      }
+    \prg_do_nothing:
+  }
+\cs_new:Npn \msg_aux_show:w #1 > { }
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}[aux,EXP]{\msg_aux_show:n}
+% \begin{macro}[aux,EXP]{\msg_aux_show:nn}
+% \begin{macro}[aux,EXP]{\msg_aux_show_unbraced:nn}
+%   Each item in the variable is formatted using one of
+%   the following functions.
+%    \begin{macrocode}
+\cs_new:Npn \msg_aux_show:n #1
+  {
+    \iow_newline: > \c_space_tl \c_space_tl { \exp_not:n {#1} }
+  }
+\cs_new:Npn \msg_aux_show:nn #1#2
+  {
+    \iow_newline: > \c_space_tl \c_space_tl { \exp_not:n {#1} }
+    \c_space_tl \c_space_tl => \c_space_tl \c_space_tl { \exp_not:n {#2} }
+  }
+\cs_new:Npn \msg_aux_show_unbraced:nn #1#2
+  {
+    \iow_newline: > \c_space_tl \c_space_tl \exp_not:n {#1}
+    \c_space_tl \c_space_tl => \c_space_tl \c_space_tl \exp_not:n {#2}
+  }
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
 % \subsection{Deprecated functions}
 %
 % Deprecated on 2011-05-27, for removal by 2011-08-31.
@@ -1722,6 +1938,32 @@
 % \end{macro}
 % \end{macro}
 %
+% \begin{macro}{\msg_kernel_bug:x}
+% \begin{variable}{\c_msg_kernel_bug_text_tl, \c_msg_kernel_bug_more_text_tl}
+%    \begin{macrocode}
+%<*deprecated>
+\cs_set_protected:Npn \msg_kernel_bug:x #1
+  {
+    \msg_interrupt:xxx { \c_msg_kernel_bug_text_tl }
+      {
+        #1
+       \msg_see_documentation_text:n { LaTeX3 }
+      }
+      { \c_msg_kernel_bug_more_text_tl }
+  }
+\tl_const:Nn \c_msg_kernel_bug_text_tl
+  { This~is~a~LaTeX~bug:~check~coding! }
+\tl_const:Nn \c_msg_kernel_bug_more_text_tl
+  {
+    There~is~a~coding~bug~somewhere~around~here. \\
+    This~probably~needs~examining~by~an~expert.
+    \c_msg_return_text_tl
+  }
+%</deprecated>
+%    \end{macrocode}
+% \end{variable}
+% \end{macro}
+%
 %    \begin{macrocode}
 %</initex|package>
 %    \end{macrocode}