From 17036ad38f780e71d150dd4b6272d79dd19e9997 Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Mon, 29 Mar 2010 23:33:43 +0000
Subject: spreadtab 0.3 (28mar10)

git-svn-id: svn://tug.org/texlive/trunk@17613 c570f23f-e606-0410-a88d-b1316a301751
---
 .../doc/latex/spreadtab/spreadtab_doc_en.tex       | 159 +++++++++++++++++----
 1 file changed, 134 insertions(+), 25 deletions(-)

(limited to 'Master/texmf-dist/doc/latex/spreadtab/spreadtab_doc_en.tex')

diff --git a/Master/texmf-dist/doc/latex/spreadtab/spreadtab_doc_en.tex b/Master/texmf-dist/doc/latex/spreadtab/spreadtab_doc_en.tex
index c421123febe..d2471820012 100644
--- a/Master/texmf-dist/doc/latex/spreadtab/spreadtab_doc_en.tex
+++ b/Master/texmf-dist/doc/latex/spreadtab/spreadtab_doc_en.tex
@@ -28,7 +28,7 @@
 \usepackage[utf8]{inputenc}
 \usepackage[T1]{fontenc}
 \usepackage{lmodern}
-\usepackage[a4paper,margin=2.5cm]{geometry}
+\usepackage[a4paper,margin=2.6cm]{geometry}
 \usepackage{amsmath,amssymb}
 \usepackage{textcomp}
 \usepackage{array}
@@ -68,11 +68,11 @@
 	captionpos=t,xleftmargin=1em,xrightmargin=1em,lineskip=0pt,%
 	numbersep=1em,classoffset=1,%
 	morekeywords={% les macros et commandes de spreadtab
-		spreadtab,SThiderow,SThidecol,STsavecell,STautoround,STmessage,STsetdecimalsep,STtransposecar,STdebug,STdisplaytab,%
+		spreadtab,SThiderow,SThidecol,STsavecell,STautoround,STmessage,STsetdecimalsep,STtransposecar,STdebug,STdisplaytab,STsetdisplaymarks,%
 		STnumericfieldmarker,STtextcell,STcopy,fact,ifeq,ifgt,iflt,numtofrshortdate,%
 		numtoengshortdate,numtofrlongdate,numtoenglongdate,numtofrmonth,%
 		numtoengmonth,numtofrday,numtoengday,sum,rand,randint,sumprod,%
-		frshortdatetonum,engshortdatetonum,englongdatetonum,frlongdatetonum},%
+		frshortdatetonum,engshortdatetonum,englongdatetonum,frlongdatetonum,gcd,lcm},%
 	keywordstyle=\color{ST@keywordstc},classoffset=0}
 
 
@@ -163,12 +163,12 @@
 \end{titlepage}
 
 \tableofcontents\newpage
-\parskip\medskipamount This manual is a translation of the french manual. I apologize for my poor english but I did my best\footnote{Any help to improve this translation is welcome!}, and I hope that the following is comprehensible!
+\parskip\medskipamount This manual is a translation of the french manual. I apologize for my poor english but I did my best and I hope that the following is comprehensible! Any help improve this translation will be greatly appreciated.
 \section{Introduction}
 \subsection{Presentation}
 This package allows us to construct tables in a manner similar to a spreadsheet. The cells of a table have row and column indices and these can be used in formulas to generate values in other cells.
 
-The package requires $\varepsilon$-\TeX, \LaTeXe{} and the \href{http://www.ctan.org/tex-archive/macros/latex/contrib/fp/}{\texttt{\textbf{fp}}} package, which performs arithmetic on cell values. Also, the \href{http://www.ctan.org/tex-archive/macros/latex/contrib/xstring/}{\texttt{\textbf{xstring}}} package is needed in its \falseverb{v1.5c [2009/06/05]} version or later.\medskip
+The package requires $\varepsilon$-\TeX, \LaTeXe{} and the \href{http://www.ctan.org/tex-archive/macros/latex/contrib/fp/}{\texttt{\textbf{fp}}} package, which performs arithmetic on cell values. Also, the \href{http://www.ctan.org/tex-archive/macros/latex/contrib/xstring/}{\texttt{\textbf{xstring}}} package is needed in its \falseverb{v1.5d [2010/03/28]} version or later.\medskip
 
 The package is compatible with \emph{all} tabular environments, and assumes that `\verb=&=' is used to delimit columns and `\verb-\\-' to end the lines. This  compatibility requirement led me to program \ST so that it works independently of the table environment. Thus, reading the table, processing and calculating the formulas is done \emph{before} the environment table `sees' the body of the table.\medskip
 
@@ -568,6 +568,39 @@ It lasts more than \hhh\ hours.
 It lasts more than \hhh\ hours.
 \end{center}
 
+\subsection{Display the value of a cell}
+In order to display the numeric field of a cell in a textual field, we have seen that we could save this value in a control sequence and use this control sequence anywhere in the table. The process is somewhat tedious\ldots{} Indeed, the \verbinline-\STsavecell- is not intented to be used in such a way. Its aim is to save the value of a numeric field for a further use \emph{outside} the table.
+
+There is a simpler way to display the numeric field of a cell in a textual field using the syntax \verb-<<reference>>- which is replaced by the numeric field of the cell \verb-reference-, where the \verb-reference- can be absolute or relative. If the text between \verb-<<- and \verb->>- is not a reference, then \verb-<<text>>- is left as is. The \verb-reference- must not contain any space, and for exampple, if you write \verb-<< a1>>-, \ST does not uderstand it as a reference because of the space before "\verb-a1-".
+
+Example in a textual cell \verb-a3-:
+\begin{lstlisting}
+\begin{spreadtab}{{tabular}{lr}}
+@Sell price             & 250  \\
+@Purchase price         & 216  \\\hline
+@Profit (<<b1>>-<<b2>>) & b1-b2
+\end{spreadtab}
+\end{lstlisting}
+\begin{center}
+\begin{spreadtab}{{tabular}{lr}}
+@Sell price             & 250  \\
+@Purchase price         & 216  \\\hline
+@Profit (<<b1>>-<<b2>>) & b1-b2
+\end{spreadtab}
+\end{center}
+Example in the mixed cell \verb-c1-:
+\begin{lstlisting}
+\begin{spreadtab}{{tabular}{|c|c||c|}}\hline
+23 & 32 & Average $= \frac{<<a1>>+<<b1>>}{2}= :={(a1+b1)/2}$\\\hline
+\end{spreadtab}
+\end{lstlisting}
+\begin{center}
+\begin{spreadtab}{{tabular}{|c|c||c|}}\hline
+23 & 32 & Average $= \frac{<<a1>>+<<b1>>}{2}= :={(a1+b1)/2}$\\\hline
+\end{spreadtab}
+\end{center}
+The chars used to delimit the reference are set to "\verb-<<-" and "\verb->>-" by default. They can be modified with the \verbinline-\STsetdisplaymarks- command whose arguments contain the left and right delimiters. For example, if you write \verbinline-\STsetdisplaymarks{|}{|}-, you will write \verb-|reference|- in order to display the content of the numeric field of the cell \verb-reference-.
+
 \subsection{The use of \ttfamily\textbackslash multicolumn}
 \ST is compatible with the syntax \verbinline=\multicolumn{<number>}{<type>}{<content>}= which merges \falseverb{<number>} cells in unique cell whose type and content are specified in the arguments.
 
@@ -610,12 +643,19 @@ The number of digits displayed can be controlled in various ways:
 \begin{itemize}
 	\item the \href{http://www.ctan.org/tex-archive/macros/latex/contrib/numprint/}{\texttt{\textbf{numprint}}} package can be used in order to properly display numbers;
 	\item \verb=fp= can round or truc numbers with \verb-round(number,integer)- or \verb-trunc(number,integer)- but the syntax makes this tedious to write if this is needed for many cells;
-	\item \ST can round \emph{all} the numbers in the table with the macro \verbinline-\STautoround- whose argument is number of digits in the decimal part. If the argument is empty, no rounding is done.
+	\item \ST can round \emph{all} the numbers in the table with the macro \verbinline-\STautoround- whose argument is number of digits in the decimal part. If the argument is empty, no rounding is done. If the starred macro \verbinline-\STautoround*- is used, the decimal part is filled with 0 if necessary.
 \end{itemize}
 In this example, floating point numbers are rounded to 6 digits:\par\nobreak
 \begin{lstlisting}
 \STautoround{6}
-\begin{spreadtab}{{tabular}{|l|*7{>{\centering\arraybackslash}m{1.45cm}|}}}
+\begin{spreadtab}{{tabular}{|l|*7{>{\centering\arraybackslash}m{1.35cm}|}}}
+\hline
+@$x$     & 1    & 2    & 3    & 4    & 5    & 6    & 7   \\\hline
+@$x^{-1}$& 1/b1 & 1/c1 & 1/d1 & 1/e1 & 1/f1 & 1/g1 & 1/h1\\\hline
+\end{spreadtab}\medskip
+
+\STautoround*{6}
+\begin{spreadtab}{{tabular}{|l|*7{>{\centering\arraybackslash}m{1.35cm}|}}}
 \hline
 @$x$     & 1    & 2    & 3    & 4    & 5    & 6    & 7   \\\hline
 @$x^{-1}$& 1/b1 & 1/c1 & 1/d1 & 1/e1 & 1/f1 & 1/g1 & 1/h1\\\hline
@@ -623,7 +663,14 @@ In this example, floating point numbers are rounded to 6 digits:\par\nobreak
 \end{lstlisting}
 \begin{center}
 \STautoround{6}
-\begin{spreadtab}{{tabular}{|l|*7{>{\centering\arraybackslash}m{1.45cm}|}}}
+\begin{spreadtab}{{tabular}{|l|*7{>{\centering\arraybackslash}m{1.35cm}|}}}
+\hline
+@$x$     & 1    & 2    & 3    & 4    & 5    & 6    & 7   \\\hline
+@$x^{-1}$& 1/b1 & 1/c1 & 1/d1 & 1/e1 & 1/f1 & 1/g1 & 1/h1\\\hline
+\end{spreadtab}\medskip
+
+\STautoround*{6}
+\begin{spreadtab}{{tabular}{|l|*7{>{\centering\arraybackslash}m{1.35cm}|}}}
 \hline
 @$x$     & 1    & 2    & 3    & 4    & 5    & 6    & 7   \\\hline
 @$x^{-1}$& 1/b1 & 1/c1 & 1/d1 & 1/e1 & 1/f1 & 1/g1 & 1/h1\\\hline
@@ -801,6 +848,64 @@ The macro-function \verbinline-rand()- returns a random number between 0 and 1.\
 \end{spreadtab}
 \end{center}
 
+\subsubsection{GCD and LCM}
+The macro functions "gcd" and "lcm" compute the Greatest Common Divisor and the Least Common Multiple of list of numbers in their argument:
+\begin{center}
+\verbinline-gcd(number1,number2,...,numberN)-\par
+\verbinline-lcm(number1,number2,...,numberN)-
+\end{center}
+Exemple :
+\begin{lstlisting}
+\begin{spreadtab}{{tabular}{|r|r|r||c|c|}}\hline
+\multicolumn3{|c||}{@Numbers}& @GCD & @LCM \\\hline
+24 & 18 & 12 & \STcopy{v}{gcd(a2,b2,c2)} & \STcopy{v}{lcm(a2,b2,c2)}\\
+15 & 10 & 25 & & \\
+16 & 12 & 15 & & \\
+\hline
+\end{spreadtab}
+\end{lstlisting}
+\begin{center}
+\begin{spreadtab}{{tabular}{|r|r|r||c|c|}}\hline
+\multicolumn3{|c||}{@Numbers}& @GCD & @LCM \\\hline
+24 & 18 & 12 & \STcopy{v}{gcd(a2,b2,c2)} & \STcopy{v}{lcm(a2,b2,c2)}\\
+15 & 10 & 25 & & \\
+16 & 12 & 15 & & \\
+\hline
+\end{spreadtab}
+\end{center}
+
+\subsubsection{Scientific notation}
+The macro function "scitodec" enables to convert a number written in scientific notation into a decimal number, understandable by \ST to achieve its calculations. The syntax is \verbinline-scitodec(<text>)-, where \verb-<text>- is:
+\begin{itemize}
+	\item a sequence of characters with the syntax \verb-<mantissa>EE<exponent>- where \verb-<mantissa>- is a decimal number and the \verb-<exponent>- is an integer. The "E" may be written uppercase or lowercase.
+	
+	\verb-<mantissa>EE<exponent>- means the number $\text{\ttfamily <mantissa>}\times10^{\text{\ttfamily <exponent>}}$
+	\item a reference to the \emph{textual} field of a cell which must contain characters written with the syntax \verb-<mantissa>EE<exponent>-
+\end{itemize}
+Example :
+\begin{lstlisting}
+\begin{spreadtab}{{tabular}{|r|r|}}\hline
+@Scientific notations    & @Decimal notations \\\hline
+@4EE2                    & \STcopy{v}{scitodec([-1,0])}\\
+@-3.1EE-3                & \\
+@15ee5                   & \\
+@-0.025ee7               & \\
+@2.125EE0                & \\
+@3.1575EE-4              & \\\hline
+\end{spreadtab}
+\end{lstlisting}
+\begin{center}
+\begin{spreadtab}{{tabular}{|r|r|}}\hline
+@Scientific notations    & @Decimal notations \\\hline
+@4EE2                    & \STcopy{v}{scitodec([-1,0])}\\
+@-3.1EE-3                & \\
+@15ee5                   & \\
+@-0.025ee7               & \\
+@2.125EE0                & \\
+@3.1575EE-4              & \\\hline
+\end{spreadtab}
+\end{center}
+
 \subsection{Tests}
 Three macro-functions provide tests:\par\nobreak
 \begin{center}
@@ -1256,30 +1361,34 @@ This table is generated by the environment \verb=tabularx= stretched to fit 80\%
 \begin{lstlisting}
 \nprounddigits2
 \let\PC\%
-\begin{spreadtab}{{tabularx}{0.8\linewidth}{|>{\rule[-1.2ex]{0pt}{4ex}}X>{{\color{red}}}N42>{\color{red}}cN42>{\color{red}}cN42|}}
+\newcommand\Mystrut{\rule[-1.2ex]{0pt}{4ex}}
+\newcommand\RED{\color{red}}
+\begin{spreadtab}{{tabularx}{0.8\linewidth}{|>\Mystrut X>\RED N42>\RED c N42>\RED c<\PC N42|}}
 \hline
-@Items &@\multicolumn{1}{c}{Price/U}& @\multicolumn{1}{c}{Qty} & @\multicolumn{1}{c}{Price} & @\multicolumn{1}{c}{Reduction} & @\textbf{Net}\\\hline
-@Item 1 & 5.99 & 20 & [-2,0]*[-1,0] & $-:={20}\PC$ & [-2,0]*(1-[-1,0]/100)\\
-@Item 2 & 12   & 7  & [-2,0]*[-1,0] & $-:={10}\PC$ & [-2,0]*(1-[-1,0]/100)\\
-@Item 3 & 4.50 & 40 & [-2,0]*[-1,0] & $-:={35}\PC$ & [-2,0]*(1-[-1,0]/100)\\
-@Item 4 & 650  & 2  & [-2,0]*[-1,0] & $-:={15}\PC$ & [-2,0]*(1-[-1,0]/100)\\\hline
-@\multicolumn{6}{c}{\vspace{-1.5ex}}\\\cline{4-6}% empty line and raise it a little
-@\multicolumn{1}{c}{\rule[-1.2ex]{0pt}{4ex}}&@\multicolumn{2}{r|}{\textbf{Total}}& sum(d2:[0,-2]) & \multicolumn{1}{c}{$:={round(([1,0]/[-1,0]-1)*100,0)}\PC$} & {\fontseries{b}\selectfont}:={sum(f2:[0,-2])}\\
+@Item &@\multicolumn1c{Price/U}& @\multicolumn1c{Qty} & @\multicolumn1c{Price} & @\multicolumn1c{Reduction} & @\textbf{Net}\\\hline
+@Item 1 & 5.99 & 20 & [-2,0]*[-1,0] & $-:={20}$ & [-2,0]*(1-[-1,0]/100)\\
+@Item 2 & 12   & 7  & [-2,0]*[-1,0] & $-:={10}$ & [-2,0]*(1-[-1,0]/100)\\
+@Item 3 & 4.50 & 40 & [-2,0]*[-1,0] & $-:={35}$ & [-2,0]*(1-[-1,0]/100)\\
+@Item 4 & 650  & 2  & [-2,0]*[-1,0] & $-:={15}$ & [-2,0]*(1-[-1,0]/100)\\\hline
+@\multicolumn6c{}\\[-1.5ex]\cline{4-6}% empty line and raise it a little
+@\multicolumn1c{\Mystrut}&@\multicolumn2{r|}{\textbf{Total}}& sum(d2:[0,-2]) & \multicolumn1c{$:={round(([1,0]/[-1,0]-1)*100,0)}\PC$} & {\fontseries{b}\selectfont}:={sum(f2:[0,-2])}\\
 \cline{4-6}
 \end{spreadtab}
 \end{lstlisting}
 \begin{center}
 \nprounddigits2
 \let\PC\%
-\begin{spreadtab}{{tabularx}{0.8\linewidth}{|>{\rule[-1.2ex]{0pt}{4ex}}X>{{\color{red}}}N42>{\color{red}}cN42>{\color{red}}cN42|}}
+\newcommand\Mystrut{\rule[-1.2ex]{0pt}{4ex}}
+\newcommand\RED{\color{red}}
+\begin{spreadtab}{{tabularx}{0.8\linewidth}{|>\Mystrut X>\RED N42>\RED c N42>\RED c<\PC N42|}}
 \hline
-@Items &@\multicolumn{1}{c}{Price/U}& @\multicolumn{1}{c}{Qty} & @\multicolumn{1}{c}{Price} & @\multicolumn{1}{c}{Reduction} & @\textbf{Net}\\\hline
-@Item 1 & 5.99 & 20 & [-2,0]*[-1,0] & $-:={20}\PC$ & [-2,0]*(1-[-1,0]/100)\\
-@Item 2 & 12   & 7  & [-2,0]*[-1,0] & $-:={10}\PC$ & [-2,0]*(1-[-1,0]/100)\\
-@Item 3 & 4.50 & 40 & [-2,0]*[-1,0] & $-:={35}\PC$ & [-2,0]*(1-[-1,0]/100)\\
-@Item 4 & 650  & 2  & [-2,0]*[-1,0] & $-:={15}\PC$ & [-2,0]*(1-[-1,0]/100)\\\hline
-@\multicolumn{6}{c}{\vspace{-1.5ex}}\\\cline{4-6}% empty line and raise it a little
-@\multicolumn{1}{c}{\rule[-1.2ex]{0pt}{4ex}}&@\multicolumn{2}{r|}{\textbf{Total}}& sum(d2:[0,-2]) & \multicolumn{1}{c}{$:={round(([1,0]/[-1,0]-1)*100,0)}\PC$} & {\fontseries{b}\selectfont}:={sum(f2:[0,-2])}\\
+@Item &@\multicolumn1c{Price/U}& @\multicolumn1c{Qty} & @\multicolumn1c{Price} & @\multicolumn1c{Reduction} & @\textbf{Net}\\\hline
+@Item 1 & 5.99 & 20 & [-2,0]*[-1,0] & $-:={20}$ & [-2,0]*(1-[-1,0]/100)\\
+@Item 2 & 12   & 7  & [-2,0]*[-1,0] & $-:={10}$ & [-2,0]*(1-[-1,0]/100)\\
+@Item 3 & 4.50 & 40 & [-2,0]*[-1,0] & $-:={35}$ & [-2,0]*(1-[-1,0]/100)\\
+@Item 4 & 650  & 2  & [-2,0]*[-1,0] & $-:={15}$ & [-2,0]*(1-[-1,0]/100)\\\hline
+@\multicolumn6c{}\\[-1.5ex]\cline{4-6}% empty line and raise it a little
+@\multicolumn1c{\Mystrut}&@\multicolumn2{r|}{\textbf{Total}}& sum(d2:[0,-2]) & \multicolumn1c{$:={round(([1,0]/[-1,0]-1)*100,0)}\PC$} & {\fontseries{b}\selectfont}:={sum(f2:[0,-2])}\\
 \cline{4-6}
 \end{spreadtab}
 \end{center}
@@ -1335,7 +1444,7 @@ $\star$\par
 $\star\quad\star$
 \end{center}\bigskip
 That's all, I hope we will find this package useful!\par\nobreak\medskip
-Given the youth of this package, please, be tolerant if you find bugs: with comments from users, better versions should be available soon. Indeed, this version is just beginning and, though rather stable, many things are still imperfect. Especially, it is obvious that many other macro-functions need to be written.\par\nobreak\medskip
+Given the youth of this package, please, be tolerant if you find bugs: with comments from users, better versions should be available soon. Indeed, this version is just beginning and, though rather stable, many things are still imperfect.\par\nobreak\medskip
 I thank you in advance for sending by \href{mailto:unbonpetit@gmail.com}{\texttt{\textbf{email}}} any bug you find, any macro-function or improvment you would like to be implemented, assumed that it must be \emph{realistic}. This package has to be modest and \ST is not excel or calc: it is impossible to implement some advanced features of these spreadsheets.\ldots\par\nobreak\bigskip
 Christian \textsc{Tellechea}
 \end{document}
\ No newline at end of file
-- 
cgit v1.2.3

