[latex3-commits] [l3svn] r7210 - Improve documentation of functions that read from files

[noreply at latex-project.org]

Author: bruno
Date: 2017-05-28 03:13:54 +0200 (Sun, 28 May 2017)
New Revision: 7210

Modified:
   trunk/l3kernel/l3file.dtx
Log:
Improve documentation of functions that read from files

Rather than duplicating a lengthy explanation I've described
\ior_map_inline:Nn in terms of \ior_get:NN and cleaned up that
documentation.


Modified: trunk/l3kernel/l3file.dtx
===================================================================
--- trunk/l3kernel/l3file.dtx	2017-05-27 21:55:26 UTC (rev 7209)
+++ trunk/l3kernel/l3file.dtx	2017-05-28 01:13:54 UTC (rev 7210)
@@ -232,28 +232,34 @@
 %   and right braces are found) from the input \meta{stream} and stores
 %   the result locally in the \meta{token list} variable. If the
 %   \meta{stream} is not open, input is requested from the terminal.
-%   The material read from the \meta{stream} will be tokenized by
-%   \TeX{} according to the category codes in force when the function
-%   is used. Note that any blank lines will be converted to the token
-%   \cs{par}. Therefore, if skipping blank lines is requires a test such as
+%   The material read from the \meta{stream} will be tokenized by \TeX{}
+%   according to the category codes and \tn{endlinechar} in force when
+%   the function is used.  Assuming normal settings, any lines which do
+%   not end in a comment character~|%| will have the line ending
+%   converted to a space, so for example input
 %   \begin{verbatim}
+%      a b  c
+%   \end{verbatim}
+%   will result in a token list \verb*|a b c |.  Any blank line is
+%   converted to the token \cs{par}. Therefore, blank lines can be
+%   skipped by using a test such as
+%   \begin{verbatim}
 %      \ior_get:NN \l_my_stream \l_tmpa_tl
 %      \tl_set:Nn \l_tmpb_tl { \par }
 %      \tl_if_eq:NNF \l_tmpa_tl \l_tmpb_tl
 %      ...
 %   \end{verbatim}
-%   may be used. Also notice that if multiple lines are read to match braces
-%   then the resulting token list will contain \cs{par} tokens. As normal
-%   \TeX{} tokenization is in force, any lines which do not end in a comment
-%   character (usually |%|) will have the line ending converted to a space,
-%   so for example input
-%   \begin{verbatim}
-%      a b  c
-%   \end{verbatim}
-%   will result in a token list |a b c |.
+%   Also notice that if multiple lines are read to match braces
+%   then the resulting token list can contain \cs{par} tokens.
 %   \begin{texnote}
-%     This protected macro expands to the \TeX{} primitive \tn{read}
-%     along with the |to| keyword.
+%     This protected macro is a wrapper around the \TeX{} primitive
+%     \tn{read}.  Regardless of settings, \TeX{} replaces trailing space
+%     and tab characters (character codes 32 and~9) in each line by an
+%     end-of-line character (character code \tn{endlinechar}, omitted if
+%     \tn{endlinechar} is negative or too large) before turning
+%     characters into tokens according to current category codes.  With
+%     default settings, spaces appearing at the beginning of lines are
+%     also ignored.
 %   \end{texnote}
 % \end{function}
 %
@@ -279,9 +285,10 @@
 %   having category code~12.
 %   \begin{texnote}
 %     This protected macro is a wrapper around the \eTeX{} primitive
-%     \tn{readline}.  However, the end-line character normally added by
-%     this primitive is not included in the result of
-%     \cs{ior_str_get:NN}.
+%     \tn{readline}.  Regardless of settings, \TeX{} removes trailing
+%     space and tab characters (character codes 32 and~9).  However, the
+%     end-line character normally added by this primitive is not
+%     included in the result of \cs{ior_str_get:NN}.
 %   \end{texnote}
 % \end{function}
 %
@@ -289,13 +296,11 @@
 %   \begin{syntax}
 %     \cs{ior_map_inline:Nn} \meta{stream} \Arg{inline function}
 %   \end{syntax}
-%   Applies the \meta{inline function} to \meta{lines} obtained by
-%   reading one or more lines (until an equal number of left and right
-%   braces are found) from the \meta{stream}. The \meta{inline function}
-%   should consist of code which will receive the \meta{line} as |#1|.
-%   Note that \TeX{} removes trailing space and tab characters
-%   (character codes 32 and 9) from every line upon input.  \TeX{} also
-%   ignores any trailing new-line marker from the file it reads.
+%   Applies the \meta{inline function} to each set of \meta{lines}
+%   obtained by calling \cs{ior_get:NN} until reaching the end of the
+%   file.  \TeX{} ignores any trailing new-line marker from the file it
+%   reads.  The \meta{inline function} should consist of code which will
+%   receive the \meta{line} as |#1|.
 % \end{function}
 %
 % \begin{function}[added = 2012-02-11]{\ior_str_map_inline:Nn}