[latex3-commits] [latex3/latex2e] l3sys-query: missing section and other comments raised by @FrankMittelbach (3aba6516)

[github at latex-project.org]

Repository : https://github.com/latex3/latex2e
On branch  : l3sys-query
Link       : https://github.com/latex3/latex2e/commit/3aba6516985a9795e3363f93b1c6221c6f09ae17

>---------------------------------------------------------------

commit 3aba6516985a9795e3363f93b1c6221c6f09ae17
Author: David Carlisle <d.p.carlisle at gmail.com>
Date:   Wed Mar 13 23:16:41 2024 +0000

    missing section and other comments raised by @FrankMittelbach


>---------------------------------------------------------------

3aba6516985a9795e3363f93b1c6221c6f09ae17
 required/tools/l3sys-query.dtx | 61 ++++++++++++++++++++++++++++++++++++------
 1 file changed, 53 insertions(+), 8 deletions(-)

diff --git a/required/tools/l3sys-query.dtx b/required/tools/l3sys-query.dtx
index 243c559e..ac20e2c6 100644
--- a/required/tools/l3sys-query.dtx
+++ b/required/tools/l3sys-query.dtx
@@ -69,7 +69,7 @@
 % 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
+% 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
@@ -81,6 +81,11 @@
 % 
 % \section{The document level key-value  interface\label{sec:kv}}
 %
+% A document level interface is provided by this \pkg{l3sys-query} package.
+% This provides an interface based on \pkg{l3keys} that  allows the options to be
+% specified and checked individually. Internally the supplyed key values are used to build up
+% the arguments to the commands described above in \ref{sec:expl3}
+%
 % The package just provides three commands.
 %
 % \begin{function}
@@ -88,8 +93,8 @@
 %   \begin{syntax}
 %     \cs{QueryWorkingDirectory} \Arg{result cmd}
 %   \end{syntax}
-%   Returns the current working directory of the \TeX\ system in the
-%   supplied command \meta{result cmd}.
+%   Returns the absolute path to the current working directory of the
+%   \TeX\ system in the supplied command \meta{result cmd}.
 % \end{function}
 % 
 % \begin{function}
@@ -98,10 +103,50 @@
 %     \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}
-%   Returns the current working directory of the \TeX\ system in the
-%   supplied command \meta{result cmd}.
+%   This generates a file list  based on the \meta{spec} and \meta{options}
+%   the options 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 previous 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.
+% 
+%  \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.
+%  
+%  
+% 
+%
 % \section{The L3 programming layer interface\label{sec:expl3}}
 % 
 % \begin{function}
@@ -115,7 +160,7 @@
 %   \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 present working directory
+%     \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}
@@ -130,7 +175,7 @@
 %     \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_split_query:nnnN}, but sets the \meta{seq}
+%   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}
 % 
@@ -299,7 +344,7 @@
 % \begin{verbatim}
 % ! I can't find file `"|l3sys-query ls '*.png'"'.
 % \end{verbatim}
-% The \LaTeX{} interfaces described below adust the quoting used depending on the
+% The \LaTeX{} interfaces described above adjust the quoting used depending on the
 % |shell-escape| status.
 % 
 %