diff options
author | Karl Berry <karl@freefriends.org> | 2017-07-15 21:27:01 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2017-07-15 21:27:01 +0000 |
commit | b1ce47fe4d0e1f06d1b019c3c6eb5f1b0ecd5e14 (patch) | |
tree | 58362abe4b603bb5f6db898b9b835bc8af730b3e /Master/texmf-dist/source/latex/l3kernel/l3msg.dtx | |
parent | 03b8dcfa3435f0265dfad4fd09aaab8f4ff9c617 (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.dtx | 169 |
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} |