[latex3-commits] [latex3/latex2e] l3sys-query: editorial rewording, and code comments (c490ce9f)

[github at latex-project.org]

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

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

commit c490ce9f69d80f8519cf5c2ad41ecab797601411
Author: David Carlisle <d.p.carlisle at gmail.com>
Date:   Thu Mar 14 09:16:49 2024 +0000

    editorial rewording, and code comments


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

c490ce9f69d80f8519cf5c2ad41ecab797601411
 required/tools/l3sys-query.dtx | 38 ++++++++++++++++++++++++++++++--------
 1 file changed, 30 insertions(+), 8 deletions(-)

diff --git a/required/tools/l3sys-query.dtx b/required/tools/l3sys-query.dtx
index d2e07716..2b89bc22 100644
--- a/required/tools/l3sys-query.dtx
+++ b/required/tools/l3sys-query.dtx
@@ -81,12 +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 supplied key values are used to build up
-% the arguments to the commands described above in \ref{sec:expl3}
-%
-% The package just provides three commands.
+% 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.
@@ -97,8 +96,11 @@
 %   \begin{syntax}
 %     \cs{QueryWorkingDirectory} \Arg{result cmd}
 %   \end{syntax}
-%   Returns the absolute path to the current working directory of the
-%   \TeX\ system in the supplied command \meta{result cmd}.
+%   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}
@@ -377,8 +379,11 @@
 %
 %    \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}
@@ -386,12 +391,21 @@
   }
 %    \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
@@ -466,6 +480,8 @@
  }
 %    \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}
@@ -495,9 +511,15 @@ exclude .code:n  =\tl_put_right:Ne \l_tmpa_tl {
 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}