summaryrefslogtreecommitdiff
path: root/macros/latex/base/usrguide.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2024-06-02 03:03:43 +0000
committerNorbert Preining <norbert@preining.info>2024-06-02 03:03:43 +0000
commitd751a6e51be81d6c1ba797cd91d4079e7e2e407b (patch)
tree30738f61076dd0b1543343a753941b74ad1b07d7 /macros/latex/base/usrguide.tex
parentc4af6b71665be2eeee42e63d081e50debde63162 (diff)
CTAN sync 202406020303
Diffstat (limited to 'macros/latex/base/usrguide.tex')
-rw-r--r--macros/latex/base/usrguide.tex153
1 files changed, 131 insertions, 22 deletions
diff --git a/macros/latex/base/usrguide.tex b/macros/latex/base/usrguide.tex
index d3ccb2161e..2b9e959627 100644
--- a/macros/latex/base/usrguide.tex
+++ b/macros/latex/base/usrguide.tex
@@ -34,8 +34,8 @@
\usepackage{csquotes}
\usepackage{url}
-\title{\LaTeX\ for authors --- current version}
-\author{\copyright~Copyright 2020-2023, \LaTeX\ Project Team.\\
+\title{\LaTeX\ for authors\\ current version}
+\author{\copyright~Copyright 2020--2024, \LaTeX\ Project Team.\\
All rights reserved.%
\footnote{This file may be distributed and/or modified under the
conditions of the \LaTeX{} Project Public License, either version 1.3c
@@ -43,7 +43,7 @@
\texttt{usrguide.tex} for full details.}%
}
-\date{2023-05-23}
+\date{2024-05-24}
\NewDocumentCommand\cs{m}{\texttt{\textbackslash\detokenize{#1}}}
\NewDocumentCommand\marg{m}{\arg{#1}}
@@ -646,7 +646,7 @@ take account of the possibility that the \meta{token} has been made active
(category code~$13$) and will split at such tokens.
Spaces are trimmed at each end of each item parsed. Exactly one set
of braces will be stripped if an entire item is surrounded by them,
-i.e.~the following inputs and outputs result (each separte item as
+i.e.~the following inputs and outputs result (each separate item as
a brace group).
\begin{verbatim}
a ==> {a}
@@ -794,6 +794,73 @@ a & b & c \\
\end{tabular}
\end{verbatim}
+\subsection{Using the verbatim argument types}
+
+As described above, the \texttt{v}-type argument may be viewed as similar to
+\cs{verb}. Before looking at exactly what that means, it is important to
+highlight some key differences. Most notably, \emph{grabbing} a verbatim-like
+argument is separate from \emph{typesetting} it: the latter is covered in the
+next section.
+
+When grabbing a \texttt{v}-type argument, \LaTeX{} first uses the kernel
+command \cs{dospecials} to turn off the \enquote{special} nature of characters.
+It then makes both spaces and tabs \enquote{active}, so that they can be given
+a custom definition. Any other characters are grabbed as-is: this means that if
+any characters have been made \enquote{special} and are not listed in
+\cs{dospecials}, an error will arise (see below).
+
+The characters that are grabbed as the argument are all those between two
+identical: in contrast to \cs{verb}, the characters \texttt{\textbackslash},
+|{|, |}| and |%| \emph{cannot} be used as the delimiter character. If any of
+the grabbed tokens have \enquote{special} meaning, an error will be issued.
+
+For the \texttt{+v}-type argument, which allows line breaks within the
+argument, newline characters are converted into \cs{obeyedline} commands. The
+standard definition of \cs{obeyedline} is simple |\par|, thus allowing the
+grabbed tokens to be used directly in typesetting. A local redefinition of
+\cs{obeyedline} can be used to achieve other outputs. For example, to retain
+blank lines whilst typesetting, one could use
+\begin{verbatim}
+\renewcommand*\obeyedline{\mbox{}\par}
+\end{verbatim}
+More information about using these arguments in typesetting is in the following
+subsection.
+
+Some additional details that may be useful for those with more \TeX{}
+knowledge: do not worry if this does not make sense to you! Spaces and tabs are
+stored as active characters. In Unicode engines, all other characters are of
+type \enquote{other}. In $8$-bit engines, the ASCII characters other than tab
+and space are of type \enquote{other}, and non-ASCII characters are active. As
+such, token-based comparisons are likely to fail unless set up properly.
+
+\subsection{Typesetting verbatim-like material}
+
+In contrast to \cs{verb}, the \texttt{(+)v}-type argument is only about
+\emph{grabbing} the argument, not \emph{typesetting} it. As such, features that
+users often associate with \enquote{verbatim} are not automatically activated,
+e.g., selecting a monospaced font. Material grabbed by the \texttt{v}-type
+argument does not automatically suppress ligatures: with modern \TeX{} engines,
+this largely can be done without the token manipulation which \cs{verb} uses.
+(In \cs{verb}, ligatures are suppressed by making characters active and
+inserting a zero-width kern before the character itself.)
+
+The \cs{verb} command also selects a monospaced font: this is not intrinsic to
+verbatim material, so will need to be set up using for example \cs{ttfamily}.
+Similarly, the \texttt{verbatim} environment sets up the meaning of \cs{par}
+suitable for breaking lines.
+
+\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. It should be noted 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 +1018,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}.
@@ -1052,11 +1119,17 @@ to give a purely numerical result.
Briefly, the floating point expressions may comprise:
\begin{itemize}
\item Basic arithmetic: addition $x\fpbin{+}y$, subtraction $x\fpbin{-}y$,
- multiplication $x\fpbin{*}y$, division $x\fpbin{/}y$, square root~$\sqrt{x}$,
+ multiplication $x\fpbin{*}y$, division $x\fpbin{/}y$, square root~$\fpop{sqrt}{x}$,
and parentheses.
\item Comparison operators: $x\fprel{<}y$,
$x\fprel{<=}y$, $x\fprel{>?}y$,
$x\fprel{!=}y$ \emph{etc.}
+
+ The relation $x\fprel{?}y$ is true exactly if one or both operands is~\nan{} or is
+ a tuple, unless they are equal tuples. Each \meta{relation}
+ can be any (non-empty) combination of |<|, |=|, |>|, and~|?|, plus
+ an optional leading~|!| (which negates the \meta{relation}), with
+ the restriction that the negated \meta{relation} may not start with~|?|.
\item Boolean logic: sign $\fpop{sign} x$,
negation $\fpop{!}x$, conjunction
$x\fprel{\&\&}y$, disjunction $x\fprel{\string|\string|}y$, ternary
@@ -1161,7 +1234,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 +1259,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{tabular}{rl}
+\begin{flushleft}
+ \begin{tabular}{@{}ll}
|\MakeUppercase{hello WORLD ßüé}| & \MakeUppercase{hello WORLD ßüé} \\
|\MakeLowercase{hello WORLD ßüé}| & \MakeLowercase{hello WORLD ßüé} \\
|\MakeTitlecase{hello WORLD ßüé}| & \MakeTitlecase{hello WORLD ßüé} \\
\end{tabular}
-\end{quotation}
+\end{flushleft}
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 +1281,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{tabular}{rl}
+\begin{flushleft}
+ \begin{tabular}{@{}ll}
|\MakeUppercase{Some text $y = mx + c$}|
& \MakeUppercase{Some text $y = mx + c$} \\
|\MakeUppercase{\NoCaseChange{iPhone}}|
& \MakeLowercase{\NoCaseChange{iPhone}} \\
\end{tabular}
-\end{quotation}
+\end{flushleft}
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 +1317,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}
- |\DeclareUppercaseMapping{"01F0}{\v{J}}|
-\end{quotation}
+\begin{verbatim}
+\DeclareUppercaseMapping{"01F0}{\v{J}}
+\end{verbatim}
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}
- |\DeclareLowercaseMapping[xx]{"0049}{\i}|\\
- |\DeclareLowercaseMapping[xx]{"0130}{i}|\\
- |\DeclareUppercaseMapping[xx]{"0069}{\.{I}}|\\
- |\DeclareUppercaseMapping[xx]{"0131}{I}|
-\end{quotation}
+\begin{verbatim}
+\DeclareLowercaseMapping[xx]{"0049}{\i}
+\DeclareLowercaseMapping[xx]{"0130}{i}
+\DeclareUppercaseMapping[xx]{"0069}{\.{I}}
+\DeclareUppercaseMapping[xx]{"0131}{I}
+\end{verbatim}
+
+\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}