summaryrefslogtreecommitdiff
path: root/macros/generic/xlop/doc/xlop-doc.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/generic/xlop/doc/xlop-doc.tex')
-rw-r--r--macros/generic/xlop/doc/xlop-doc.tex261
1 files changed, 196 insertions, 65 deletions
diff --git a/macros/generic/xlop/doc/xlop-doc.tex b/macros/generic/xlop/doc/xlop-doc.tex
index fb623b21d0..26581f844c 100644
--- a/macros/generic/xlop/doc/xlop-doc.tex
+++ b/macros/generic/xlop/doc/xlop-doc.tex
@@ -1,16 +1,62 @@
\documentclass[12pt]{report}
-\usepackage{manual}
+\usepackage[T1]{fontenc}
+\usepackage[utf8]{inputenc}
+\usepackage{fourier}
+\usepackage[scaled]{helvet}
+\usepackage[scaled]{luximono}
+\usepackage{makeidx}
+\usepackage{longtable}
+\usepackage{multicol}
+\usepackage{pst-node}
+\usepackage{fancyvrb-ex}
+\usepackage{geometry}
+\usepackage{xlop}
\usepackage[english]{babel}
\usepackage[autolanguage]{numprint}
\usepackage{dcolumn}
+\usepackage{hyperref}
+\usepackage{microtype}
+
+\fvset{label=source}% english
\newcommand*\boi{\textbackslash}
\newcommand*\at{@}
-\fvset{label=source}% english
-\renewcommand\parameter[1]{\texttt{#1}\index{#1@\texttt{#1}}%
+\fvset{xrightmargin=5cm,frame=single,fontsize=\small}
+\geometry{a4paper,left=4cm,right=4cm,top=3cm,bottom=3cm,nohead}
+
+\let\SBSori\SideBySideExample
+\def\SideBySideExample{%
+ \par\bigbreak\SBSori
+}
+\let\endSBSori\endSideBySideExample
+\def\endSideBySideExample{%
+ \endSBSori
+ \par\bigskip\noindent
+}
+
+\newenvironment{syntaxBNF}{%
+ \catcode`\_=12
+ \def\*##1*{$\langle$##1$\rangle$}%
+ \def\alt{\unskip~$|$~\ignorespaces}%
+ \def\sameline{\multicolumn{1}{c}{} & \null\quad}%
+ \ttfamily
+ \begin{center}\begin{tabular}{r@{\quad:=\quad}l}}
+{\end{tabular}\end{center}}
+
+\setlongtables
+\newcommand\package[1]{\textsf{#1}}
+\newcommand\file[1]{\texttt{#1}}
+
+\newcommand\macro[1]{\texttt{$\backslash$#1}\index{#1@\texttt{\boi {#1}}}}
+\newcommand\parameter[1]{\texttt{#1}\index{#1@\texttt{#1}}%
\index{parameter!\texttt{#1}}}
+\newcommand\bull{\vrule width3pt height4pt depth-1pt}
+
+\newcounter{stuff}
+\makeindex
+
\begin{document}
\begin{titlepage}
\null\par\vfill
@@ -32,7 +78,7 @@
\end{center}
\vfill
\begin{center}
- Jean-C鬽e Charpentier\\
+ Jean-C么me Charpentier\\
\today
\end{center}
\vfill\null\par
@@ -44,9 +90,9 @@
\pagenumbering{arabic}
\chapter{Overview}
-\label{chap:Pr閟entation}
+\label{chap:Pr茅sentation}
The \package{xlop} package is intended to make automatic arithmetic
-operation on arbitrary sized numbers and to display result either on
+operations on arbitrary sized numbers and to display result either on
display mode or inline mode. Here is a first exemple for an overview
of the syntax:
\begin{SideBySideExample}
@@ -156,13 +202,13 @@ you can compute complex expression in infix form:
\chapter{\package{xlop} Instructions}
Except some macros which will be examined later, the \package{xlop}'s
-macros can have an optional argument between squared braces in order
-to localy modify parameter's values. The other arguments (mandatory)
+macros can have an optional argument between brackets in order
+to localy modify parameter's values. The other (mandatory) arguments
are (nearly) always numbers. The two sections of this chapter describe
in details what is a number for \package{xlop} and how use parameters.
\section{In the Beginning Was the Number}
-\label{sec:Au d閎ut etait le nombre}
+\label{sec:Au d茅but etait le nombre}
\subsection{Size}
\label{subsec:Taille}
Before we see the general syntax of number, we examin the very
@@ -179,7 +225,7 @@ Here is a table showing a \TeX{} compilation for a multiplication with
two operands of same size, on a linux computer, pentium~II~600 and
256~Mb RAM:\footnote{In fact it was the author computer in 2004. The
actual author computer is \emph{more} powerfull but the author is
- lazy, and he has not remake the tests!}
+ lazy, and he has not remade the tests!}
\begin{center}
\begin{tabular}{|l|*{6}{c|}}
\hline
@@ -217,7 +263,7 @@ explanations later:
\*sep* \\
\sameline \textnormal{, and } \*digit*
\end{syntaxBNF}
-\index{syntax!BNF}\index{BNF grammar}
+\index{syntax (BNF)}\index{BNF syntax}
The \texttt{character} symbol means nearly any character accepted by
\TeX{}. The exceptions are characters \verb+%+ and \verb+#+ which are
@@ -239,14 +285,14 @@ the right definition! This possibility to have a name using macro
could seem useless but it is not true. For instance, you can realize
loops\index{loop} with names as \verb+r1+, \verb+r2+, \ldots,
\verb+r<n>+ using the code \verb+r\the\cpt+ as variable name, where
-\verb+cpt+ is a counter in the \TeX{} meaning. With \LaTeX{}, the code
+\verb+cpt+ is a counter in \TeX{} meaning. With \LaTeX{}, the code
is more verbose with \verb+r\number\value{cpt}+ where \verb+cpt+ is
now a \LaTeX{} counter. We will see an example using this syntax in
the section~\ref{sec:Creation d'operations complexes}
page~\pageref{sec:Creation d'operations complexes}.
\index{number!valid}In practice, what does it mean all these rules?
-First, they means that a number writes in a decimal form can be
+First, they mean that a number written in a decimal form can be
preceded by any sequence of plus or minus signs. Obviously, if there
is an odd number of minus signs, the number will be negative. Next, a
decimal number admits only one decimal separator symbol which can
@@ -266,14 +312,15 @@ have to use the \macro{opset} macro. For instance:
\begin{Verbatim}[xrightmargin=0pt]
\opset{decimalsepsymbol={,}}
\end{Verbatim}
-give the comma as decimal separator symbol for the whole document, at
+gives the comma as decimal separator symbol for the whole document, at
least, until another redefinition with \verb+\opset+.
\subsection{Symbols}
\label{subsecSymboles}
The \parameter{afterperiodsymbol} parameter indicates the symbol that
follows a quotient in line in a division with period
-search\index{division!period}. Its default value is \verb+$\ldots$+
+search\index{division!period}. We will see this parameter with the
+division. Its default value is \verb+$\ldots$+
The \parameter{equalsymbol} parameter indicates the symbol used for
equality. Its default value is \verb+$=$+. In fact, this parameter is
@@ -305,9 +352,11 @@ operation is put with respect to the baseline. The possible values are
default value.
\begin{SideBySideExample}
top\quad
- \opadd[voperation=top]{45}{172}\par
+ \opadd[voperation=top]{45}{172}
+
center\quad
- \opadd[voperation=center]{45}{172}\par
+ \opadd[voperation=center]{45}{172}
+
bottom\quad
\opadd[voperation=bottom]{45}{172}
\end{SideBySideExample}
@@ -317,16 +366,18 @@ is put with repect to operands. The possible values are \verb+top+,
\verb+center+ (default value), and \verb+bottom+.
\begin{SideBySideExample}
top\quad
- \opadd[voperator=top]{45}{172}\par
+ \opadd[voperator=top]{45}{172}
+
center\quad
- \opadd[voperator=center]{45}{172}\par
+ \opadd[voperator=center]{45}{172}
+
bottom\quad
\opadd[voperator=bottom]{45}{172}
\end{SideBySideExample}
-The \parameter{deletezero} parameter indicates if some numbers in
+The \parameter{deletezero} parameter indicates if numbers in
operation should be displayed with or whithout non-significant
-zeros. Exact r鬺e of this parameter depends of the actual
+zeros. Exact r么le of this parameter depends of the actual
operation. We will see that when we will study the different
operations.
@@ -374,10 +425,10 @@ negative numbers in inline operations. The possible values are:
\subsection{Dimensions}
\label{subsec:Dimensions}
In displayed operations, figures are put in fixed size boxes. The
-width is given by the \parameter{lineheight} parameter and the height
-is given by the \parameter{lineheight} parameter. The default value of
-\texttt{lineheight} is \verb+\baselineskip+ that is, interline space
-in operation is the same (by default) as in the normal text. The
+width and height are given by the \parameter{lineheight}
+and \parameter{lineheight} parameters. The default value of
+\texttt{lineheight} is \verb+\baselineskip+, that is, the interline
+space in operation is the same (by default) as in the normal text. The
default value for \texttt{columnwidth} is \texttt{2ex} because the
``normal'' width of figures would give bad results.
\begin{SideBySideExample}
@@ -393,14 +444,14 @@ improve this presentation giving a ``normal'' width to the dot.
decimalsepwidth=0.27778em]
{45.89}{127.5}
\end{SideBySideExample}
-It is better but give a positive width to the box that contain the
-decimal separator is risked. It will be more difficult to place
-extern object and it is counter against the idea to have a fixed
+It is better but it is dangerous to give a positive width to the box
+which contains the decimal separator. It will be more difficult to
+place extern object and it is counter against the idea to have a fixed
grid. You should avoid this in normal time.
The \parameter{columnwidth} and \parameter{lineheight} parameters
correspond to the only dimensions that \package{xlop} provides as
-public one, that is,
+public ones, that is,
\verb+\opcolumnwidth+\index{opcolumnwidth@\texttt{$\backslash$opcolumnwidth}}
and
\verb+\oplineheight+\index{oplineheight@\texttt{$\backslash$oplineheight}}
@@ -421,8 +472,8 @@ run over numbers.
\opadd[hrulewidth=8pt]{42}{172}
\end{SideBySideExample}
-There is also a paramater which allows to control the horizontal shift
-of decimal separator. It is the \parameter{decimalsepoffset} paramater
+There is also a parameter which allows to control the horizontal shift
+of decimal separator. It is the \parameter{decimalsepoffset} parameter
with a default value of~\texttt{-0.35}. This value indicates a length
with the unit \verb+\opcolumnwidth+. We will see an example at
section~\ref{sec:Division} page~\pageref{sec:Division}.
@@ -430,7 +481,7 @@ section~\ref{sec:Division} page~\pageref{sec:Division}.
\subsection{Figure's Styles}
\label{subsec:Styles des chiffres}
The \package{xlop} package provides five types of numbers and
-associates five style paramaters:
+associates five style parameters:
\begin{itemize}
\item operands with \parameter{operandstyle};
\item result with \parameter{resultstyle};
@@ -445,7 +496,7 @@ associates five style paramaters:
{45.89}{127.5}
\end{SideBySideExample}
Keep in mind that, in this manual, we use
-\package{pstricks}\index{pstricks} package.
+\package{pstricks}\index{pstricks@\package{pstricks}} package.
\index{parameter!index|(}%
In fact, the management of these styles is even more powerfull since
@@ -465,7 +516,7 @@ with the \verb+\lightgray+ style. We don't indicate anything for the
second operand, so it takes the basic style for its class. (Then with
\verb+\blue+ style.)
-This mechanism is even more powerfull since you can write two level
+This mechanism is even more powerfull since you can write two levels
index for operands, carries, and intermediary numbers (one level for
result and carry) in order to access to each style figure of these
numbers. To simplify index, a positive index indicates the rank of a
@@ -522,7 +573,7 @@ access individually to the decimal separator style, you have to use
\index{parameter!syntax|)}
\chapter{Arithmetic Operations}
-\label{chap:Op閞ations arithm閠iques}
+\label{chap:Op茅rations arithm茅tiques}
\section{Addition}
\label{sec:Addition}
Addition is deal by the \macro{opadd} macro. When it is in display
@@ -554,7 +605,7 @@ or not. Its default value is \texttt{true}.
The \parameter{lastcarry} parameter is also a boolean parameter. It
indicates if a carry without matching digit for the two operands must
be showed or not. Its default value is \texttt{false}. Take care to
-the exact r鬺e of this parameter. For instance, if the second operand
+the exact r么le of this parameter. For instance, if the second operand
in the following example is~15307, the last carry would be showed for
any value of the \texttt{lastcarry} parameter since there is a
matching digit in the second operand.
@@ -575,19 +626,85 @@ operands and the result has the same number of digits. For that,
\package{xlop} package adds non-significant zeros. Also, the
non-significant zeros of operands are not removed.
\begin{SideBySideExample}
- \opadd{012.3427}{5.2773}\par
+ \opadd{012.3427}{5.2773}
+
\opadd[deletezero=false]
{012.3427}{5.2773}
\end{SideBySideExample}
-This parameter has exactly the same r鬺e for inline mode than for
+This parameter has exactly the same r么le for inline mode than for
displayed mode.
\begin{SideBySideExample}
- \opadd[style=text]{02.8}{1.2}\par
+ \opadd[style=text]{02.8}{1.2}
+
\opadd[style=text,
- deletezero=false]{02.8}{1.2}\par
+ deletezero=false]{02.8}{1.2}
+\end{SideBySideExample}
+
+Version 0.27 adds a \macro{opmanyadd} macro in order to add more than
+two operands. There are some limitations:
+\begin{itemize}
+\item all the operands must be non negative;
+\item some parameters are useless, for instance \parameter{style};
+\item carries aren't displayed.
+\end{itemize}
+In the other hand, the \parameter{vmanyoperator} allows to control the
+operator signs.
+
+Here is the first example with the basic syntax. The operands must be
+enclosed inside braces. The number of arguments is not limited.
+\begin{SideBySideExample}
+ \opmanyadd{123.4}{3.1416}
+ {2.71828}{0.001}
+\end{SideBySideExample}
+
+The \macro{opmanyadd} macro accepts the style parameters for operands
+and result. About the operand style, the first index is the operand's
+place (top to bottom ones) and the second index is the digit of
+operand. For instance:
+\begin{SideBySideExample}
+ \newcommand\R{\color{red}}
+ \opmanyadd[operandstyle.2.3=\R,
+ operandstyle.3.3=\R,
+ resultstyle.3=\R,
+ resultstyle.4=\R]
+ {12.6}{853.3}{158.1}
+\end{SideBySideExample}
+This example shows that non significant zeros are discarded. They can
+be display with the \parameter{deletezero} parameter at false value:
+\begin{SideBySideExample}
+ \opmanyadd[deletezero=false]
+ {12.6}{853.3}{158.1}
\end{SideBySideExample}
+The \macro{opmanyadd} macro uses also the \parameter{voperation}
+parameter as for \macro{opadd} macro.
+
+There is a parameter which is specific to \macro{opmanyadd}:
+the \parameter{vmanyoperator} one. These parameter allows to
+display plus operator in six different ways.
+\begin{CenterExample}
+ \opmanyadd{1}{12}{123}{1234}\quad
+ \opmanyadd[vmanyoperator=center]
+ {1}{12}{123}{1234}\quad
+ \opmanyadd[vmanyoperator=top]
+ {1}{12}{123}{1234}\quad
+ \opmanyadd[vmanyoperator=bottom]
+ {1}{12}{123}{1234}
+\end{CenterExample}
+We can see that the default value is center. The values with lowercase
+first letter display as many operators than operands minus one. The
+same values with upercase first letter display one single plus
+operator:
+\begin{CenterExample}
+ \opmanyadd[vmanyoperator=Center]
+ {1}{12}{123}{1234}\quad
+ \opmanyadd[vmanyoperator=Top]
+ {1}{12}{123}{1234}\quad
+ \opmanyadd[vmanyoperator=Bottom]
+ {1}{12}{123}{1234}
+\end{CenterExample}
+
\section{Substraction}
\label{sec:soustraction}
Substraction is made by \macro{opsub} macro. In displayed mode, the
@@ -990,7 +1107,7 @@ anything. Result is record in a variable given as argument.
Since these commands don't display anything, parameters don't make
sens and aren't allowed for \macro{opadd*}, \macro{opsub*},
\macro{opmul*}, and \macro{opidiv*}. In the other hand,
-parameters \parameter{maxdivestep}, \parameter{safedivstep},
+parameters \parameter{maxdivstep}, \parameter{safedivstep},
and \parameter{period} influence calculations, then \macro{opdiv*}
macro accepts an optional argument to take account of them.
\begin{SideBySideExample}
@@ -1135,7 +1252,7 @@ decimal part are numbered from right to left, figures for integer part
are numbered from left to right. For instance, with the number
1234.56789, the second figure is 8, the second figure of the integer
part is 3, and the second figure of the decimal part is 6. It is now
-easy to guess the r鬺e of the six next macros:
+easy to guess the r么le of the six next macros:
\begin{itemize}
\item \parameter{opgetdigit} ;
\item \parameter{opsetdigit} ;
@@ -1146,11 +1263,11 @@ easy to guess the r鬺e of the six next macros:
\end{itemize}
Syntax is the same for these macros. The first argument is the
processed number (reading or writting), the second one is the index of
-te figure, and the third one is the variable name which hold the
-result (figure read or changed number). If index is out of the range,
-the reading macros give \texttt{0} as result and writing macros
-extend the number in order to reach this index (for that, zero will be
-created in new slots).
+the figure, and the third one is the variable name which hold the
+result (figure read) or the new figure (changed number). If index is
+out of the range, the reading macros give \texttt{0} as result and
+writing macros extend the number in order to reach this index (for
+that, zero will be created in new slots).
\section{Comparisons}
\label{sec:Comparaisons}
@@ -1438,8 +1555,8 @@ expression in \package{xlop}, more pleasant for users.
Formulas accept usual arithmetic operators \texttt{+}, \texttt{-},
\texttt{*}, and \texttt{/}. They accept also \texttt{:} operator for
euclidian division, and \verb+^+ for power. The \texttt{-} operator
-has both r鬺e of substraction and unary operator for opposite. The
-\texttt{+} has also these r鬺es, here the unary operator do\dots{}
+has both r么le of substraction and unary operator for opposite. The
+\texttt{+} has also these r么les, here the unary operator do\dots{}
nothing! Operands are written in decimal form or \emph{via} variable
name. However, \macro{opexpr} introduces a restriction about variable
name since variable names must be different to function names
@@ -1487,7 +1604,7 @@ Here is another example that shows that datas can come from a macro:
\appendix
\chapter{Short Summary}
-\label{chap:Aide-m閙oire}
+\label{chap:Aide-m茅moire}
\section{Compilation times}
\label{sec:Temps de compilation}
Compilation times was measured on a computer with
@@ -1700,6 +1817,8 @@ expected.
\verb+\oplput(T1,T2){<object>}+ &
Put \verb+<object>+ to the right of the point with coordinates
\verb+(T1,T2)+ in relation to reference point. \\\hline
+ \verb+opmanyadd[P]{n1}...{np}+ &
+ Display result of $\mathrm{n1}+\cdots+\mathrm{np}$ \\\hline
\verb+\opmul[P]{n1}{n2}+ &
Display result of \verb+n1*n2+. \\\hline
\verb+\opmul*{n1}{n2}{N}+ &
@@ -1763,7 +1882,7 @@ In this table, parameters:
\section{Parameter list}
\label{sec:Liste des parametres}
-\index{parameter@parameter!table of|(}%
+\index{parameter!table of|(}%
\begingroup
\advance\hoffset by-1.75cm \advance\linewidth by1.75cm
\begin{longtable}{|l|l|p{7cm}|}
@@ -1822,24 +1941,36 @@ In this table, parameters:
displayed only for additional shifting (value \verb+shift+), for
all the shifting (value \verb+all+), or never (value
\verb+none+). \\\hline
+ \verb+vmanyoperator+ &
+ \verb+center+ &
+ Vertical alignment for add symbol in displayed many operand
+ addition. The value \verb+top+ put operators from the level of first
+ operand to the level of second to last operand. The value
+ \verb+center+ put operators between operands. The value
+ \verb+bottom+ put operators from the level of second operand to the
+ level of last operand. The value \verb+Top+ put one single operator
+ at the level of first operand. The value \verb+\center+ put one
+ single operator at the vertical middle of operands. The value
+ \verb+Bottom+ put one single operator at the level of last
+ operand. \\\hline
\verb+voperation+ &
\verb+bottom+ &
- Vertical alignement for displayed operation. The value \verb+bottom+
+ Vertical alignment for displayed operation. The value \verb+bottom+
indicates that the bottom of operation will be aligned with
baseline. The value \verb+top+ indicates that the top of operation
will be aligned with baseline. The value \verb+center+ indicates
that operation will be verticaly centred with baseline. \\\hline
\verb+voperator+ &
\verb+center+ &
- Vertical alignement for operators in displayed operations. The value
+ Vertical alignment for operators in displayed operations. The value
\verb+top+ put operator at the level of first operand. The value
\verb+bottom+ put operator at the level of second operand. The value
\verb+center+ put operator between operands. \\\hline
\verb+hfactor+ &
\verb+decimal+ &
- Sort of operands alignement for displayed operation. The value
- \verb+decimal+ indicates an alignement on decimal separator. The
- value \verb+right+ indicates a flushright alignement. \\\hline
+ Sort of operands alignment for displayed operation. The value
+ \verb+decimal+ indicates an alignment on decimal separator. The
+ value \verb+right+ indicates a flushright alignment. \\\hline
\verb+vruleperiod+ &
\verb+-0.2+ &
Vertical position of rule which indicates period of quotient for
@@ -1954,20 +2085,21 @@ In this table, parameters:
\verb+\scriptsize+ &
Style for carries. The default value when compilation are made
without \LaTeX{} is \verb+\sevenrm+. \\\hline
-\end{longtable}\index{parameter@parameter!table of|)}
+\end{longtable}\index{parameter!table of|)}
\endgroup
\chapter{Tricks}
\label{chap:Trucs et astuces}
-\section{\package{xlop} vs. \package{calc} and \package{fp}}
+\section{\package{xlop} vs. \package{calc} and \package{xfp}}
You could believe that \package{xlop} can replace package such
\package{calc}\index{package!calc}\index{calc} and
-\package{fp}\index{package!fp}\index{fp}. In fact, that is not so
+\package{xfp}\index{package!xfp}\index{xfp}. In fact, that is not so
simple. Obviously \package{xlop} can do complex calculations, on arbitrary
long numbers but, unlike \package{calc}, it don't allow to process
-directly dimensions. Comparison with \package{fp} is somewhere more
+directly dimensions. Comparison with \package{xfp} is somewhere more
realistic but remember that \package{xlop} can make memory usage too
-high.
+high. In fact \package{xfp} is far more powerfull than \package{xlop}
+about pure calmculation!
If you want to process calculations on length\index{length}, you can use
that a dimen register allocation to a counter gives a number which
@@ -2182,7 +2314,7 @@ aren't allowed. It's not a bug, it's a feature. Author thinks that a
user who write brackets without anything between these brackets is
going to make a mistake. To obviate this
prohibition\index{parameter!void}, there is the particular
-parameter \parameter{nil} which has exactly this r鬺e.
+parameter \parameter{nil} which has exactly this r么le.
\index{loop|)}
Finally, note the trick \verb+{\setbox2=\box2}+ to obtain a void box
@@ -2272,8 +2404,8 @@ version~0.3 and its ``stable'' version will be version~0.4.
The features of version~0.3 aren't definitively fixed but there are
some points planned:
\begin{itemize}
-\item international version for pos閑s;
-\item op閞ations from 2 to 36~basis;
+\item international version for pos茅es;
+\item op茅rations from 2 to 36~basis;
\item additional high level functions with roots (\macro{oproot} for
any roots and \macro{opsqrt} for square root), exponential function,
logarithm, trigonometric functions (direct, inverse, hyperbolic);
@@ -2282,7 +2414,6 @@ some points planned:
are not the ones of the number, there will be overflow or filling);
this macro was present in version~0.1 and allow to display numbers
decimal aligned, right aligned, or left aligned;
-\item macro for addition with more than two operands;
\item parameter for scientific or engineer notation;
\item macro to allow to write a multi-line number and/or with thousand
separator;