summaryrefslogtreecommitdiff
path: root/macros/latex-dev/base/usrguide.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex-dev/base/usrguide.tex')
-rw-r--r--macros/latex-dev/base/usrguide.tex72
1 files changed, 60 insertions, 12 deletions
diff --git a/macros/latex-dev/base/usrguide.tex b/macros/latex-dev/base/usrguide.tex
index 05fc93e7af..9f5cfb181a 100644
--- a/macros/latex-dev/base/usrguide.tex
+++ b/macros/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}