[latex3-commits] [git/latex3] master: Redocument \__int_to_roman:w and \__int_value:w (fixes #397) (5e3f565)

[Bruno Le Floch]

Repository : https://github.com/latex3/latex3
On branch  : master
Link       : https://github.com/latex3/latex3/commit/5e3f56599b304d210aa30e9117adc95821d9c716

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

commit 5e3f56599b304d210aa30e9117adc95821d9c716
Author: Bruno Le Floch <bruno at le-floch.fr>
Date:   Tue Nov 28 16:00:30 2017 -0500

    Redocument \__int_to_roman:w and \__int_value:w (fixes #397)


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

5e3f56599b304d210aa30e9117adc95821d9c716
 l3kernel/l3int.dtx |   47 +++++++++++++++++++++++++++++++----------------
 1 file changed, 31 insertions(+), 16 deletions(-)

diff --git a/l3kernel/l3int.dtx b/l3kernel/l3int.dtx
index db69661..fbe0b4c 100644
--- a/l3kernel/l3int.dtx
+++ b/l3kernel/l3int.dtx
@@ -900,31 +900,46 @@
 %
 % \section{Internal functions}
 %
-% \begin{function}[EXP]{\__int_to_roman:w}
+% \begin{function}[EXP]{\__int_value:w}
 %   \begin{syntax}
-%     \cs{__int_to_roman:w} \meta{integer} \meta{space} \textit{or} \meta{non-expandable token}
+%     \cs{__int_value:w} \meta{integer}
+%     \cs{__int_value:w} \meta{integer denotation} \meta{optional space}
 %   \end{syntax}
-%   Converts \meta{integer} to it lower case Roman representation. Expansion
-%   ends when a space or non-expandable token is found.
-%   Note that this function produces a string of letters with category code
-%   $12$ and that protected functions \emph{are} expanded by this
-%   process. Negative \meta{integer} values result in no output, although
-%   the function does not terminate expansion until a suitable endpoint
-%   is found in the same way as for positive numbers.
+%   Expands the following tokens until an \meta{integer} is formed, and
+%   leaves a normalized form (no leading sign except for negative
+%   numbers, no leading digit~|0| except for zero) in the input stream
+%   as category code $12$ (other) characters.  The \meta{integer} can
+%   consist of any number of signs (with intervening spaces) followed
+%   by
+%   \begin{itemize}
+%     \item an integer variable (in fact, any \TeX{} register except
+%       \tn{toks}) or
+%     \item \cs{__int_eval:w} \meta{intexpr} \cs{__int_eval_end:} (or
+%       another \eTeX{} expression) or
+%     \item explicit digits (or by |'|\meta{octal digits} or |"|\meta{hexadecimal digits} or |`|\meta{character}
+%   \end{itemize}
+%   In this last case expansion stops once a non-digit is found; if that is a space it is removed as in \texttt{f}-expansion.
+%   Note that protected functions \emph{are} expanded by this process
 %   \begin{texnote}
-%     This is the \TeX{} primitive \tn{romannumeral} renamed.
+%     This is the \TeX{} primitive \tn{number}.
 %   \end{texnote}
 % \end{function}
 %
-% \begin{function}[EXP]{\__int_value:w}
+% \begin{function}[EXP]{\__int_to_roman:w}
 %   \begin{syntax}
-%     \cs{__int_value:w} \meta{integer}
-%     \cs{__int_value:w} \meta{tokens} \meta{optional space}
+%     \cs{__int_to_roman:w} \meta{integer}
+%     \cs{__int_to_roman:w} \meta{integer denotation} \meta{optional space}
 %   \end{syntax}
-%   Expands \meta{tokens} until an \meta{integer} is formed. One space may be
-%   gobbled in the process.
+%   Converts an \meta{integer} to lower case Roman representation.  The
+%   \meta{integer} is found as in \cs{__int_value:w} by expanding what
+%   follows exhaustively.  One (optional) space is lost if the
+%   \meta{integer} is given by explicit digits.  Note that this function
+%   produces a string of letters with category code~$12$. Negative
+%   \meta{integer} values result in no output, although the function
+%   does not terminate expansion until a suitable endpoint is found in
+%   the same way as for positive numbers.
 %   \begin{texnote}
-%     This is the \TeX{} primitive \tn{number}.
+%     This is the \TeX{} primitive \tn{romannumeral} renamed.
 %   \end{texnote}
 % \end{function}
 %