[latex3-commits] [l3svn] r6895 - Small l3fp doc improvements

[noreply at latex-project.org]

Author: bruno
Date: 2017-02-11 21:58:54 +0100 (Sat, 11 Feb 2017)
New Revision: 6895

Modified:
   trunk/l3kernel/l3fp.dtx
Log:
Small l3fp doc improvements


Modified: trunk/l3kernel/l3fp.dtx
===================================================================
--- trunk/l3kernel/l3fp.dtx	2017-02-11 19:58:50 UTC (rev 6894)
+++ trunk/l3kernel/l3fp.dtx	2017-02-11 20:58:54 UTC (rev 6895)
@@ -136,12 +136,15 @@
 % for higher-level commands.  For example, one could provide a function
 % to typeset nicely the result of floating point computations.
 % \begin{verbatim}
+%   \documentclass{article}
 %   \usepackage{xparse, siunitx}
 %   \ExplSyntaxOn
 %   \NewDocumentCommand { \calcnum } { m }
 %     { \num { \fp_to_scientific:n {#1} } }
 %   \ExplSyntaxOff
+%   \begin{document}
 %   \calcnum { 2 pi * sin ( 2.3 ^ 5 ) }
+%   \end{document}
 % \end{verbatim}
 %
 % \section{Creating and initialising floating point variables}
@@ -362,7 +365,7 @@
 %   \texttt{true} if the \meta{relation} is obeyed.  Two floating point
 %   numbers $x$ and~$y$ may obey four mutually exclusive relations:
 %   $x<y$, $x=y$, $x>y$, or $x$ and~$y$ are not ordered.  The latter
-%   case occurs exactly when either operand is~\nan{}, and this relation
+%   case occurs exactly when one or both operands is~\nan{}, and this relation
 %   is denoted by the symbol~|?|.  Note that a~\nan{} is distinct from
 %   any value, even another~\nan{}, hence $x=x$ is not true for
 %   a~\nan{}.  To test if a value is~\nan{}, compare it to an arbitrary
@@ -406,7 +409,7 @@
 %   computed, even if one comparison is \texttt{false}.  Two floating
 %   point numbers $x$ and~$y$ may obey four mutually exclusive
 %   relations: $x<y$, $x=y$, $x>y$, or $x$ and~$y$ are not ordered.  The
-%   latter case occurs exactly when one of the operands is~\nan{}, and
+%   latter case occurs exactly when one or both operands is~\nan{}, and
 %   this relation is denoted by the symbol~|?|.  Each \meta{relation}
 %   can be any (non-empty) combination of |<|, |=|, |>|, and~|?|, plus
 %   an optional leading~|!| (which negates the \meta{relation}), with
@@ -632,7 +635,8 @@
 %
 % \enquote{Exceptions} may occur when performing some floating point
 % operations, such as \texttt{0 / 0}, or \texttt{10 ** 1e9999}.  The
-% \textsc{IEEE} standard defines $5$ types of exceptions.
+% relevant \textsc{IEEE} standard defines $5$ types of exceptions,
+% of which we implement~$4$.
 % \begin{itemize}
 % \item \emph{Overflow} occurs whenever the result of an operation is
 %   too large to be represented as a normal floating point number.  This
@@ -641,16 +645,16 @@
 %   too close to $0$ to be represented as a normal floating point
 %   number.  This results in $\pm 0$.
 % \item \emph{Invalid operation} occurs for operations with no defined
-%   outcome, for instance $0/0$, or $\sin(\infty)$, and almost any
-%   operation involving a \nan{}.  This normally results in a \nan{},
-%   except for conversion functions whose target type does not have a
-%   notion of \nan{} (\emph{e.g.}, \cs{fp_to_dim:n}).
+%   outcome, for instance $0/0$ or $\sin(\infty)$, and results in a \nan{}.
+%   It also occurs for conversion functions whose target type does not
+%   have the appropriate infinite or \nan{} value (\emph{e.g.},
+%   \cs{fp_to_dim:n}).
 % \item \emph{Division by zero} occurs when dividing a non-zero number
-%   by $0$, or when evaluating \emph{e.g.}, $\ln(0)$ or $\cot(0)$.  This
-%   results in $\pm\infty$.
-% \item \emph{Inexact} occurs whenever the result of a computation is
-%   not exact, in other words, almost always.  At the moment, this
-%   exception is entirely ignored in \LaTeX3.
+%   by $0$, or when evaluating functions at poles, \emph{e.g.},
+%   $\ln(0)$ or $\cot(0)$.  This results in $\pm\infty$.
+% \item [\emph{(not yet)}] \emph{Inexact} occurs whenever the result of
+%   a computation is not exact, in other words, almost always.  At the
+%   moment, this exception is entirely ignored in \LaTeX3.
 % \end{itemize}
 % To each exception is associated a \enquote{flag}, which can be either
 % \emph{on} or \emph{off}.  By default, the \enquote{invalid operation}
@@ -774,11 +778,17 @@
 % replaced by $\pm\infty$), or an underflow (resulting in $\pm 0$).
 %
 % The result is thus $\pm 0$ if and only if \meta{significand} contains no
-% non-zero digit (\emph{i.e.}, consists only in~|0| characters, and an
-% optional |.| character), or if there is an underflow.  Note that a
+% non-zero digit (\emph{i.e.}, consists only in characters~|0|, and an
+% optional period), or if there is an underflow.  Note that a
 % single dot is currently a valid floating point number, equal to~$+0$,
 % but that is not guaranteed to remain true.
 %
+% The \meta{significand} must be non-empty, so |e1| and |e-1| are not
+% valid floating point numbers.  Note that the latter could be mistaken
+% with the difference of \enquote{\texttt{e}} and $1$.  To avoid
+% confusions, the base of natural logarithms cannot be input as |e| and
+% should be input as \texttt{exp(1)} or \cs{c_e_fp}.
+%
 % Special numbers are input as follows:
 % \begin{itemize}
 %   \item \texttt{inf} represents $+\infty$, and can be preceded by any
@@ -789,13 +799,6 @@
 %     \nan{}.
 % \end{itemize}
 %
-% Note that~|e-1| is not a representation of $10^{-1}$, because it could
-% be mistaken with the difference of \enquote{\texttt{e}} and $1$.  This
-% is consistent with several other programming languages.  However, in
-% order to avoid confusions, |e-1| is not considered to be this
-% difference either.  To input the base of natural logarithms, use
-% \texttt{exp(1)} or \cs{c_e_fp}.
-%
 % \subsection{Precedence of operators}
 % \label{sec:l3fp:fp-precedence}
 %
@@ -1284,7 +1287,7 @@
 % \section{Disclaimer and roadmap}
 %
 % The package may break down if the escape character is among
-% |0123456789_+|; if it receives a \TeX{} primitive conditional affected
+% |0123456789_+|, or if it receives a \TeX{} primitive conditional affected
 % by \cs{exp_not:N}.
 %
 % The following need to be done. I'll try to time-order the items.
@@ -1339,7 +1342,6 @@
 %   \item Document that \pkg{l3trial/l3fp-types} introduces tools for
 %     adding new types.
 %   \item In subsection~\ref{sec:l3fp:fp-floats}, write a grammar.
-%   \item Fix the |TWO BARS| business with the index.
 %   \item It would be nice if the \texttt{parse} auxiliaries for each
 %     operation were set up in the corresponding module, rather than
 %     centralizing in \pkg{l3fp-parse}.