path: root/Master/texmf-dist/doc/latex/tabularcalc/tabularcalc_doc_en.tex

% Ceci est tabularcalc_doc_fr.tex, le manuel en français de tabularcalc
% This is tabularcalc_doc_fr.tex, the french manual of tabularcalc
%
% Christian Tellechea 2009
%
% email : unbonpetit@gmail.com
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3
% of this license or (at your option) any later version.
% The latest version of this license is in
%
%     http://www.latex-project.org/lppl.txt
%
% and version 1.3 or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\documentclass[a4paper,10pt]{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[a4paper,dvips,colorlinks=true,hyperfootnotes=false,filecolor=black,linkcolor=blue,urlcolor=magenta,bookmarks=false,pdfauthor={Christian TELLECHEA},pdftitle={tabularcalc},pdfsubject={package for tables of values},pdfkeywords={tabularcalc},pdfcreator={LaTeX}]{hyperref}
\usepackage[a4paper,dvips,margin=2.75cm]{geometry}
\usepackage[autolanguage]{numprint}
\usepackage{amsmath}
\usepackage{colortbl}
\usepackage{xcolor}
\usepackage{lmodern}
\usepackage{xspace}
\usepackage{listings}
\usepackage{tabularcalc}
\usepackage[bottom]{footmisc}
\usepackage[frenchb,english]{babel}
\makeatletter
\definecolor{tc@bckgcolor}{rgb}{1,1,0.875}
\definecolor{tc@keywordstc}{rgb}{0.7,0,0}
\definecolor{tc@keywordslatex}{rgb}{0,0,1}
\definecolor{tc@arguments}{rgb}{0,0,0}
\definecolor{tc@comments}{rgb}{0.5,0.5,0.5}
\lstset{%
	language=[AlLaTeX]TeX,%
	float=hbp,%
	basicstyle=\footnotesize\ttfamily,%
	identifierstyle=\color{tc@arguments},%
	keywordstyle=\color{tc@keywordslatex},%
	commentstyle=\itshape\color{tc@comments},%
	columns=fixed,%
	tabsize=4,%
	frame=single,%
	extendedchars=true,%
	showspaces=false,%
	showstringspaces=false,%
	numbers=left,%
	numberstyle=\tiny\ttfamily,%
	breaklines=true,%
	breakindent=3em,%
	backgroundcolor=\color{tc@bckgcolor},%
	breakautoindent=true,%
	captionpos=t,%
	xleftmargin=1em,%
	xrightmargin=1em,%
	lineskip=0pt,%
	numbersep=1em,
	classoffset=1,%
	morekeywords={% les macros et commandes de tabularcalc
		tccol,tclin,%
		htablecalc,vtablecalc,%
		tcnoshowmark,tcatbeginrow,tcresetcellcode,edefcellcode,defcellcode,%
		tcsethrule,tcresethrule,tcsetcoltype,tcresetcoltype,%
		tcprintvalue,tcprintresult,tclistsep,%
		tc@evalexpr,tc@currentresult,%
		tcprintroundresult,tcprintroundvalue,%
		tcuseinfix,tcusepostfix,tcwritetofile},%
	keywordstyle=\color{tc@keywordstc},%
	classoffset=0}
\makeatother

\newcommand\guill[1]{\og{}#1\fg{}}
\newcommand\argu[1]{$\langle$\textit{#1}$\rangle$}
\newcommand\ARGU[1]{\texttt{\{}\argu{#1}\texttt{\}}}
\newcommand\arguC[1]{\texttt{[}\argu{#1}\texttt{]}}

\newcommand\tbcalc{\textsf{tabularcalc}\xspace}
\newcommand\verbinline{\lstinline[breaklines=false,basicstyle=\normalsize\ttfamily]}
\newcommand\mywidth{0.85\linewidth}

\begin{document}
\selectlanguage{english}
\npthousandthpartsep{\;}
\setlength{\parindent}{0pt}
\begin{titlepage}
	\null\par\vfill
	\begin{center}
		\begin{minipage}{0.75\linewidth}
			\begin{center}
				\Huge\bfseries \tbcalc\par\vspace{5pt}
				\small v\tabularcalcversion\par\vspace{25pt}
				\normalsize User's manual
			\end{center}
		\end{minipage}
	\end{center}
	\vspace{1cm}
	\begin{center}
		Christian {\sc Tellechea}\par\small
		\href{mailto:unbonpetit@gmail.com}{\texttt{\textbf{unbonpetit@gmail.com}}}\par\vspace{5pt}
		\tabularcalcenglishdate
	\end{center}
	\vfill\hrulefill
	\begin{center}
		\begin{minipage}{0.85\linewidth}
			\noindent
			\hfill\textbf{\textit{Abstract}}\hfill{}\medskip\par
				Given a list of numbers and one (or more) formulas, this package allows with an easy syntax to build a table of values, i.e a tables in which the first row contains the list of numbers, and the other rows contain the \emph{calculated} values of the formulas for each number of the list:
				\begin{center}
					\tcsethrule{\hline}{\hline\hline}{\hline}
					\tcsetcoltype{|c|}{>{\centering\arraybackslash}m{1.5cm}|}
					\htablecalc[3]{$x$}{x=-4,-2,0,2.25,7}
					              {$f(x)=2x-3$}{2*x-3}
					              {$x^2$}{x*x}
					              {$h(x)=\sqrt{x^2+1}$}{round(root(2,x*x+1),6)}
				\end{center}
				The table can be built either horizontally or vertically, and it is fully customizable (height of rows, columns and lines types). Moreover, the content of any cell can be easily hidden.\smallskip

				Other local effects are possible since a command allows to execute any code in any particular cell.
		\end{minipage}
	\end{center}
	\hrulefill\vfill{}
\end{titlepage}

\tableofcontents
\bigskip

\textbf{Attention}: this manual is the laboured\footnote{Indeed, I \textbf{do not speak english}, and I did my best to achieve this translation. Please, be indulgent, and try to take my place and imagine what it would be for you if you had to translate a manual into french, with some old poor school knowledge!} translation of the french manual.\medskip

Many thanks to Derek~\textsc{O'Connor} for the interest he brought to this package and the tests he made on beta versions. His pertinent suggestions of new features have been very useful. Without his advice, \tbcalc would not be what it is.\medskip

My thanks also to Le \textsc{Huu Dien Khue} who offered the translation of this manual into Vietnamese.

\section{Introduction}
\subsection{Presentation}
This package provides commands which make easy possible to build tables of calculated results coming from formulas for a given list of values. Tables are displayed using the standard \verb|tabular| environment.

\tbcalc needs \LaTeX$2\varepsilon$ and requires \href{http://www.ctan.org/tex-archive/macros/latex/contrib/fp/}{\texttt{\textbf{fp}}}, \href{http://www.ctan.org/tex-archive/macros/latex/contrib/xstring/}{\texttt{\textbf{xstring}}} and \href{http://www.ctan.org/tex-archive/macros/latex/contrib/numprint/}{\texttt{\textbf{numprint}}} packages.\medskip

This package is not intended to compete with the excellent \href{http://www.ctan.org/tex-archive/graphics/pgf/contrib/pgfplots/}{\texttt{\textbf{pgfplotstable}}} package of Christian \textsc{Feuers\"anger} which has much more extended customization features, but in compensation, has a difficult to learn syntax. \tbcalc is meant to be more modest and gives priority to customization and easy syntax.\medskip


To display decimal numbers, in my view, nothing is better than the \href{http://www.ctan.org/tex-archive/macros/latex/contrib/numprint/}{\texttt{\textbf{numprint}}} package. The engine used to display decimal numbers can be changed or customized, see page~\pageref{persoaffichage}.\medskip

\subsection{The {\ttfamily fp} package}
For calculation, the computation of an expression such as \verb|2*x*x-5*x+7| when \hbox{\verb|x = 2.7|} is, with \TeX{}, a very complex thing that \tbcalc does not make. It leaves this task to a math engine provided by the \verb=fp= package. It provides all usual arithmetic, trigonometric and scientific operations. Moreover, infix and postfix notation are available: see the \href{http://www.ctan.org/get/macros/latex/contrib/fp/README}{\texttt{\textbf{README}}} file for the list of functions available for each notation.\medskip

I fixed 2 issues in the macro \verb=\FPpow= of the \verb=fp= package\footnote{I did not warn the author of {\ttfamily fp} and I did not ask his permission beacuse he does not maintain his package for a long time now.}. This macro is in charge of power calculation such as $a^b$.
\parindent2em
\begin{itemize}
	\item first of all a spurious space appears when a power is computed. This space is fixed by \tbcalc
	\item but there is another annoying issue: when \verb=fp= computes $a^b$ it uses this formula $a^b=\mathrm{e}^{b\ln a}$. There is an issue when $b$ is an integer and $a$ is negative. For example: $(-3)^2=\mathrm{e}^{2\ln(-3)}$. The logarithm of a negative number is undefined and \verb=fp= is unable to compute this simple calculation. This bug is fixed and \verb=fp= now computes this kind of calculation properly.
\end{itemize}\smallskip\parindent0pt

To enable \tbcalc fix these issues, the option "\verb=fixFPpow=" can be declared when calling the package:
\begin{center}
\begin{minipage}{\mywidth}
\begin{lstlisting}
\usepackage[fixFPpow]{tabularcalc}
\end{lstlisting}
\end{minipage}
\end{center}

\subsection{What is new?}
Unfortunaltely, there are some incompatibilities with other packages because the name of macros of \tbcalc was already used. I decided with a heavy heart to rename almost all the public macros, risking a probable incompatibility with the previous version. I apologize for this inconvenience. I rename them with "\verb=tc=" at their begining:
\begin{center}
	\begin{tabular}{rl}
		Old name&New name\\\hline
		\verb=\noshowmark=&\verb=\tcnoshowmark= \\
		\verb=\startline=&\verb=\tcatbeginrow=\\
		\verb=\resetcellcode=&\verb=\tcresetcellcode=\\
		\verb=\listsep=&\verb=\tclistsep=\\
		\verb=\printvalue=&\verb=\tcprintvalue=\\
		\verb=\printresult=&\verb=\tcprintresult=\\
		\verb=\sethrule=&\verb=\tcsethrule=\\
		\verb=\resethrule=&\verb=\tcresethrule=\\
		\verb=\setcoltype=&\verb=\tcsetcoltype=\\
		\verb=\resetcoltype=&\verb=\tcresetcoltype=
	\end{tabular}
\end{center}

Here is the other new features for the users of the previous version:
\parindent3em
\begin{itemize}
	\item calculation is made with \verb=fp= since \verb=pgfmath= has a poor precision;
	\item values can be computed;
	\item the code of a table can be exported in a file.
\end{itemize}\parindent0pt

\subsection{Vocabulary}
To define vocabulary for later use, in the simple tables below, red numbers are the "{\color{red}values}", blue numbers are the "{\color{blue}results}" and brown texts are the  "{\color{brown}labels}". The cell on the up-left corner is the "cell(0,0)":
\begin{minipage}{0.5\linewidth}
\begin{center}
{\scriptsize Horizontal table}\par\nobreak\smallskip
\def\tcprintvalue#1{\color{red}$#1$}
\def\tcprintresult#1#2{\color{blue}$#1$}
\htablecalc[3]{cellule (0,0)}{x=-5,-1,0,3,10}{\color{brown}$x$}{x}{\color{brown}$2x$}{2*x}{\color{brown}$3x$}{3*x}
\end{center}
\end{minipage}%
\begin{minipage}{0.5\linewidth}
\begin{center}
{\scriptsize Vertical table}\par\nobreak\smallskip
\def\tcprintvalue#1{\color{red}$#1$}
\def\tcprintresult#1#2{\color{blue}$#1$}
\vtablecalc[3]{cellule (0,0)}{x=-5,-1,0,3,10}{\color{brown}$x$}{x}{\color{brown}$2x$}{2*x}{\color{brown}$3x$}{3*x}
\end{center}
\end{minipage}

\section{Basic features}
\subsection{Horizontal tables}
The macro \verbinline|\htablecalc| builds horizontal table whose first row contains the "values" and the other rows the "results". The syntax is:\smallskip

\setbox0=\hbox{\verbinline|\htablecalc|\arguC{n}}
\verbinline|\htablecalc|\arguC{n}\ARGU{cell (0,0)}\ARGU{variable=list of values}\par
\hskip\wd0\ARGU{label 1}\ARGU{formula 1}\par
\hskip\wd0\ARGU{label 2}\ARGU{formula 2}\par
\hskip\wd0\ldots\par
\hskip\wd0\ARGU{label n}\ARGU{formula n}\medskip

where :\parindent1.5em
\begin{itemize}
	\item \argu{n} is the number of formulas (1 by default);
	\item \argu{cell (0,0)} is the content of the cell (0,0);
	\item \argu{variable} is the dummy variable in \argu{formula i} used to compute the results;
	\item \argu{list of values} is the list of values, separated with a comma. Two consecutive commas make an empty column;
	\item \argu{label i} is the $i{}^\text{th}$ label;
	\item \argu{formula i} is the $i^\text{th}$ formula, used to calculate the reults of the $i^\text{th}$ row.
\end{itemize}\parindent0em
\medskip

In the list of values, a comma separates values by default. This comma is the expansion of  \verbinline|\tclistsep|, and can be changed to "|" for example with \verbinline=\def\tclistsep{|}=\medskip

For a first example, here is a try to obtain the table of the first page:
\begin{center}
\begin{minipage}{\mywidth}
\begin{lstlisting}
\htablecalc[3]{$x$}{x=-4,-2,0,2.25,7}
              {$f(x)=2x-3$}{2*x-3}
              {$x^2$}{x*x}
              {$h(x)=\sqrt{x^2+1}$}{round(root(2,x*x+1),6)}
\end{lstlisting}
\end{minipage}
\htablecalc[3]{$x$}{x=-4,-2,0,2.25,7}
              {$f(x)=2x-3$}{2*x-3}
              {$x^2$}{x*x}
              {$h(x)=\sqrt{x^2+1}$}{round(root(2,x*x+1),6)}
\end{center}
This table is not strictly the same than the table of the first page: columns containing results do not have the same width and the line at the bottom of the first row is different. We will see later how to customize this.

\subsection{Vertical tables}
The macro \verbinline|\vtablecalc| builds vertical table whose first column contains the "values" and the other rows the "results". The syntax is:\smallskip

\setbox0=\hbox{\verbinline|\vtablecalc|\arguC{n}}
\verbinline|\vtablecalc|\arguC{n}\ARGU{cell (0,0)}\ARGU{variable=list of values}\par
\hskip\wd0\ARGU{label 1}\ARGU{formula 1}\par
\hskip\wd0\ARGU{label 2}\ARGU{formula 2}\par
\hskip\wd0\ldots\par
\hskip\wd0\ARGU{label n}\ARGU{formula n}\medskip

where :\parindent1.5em
\begin{itemize}
	\item \argu{n} is the number of formulas (1 by default);
	\item \argu{cell (0,0)} is the content of the cell (0,0);
	\item \argu{variable} is the dummy variable in \argu{formula i} used to compute the results;
	\item \argu{list of values} is the list of values, separated with a comma. Two consecutive commas make an empty column;
	\item \argu{label i} is the $i{}^\text{th}$ label;
	\item \argu{formula i} is the $i^\text{th}$ formula, used to calculate the reults of the $i^\text{th}$ row.
\end{itemize}\parindent0em
\medskip

Here is the previous table, but vertically built:\par\nobreak
\begin{center}
\begin{minipage}{\mywidth}
\begin{lstlisting}
\vtablecalc[3]{$x$}{y=-4,-2,0,2.25,7}
              {$f(x)=2x-3$}{2*y-3}
              {$x^2$}{y*y}
              {$h(x)=\sqrt{x^2+1}$}{round(root(2,y*y+1),6)}
\end{lstlisting}
\end{minipage}

\vtablecalc[3]{$x$}{y=-4,-2,0,2.25,7}
              {$f(x)=2x-3$}{2*y-3}
              {$x^2$}{y*y}
              {$h(x)=\sqrt{x^2+1}$}{round(root(2,y*y+1),6)}
\end{center}

\subsection{How to hide numbers}\label{masquercellules}
The content of any cell can be hidden, as well as in a horizontal or vertical table.

\subsubsection{Hide a value}
In the list of values, a "\verb|@|" before a value hides it. In the following example, the second and fifth values are hidden:\smallskip
\begin{center}
\begin{minipage}{\mywidth}
\begin{lstlisting}
\htablecalc[3]{$x$}{x=-4,@-2,0,2.25,@7}
              {$f(x)=2x-3$}{2*x-3}
              {$x^2$}{x*x}
              {$h(x)=\sqrt{x^2+1}$}{round(root(2,x*x+1),6)}
\end{lstlisting}
\end{minipage}

\htablecalc[3]{$x$}{x=-4,@-2,0,2.25,@7}
              {$f(x)=2x-3$}{2*x-3}
              {$x^2$}{x*x}
              {$h(x)=\sqrt{x^2+1}$}{round(root(2,x*x+1),6)}
\end{center}
\medskip

Behind the scene, the "\verb|@|" token is the expansion of \verbinline|\tcnoshowmark|. To change this token to "=", this simple code does the job: \verbinline|\def\tcnoshowmark{=}|

\subsubsection{Hide a result}
If a value is followed by $[a_1][a_2]\ldots[a_n]$ where the numbers $a_i$ are increasing, the results number $a_1,a_2,\ldots,a_n$ will be hidden. If a number $a_j=0$, all the others $a_k$ where $k>j$ will be ignored and the results following the previous hidden result will be hidden.\medskip

In the example, with the list of values "\verb|-4[2],-2,0[1][3],2.25[0],7[2][0]|", we are going to:\parindent1.5em
\begin{itemize}
	\item hide the second result of the first value with "\verb|-4[2]|"
	\item let all the results visible for the second value with "\verb|-2|"
	\item hide the results number 1 and 3 of the third value with "\verb|0[1][3]|"
	\item hide all the results of the fourth value with "\verb|2.25[0]|"
	\item for the fifth value, hide all the results from the second with "\verb|7[2][0]|"
\end{itemize}\parindent0em

\begin{center}
\begin{minipage}{\mywidth}
\begin{lstlisting}
\htablecalc[3]{$x$}{x=-4[2],-2,0[1][3],2.25[0],7[2][0]}
              {$f(x)=2x-3$}{2*x-3}
              {$x^2$}{x*x}
              {$h(x)=\sqrt{x^2+1}$}{round(root(2,x*x+1),6)}
\end{lstlisting}
\end{minipage}

\htablecalc[3]{$x$}{x=-4[2],-2,0[1][3],2.25[0],7[2][0]}
              {$f(x)=2x-3$}{2*x-3}
              {$x^2$}{x*x}
              {$h(x)=\sqrt{x^2+1}$}{round(root(2,x*x+1),6)}
\end{center}
This feature can be mixed with "\verb|@|" to hide a value and results.

\subsection{Height of rows}
At the begining of a row, when it is displayed, the macro \verbinline|\tcatbeginrow| runs.

By default, this command is defined by: \verbinline|\def\tcatbeginrow{\rule[-1.2ex]{0pt}{4ex}}|. Its expansion is a "strut" which adjusts the height of the row. Here is this strut, made visible before the lettre "a": \rule[-1.2ex]{2pt}{4ex}a\medskip

Any other action, or another strut can be defined:
\begin{center}
\begin{minipage}{\mywidth}
\begin{lstlisting}
\def\tcatbeginrow{%
	{\bfseries\number\tclin)\ }%
}
\htablecalc[3]{$x$}{x=-4,-2,0,2.25,7}
              {$f(x)=2x-3$}{2*x-3}
              {$x^2$}{x*x}
              {$h(x)=\sqrt{x^2+1}$}{round(root(2,x*x+1),6)}
\end{lstlisting}
\end{minipage}

\def\tcatbeginrow{%
	{\bfseries\number\tclin)\ }%
}
\htablecalc[3]{$x$}{x=-4,-2,0,2.25,7}
              {$f(x)=2x-3$}{2*x-3}
              {$x^2$}{x*x}
              {$h(x)=\sqrt{x^2+1}$}{round(root(2,x*x+1),6)}
\end{center}
Here, no strut is defined (the lines recover their natural height), and at line 2 of the code, the number of the row (contained in the counter \verbinline|\tclin|) is displayed with bold chars.

\subsection{Horizontal lines}
\tbcalc allows to define 3 types of horizontal lines. The macro \verbinline|\tcsethrule| has 3 arguments:

\parindent1.5em
\begin{itemize}
	\item the first that we call "line 0" is displayed on the top and bottom of the table;
	\item the second, "line 1", is displayed at the bottom of the first row;
	\item the third, "other lines", is displayed at the bottom of the other rows, excepted the last one which is the bottom of the table.
\end{itemize}\parindent0em
Here is the syntax:

\verbinline|\tcsethrule|\ARGU{line 0}\ARGU{line 1}\ARGU{other lines}
\medskip

By default, the three arguments contain \verbinline|\hline|.\medskip

This is an example in which the "line 1" is a double line, and the "other lines" are not drawn:
\begin{center}
\begin{minipage}{\mywidth}
\begin{lstlisting}
\tcsethrule{\hline}{\hline\hline}{}
\htablecalc[3]{$x$}{x=-2,-1,0,1,2,3}
              {$2x$}{2*x}
              {$3x$}{3*x}
              {$4x$}{4*x}
\end{lstlisting}
\end{minipage}

\tcsethrule{\hline}{\hline\hline}{}
\htablecalc[3]{$x$}{x=-2,-1,0,1,2,3}
              {$2x$}{2*x}
              {$3x$}{3*x}
              {$4x$}{4*x}
\end{center}

The command \verbinline|\tcresethrule| resets the defined lines and restores the default lines.

\subsection{Customizing columns}
\subsubsection{Vertical lines}
2 types of column can be defined: the type of the left one and the type of others columns. The command \verbinline|\tcsetcoltype| has an optionnal argument and 2 mandatory arguments:
\begin{itemize}
	\item the optional argument, empty by default, defines the vertical lines at the right of the table;
	\item the "type 1" of the first column, set to "\verb-|c|-" by default;
	\item the  "type 2" of the other colunms, set to "\verb-c|-" by default.
\end{itemize}\medskip

The syntax of the command is:\par\nobreak
\verbinline|\tcsetcoltype|\arguC{right lines}\ARGU{type 1}\ARGU{type 2}\medskip

In this example, a double line is displayed at the right of the table (\verb=[||]=), and on the edges of the first column (\verb=||c||=). The other columns do not have vertical lines (\verb|c|):
\begin{center}
\begin{minipage}{\mywidth}
\begin{lstlisting}
\tcsetcoltype[||]{||c||}{c}
\htablecalc[3]{$x$}{x=-2,-1,0,1,2,3}
              {$2x$}{2*x}
              {$3x$}{3*x}
              {$4x$}{4*x}
\end{lstlisting}
\end{minipage}

\tcsetcoltype[||]{||c||}{c}
\htablecalc[3]{$x$}{x=-2,-1,0,1,2,3}
              {$2x$}{2*x}
              {$3x$}{3*x}
              {$4x$}{4*x}
\end{center}

\verbinline|\tcresetcoltype| restores the default vertical lines.

\subsubsection{Width of columns}
Instead of the usual column type "\verb|c|" used until now, other types of column can be specified: for example, the "\verb|m|" type of the \href{http://www.ctan.org/tex-archive/graphics/pgf/base/latex/pgf/basiclayer/}{\texttt{\textbf{array}}} package allows to set the width of columns this way: \verb|m{1.5cm}|.\medskip

In this example, the first column is right aligned, and the other columns are centered and \numprint[cm]{1.5} width:
\begin{center}
\begin{minipage}{\mywidth}
\begin{lstlisting}
\usepackage{array}
\tcsetcoltype{|r|}{>{\centering\arraybackslash}m{1.5cm}|}
\htablecalc[3]{$x$}{x=-4,-2,0,2.25,7}
              {$f(x)=2x-3$}{2*x-3}
              {$x^2$}{x*x}
              {$h(x)=\sqrt{x^2+1}$}{round(root(2,x*x+1),6)}
\end{lstlisting}
\end{minipage}

\tcsetcoltype{|r|}{>{\centering\arraybackslash}m{1.5cm}|}
\htablecalc[3]{$x$}{x=-4,-2,0,2.25,7}
              {$f(x)=2x-3$}{2*x-3}
              {$x^2$}{x*x}
              {$h(x)=\sqrt{x^2+1}$}{round(root(2,x*x+1),6)}
\end{center}

\section{How to compute the values?}
When values can be calculated with a math formula, it may be more simple to write the formula than all the values. This code:
\begin{center}
\begin{minipage}{\mywidth}
\begin{lstlisting}
\htablecalc[2]{$x$}{x=-3,-1,1,3,5,7,9,11,13}
              {$2x$}{2*x}
              {$x^2$}{x*x}
\end{lstlisting}
\end{minipage}
\end{center}
can be replaced by this shorter oneo:
\begin{center}
\begin{minipage}{\mywidth}
\begin{lstlisting}
\htablecalc[2]{$x$}{x=a;a=-3:13[2]}
              {$2x$}{2*x}
              {$x^2$}{x*x}
\end{lstlisting}
\end{minipage}
\end{center}
The presence of a "\verb=;=" changes the analysis of the argument: on the right of "\verb=;=" we say that the dummy variable "\verb=a=" varies between $-3$ and 13 with a step of 2. Therefore is an \emph{odd} integer. On the left of "\verb=;=" we say that the dummy variable --~here \verb=x=~-- involved in the formulas used to compute the results is equal to \verb=a= and consequently the values are odd integers between $-3$ and 13.

These values could have been generated with this argument \verb|{x=2*a+1:a=-2:6}| (the step is 1 by default) or this other one \verb|{x=2*a-3;a=0:8}|, or another one because there are several way to generate a set of values.\bigskip

When using an argument with "\verb=;=", the feature enabling to hide cells (see page~\pageref{masquercellules}) is not available. Moreover, the user should be aware of the number of generated values to avoid huge tables.\medskip

With a "\verb=;=", the syntax of the argument is:\par\smallskip\nobreak
\hfill\argu{variable 1}\verb|=|\argu{formula}\verb|;|\argu{variable 2}\verb|=|\argu{min}\verb|:|\argu{max}\arguC{step}\hfill{}\smallskip

where:
\begin{itemize}
	\item \argu{variable 1} is the dummy variable involved in the formulas used to compute the results;
	\item \argu{variable 2} is the dummy variable involved in the formulas used to compute the values; it must be different from \argu{variable 1};
	\item \argu{formula} is the formula used to compute the values. The variable in this formula is \argu{variable 2};
	\item \argu{min}\verb|:|\argu{max} is the interval in which \argu{variable 2} varies;
	\item \argu{step} is the step added to \argu{variable 2} until it reaches \argu{max} or more. It is optional and its defaul value is 1. It must be different from 0.
\end{itemize}\parindent0em
\medskip

There are many different ways to generate the same set of values.

For example, the values \texttt{\{0,1,2,3,4,5,6,7,8,9,10\}} can be generated with:

\parindent2em
\begin{itemize}
	\item \verb|{z=x;x=0:10}| and \og\verb=z=\fg{} will be the dummy variable in formulas;
	\item \verb|{n=2*a;a=0:5[0.5]}| and \og\verb=n=\fg{} will be the dummy variable in formulas;
	\item \verb|{x=y/10;y=0:100[10]}| and \og\verb=x=\fg{} will be the dummy variable in formulas;
\end{itemize}
\parindent0pt\medskip

The value of \argu{step} and \argu{min}\verb|:|\argu{max} must be coherent: \verb|0:10[-1]| will provoke an error message from \tbcalc!\medskip

This is an example using the trigonometric functions of \verb|fp|:
\begin{center}
\begin{minipage}{\mywidth}
\begin{lstlisting}
\htablecalc[6]{$x$\ [deg]}{x=a;a=15:75[15]}
              {$\sin x$}{round(sin(x*pi/180),6)}
              {$\cos x$}{round(cos(x*pi/180),6)}
              {$\tan x$}{round(tan(x*pi/180),6)}
              {$\sin^2x$}{round(sin(x*pi/180)^2,6)}
              {$\cos^2x$}{round(cos(x*pi/180)^2,6)}
              {$\tan^2x$}{round(tan(x*pi/180)^2,6)}
\end{lstlisting}
\end{minipage}

\htablecalc[6]{$x$\ [deg]}{x=a;a=15:75[15]}
              {$\sin x$}{round(sin(x*pi/180),6)}
              {$\cos x$}{round(cos(x*pi/180),6)}
              {$\tan x$}{round(tan(x*pi/180),6)}
              {$\sin^2x$}{round(sin(x*pi/180)^2,6)}
              {$\cos^2x$}{round(cos(x*pi/180)^2,6)}
              {$\tan^2x$}{round(tan(x*pi/180)^2,6)}
\end{center}
\medskip

And here is another table displaying powers of 10, their decimal logarithm, their square root and their inverse:
\begin{center}
\begin{minipage}{\mywidth}
\begin{lstlisting}
\htablecalc[3]{Power of 10}{x=round(10^n,4);n=-3:3}
              {Decimal logarithm}{ln(x)/ln(10)}
              {Square root}{round(root(2,x),3)}
              {Inverse}{1/x}
\end{lstlisting}
\end{minipage}

\htablecalc[3]{Power of 10}{x=round(10^n,4);n=-3:3}
              {Decimal logarithm}{ln(x)/ln(10)}
              {Square root}{round(root(2,x),3)}
              {Inverse}{1/x}
\end{center}

\section{Advanced customization}
\subsection{Put a code in a cell}
The command \verbinline|\defcellcode| allows to execute any code in a unique cell, or in every cells of a row or in every cells of a column. Cells have the following coordinates:

\begin{center}
	\def\tcprintvalue#1{}\def\tcprintresult#1#2{}
	\edefcellcode{}{}{(\number\tclin,\number\tccol)}
	\htablecalc[3]{}{x=1,2,3,4,5}{}{x}{}{x}{}{x}
\end{center}
\medskip

Here is the syntax:

\verbinline|\defcellcode|\ARGU{number 1}\ARGU{number 2}\ARGU{code}
\smallskip

where :\parindent1.5em
\begin{itemize}
	\item \argu{number 1} is the first coordinate (row number);
	\item \argu{nombre 2} is the second coordinate (column number);
	\item \argu{code} is the code executed \emph{when the specified cell is displayed};
	\item if \argu{number 1} is empty, all the rows are concerned;
	\item if \argu{nombre 2} is empty, all the columns are concerned;
\end{itemize}\parindent0em
\smallskip

Behind the scene, the first coordinate --~the row number~-- is the counter \verbinline{\tclin}, and the number of the column is the counter \verbinline{\tccol}.\smallskip

Notice that the code is expanded when the cell is displayed, and at that moment, the counter \verbinline|\tccol| does not contain anymore the column number of the cell: you should \textbf{not} use \verbinline|\tccol| in the code definied with the macro \verbinline|\defcellcode|. On the other hand, the counter \verbinline|\tclin| does contain the reliable number of the current line.

If codes are defined with \verbinline|\defcellcode| and several of them are runned in the same cell, they will be executed in the same order of their definition.\medskip

In this example, with the package \verb|xcolor|, the cell (2~,~3) is colored in blue, the row 1 in red and the column 4 in brown:
\begin{center}
\begin{minipage}{\mywidth}
\begin{lstlisting}
\usepackage{color}
\defcellcode{2}{3}{\color{blue}}
\defcellcode{1}{}{\color{red}}
\defcellcode{}{4}{\color{brown}}
\htablecalc[3]{$x$}{x=-2,-1,0,1,2,3}
              {$2x$}{2*x}
              {$3x$}{3*x}
              {$4x$}{4*x}
\end{lstlisting}
\end{minipage}

\defcellcode{2}{3}{\color{blue}}
\defcellcode{1}{}{\color{red}}
\defcellcode{}{4}{\color{brown}}
\htablecalc[3]{$x$}{x=-2,-1,0,1,2,3}
              {$2x$}{2*x}
              {$3x$}{3*x}
              {$4x$}{4*x}
\end{center}

Notice that the cell (1~,~4) whose content is {\color{brown}\numprint{2}} has been colored in red (line 3 of the code) \emph{and then} in brown (line 4 of the code).\bigskip

Another similar command is provided to execute code in a cell: \verbinline|\edefcellcode|. With this command, the code is expanded a first time with an \verbinline|\edef|\footnote{If a command must not be expanded at this time, a \texttt{\string\noexpand} must be put before it.} when cell is built: at this time, the counter \verbinline|\tccol| does contain the number of the column. Then, the expansion obtained is runned a second time when cell is displayed.\medskip

In this example, text is blue if the column number is greater than 2:
\begin{center}
\begin{minipage}{\mywidth}
\begin{lstlisting}
\usepackage{color}
\edefcellcode{}{}{%
	\ifnum\tccol>2 \noexpand\color{blue}\fi}
\htablecalc[3]{$x$}{x=-2,-1,0,1,2,3}
              {$2x$}{2*x}
              {$3x$}{3*x}
              {$4x$}{4*x}
\end{lstlisting}
\end{minipage}

\edefcellcode{}{}{%
	\ifnum\tccol>2 \noexpand\color{blue}\fi}
\htablecalc[3]{$x$}{x=-2,-1,0,1,2,3}
              {$2x$}{2*x}
              {$3x$}{3*x}
              {$4x$}{4*x}
\end{center}

\subsection{Customizing the number display}
\subsubsection{Macros {\ttfamily\textbackslash printvalue} and {\ttfamily\textbackslash printresult}}\label{persoaffichage}
To display a value, the macro \verbinline|\tcprintvalue| is called. It requires one argument: the number to display which comes from \verb|pgfcalc|. This argument has a raw format: \verb|12345.6789| for "\numprint{12345.6789}".

By default, \verbinline|\tcprintvalue| is defined with this code:\par\nobreak\smallskip
\hfill\verbinline|\def\tcprintvalue#1{\numprint{#1}}|\hfill{}
\smallskip

Notice that the macro \verb|\numprint| is called to print the number.\bigskip

To display a result, the macro \verbinline|\tcprintresult| is called. It requires \textbf{two} arguments: the first is the number to display in raw format coming from \verb|pgfcalc| and the second is the value used to compute the result.

By default, \verbinline|\tcprintresult| is defined with this code:\par\nobreak\smallskip
\hfill\verbinline|\def\tcprintresult#1#2{\numprint{#1}}|\hfill{}
\smallskip

Notice that the argument \verb|#2| (the value) is ignored by \verbinline|\tcprintresult|. But it is easy to imagine an example in which it would not be. In this example, a red "\verb|X|" is printed if the lenght of the square (which is argument \verb|#2|) is negative. If not, the result with the unit is printed. For the pleasure of customization, any result less than 10 is printed in blue:\par\nobreak
\begin{center}
\begin{minipage}{\mywidth}
\begin{lstlisting}
\usepackage{color}
\def\tcprintresult#1#2{%
	\ifdim#1pt<10pt\color{blue}\fi
	\ifdim#2pt<0pt
		\color{red}\texttt{X}%
	\else
		\numprint[cm^2]{#1}%
	\fi}
\htablecalc{length}{x=0.7,-10,3,-2,5,12}
           {Area of square}{x*x}
\end{lstlisting}
\end{minipage}
\smallskip
\def\tcprintresult#1#2{%
	\ifdim#1pt<10pt\color{blue}\fi
	\ifdim#2pt<0pt
		\color{red}\texttt{X}%
	\else
		\numprint[cm^2]{#1}%
	\fi}
\htablecalc{length}{x=0.7,-10,3,-2,5,12}{Area of square}{x*x}
\end{center}

\subsubsection{How to control the rounding of numbers}
Results of calculation coming from \verb=fp= have a good precision, and decimal resultas have often many digits. Here is, for example the decimal value of $\sqrt{10}$, computed by \verb=fp=:
\begin{center}\FPeval\truc{root(2,10)}\numprint\truc\end{center}
The first 11 digits are right, the 12${}^{\text{th}}$ is rounded.\medskip

To display results, the \verb|round(number,precision)| of \verb=fp= can be used. To avoid writing many times \verb|round(number,precision)| in the code, \tbcalc provides \verbinline|\tcprintroundresult|. Its mandatory argument is the precision of the decimal part. The starred macro \verbinline|\tcprintroundresult*| fills the decimal part with "0" if necessary. If the argument is empty, no rounding is done (default behaviour).
\begin{center}
\begin{minipage}{0.5\linewidth}
\begin{center}
\begin{lstlisting}
\tcprintroundresult{3}
\htablecalc{$x$}{x=2,3,4,5}
           {$\sqrt{x}$}{root(2,x)}
\end{lstlisting}
\tcprintroundresult{3}
\htablecalc{$x$}{x=2,3,4,5}
           {$\sqrt{x}$}{root(2,x)}
\end{center}
\end{minipage}%
\begin{minipage}{0.5\linewidth}
\begin{center}
\begin{lstlisting}
\tcprintroundresult*{3}
\htablecalc{$x$}{x=2,3,4,5}
           {$\sqrt{x}$}{root(2,x)}
\end{lstlisting}
\tcprintroundresult*{3}
\htablecalc{$x$}{x=2,3,4,5}
           {$\sqrt{x}$}{root(2,x)}
\end{center}
\end{minipage}
\end{center}
To round values, it is not adviced to use the \verb|round| function of \verb=fp= since the rounded values will be used to compute the results, and rounding errors may add up. In this example, the values (square roots of integers) are the are rounded at $10^{-2}$, and the results are the square of values:
\begin{center}
\begin{minipage}{0.75\linewidth}
\begin{lstlisting}
\htablecalc{squre roots}{x=round(root(2,k),2);k=2:4}
           {square}{x*x}
\end{lstlisting}
\end{minipage}

\htablecalc{squre roots}{x=round(root(2,k),2);k=2:4}
           {square}{x*x}
\end{center}
It is obvious that rounding errors are taken into account to compute results.

It is better to use \verbinline|\tcprintroundvalue| which works like \verbinline|\tcprintroundresult|:
\begin{center}
\begin{lstlisting}
\tcprintroundvalue{2}
\htablecalc{squre roots}{x=root(2,k);k=2:4}
           {square}{x*x}
\end{lstlisting}
\tcprintroundvalue{2}
\htablecalc{squre roots}{x=root(2,k);k=2:4}
           {square}{x*x}
\end{center}
The results --~which are not rounded~-- are much nearer the expected integers.

\subsubsection{For the fun}
Other uses of this package can be designed, such as the drawing of a chess board whose squares are \numprint[cm]{0.5} long:\par\nobreak\parindent1.5em
\begin{itemize}
	\item on line 1, the separators of the table are initialzes at \verb|0pt| to obtain the length of \numprint[cm]{0.5};
	\item the display of values and results is cancelled at line 2;
	\item horizontal lines of the top and bottom of the table are drawn (line 3), and vertical lines of the left and right (line 4);
	\item a strut \numprint[cm]{0.5} height is defined to be displayed at the begining of every row (line 5);
	\item finally, if the sum of the row number and the column number is odd, the square is filled of gray (line 7 and 8).
\end{itemize}\parindent0em
\begin{center}
\begin{minipage}{\mywidth}
\begin{lstlisting}
\arraycolsep=0pt\tabcolsep=0pt
\def\tcprintvalue#1{}\def\tcprintresult#1#2{}
\tcsethrule{\hline}{}{}
\tcsetcoltype[|]{|m{0.5cm}}{m{0.5cm}}
\def\tcatbeginrow{\rule[-0.2cm]{0pt}{0.3cm}}
\edefcellcode{}{}{%
	\ifodd\numexpr\tccol+\tclin\relax
		\noexpand\cellcolor{lightgray}\fi
}
\htablecalc[7]{}{x=1,2,3,4,5,6,7}
	{}{x}{}{x}{}{x}{}{x}{}{x}{}{x}{}{x}
\end{lstlisting}
\end{minipage}

\arraycolsep=0pt\tabcolsep=0pt
\def\tcprintvalue#1{}\def\tcprintresult#1#2{}
\tcsethrule{\hline}{}{}
\tcsetcoltype[|]{|m{0.5cm}}{m{0.5cm}}
\def\tcatbeginrow{\rule[-0.2cm]{0pt}{0.3cm}}
\edefcellcode{}{}{%
	\ifodd\numexpr\tccol+\tclin\relax
		\noexpand\cellcolor{lightgray}\fi
}
\htablecalc[7]{}{x=1,2,3,4,5,6,7}
	{}{x}{}{x}{}{x}{}{x}{}{x}{}{x}{}{x}
\end{center}

\section{Export a table in a file}
No matter how customizable \tbcalc is, some tables need fine adjustments by the user at the keyboard. The \verbinline=\tcwritetofile=\ARGU{filename} has a mandatory argument which is the name of a file without extension. The next \verbinline=\htablecalc= or \verbinline=\vtablecalc= after this command will not display the tables, but a file named \argu{filename}\verb|.tex| will be written in the current directory, and its content will be the code of the table.\medskip

Here is an example:
\begin{center}
\begin{minipage}{\mywidth}
\begin{lstlisting}
\tcwritetofile{mytable}
\defcellcode{}{2}{\color{blue}}
\htablecalc[2]{$x$}{x=k;k=0:4}
               {$2x$}{2*x}
               {$x^2$}{x*x}
\tcresetcellcode
\end{lstlisting}
\end{minipage}
\end{center}
\tcwritetofile{mytable}
\defcellcode{}{2}{\color{blue}}
\htablecalc[2]{$x$}{x=k;k=0:4}
               {$2x$}{2*x}
               {$x^2$}{x*x}
\tcresetcellcode

A file \og\verb=mytable.tex=\fg{} is created in the current directory and its content is the code of the table:
\begin{center}
\begin{minipage}{\mywidth}
\begin{lstlisting}
\begin {tabular}{|c|*{5}{c|}}\hline
\tcatbeginrow $x$&\tcprintvalue {0}&\color {blue}\tcprintvalue {1}&\tcprintvalue {2}&\tcprintvalue {3}&\tcprintvalue {4}\\\hline
\tcatbeginrow $2x$&\tcprintresult {0}{0}&\color {blue}\tcprintresult {2}{1}&\tcprintresult {4}{2}&\tcprintresult {6}{3}&\tcprintresult {8}{4}\\ \hline
\tcatbeginrow $x^2$&\tcprintresult {0}{0}&\color {blue}\tcprintresult {1}{1}&\tcprintresult {4}{2}&\tcprintresult {9}{3}&\tcprintresult {16}{4}\\ \hline
\end {tabular}
\end{lstlisting}
\end{minipage}
\end{center}
The user can modify this code, and then this file can be included in the \LaTeX{} code with:
\begin{center}
\begin{minipage}{\mywidth}
\begin{lstlisting}
\input{mytable.tex}
\end{lstlisting}
\end{minipage}
\end{center}
and here is the result:
\begin{center}
\input{mytable.tex}
\end{center}

\section{Use infix or postfix notation}
Infix or postfix notation can be used since \verb=\FPeval= accepts both. In this exaple, the same table is generated with each notation. The result is exactly the same since only notation changes while math engine is the same:
\begin{center}
\begin{minipage}{\mywidth}
\begin{lstlisting}
\tcprintroundvalue{6}
\tcprintroundresult{6}
With infix notation\par
\htablecalc[3]{$x=10^k$ o\`u $k\in[-3;3]$}{x=10^k;k=-3:3}
               {$\log x$}{ln(x)/ln(10)}
               {$\sqrt{x}$}{root(2,x)}
               {$\frac{1}{x}$}{1/x}

\medskip
With postfix notation\par
\htablecalc[3]{$x=10^k$ o\`u $k\in[-3;3]$}{x=k 10 pow;k=-3:3}
               {$\log x$}{x ln 10 ln div}
               {$\sqrt{x}$}{2 x root}
               {$\frac{1}{x}$}{1 x div}
\end{lstlisting}
\end{minipage}

\tcprintroundvalue{6}
\tcprintroundresult{6}
With infix notation\par
\htablecalc[3]{$x=10^k$ o\`u $k\in[-3;3]$}{x=10^k;k=-3:3}
               {$\log x$}{ln(x)/ln(10)}
               {$\sqrt{x}$}{root(2,x)}
               {$\frac{1}{x}$}{1/x}

\medskip
With postfix notation\par
\htablecalc[3]{$x=10^k$ o\`u $k\in[-3;3]$}{x=k 10 pow;k=-3:3}
               {$\log x$}{x ln 10 ln div}
               {$\sqrt{x}$}{2 x root}
               {$\frac{1}{x}$}{1 x div}
\end{center}
If possible and if the user is used to it, the postfix notation should be prefered beacuse it often saves computation times. Indeed, to compute $\cos x(1-\cos x)$, here is the infix notation:
\begin{center}
\begin{minipage}{\mywidth}
\begin{lstlisting}
cos(x)*(1-cos(x))
\end{lstlisting}
\end{minipage}
\end{center}
Obviously, $\cos x$ is unnecessarily computed twice which slows down the compilation.\smallskip

With the postfix notation, it is computed once:
\begin{center}
\begin{minipage}{\mywidth}
\begin{lstlisting}
x cos copy 1 swap sub mul
\end{lstlisting}
\end{minipage}
\end{center}

\bigskip
\begin{center}
$\star$\par
$\star$\quad$\star$
\end{center}
\bigskip\bigskip

That's all, I hope you will find this package useful!\par\nobreak
Please, send me an \href{mailto:unbonpetit@gmail.com}{\texttt{\textbf{email}}} if you find a bug or if you have any idea of improvement\ldots\par\nobreak\medskip
Christian \textsc{Tellechea}
\end{document}