[latex3-commits] [latex3/latex3] main: Re-order file docs (440d25875)
github at latex-project.org
github at latex-project.org
Sun Dec 10 21:27:42 CET 2023
Repository : https://github.com/latex3/latex3
On branch : main
Link : https://github.com/latex3/latex3/commit/440d2587553d624182d3640c2071266bdfec4378
>---------------------------------------------------------------
commit 440d2587553d624182d3640c2071266bdfec4378
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date: Sun Dec 10 20:27:42 2023 +0000
Re-order file docs
>---------------------------------------------------------------
440d2587553d624182d3640c2071266bdfec4378
l3kernel/l3file.dtx | 184 +++++++++++++++++++++++++++-------------------------
1 file changed, 95 insertions(+), 89 deletions(-)
diff --git a/l3kernel/l3file.dtx b/l3kernel/l3file.dtx
index 8545a8394..9578156eb 100644
--- a/l3kernel/l3file.dtx
+++ b/l3kernel/l3file.dtx
@@ -673,7 +673,9 @@
% \end{texnote}
% \end{function}
%
-% \section{File operation functions}
+% \section{File opertions}
+%
+% \subsection{Basic file operations}
%
% \begin{variable}[added = 2017-06-21]
% {
@@ -722,94 +724,7 @@
% \cs{l_file_search_path_seq}.
% \end{function}
%
-% \begin{function}[noTF, added = 2019-01-16, updated = 2019-02-16]
-% {\file_get:nnN, \file_get:VnN}
-% \begin{syntax}
-% \cs{file_get:nnN} \Arg{file name} \Arg{setup} \meta{tl}
-% \cs{file_get:nnNTF} \Arg{file name} \Arg{setup} \meta{tl} \Arg{true code} \Arg{false code}
-% \end{syntax}
-% Defines \meta{tl} to the contents of \meta{file name}.
-% Category codes may need to be set appropriately via the \meta{setup}
-% argument.
-% The non-branching version sets the \meta{tl} to \cs{q_no_value} if the file is
-% not found. The branching version runs the \meta{true code} after the
-% assignment to \meta{tl} if the file is found, and \meta{false code}
-% otherwise.
-% \end{function}
-%
-% \begin{function}[noTF, updated = 2019-02-16]
-% {\file_get_full_name:nN, \file_get_full_name:VN}
-% \begin{syntax}
-% \cs{file_get_full_name:nN} \Arg{file name} \meta{tl}
-% \cs{file_get_full_name:nNTF} \Arg{file name} \meta{tl} \Arg{true code} \Arg{false code}
-% \end{syntax}
-% Searches for \meta{file name} in the path as detailed for
-% \cs{file_if_exist:nTF}, and if found sets the \meta{tl var} the
-% fully-qualified name of the file, \emph{i.e.}~the path and file name.
-% This includes an extension |.tex| when the given \meta{file name}
-% has no extension but the file found has that extension.
-% In the non-branching version, the \meta{tl var} will be set to
-% \cs{q_no_value} in the case that the file does not exist.
-% \end{function}
-%
-% \begin{function}[added = 2019-09-03, rEXP]{\file_full_name:n, \file_full_name:V}
-% \begin{syntax}
-% \cs{file_full_name:n} \Arg{file name}
-% \end{syntax}
-% Searches for \meta{file name} in the path as detailed for
-% \cs{file_if_exist:nTF}, and if found leaves the
-% fully-qualified name of the file, \emph{i.e.}~the path and file name,
-% in the input stream.
-% This includes an extension |.tex| when the given \meta{file name}
-% has no extension but the file found has that extension.
-% If the file is not found on the path, the expansion is empty.
-% \end{function}
-%
-% \begin{function}[added = 2017-06-23, updated = 2020-06-24]
-% {\file_parse_full_name:nNNN, \file_parse_full_name:VNNN}
-% \begin{syntax}
-% \cs{file_parse_full_name:nNNN} \Arg{full name} \meta{dir} \meta{name} \meta{ext}
-% \end{syntax}
-% Parses the \meta{full name} and splits it into three parts, each of
-% which is returned by setting the appropriate local string variable:
-% \begin{itemize}
-% \item The \meta{dir}: everything up to the last |/| (path separator)
-% in the \meta{file path}. As with system \texttt{PATH} variables
-% and related functions, the \meta{dir} does \emph{not} include the
-% trailing |/| unless it points to the root directory. If there is no path (only
-% a file name), \meta{dir} is empty.
-% \item The \meta{name}: everything after the last |/| up to the last |.|,
-% where both of those characters are optional. The \meta{name} may
-% contain multiple |.| characters. It is empty if \meta{full name}
-% consists only of a directory name.
-% \item The \meta{ext}: everything after the last |.| (including the dot).
-% The \meta{ext} is empty if there is no |.| after the last |/|.
-% \end{itemize}
-%
-% Before parsing, the \meta{full name} is expanded until only non-expandable
-% tokens remain, except that active characters are also not expanded.
-% Quotes (|"|) are invalid in file names and are discarded from the input.
-% \end{function}
-%
-% \begin{function}[EXP, added = 2020-06-24]
-% {\file_parse_full_name:n, \file_parse_full_name:V}
-% \begin{syntax}
-% \cs{file_parse_full_name:n} \Arg{full name}
-% \end{syntax}
-% Parses the \meta{full name} as described for \cs{file_parse_full_name:nNNN},
-% and leaves \meta{dir}, \meta{name}, and \meta{ext} in the input stream,
-% each inside a pair of braces.
-% \end{function}
-%
-% \begin{function}[EXP, added = 2020-06-24]
-% {\file_parse_full_name_apply:nN, \file_parse_full_name_apply:VN}
-% \begin{syntax}
-% \cs{file_parse_full_name_apply:nN} \Arg{full name} \meta{function}
-% \end{syntax}
-% Parses the \meta{full name} as described for \cs{file_parse_full_name:nNNN},
-% and passes \meta{dir}, \meta{name}, and \meta{ext} as arguments to \meta{function},
-% as an \texttt{n}-type argument each, in this order.
-% \end{function}
+% \subsection{Information about files and file contents}
%
% \begin{function}[rEXP, added = 2019-11-19]
% {
@@ -947,6 +862,97 @@
% This is not available in older versions of \XeTeX{}.
% \end{function}
%
+% \begin{function}[noTF, updated = 2019-02-16]
+% {\file_get_full_name:nN, \file_get_full_name:VN}
+% \begin{syntax}
+% \cs{file_get_full_name:nN} \Arg{file name} \meta{tl}
+% \cs{file_get_full_name:nNTF} \Arg{file name} \meta{tl} \Arg{true code} \Arg{false code}
+% \end{syntax}
+% Searches for \meta{file name} in the path as detailed for
+% \cs{file_if_exist:nTF}, and if found sets the \meta{tl var} the
+% fully-qualified name of the file, \emph{i.e.}~the path and file name.
+% This includes an extension |.tex| when the given \meta{file name}
+% has no extension but the file found has that extension.
+% In the non-branching version, the \meta{tl var} will be set to
+% \cs{q_no_value} in the case that the file does not exist.
+% \end{function}
+%
+% \begin{function}[added = 2019-09-03, rEXP]{\file_full_name:n, \file_full_name:V}
+% \begin{syntax}
+% \cs{file_full_name:n} \Arg{file name}
+% \end{syntax}
+% Searches for \meta{file name} in the path as detailed for
+% \cs{file_if_exist:nTF}, and if found leaves the
+% fully-qualified name of the file, \emph{i.e.}~the path and file name,
+% in the input stream.
+% This includes an extension |.tex| when the given \meta{file name}
+% has no extension but the file found has that extension.
+% If the file is not found on the path, the expansion is empty.
+% \end{function}
+%
+% \begin{function}[added = 2017-06-23, updated = 2020-06-24]
+% {\file_parse_full_name:nNNN, \file_parse_full_name:VNNN}
+% \begin{syntax}
+% \cs{file_parse_full_name:nNNN} \Arg{full name} \meta{dir} \meta{name} \meta{ext}
+% \end{syntax}
+% Parses the \meta{full name} and splits it into three parts, each of
+% which is returned by setting the appropriate local string variable:
+% \begin{itemize}
+% \item The \meta{dir}: everything up to the last |/| (path separator)
+% in the \meta{file path}. As with system \texttt{PATH} variables
+% and related functions, the \meta{dir} does \emph{not} include the
+% trailing |/| unless it points to the root directory. If there is no path (only
+% a file name), \meta{dir} is empty.
+% \item The \meta{name}: everything after the last |/| up to the last |.|,
+% where both of those characters are optional. The \meta{name} may
+% contain multiple |.| characters. It is empty if \meta{full name}
+% consists only of a directory name.
+% \item The \meta{ext}: everything after the last |.| (including the dot).
+% The \meta{ext} is empty if there is no |.| after the last |/|.
+% \end{itemize}
+%
+% Before parsing, the \meta{full name} is expanded until only non-expandable
+% tokens remain, except that active characters are also not expanded.
+% Quotes (|"|) are invalid in file names and are discarded from the input.
+% \end{function}
+%
+% \begin{function}[EXP, added = 2020-06-24]
+% {\file_parse_full_name:n, \file_parse_full_name:V}
+% \begin{syntax}
+% \cs{file_parse_full_name:n} \Arg{full name}
+% \end{syntax}
+% Parses the \meta{full name} as described for \cs{file_parse_full_name:nNNN},
+% and leaves \meta{dir}, \meta{name}, and \meta{ext} in the input stream,
+% each inside a pair of braces.
+% \end{function}
+%
+% \begin{function}[EXP, added = 2020-06-24]
+% {\file_parse_full_name_apply:nN, \file_parse_full_name_apply:VN}
+% \begin{syntax}
+% \cs{file_parse_full_name_apply:nN} \Arg{full name} \meta{function}
+% \end{syntax}
+% Parses the \meta{full name} as described for \cs{file_parse_full_name:nNNN},
+% and passes \meta{dir}, \meta{name}, and \meta{ext} as arguments to \meta{function},
+% as an \texttt{n}-type argument each, in this order.
+% \end{function}
+%
+% \subsection{Accessing file contents}
+%
+% \begin{function}[noTF, added = 2019-01-16, updated = 2019-02-16]
+% {\file_get:nnN, \file_get:VnN}
+% \begin{syntax}
+% \cs{file_get:nnN} \Arg{file name} \Arg{setup} \meta{tl}
+% \cs{file_get:nnNTF} \Arg{file name} \Arg{setup} \meta{tl} \Arg{true code} \Arg{false code}
+% \end{syntax}
+% Defines \meta{tl} to the contents of \meta{file name}.
+% Category codes may need to be set appropriately via the \meta{setup}
+% argument.
+% The non-branching version sets the \meta{tl} to \cs{q_no_value} if the file is
+% not found. The branching version runs the \meta{true code} after the
+% assignment to \meta{tl} if the file is found, and \meta{false code}
+% otherwise. The file content will be tokenized using the current
+% category code régime,
+% \end{function}
%
% \begin{function}[updated = 2017-06-26]{\file_input:n, \file_input:V}
% \begin{syntax}
More information about the latex3-commits
mailing list.