diff options
Diffstat (limited to 'macros/latex-dev/required/tools')
34 files changed, 679 insertions, 45 deletions
diff --git a/macros/latex-dev/required/tools/README.md b/macros/latex-dev/required/tools/README.md index 8c55bf3449..f1500cc4c4 100644 --- a/macros/latex-dev/required/tools/README.md +++ b/macros/latex-dev/required/tools/README.md @@ -1,7 +1,7 @@ The LaTeX `tools` bundle ======================== -Release 2024-06-01 pre-release 1 +Release 2024-06-01 pre-release 2 Overview -------- diff --git a/macros/latex-dev/required/tools/afterpage.pdf b/macros/latex-dev/required/tools/afterpage.pdf Binary files differindex a6f340967f..afe6cd4471 100644 --- a/macros/latex-dev/required/tools/afterpage.pdf +++ b/macros/latex-dev/required/tools/afterpage.pdf diff --git a/macros/latex-dev/required/tools/array.pdf b/macros/latex-dev/required/tools/array.pdf Binary files differindex 87880c97fb..c0c1d1035f 100644 --- a/macros/latex-dev/required/tools/array.pdf +++ b/macros/latex-dev/required/tools/array.pdf diff --git a/macros/latex-dev/required/tools/bm.pdf b/macros/latex-dev/required/tools/bm.pdf Binary files differindex 1f9efb0b02..a94e1325b8 100644 --- a/macros/latex-dev/required/tools/bm.pdf +++ b/macros/latex-dev/required/tools/bm.pdf diff --git a/macros/latex-dev/required/tools/calc.pdf b/macros/latex-dev/required/tools/calc.pdf Binary files differindex 3cff423972..3e1f07af3a 100644 --- a/macros/latex-dev/required/tools/calc.pdf +++ b/macros/latex-dev/required/tools/calc.pdf diff --git a/macros/latex-dev/required/tools/changes.txt b/macros/latex-dev/required/tools/changes.txt index ebf705e687..4339d8e702 100644 --- a/macros/latex-dev/required/tools/changes.txt +++ b/macros/latex-dev/required/tools/changes.txt @@ -5,6 +5,11 @@ completeness or accuracy and it contains some references to files that are not part of the distribution. ======================================================================= +2024-03-13 David Carlisle <David.Carlisle@latex-project.org> + + * l3sys-query.dtx + New package, providing a document interface to the l3sys-query Lua script. + 2024-01-22 Lars Madsen <daleif@math.au.dk> * verbatim.dtx: added TAB marking support to \verbatiminput* (gh/1245) diff --git a/macros/latex-dev/required/tools/dcolumn.pdf b/macros/latex-dev/required/tools/dcolumn.pdf Binary files differindex 588505c218..3b0e4e485b 100644 --- a/macros/latex-dev/required/tools/dcolumn.pdf +++ b/macros/latex-dev/required/tools/dcolumn.pdf diff --git a/macros/latex-dev/required/tools/delarray.pdf b/macros/latex-dev/required/tools/delarray.pdf Binary files differindex 1fe65b8c75..75c9f0225e 100644 --- a/macros/latex-dev/required/tools/delarray.pdf +++ b/macros/latex-dev/required/tools/delarray.pdf diff --git a/macros/latex-dev/required/tools/enumerate.pdf b/macros/latex-dev/required/tools/enumerate.pdf Binary files differindex 66a10c9002..71af43ddc0 100644 --- a/macros/latex-dev/required/tools/enumerate.pdf +++ b/macros/latex-dev/required/tools/enumerate.pdf diff --git a/macros/latex-dev/required/tools/fileerr.pdf b/macros/latex-dev/required/tools/fileerr.pdf Binary files differindex 102b8c865d..bfa08b68cb 100644 --- a/macros/latex-dev/required/tools/fileerr.pdf +++ b/macros/latex-dev/required/tools/fileerr.pdf diff --git a/macros/latex-dev/required/tools/fontsmpl.pdf b/macros/latex-dev/required/tools/fontsmpl.pdf Binary files differindex a40e5d5566..54a21ad1cc 100644 --- a/macros/latex-dev/required/tools/fontsmpl.pdf +++ b/macros/latex-dev/required/tools/fontsmpl.pdf diff --git a/macros/latex-dev/required/tools/ftnright.pdf b/macros/latex-dev/required/tools/ftnright.pdf Binary files differindex e7f13295c7..7218f93ab4 100644 --- a/macros/latex-dev/required/tools/ftnright.pdf +++ b/macros/latex-dev/required/tools/ftnright.pdf diff --git a/macros/latex-dev/required/tools/hhline.pdf b/macros/latex-dev/required/tools/hhline.pdf Binary files differindex c8484ff875..2040d11a2e 100644 --- a/macros/latex-dev/required/tools/hhline.pdf +++ b/macros/latex-dev/required/tools/hhline.pdf diff --git a/macros/latex-dev/required/tools/indentfirst.pdf b/macros/latex-dev/required/tools/indentfirst.pdf Binary files differindex 96440b6c57..4ac9dbaf87 100644 --- a/macros/latex-dev/required/tools/indentfirst.pdf +++ b/macros/latex-dev/required/tools/indentfirst.pdf diff --git a/macros/latex-dev/required/tools/l3sys-query.dtx b/macros/latex-dev/required/tools/l3sys-query.dtx new file mode 100644 index 0000000000..d8c92adac1 --- /dev/null +++ b/macros/latex-dev/required/tools/l3sys-query.dtx @@ -0,0 +1,545 @@ +% \iffalse +%% Source File: l3sys-query.dtx +%% Copyright (C) 2024 +%% +%% The LaTeX Project and any individual authors listed elsewhere +%% in this file. +%% +%% This file may be distributed under the terms of the LPPL. +%% See README for details. +% +%<*dtx> + \ProvidesFile{l3sys-query.dtx} +%</dtx> +%<package>\ProvidesPackage{l3sys-query} +%<driver> \ProvidesFile{l3sys-query.drv} +% \fi +% \ProvidesFile{l3sys-query.dtx} + [2024-03-13 v1.0a LaTeX2e interface for l3sys file queries] +% +% \iffalse +%<*driver> +\documentclass{l3doc}%{ltxdoc} +\begin{document} +\DocInput{l3sys-query.dtx} +\end{document} +%</driver> +% \fi +% +% \GetFileInfo{l3sys-query.dtx} +% +% \title{\LaTeX\ document interface to the \pkg{l3sys-query} script: +% System queries for LaTeX using Lua\thanks{This file +% has version number \fileversion, last +% revised \filedate.}} +% \author{\LaTeX\ project} +% \date{\filedate} +% +% +% \maketitle +% +% \tableofcontents +% +% \section{Introduction} +% +% \TeX{} engines provide only very limited access to information about the system +% they are used on: using primitives, one can for example get the size of a single +% file, but not a list of files in a given location. For most documents, this is +% not an issue as they are self-contained. However, for cases where +% \enquote{dynamic} construction of parts of a document is needed based on file +% lists or other system-dependent data, methods to obtain this from (restricted) +% shell escape are desirable. +% +% Security considerations mean that directly querying the system shell is +% problematic for general use. Instead, \emph{restricted} shell escape may be used +% to get many details, provided a suitable tool is available to provide the +% information in a platform-neutral and security-conscious way. The Java program +% \texttt{texosquery}, written by Nicola Talbot, has been available for a number +% of years to provide this facility. As well as file system insight, +% \texttt{texosquery} also provides for example locale data and other system +% information. However, the requirement for Java means that the script is not +% automatically usable when a \TeX{} system is installed. +% +% The \LaTeX{} team have therefore provided a Lua-based script, +% \texttt{l3sys-query}, which conforms to the security requirements of \TeX{} Live +% using Lua to obtain the system information. This means that it can be used +% \enquote{out of the box} across platforms. The facilities provided by +% \texttt{l3sys-query} are more limited than \texttt{texosquery}, partly as some +% information is available in modern \TeX{} systems using primitives, and partly +% as the aim of \texttt{l3sys-query} is to provide information where there are +% defined use cases. Requests for additional data interfaces are welcome. +% +% This package provides a document level \textit{Key-Value} interface +% to The \texttt{l3sys-query} functionality, although as a convenience +% it also summarizes the documentation for the L3 programming +% interface layer (prvided by the \pkg{l3sys} module of +% \pkg{l3kernel}, and of the command line Lua script +% \texttt{l3sys-query} which is distributed separately and provides +% the underlying functionality. +% +% +% +% \section{The document level key-value interface\label{sec:kv}} +% +% This provides an interface to \texttt{l3sys-query} based on +% \pkg{l3keys} that allows the options to be specified and checked +% individually. Internally the supplied key values are used to build +% up the arguments to the commands described above in the L3 +% programming layer commands described in section~\ref{sec:expl3} +% +% Results containing path separators \emph{always} +% use~|/|, irrespective of the platform in use. +% +% +% \begin{function} +% {\QueryWorkingDirectory} +% \begin{syntax} +% \cs{QueryWorkingDirectory} \Arg{result cmd} +% \end{syntax} +% Defines supplied command \meta{result cmd} to hold +% the absolute path to the current working directory of the +% \TeX\ system. +% This is the directory (folder) from which \TeX\ was started, so usually +% the location of the main document file. +% \end{function} +% +% \begin{function} +% {\QueryFiles, \QueryFilesTF} +% \begin{syntax} +% \cs{QueryFiles} \oarg{options} \Arg{spec} \Arg{function} +% \cs{QueryFilesTF} \oarg{options} \Arg{spec} \Arg{function} \Arg{pre code} \Arg{empty list code} +% \end{syntax} +% This generates a file list based on the \meta{spec} and \meta{options}. +% The command then applies \meta{function} to each item in the sequence of filenames. +% The \meta{function} should be a macro body which will be passed the file path as |#1|. +% +% The TF version executes the T (\meta{pre code}) argument before iterating over the list +% and the F (\meta{empty list code}) argument if the list is empty. +% \end{function} +% +% Note that this interface in mapping directly over the sequence of +% filenames does not allow some uses which are provided by the +% programming interface described in the following section, which allows +% the sequence to be manipulated before being used. +% +% The defined keys map vey closely to the options of the +% \texttt{l3sys-query} command which is described in +% section~\ref{sec:lua}. +% +% \begin{itemize} +% \item +% The keys \texttt{recursive}, \texttt{ignore-case}, \texttt{reverse}, \texttt{pattern} +% take no values and map directly to the command line options of the same name. +% +% \item +% The key \texttt{sort} accepts the values \texttt{date} and \texttt{name}. +% +% \item +% The key \texttt{type} accepts \texttt{d} or \texttt{f}. +% +% \item +% The key \texttt{exclude} accepts a glob (or Lua pattern) mathing +% files to be excluded. The package arranges that the quoting of the +% argument is automatically added if unrestricted shell escape is +% enabled. +% +% \end{itemize} +% +% Within the main \meta{spec} argument, and the value of the \texttt{exclude} key, +% the following characters may need special handling. +% |~| may be used (which \texttt{kpathsea} uses to denote the users home directory). +% |\%|, or at the top level |%|, may be used to produce a literal |%| +% which may be especially useful if the \texttt{pattern} key is used +% as \% is the escape character in Lua patterns. +% +% \subsection{Examples\label{sec:examples2e}} +% +% \begin{itemize} +% \item +% Include every |png| file in the current directory. +% \begin{verbatim} +% \QueryFiles{*.png}{\includegraphics{#1}\par} +% \end{verbatim} +% +% \item +% Input every \TeX\ file with a filename matching \texttt{chapter[0-9].tex}. +% \begin{verbatim} +% \QueryFiles[pattern]{chapter%d.*%.tex}{\input{#1}} +% \end{verbatim} +% \end{itemize} +% +% \section{The L3 programming layer interface\label{sec:expl3}} +% +% \begin{function} +% {\sys_get_query:nN, \sys_get_query:nnN, \sys_get_query:nnnN} +% \begin{syntax} +% \cs{sys_get_query:nN} \Arg{cmd} \Arg{tl var} +% \cs{sys_get_query:nnN} \Arg{cmd} \Arg{spec} \Arg{tl var} +% \cs{sys_get_query:nnnN} \Arg{cmd} \Arg{options} \Arg{spec} \Arg{tl var} +% \end{syntax} +% Sets the \meta{tl var} to the information returned by the +% \texttt{l3sys-query} \meta{cmd}, potentially supplying the \meta{options} +% and \meta{spec} to the query call. The valid \meta{cmd} names are at present +% \begin{itemize} +% \item \texttt{pwd} Returns the absolute path to the current working directory +% \item \texttt{ls} Returns a directory listing, using the \meta{spec} to +% select files and applying the \meta{options} if given +% \end{itemize} +% The \meta{spec} should be a file glob and will automatically be passed to +% the script without shell expansion. +% \end{function} +% +% \begin{function} +% {\sys_split_query:nN, \sys_split_query:nnN, \sys_split_query:nnnN} +% \begin{syntax} +% \cs{sys_split_query:nN} \Arg{cmd} \Arg{seq} +% \cs{sys_split_query:nnN} \Arg{cmd} \Arg{spec} \Arg{seq} +% \cs{sys_split_query:nnnN} \Arg{cmd} \Arg{options} \Arg{spec} \Arg{seq} +% \end{syntax} +% Works as described for \cs{sys_get_query:nnnN}, but sets the \meta{seq} +% to contain one entry for each line returned by \texttt{l3sys-query}. +% \end{function} +% +% \section{The \texttt{l3sys-query} Lua script\label{sec:lua}} +% \subsection{The command line interface} +% +% The command line interface to +% \begin{center} +% \ttfamily +% l3sys-query \meta{cmd} [\meta{option(s)}] [\meta{args}] +% \end{center} +% where \texttt{\meta{cmd}} can be one of the following: +% \begin{itemize}[noitemsep]\ttfamily +% \item ls +% \item ls \meta{args} +% \item pwd +% \end{itemize} +% The \meta{cmd} are described below. The result of the \meta{cmd} will be printed +% to the terminal in an interactive run; in normal usage, this will be piped to +% the calling \TeX{} process. Results containing path separators \emph{always} +% use~|/|, irrespective of the platform in use. +% +% As well as these targets, the script recognizes the options +% \begin{itemize} +% \item |--exclude| Specification for directory entries to exclude +% \item |--ignore-case| Ignores case when sorting directory listings +% \item |--pattern| (|-p|) Treat the \meta{args} as Lua patterns rather +% than converting from wildcards +% \item |--recursive| (|-r|) Enables recursive searching during directory +% listings +% \item |--reverse| Causes sorting to go from highest to lowest rather +% than lowest to highest +% \item |--sort| Sets the method used to sort entries returned by |ls| +% \item |--type| Selects the type of entry returned by |ls| +% \end{itemize} +% The action of these options on the appropriate \meta{cmd(s)} is detailed below. +% +% \subsubsection{\texttt{ls [\meta{args}]}} +% +% Lists the contents of one or more directories, in a manner somewhat reminiscent +% of the Unix command |ls| or the Windows command |dir|. The exact nature of the +% output will depend on the \meta{args}, if given, along with the prevailing +% options. Note that the options names are inspired by ideas from the Unix +% commands |ls| and |find| as well as the Windows command |dir|: they therefore do +% not map directly to those of any one of the command line tools that they +% somewhat mirror. +% +% When no \meta{args} are given, all entries in the current directory will be +% listed, one per line in the output. This will include both files and +% subdirectories. Each entry will include a path relative to the current +% directory: for files \emph{in} the current directory, this will be |./|. The +% order of results will be determined by the underlying operating system process: +% unless requested \emph{via} an option, no sorting takes place. +% +% As standard, the \meta{args} are treated as a file/path name potentially +% including |?| and |*| as wildcards, for example |*.png| or |file?.txt|. +% \begin{verbatim} +% l3sys-query ls '*.png' +% \end{verbatim} +% Some care is needed in preventing expansion of such wildcards by the shell or +% \texttt{texlua} process: these are detailed in Section~\ref{sec:wildcard}. In +% this section, |'| is used to indicate a character being used to suppress +% expansion: this is for example normal on macOS and Linux. +% +% Removal of entries from the listing can be achieved using the |--exclude| +% option, which should be given with a \meta{xarg}, for example +% \begin{verbatim} +% l3sys-query ls --exclude '*.bak' 'graphics/*' +% \end{verbatim} +% Directory entries starting |.| are traditionally hidden on Linux and macOS +% systems: these \enquote{dot} entries are excluded from the output of +% \texttt{l3sys-query}. The entries |.| and |..| for the current and parent +% directory are also excluded from the results returned by \texttt{l3sys-query} as +% they can always be assumed. +% +% For more complex matching, the \meta{args} can be treated as a Lua pattern using +% the |--pattern| (|-p|) option; this also applies to the \meta{xarg} argument to +% the |--exclude| option. For example, the equivalent to wildcard |*.png| could be +% obtained using +% \begin{verbatim} +% l3sys-query ls --pattern '^.*%.png$' +% \end{verbatim} +% +% The results returned by |ls| can be sorted using the |--sort| option. This can +% be set to |none| (use the order from the file system: the default), |name| (sort +% by file name) or |date| (sort by date last modified). The sorting order can be +% reversed using |--reverse|. Sorting normally takes account of case: this can be +% suppressed with the |--ignore-case| option. +% +% The listing can be filtered based on the type of entry using the |--type| +% option. This takes a string argument, one of |d| (directory) or |f| (file). +% +% As standard, only the path specified as part of the \meta{args} is queried. +% However, if the |--recursive| (|-r|) option is set, the query is applied within +% all subdirectories. Subdirectories starting with~|.| (macOS and Linux hidden) +% are excluded from recursion. +% +% For security reasons, only paths within the current working directory can be +% queried, thus for example |graphics/*.png| will list all |png| files in the +% |graphics| subdirectory, but |../graphics/*.png| will yield no output. +% +% \subsubsection{\texttt{pwd}} +% +% Returns the current working directory from which \texttt{l3sys-query} is run. +% From within a \TeX{} run, this will (usually) be the directory containing the +% main file, assuming a command such as +% \begin{verbatim} +% pdflatex main.tex +% \end{verbatim} +% The \texttt{pwd} command is unaffected by any options. +% +% \subsection{Spaces in arguments} +% +% Since \texttt{l3sys-query} is intended primarily for use with restricted shell +% escape calls from \TeX{} processes, handling of spaces is unusual. It is not +% possible to quote spaces in such a call, so for example whilst +% \begin{verbatim} +% l3sys-query ls "foo *" +% \end{verbatim} +% does work from the command prompt to find all files with names starting +% \verb*|foo |, it would not work \emph{via} restricted shell escape. To +% circumvent this, \texttt{l3sys-query} will collect all command line arguments +% after any \meta{options}, and combine these as a space-separated \meta{args}, +% for example allowing +% \begin{verbatim} +% l3sys-query ls foo '*' +% \end{verbatim} +% to achieve the same result as the first example. The result is that the +% \meta{args} will only every be interpreted by \texttt{l3sys-query} as a single +% argument. It also means that spaces cannot be used at the start or end of the +% argument, nor can multiple spaces appear between non-space arguments. +% +% \subsection{Wildcard expansion handling\label{sec:wildcard}} +% +% The handling of wildcards needs some further comment for those using +% \texttt{l3sys-query} from the command line: the \pkg{expl3} interface described +% in Section~\ref{sec:expl3} handles this aspect automatically for the user. +% +% On macOS and Linux, the shell normally expands globs, which include the +% wildcards |*| and |?|, before passing arguments to the appropriate command. +% This can be suppressed by surrounding the argument with |'| characters, hence +% the formulation +% \begin{verbatim} +% l3sys-query ls '*.png' +% \end{verbatim} +% earlier. +% +% On Windows, the shell does no expansion, and thus arguments are passed as-is to +% the relevant command. As such, |'| has no special meaning here. However, to +% allow quoting of wildcards from the shell in a platform-neutral manner, +% \texttt{l3sys-query} will strip exactly one set of |'| characters around each +% argument before further processing. +% +% It is not possible to use |"| quotes at all in the argument passed to +% \texttt{l3sys-query} from \TeX{}, as the \TeX{} system removes all |"| in +% |\input| while handling space quoting. +% +% Restricted shell escape prevents shell expansion of wildcards entirely. On +% non-Windows systems, it does this by ensuring that each argument is |'| quoted +% to ensure further expansion. Thus a \TeX{} call such as +% \begin{verbatim} +% \input|"l3sys-query ls '*.png'" +% \end{verbatim} +% will work if |--shell-escape| is used as the argument is passed directly to the +% shell, but in restricted shell escape will give an error such as: +% \begin{verbatim} +% ! I can't find file `"|l3sys-query ls '*.png'"'. +% \end{verbatim} +% The \LaTeX{} interfaces described above adjust the quoting used depending on the +% |shell-escape| status. +% +% +% \MaybeStop{} +% +% \section{The \LaTeXe\ package implementation} +% +% \begin{macrocode} +%<*package> +% \end{macrocode} +% +% \begin{macrocode} +\ExplSyntaxOn +%<@@=queryfiles> +% \end{macrocode} +% +% The package should eventually work in restricted shell escape but will do +% nothing useful if the process was started with |--no-shell-escape|. +% \begin{macrocode} +\sys_if_shell:F{ + \PackageWarningNoLine{l3sys-query} + {Shell ~Escape ~is ~disabled.\MessageBreak All ~queries ~will ~return ~empty ~results} + } +% \end{macrocode} +% +% \subsection{\cs{QueryWorkingDirectory}} +% |\QueryWorkingDirectory| is a direct call to the |pwd| command provided by \texttt{l3sys-query}. +% \begin{macrocode} +\NewDocumentCommand\QueryWorkingDirectory {m} { + \sys_get_query:nN {pwd} #1 +} +% \end{macrocode} +% +% \subsection{\cs{QueryFiles} and \cs{QueryFilesTF}} +% +% The declarations of these commands are done in two steps to allow catcode chanes +% before the arguments are read. This allows the use of |%| and |^^| in patterns +% at least if the command is not nested in another command argument. (|\%| may be used +% to generate |%| in all cases). +% +% Variables for saving the current definition of |\%| and |~|. +% \begin{macrocode} +\tl_new:N\l_query_percent_tl +\tl_new:N\l_query_tilde_tl +% \end{macrocode} +% +% Allow |%| and |^^| at the top level. +% \begin{macrocode} +\NewDocumentCommand\QueryFiles {} { + \group_begin: + \char_set_catcode_other:N \% + \char_set_catcode_other:N \^ + \QueryFiles_inner + } +% \end{macrocode} +% +% \begin{macrocode} +\char_set_catcode_active:N \~ +% \end{macrocode} +% +% \begin{macrocode} +\NewDocumentCommand\QueryFiles_inner {O{}m}{ + \group_end: + \tl_set:Nn\l_tmpa_tl{} + \cs_set_eq:NN \l_query_percent_tl \% + \cs_set_eq:NN \% \c_percent_str + \cs_set_eq:NN \l_query_tilde_tl ~ + \cs_set_eq:NN ~ \c_tilde_str + \keys_set:nn{QueryFiles}{#1} + \exp_args:NnV\sys_split_query:nnnN {ls} \l_tmpa_tl {#2} \l_tmpa_seq + \cs_set_eq:NN \% \l_query_percent_tl + \cs_set_eq:NN ~ \l_query_tilde_tl + \seq_map_inline:Nn\l_tmpa_seq +} +% \end{macrocode} +% +% This duplicates rather than shares code so as to read the function +% and TF arguments with normal catcode regime. +% (This could probably be optimised.) +% \begin{macrocode} +\NewDocumentCommand\QueryFilesTF {} { + \group_begin: + \char_set_catcode_other:N \% + \QueryFilesTF_inner + } +% \end{macrocode} +% +% \begin{macrocode} +\NewDocumentCommand\QueryFilesTF_inner {O{}m}{ + \group_end: + \tl_set:Nn\l_tmpa_tl{} + \cs_set_eq:NN \l_query_percent_tl \% + \cs_set_eq:NN \% \c_percent_str + \cs_set_eq:NN \l_query_tilde_tl ~ + \cs_set_eq:NN ~ \c_tilde_str + \keys_set:nn{QueryFiles}{#1} + \exp_args:NnV\sys_split_query:nnnN {ls} \l_tmpa_tl {#2} \l_tmpa_seq + \cs_set_eq:NN \% \l_query_percent_tl + \cs_set_eq:NN ~ \l_query_tilde_tl + \seq_if_empty:NTF \l_tmpa_seq \use_iii:nnn \__queryfiles_aux:nnn +} +% \end{macrocode} +% +% \begin{macrocode} +\char_set_catcode_space:N \~ +% \end{macrocode} +% +% \begin{macrocode} +\cs_new:Npn \__queryfiles_aux:nnn #1#2#3 { + #2 + \seq_map_inline:Nn\l_tmpa_seq {#1} + } +% \end{macrocode} +% +% Defining the keys. Most take no value and simply add a \texttt{l3sys-query} \texttt{-{}-} +% option to the command linebeing constructed. +% \begin{macrocode} +\keys_define:nn {QueryFiles} { +% \end{macrocode} +% +% \begin{macrocode} +recursive .code:n =\tl_put_right:Nn \l_tmpa_tl {--recursive ~ } , +recursive .value_forbidden:n = true , +% \end{macrocode} +% +% \begin{macrocode} +ignore-case .code:n =\tl_put_right:Nn \l_tmpa_tl {--ignore-case ~ } , +ignore-case .value_forbidden:n = true , +% \end{macrocode} +% +% \begin{macrocode} +reverse .code:n =\tl_put_right:Nn \l_tmpa_tl {--reverse ~ } , +reverse .value_forbidden:n = true , +% \end{macrocode} +% +% \begin{macrocode} +exclude .code:n =\tl_put_right:Ne \l_tmpa_tl { + --exclude ~ + \sys_if_shell_restricted:F' + \exp_not:n{#1} + \sys_if_shell_restricted:F' + ~ } , +exclude .value_required:n = true , +% \end{macrocode} +% +% The |type| key checks the supplied value is valid |d| for directories +% or |f| for files The default behaviour lists both. +% \begin{macrocode} +type .choices:nn = {d,f} + {\tl_put_right:Nn \l_tmpa_tl {--type ~ #1 ~ }} , +% \end{macrocode} +% +% The |sort| key checks the supplied value is valid |date| or |name|. +% \begin{macrocode} +sort .choices:nn = {date,name} +{\tl_put_right:Nn \l_tmpa_tl {--sort ~ #1 ~ }} , +% \end{macrocode} +% +% \begin{macrocode} +pattern .code:n =\tl_put_right:Nn \l_tmpa_tl {--pattern ~ } , +pattern .value_forbidden:n = true , +% \end{macrocode} +% +% \begin{macrocode} +} +% \end{macrocode} +% +% \begin{macrocode} +\ExplSyntaxOff +% \end{macrocode} +% +% \begin{macrocode} +%</package> +% \end{macrocode} +% +% \Finale +% diff --git a/macros/latex-dev/required/tools/l3sys-query.ins b/macros/latex-dev/required/tools/l3sys-query.ins new file mode 100644 index 0000000000..163eec0058 --- /dev/null +++ b/macros/latex-dev/required/tools/l3sys-query.ins @@ -0,0 +1,76 @@ +%% +%% This file will generate fast loadable files and documentation +%% driver files from the doc files in this package when run through +%% LaTeX or TeX. +%% +%% Copyright (C) 1993-2024 +%% The LaTeX Project and any individual authors listed elsewhere +%% in this file. +%% +%% This file is part of the Standard LaTeX `Tools Bundle'. +%% ------------------------------------------------------- +%% +%% It may be distributed and/or modified under the +%% conditions of the LaTeX Project Public License, either version 1.3c +%% of this license or (at your option) any later version. +%% The latest version of this license is in +%% https://www.latex-project.org/lppl.txt +%% and version 1.3c or later is part of all distributions of LaTeX +%% version 2005/12/01 or later. +%% +%% As this file contains legal notices, it is NOT PERMITTED to modify +%% this file in any way that the legal information placed into +%% generated files is changed (i.e., the files generated when the +%% original file is executed). This restriction does not apply if +%% (parts of) the content is reused in a different WORK producing its +%% own generated files. +%% +%% The list of all files belonging to the `Tools Bundle' is +%% given in the file `manifest.txt'. +%% +%% +%% --------------- start of docstrip commands ------------------ +%% +\input docstrip + +\keepsilent + +\usedir{tex/latex/tools} + +\preamble + +This is a generated file. + +The source is maintained by the LaTeX Project team and bug +reports for it can be opened at https://latex-project.org/bugs/ +(but please observe conditions on bug reports sent to that address!) + +Copyright (C) 1993-2024 +The LaTeX Project and any individual authors listed elsewhere +in this file. + +This file was generated from file(s) of the Standard LaTeX `Tools Bundle'. +-------------------------------------------------------------------------- + +It may be distributed and/or modified under the +conditions of the LaTeX Project Public License, either version 1.3c +of this license or (at your option) any later version. +The latest version of this license is in + https://www.latex-project.org/lppl.txt +and version 1.3c or later is part of all distributions of LaTeX +version 2005/12/01 or later. + +This file may only be distributed together with a copy of the LaTeX +`Tools Bundle'. You may however distribute the LaTeX `Tools Bundle' +without such generated files. + +The list of all files belonging to the LaTeX `Tools Bundle' is +given in the file `manifest.txt'. + +\endpreamble + +\keepsilent + +\generate{\file{l3sys-query.sty}{\from{l3sys-query.dtx}{package}}} + +\endbatchfile diff --git a/macros/latex-dev/required/tools/l3sys-query.pdf b/macros/latex-dev/required/tools/l3sys-query.pdf Binary files differnew file mode 100644 index 0000000000..9f67a453e1 --- /dev/null +++ b/macros/latex-dev/required/tools/l3sys-query.pdf diff --git a/macros/latex-dev/required/tools/layout.pdf b/macros/latex-dev/required/tools/layout.pdf Binary files differindex b2d34d40fc..90c51932ce 100644 --- a/macros/latex-dev/required/tools/layout.pdf +++ b/macros/latex-dev/required/tools/layout.pdf diff --git a/macros/latex-dev/required/tools/longtable.pdf b/macros/latex-dev/required/tools/longtable.pdf Binary files differindex 5fb3c4a917..c1c37913ff 100644 --- a/macros/latex-dev/required/tools/longtable.pdf +++ b/macros/latex-dev/required/tools/longtable.pdf diff --git a/macros/latex-dev/required/tools/multicol.pdf b/macros/latex-dev/required/tools/multicol.pdf Binary files differindex 360c09d0b9..dc6ec1cde6 100644 --- a/macros/latex-dev/required/tools/multicol.pdf +++ b/macros/latex-dev/required/tools/multicol.pdf diff --git a/macros/latex-dev/required/tools/rawfonts.pdf b/macros/latex-dev/required/tools/rawfonts.pdf Binary files differindex 98bfaa374a..e2cae3b61d 100644 --- a/macros/latex-dev/required/tools/rawfonts.pdf +++ b/macros/latex-dev/required/tools/rawfonts.pdf diff --git a/macros/latex-dev/required/tools/shellesc.pdf b/macros/latex-dev/required/tools/shellesc.pdf Binary files differindex c41228c1b9..290df81741 100644 --- a/macros/latex-dev/required/tools/shellesc.pdf +++ b/macros/latex-dev/required/tools/shellesc.pdf diff --git a/macros/latex-dev/required/tools/showkeys.pdf b/macros/latex-dev/required/tools/showkeys.pdf Binary files differindex 6b1ae4549e..968476380c 100644 --- a/macros/latex-dev/required/tools/showkeys.pdf +++ b/macros/latex-dev/required/tools/showkeys.pdf diff --git a/macros/latex-dev/required/tools/somedefs.pdf b/macros/latex-dev/required/tools/somedefs.pdf Binary files differindex 07a32befaa..42fe646dfb 100644 --- a/macros/latex-dev/required/tools/somedefs.pdf +++ b/macros/latex-dev/required/tools/somedefs.pdf diff --git a/macros/latex-dev/required/tools/tabularx.pdf b/macros/latex-dev/required/tools/tabularx.pdf Binary files differindex 28b61a3da3..73f2c1bdf2 100644 --- a/macros/latex-dev/required/tools/tabularx.pdf +++ b/macros/latex-dev/required/tools/tabularx.pdf diff --git a/macros/latex-dev/required/tools/theorem.pdf b/macros/latex-dev/required/tools/theorem.pdf Binary files differindex 96c8c8512f..eb1b723c21 100644 --- a/macros/latex-dev/required/tools/theorem.pdf +++ b/macros/latex-dev/required/tools/theorem.pdf diff --git a/macros/latex-dev/required/tools/tools-overview.pdf b/macros/latex-dev/required/tools/tools-overview.pdf Binary files differindex b5dd0670fb..74db7e1ce1 100644 --- a/macros/latex-dev/required/tools/tools-overview.pdf +++ b/macros/latex-dev/required/tools/tools-overview.pdf diff --git a/macros/latex-dev/required/tools/tools.ins b/macros/latex-dev/required/tools/tools.ins index 2fd1cd174b..8687d49d7f 100644 --- a/macros/latex-dev/required/tools/tools.ins +++ b/macros/latex-dev/required/tools/tools.ins @@ -178,6 +178,13 @@ given in the file `manifest.txt'. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \SimplePackage{shellesc} + +% Shell Filee System Queries +%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\batchinput{l3sys-query.ins} + + + % File-Error files %%%%%%%%%%%%%%%%%% \generate{% diff --git a/macros/latex-dev/required/tools/trace.pdf b/macros/latex-dev/required/tools/trace.pdf Binary files differindex f0065a21c3..a2f5e7d4fb 100644 --- a/macros/latex-dev/required/tools/trace.pdf +++ b/macros/latex-dev/required/tools/trace.pdf diff --git a/macros/latex-dev/required/tools/varioref.dtx b/macros/latex-dev/required/tools/varioref.dtx index ccf3468c9b..f25c524188 100644 --- a/macros/latex-dev/required/tools/varioref.dtx +++ b/macros/latex-dev/required/tools/varioref.dtx @@ -40,7 +40,7 @@ %<package>\DeclareCurrentRelease{}{2019-10-01} %<package> %<package>\ProvidesPackage{varioref} -%<package> [2022/01/09 v1.6f package for extended references (FMi)] +%<package> [2024/01/15 v1.6f package for extended references (FMi)] % \fi % %% @@ -144,8 +144,8 @@ %\DescribeMacro\vref The implementation of |\vref| below produces only % a |\ref| when reference and |\label| are on the same page. It will % additionally produce one of the strings `on the facing page', `on -% the preceding page', or `on the following page', if label and -% reference differ by one and it will produce both |\ref| and +% the preceding page', or `on the following page' if label and +% reference differ by one; and it will produce both |\ref| and % |\pageref| when the difference is larger. The word `facing' is used % when label and reference both fall onto a double spread. However, % if a special page numbering scheme is used instead of the usual @@ -169,7 +169,7 @@ % comes out as ``\ldots~see the example which shows~\ldots'', which % could be misleading. % -% A space in front of |\vpageref| it will be ignored if +% A space in front of |\vpageref| will be ignored if % the command doesn't produce any text at all. % % But in fact |\vpageref| allows even more control. It has two @@ -210,7 +210,7 @@ % \DescribeMacro\vrefrange % This command is similar to |\vref| but it % takes two mandatory arguments denoting a range to refer to (e.g., a -% sequences of figures or a sequence of equations, etc.). So if +% sequence of figures or a sequence of equations, etc.). So if % |fig:a| is your first figure in the sequence and |fig:c| your last % you can write %\begin{verbatim} @@ -273,8 +273,8 @@ % \DescribeMacro\vpagerefcompare % \NewIn{2019} % For this kind of application the package also provides -% |\vpagerefcompare| as a command that takes four argument: two labels for -% comparison and a \meta{true} and \meta{false} argument. One of them +% |\vpagerefcompare| as a command that takes four arguments: two labels +% for comparison and a \meta{true} and \meta{false} argument. One of them % is executed depending on whether the two labels are on the same page % or on different pages. With its help the above definition could be % shortened to @@ -293,8 +293,9 @@ % Another command for conditional processing is |\vpagerefnearby|. It % takes three arguments: a label and a \meta{true} and \meta{false} % argument. It compares the page reference to the label with the -% current page number and if both are Arabic number and only differ by -% $\pm1$ the \meta{true} argument is executed otherwise the +% current page number; if each of these is a positive integer +% (expressed in Arabic numerals) and they differ by at most +% $\pm1$, the \meta{true} argument is executed, otherwise the % \meta{false} argument. In other words it tells you if a |\vpageref| % to the label would result in a textual reference to the previous, % current or next page.\footnote{There is also a @@ -320,11 +321,11 @@ % versions of the macros which do not add any space before the % generated text (they do nevertheless remove space at the left). % -% However, that too has problems (one is that \pkg{hyperref} +% However, that too has problems: one is that \pkg{hyperref} % \ChangedIn{2019} -% introduced the star forms as a means to generating references -% without hyperlinks (which is clearly the more important -% application). +% introduced the star forms as a means of generating references +% without hyperlinks, which is clearly the more important +% application. % So these days I recommend to always call the package with the option % \option{nospace} which prevents \pkg{varioref} from messing with the % space in front. Of course you are then responsible to always add it @@ -381,7 +382,7 @@ % label and reference fall onto the same page, but prefer reference to % page numbers otherwise then |\thevpagerefnum| can be used. This macro % hold the current page ``number'' when |\vpageref| and friends are -% executed. Thus, by defining, for example +% executed. Thus, by defining, for example, %\begin{verbatim} %\renewcommand\reftextfaceafter {on page~\thevpagerefnum} %\renewcommand\reftextfacebefore{on page~\thevpagerefnum} @@ -436,7 +437,7 @@ %\DescribeMacro\reftextafter %\DescribeMacro\reftextfaceafter Backward references use % |\reftextbefore| if the label is on the preceding page but invisible -% and |\reftextfacebefore| if it is one the facing page (i.e., if the +% and |\reftextfacebefore| if it is on the facing page (i.e., if the % current page number is odd). Similarly |\reftextafter| is used % when the label comes on the next page but one has to turn the page % and |\reftextfaceafter| if it is on the following but facing page. @@ -447,7 +448,7 @@ %\DescribeMacro\reftextfaraway Finally we have |\reftextfaraway| which % is used whenever label and reference differ by more than one or when % they aren't numeric. This macro is a bit different because it takes -% one argument, the symbolic reference string so that one cane make +% one argument, the symbolic reference string, so that one can make % use of |\pageref| in its replacement text. % % @@ -521,7 +522,7 @@ % and \option{nospace}. While the former is the default to allow % \NewIn{2019} % documents written in the last twenty years to continue to work -% correctly, I nowadays, suggest that you always use the package with +% correctly, I nowadays suggest that you always use the package with % the option \option{nospace}. This will stop \pkg{varioref} from % meddling with the spaces preceding commands and thus make the star % forms |\vref*| and |\vpageref*| unnecessary. @@ -536,7 +537,7 @@ % Defining commands like the ones described above poses some % interesting problems. Suppose, for example, that a generated text % like `on the next page' gets broken across pages. If this happens it -% is very difficult to find an acceptable solution and in fact can +% is very difficult to find an acceptable solution and it can, in fact, % even result in a document that will always change from one state to % another (i.e., inserting one string, finding that this is wrong, % inserting another string on the next run which makes the first @@ -699,7 +700,7 @@ % \begin{macro}{\reftextbefore} % \begin{macro}{\reftextcurrent} % \label{reftextbefore} The options do set the macros that -% generate the textual strings. Note, that they do not start with a +% generate the textual strings. Note that they do not start with a % space, the space is already added in the main macro below. % \changes{v1.2a}{1998/08/22}{Added American defaults for % \cs{reftextpagerange} and \cs{reftextlabelrange}} @@ -838,7 +839,7 @@ % the noun (clause); bertentangan is ``opposite'' in the sense of % ``facing''; berikutnya is ``next'' (in this context - actually % next-to-this, literally); berikutnya also translates as ``following -% this'' sebelumnya is ``preceding''; also ``previous'' ``ini'' translates, +% this''; sebelumnya is ``preceding'', also ``previous''; ``ini'' translates, % literally, as ``this'' but is also used in the sense of current page. % \changes{v1.4o}{2005/12/02}{Bahasa Malaysia defaults added.} % \begin{macrocode} @@ -1036,7 +1037,7 @@ \let\vrefrangeformat\vrefrangedefaultformat }} % \end{macrocode} -% Default string for dutch have been contributed by Frank Poppe +% Default strings for Dutch have been contributed by Frank Poppe % (\verb=POPPE@SWOV.NL=). % This option currently supports one additional string macro % |\refpagename| so that you can easily change to |bladzijde| @@ -1124,9 +1125,9 @@ \let\vrefrangeformat\vrefrangedefaultformat }} % \end{macrocode} -% The finnish strings were suggested by Matti Rintala +% The Finnish strings were suggested by Matti Rintala % (\verb=bitti@cs.tut.fi=) and Hillevi Gavel -% \verb=Hillevi.Gavel@mdh.se=. +% (\verb=Hillevi.Gavel@mdh.se=). % \changes{v1.0m}{1994/09/23}{Added finnish strings} % \changes{v1.4o}{2005/11/07}{Added a few more finnish strings} % \begin{macrocode} @@ -1200,10 +1201,10 @@ }} % \end{macrocode} % There are no good variants for German (I think and still think but -% this is a matter of taste :-). +% this is a matter of taste :-)). % \changes{v1.0b}{1994/01/31}{Replace in incorrect `def by `let} % The following definitions were recently suggested to me but since -% the original are in for a long time i don't want to change them +% the originals have been there for a long time I don't want to change them % now since that could make a lot of documents change their formatting. % If you fancy them, add a redefinition of the corresponding macro(s) % to the preamble of your document. @@ -1935,7 +1936,7 @@ % \end{macrocode} % But if \texttt{nospace} is in force we simply use the same space % value that was used in the source document (unless that was zero -% or non-existent. +% or non-existent). % \begin{macrocode} \ifdim\@tempskipa=\z@ \else \hskip\@tempskipa @@ -1978,7 +1979,7 @@ % \begin{macrocode} \vrefpagenum\thevpagerefnum{#3}% % \end{macrocode} -% Now after the internal label has served its purpose if would be +% Now after the internal label has served its purpose it would be % nice to free the memory it occupies by using something like % \begin{verbatim} % \global\expandafter\let @@ -2008,7 +2009,7 @@ \fi \else % \end{macrocode} -% If |#2| is empty we do nothing otherwise we insert it followed by +% If |#2| is empty we do nothing, otherwise we insert it followed by % a space. % \begin{macrocode} \def\@tempc{#2}% @@ -2017,7 +2018,7 @@ \fi % \end{macrocode} % Now we check if the page number of the referenced object (stored -% in |\thevpagerefnum| is a single positive number. +% in |\thevpagerefnum|) is a single positive number. % \begin{macrocode} \is@pos@number\thevpagerefnum {% @@ -2032,7 +2033,7 @@ }% % \end{macrocode} % If it is not a positive number we assign the largest possible -% number to |\@tempcnta| and thereby pretending that label and +% number to |\@tempcnta|, thereby pretending that label and % reference are miles away from each other. % \begin{macrocode} {\@tempcnta\maxdimen}% @@ -2049,7 +2050,7 @@ % Thus if the object falls onto an odd page then the reference is % on the facing even page (and so we insert |\reftextfaceafter|), % otherwise the object can not be seen from the reference (and we -% in insert |\reftextafter|). Don't be surprised if we are not +% insert |\reftextafter|). Don't be surprised if we are not % using |\thevpagerefnum| in the check. Since |\@tempcnta| has the same % value it is faster to use the register instead of parsing the % macro contents anew. @@ -2061,7 +2062,7 @@ % used. % Since the value of |\if@twoside| is evaluated before reading in % packages we could do better (saving some tokens) by defining -% the current macro in dependence of this boolean. +% the current macro depending on this boolean. % \begin{macrocode} \if@twoside \reftextfaceafter @@ -2075,11 +2076,11 @@ % If the object is not on the page following the reference we check % if it is on the page before the reference. In \LaTeX{} this % situation is not too common, for example with floats it normally -% does not occur, but of course it isn't impossible if you more +% does not occur, but of course it isn't impossible if you have more % than one reference to the same object, or if you have back % references to sections, theorems, etc. To test this we now % subtract two from the current value of |\@tempcnta| (which was -% set to one higher as the reference page number). Note, that +% set to one higher as the reference page number). Note that % subtraction is also possible if the value was |\maxdimen| --- we % still get something that is much larger than any sensible page % number. @@ -2131,7 +2132,7 @@ \reftextfaraway{#3}}% \fi % \end{macrocode} -% Finally we generate the internal label so that it can be check on +% Finally, we generate the internal label so that it can be checked on % the next run. This means that we compare the position after the % string with the position of the referenced object. There is one % thing to note: to conserve space we locally make |\@currentlabel| @@ -2252,8 +2253,8 @@ % The star form is easy (and just a convenient shortcut), just call % |\ref| followed by |\vpageref| and pass the optional argument to % the latter. We don't support the second optional argument of -% |\vpageref|, it that is needed one has to call both commands -% explicitly +% |\vpageref|, if that is needed one has to call both commands +% explicitly. % \changes{v1.6a}{2019/08/25}{Command added to support hyperref better} % \changes{v1.6e}{2020/07/25}{Changed for Japanese (gh/352)} % \begin{macrocode} @@ -2264,7 +2265,7 @@ % % \begin{macro}{\vrefformat,\vrefdefaultformat} % Japanese needs a different word order in \cs{vref@star} so this -% is separated out o that it can be changed on language level. +% is separated out so that it can be changed at the language level. % \changes{v1.6e}{2020/07/25}{Macro added (gh/352)} % \begin{macrocode} \def\vrefdefaultformat#1#2{% @@ -2293,7 +2294,7 @@ \unskip \nobreakspace \fi % \end{macrocode} -% The use of|\nobreakspace| or |~| after the |\unskip| means that +% The use of |\nobreakspace| or |~| after the |\unskip| means that % this command will always produce a normal space while % something like |\nobreak\space| will % react to settings of |\nonfrenchspacing|. @@ -2341,10 +2342,10 @@ % Now we have to check whether or not the whole string was parsed % into that register or some remainder was left over. Since we have % added a |\@nil| token at the very end we can use that to delimit -% the argument of |\is@pos@num@|. Note, that the added space in +% the argument of |\is@pos@num@|. Note that the added space in % |\is@pos@number| \vpageref[above]{isposnumber} gets parsed away % by the counter assignment. If it would be missing, and the full -% string would consist of a number, \TeX{}would try to replace +% string would consist of a number, \TeX{} would try to replace % |\@nil| by its definition to see if it would contain additional % digits and thus we would be in trouble at this point. % \begin{macrocode} @@ -2389,7 +2390,7 @@ % % \begin{macro}{\fullrefformat,\fullrefdefaultformat} % Japanese needs a different word order in \cs{fullref} so this -% is separated out o that it can be changed on language level. +% is separated out so that it can be changed at the language level. % \changes{v1.6e}{2020/07/25}{Macro added (gh/352)} % \begin{macrocode} \def\fullrefdefaultformat#1{% @@ -2523,7 +2524,7 @@ % % \begin{macro}{\vrefrangeformat,\vrefrangedefaultformat} % Japanese needs a different word order in \cs{vrefrange} so this -% is separated out o that it can be changed on language level. +% is separated out so that it can be changed at the language level. % \changes{v1.6d}{2020/07/20}{Macro added (gh/352)} % \begin{macrocode} \def\vrefrangedefaultformat#1#2#3{% @@ -2558,7 +2559,7 @@ % % \begin{macro}{\Vrefformat,\Vrefdefaultformat} % Japanese needs a different word order in \cs{Vref} so this -% is separated out o that it can be changed on language level. +% is separated out so that it can be changed at the language level. % \changes{v1.6e}{2020/07/25}{Macro added (gh/352)} % \begin{macrocode} \def\Vrefdefaultformat#1#2{% diff --git a/macros/latex-dev/required/tools/varioref.pdf b/macros/latex-dev/required/tools/varioref.pdf Binary files differindex 01a079a5ff..a398d5ff05 100644 --- a/macros/latex-dev/required/tools/varioref.pdf +++ b/macros/latex-dev/required/tools/varioref.pdf diff --git a/macros/latex-dev/required/tools/verbatim.pdf b/macros/latex-dev/required/tools/verbatim.pdf Binary files differindex bc055db066..d2bd345190 100644 --- a/macros/latex-dev/required/tools/verbatim.pdf +++ b/macros/latex-dev/required/tools/verbatim.pdf diff --git a/macros/latex-dev/required/tools/xr.pdf b/macros/latex-dev/required/tools/xr.pdf Binary files differindex b3c4530a59..3a7be5445a 100644 --- a/macros/latex-dev/required/tools/xr.pdf +++ b/macros/latex-dev/required/tools/xr.pdf diff --git a/macros/latex-dev/required/tools/xspace.pdf b/macros/latex-dev/required/tools/xspace.pdf Binary files differindex 792cae7e6c..51de3e2c87 100644 --- a/macros/latex-dev/required/tools/xspace.pdf +++ b/macros/latex-dev/required/tools/xspace.pdf |