1 files changed, 60 insertions, 12 deletions
diff --git a/Master/texmf-dist/doc/latex-dev/base/usrguide.tex b/Master/texmf-dist/doc/latex-dev/base/usrguide.tex
index 05fc93e7af0..9f5cfb181a5 100644
--- a/Master/texmf-dist/doc/latex-dev/base/usrguide.tex
+++ b/Master/texmf-dist/doc/latex-dev/base/usrguide.tex
@@ -1,6 +1,6 @@
 % \iffalse meta-comment
 %
-% Copyright (C) 2020-2023
+% Copyright (C) 2020-2024
 % The LaTeX Project and any individual authors listed elsewhere
 % in this file.
 %
@@ -43,7 +43,7 @@
     \texttt{usrguide.tex} for full details.}%
 }
 
-\date{2023-05-23}
+\date{2023-12-02}
 
 \NewDocumentCommand\cs{m}{\texttt{\textbackslash\detokenize{#1}}}
 \NewDocumentCommand\marg{m}{\arg{#1}}
@@ -794,6 +794,18 @@ a & b & c \\
 \end{tabular}
 \end{verbatim}
 
+\subsection{Performance}
+
+For document commands where the argument specification is entirely
+comprised of |m| or |+m| entries (or is entirely empty), the internal structure
+created by \cs{NewDocumentCommand} is essentially as efficient 
+as provided by |\newcommand(*)|. As such, document commands may replace
+constructs arising from \cs{newcommand}, etc., without a need to be concerned
+about performance. Note that \cs{newcommand(*)} produces expandable
+results, so the direct replacement is \cs{NewExpandableDocumentCommand};
+in most cases, however, it is better to use \cs{NewDocumentCommand} to
+give more robust structures.
+
 \subsection{Details about argument delimiters}
 
 In normal (non-expandable) commands, the delimited types look for the
@@ -951,7 +963,7 @@ The differences between \cs{New...}, \cs{Renew...}, and
 \begin{decl}
   |\ShowEnvironment|       \arg{env}
 \end{decl}
-This displays the meaning of the begin end end code for environment \meta{env}.
+This displays the meaning of the begin and end code for environment \meta{env}.
 
 
 
@@ -1161,7 +1173,7 @@ therefore shows the same syntax peculiars as discussed
 above. Nevertheless, in practice they are usually sufficient.  For
 example
 \begin{verbatim}
-\newcommand\calculateheight[1]{%
+\NewDocumentCommand\calculateheight{m}{%
   \setlength\textheight{\dimeval{\topskip+\baselineskip*\inteval{#1-1}}}}
 \end{verbatim}
 sets the \cs{textheight} to the appropriate value if a page should
@@ -1186,13 +1198,13 @@ Titlecasing here follows the definition given by the Unicode Consortium: the
 first character of the input will be converted to (broadly) uppercase, and the
 rest of the input to lowercase. The full range of Unicode UTF-8 input can be
 supported.
-\begin{quotation}
+\begin{quote}
   \begin{tabular}{rl}
     |\MakeUppercase{hello WORLD ßüé}| & \MakeUppercase{hello WORLD ßüé} \\
     |\MakeLowercase{hello WORLD ßüé}| & \MakeLowercase{hello WORLD ßüé} \\
     |\MakeTitlecase{hello WORLD ßüé}| & \MakeTitlecase{hello WORLD ßüé} \\
   \end{tabular}
-\end{quotation}
+\end{quote}
 
 The case-changing commands take an optional argument which can be used to
 tailor the output. This optional argument accepts the key \texttt{locale},
@@ -1208,14 +1220,14 @@ are the arguments to the commands \cs{label}, \cs{ref}, \cs{cite}, \cs{begin}
 and \cs{end}. Additional exclusions can be added using the command
 \cs{AddToNoCaseChangeList}. Input can be excluded from case changing using the
 command \cs{NoCaseChange}.
-\begin{quotation}
+\begin{quote}
   \begin{tabular}{rl}
     |\MakeUppercase{Some text $y = mx + c$}|
       & \MakeUppercase{Some text $y = mx + c$} \\
     |\MakeUppercase{\NoCaseChange{iPhone}}|
       & \MakeLowercase{\NoCaseChange{iPhone}} \\
   \end{tabular}
-\end{quotation}
+\end{quote}
 
 To allow robust commands to be used within case changing \emph{and} to produce
 the expected output, two additional control commands are available.
@@ -1244,18 +1256,54 @@ apply to a specific one: this is given in BCP-47 format
 (\url{https://en.wikipedia.org/wiki/IETF_language_tag}). For example,
 the kernel customises the mapping for U+01F0 (\v{j}) when uppercasing in
 8-bit engines:
-\begin{quotation}
+\begin{quote}
   |\DeclareUppercaseMapping{"01F0}{\v{J}}|
-\end{quotation}
+\end{quote}
 as there is no pre-composed \v{J} character, and this is problematic if
 the engine does not support Unicode natively. Similarly, to set a locale
 \texttt{xx} to behave in the same way as Turkish and retain the difference
 between dotted- and dotless-i, one could use for example
-\begin{quotation}
+\begin{quote}
   |\DeclareLowercaseMapping[xx]{"0049}{\i}|\\
   |\DeclareLowercaseMapping[xx]{"0130}{i}|\\
   |\DeclareUppercaseMapping[xx]{"0069}{\.{I}}|\\
   |\DeclareUppercaseMapping[xx]{"0131}{I}|
-\end{quotation}
+\end{quote}
+
+\section{Support for problem solving}
+
+\begin{decl}
+  |\listfiles| \oarg{options}
+\end{decl}
+
+If this command is placed in the preamble then a list of the files
+read in (as a result of processing the document) will be displayed
+on the terminal (and in the log file) at the end of the run. Where
+possible, a short description will also be produced. These descriptions
+will (hopefully) include the descriptions, dates and version numbers
+for package and class files.
+
+Sometimes, it may be that a local edit has been made to a package or
+class file (or rather a copy of such a file). To allow these cases to
+be identified, \cs{listfiles} takes an optional argument which allows
+adjustment of the information printed using a key--value approach
+\begin{description}
+  \item[\texttt{hashes}] Adds the MD5 hash for each file to the
+    information printed
+  \item[\texttt{sizes}] Adds the file size for each file to the
+    information printed
+\end{description}
+Note that as Windows and Unix use different line endings (LF \emph{versus} LF
+CR), the hashes and file sizes from the two systems will not be the same. As
+such, you should compare these values between operating systems of the same
+type.
+
+\emph{Warning}: this command will list only files which were read
+using \LaTeX{} commands such as |\input|\arg{file} or
+|\include|\arg{file}.  If the file was read using the primitive \TeX{}
+syntax |\input |\emph{file} (without |{ }| braces around the file name)
+then it will not be listed; failure to use the \LaTeX{} form with the
+braces can cause more severe problems, possibly leading to overwriting
+important files, so \textbf{always put in the braces}.
 
 \end{document}