\documentclass[titlepage, fleqn]{scrartcl}

\usepackage[paper=a4paper, left = 30mm, right = 30mm, top = 30mm, bottom = 38mm]{geometry}

\usepackage[T1]{fontenc}
\usepackage[latin1]{inputenc}
\usepackage[pdftitle={documentation of csvtolatex version 1.2b},
	pdfsubject={documentation of csvtolatex version 1.2b},
	pdfauthor={Hannes Pietsch},
	pdfkeywords={pdf, LaTeX, csvtolatex, csv, Excel, calc},
	pdfstartview=FitH,
	bookmarks,
	bookmarksnumbered=true,
	colorlinks=false,
	linkbordercolor={1  1  1},
	pdfborder={0 0 0}
	]{hyperref}

\usepackage{amssymb}	% für einige Mathematischen Symbole
\usepackage{amsfonts}	% Schriftarten in Mathe
\usepackage{amsmath}	% Formellayout
\usepackage{dsfont}		% Für die Zeichen von Natürlichen Zahlen usw.
\usepackage{mathcomp}	% Sonderzeichen in Mathe

\usepackage{fancybox}

\usepackage{float}
\usepackage{graphicx}
\usepackage{subfigure}

\usepackage{color}
\usepackage{listings}

\usepackage{paralist}

\usepackage{longtable}

\usepackage{setspace}


%\usepackage{libertine}
\newcommand{\changefont}[3]{
\fontfamily{#1}  \fontseries{#2}  \fontshape{#3}  \selectfont}
\changefont{pbk}{m}{n}		% Bookman


\renewcommand{\familydefault}{\sfdefault}
\renewcommand*\oldstylenums[1]{{\fontfamily{fxlj}\selectfont  #1}}

\numberwithin{figure}{section}
\numberwithin{equation}{section}
\numberwithin{table}{section}
\renewcommand{\thefigure}{\arabic{section}-\arabic{figure}}
\renewcommand{\theequation}{\arabic{section}.\arabic{equation}}
\renewcommand{\thetable}{\arabic{section}-\arabic{table}}

\renewcommand{\figurename}{picture}
\renewcommand{\figureautorefname}{picture}


\newcommand{\latex}{\LaTeX $\ $}
\newcommand{\version}{1.3}

\parindent0pt

\lstset{
language=VBScript,
frame=l,
numbers=left,
numberstyle=\tiny,
numbersep=5pt,
columns=fixed,
showstringspaces=false,
breaklines=true,
tabsize=4,
extendedchars=true,
basicstyle=\scriptsize,
commentstyle=\scriptsize,
sensitive=false,
commentstyle=\footnotesize\color[rgb]{0.133,0.545,0.133},
keywordstyle=\bfseries\ttfamily\color[rgb]{0,0,1},
stringstyle=\ttfamily\color[rgb]{0.627,0.126,0.941},
basewidth=0.5em
}


\title{Documentation for csvtolatex version \version}
\author{by Hannes Pietsch \\
			\small \href{mailto:csvtolatex@t-online.de}{csvtolatex@t-online.de}}
\date{\today}

\begin{document}

\maketitle
\pagenumbering{Roman}
\newpage

\pdfbookmark[1]{table of contents}{toc}
\tableofcontents

\newpage

\pagenumbering{arabic}

\section{foreword}

\subsection{What is csvtolatex}
csvtolatex is a program that links spreadsheet-program like MS Excel, Libre Office Calc or Open Office Calc with \LaTeX. You might have the problem, that there is steadily a change in your table. Perhaps you measurment-table where your calculations may change. For this this program is designed.


\subsection{What is csvtolatex not}
This program is not for learning how to create tables in \latex nor it is a shortcut to create tables in \latex. You will need the knowledge how to create a table in \latex to write properly the commands in the spreadsheetprogram and to set the enviroment for the table right.


\subsection{license}

This program is under GPLv3, if you are using it, you accept the licence. The full text you can read in Licence.txt.


\subsection{updates}
For updates please visit \href{http://www.ctan.org/tex-archive/support/csvtolatex}{ctan} or \href{http://sourceforge.net/projects/csvtolatex/}{sourceforge}. Please read section \ref{sec:info} at page \pageref{sec:info}.\\

Since version 1.1b the srcipt is no longer supported nor there will be updates.


\section{how to use}

To make sure, that no \latex commands interfere with this script I decided to use a slash \verb=/= for commands, not the backslash \verb=\= like \latex uses it.\\

Since version 1.1 there is also an windows-installer that allows you to use configuration files with the extension .ctl but you can also use the script file.\\

\subsection{script or program?}

Since version 1.1b there is no support for the script, please use the program.\\

If you are using just one system for you \latex project, there is no difference in weather using the script or the program.\\
But if you are using multiple systems there will be different project-paths so I recommend to use the program, because you can use relative-paths for your input-file and your output-files this makes life easier.\\

\begin{description}
	\item[information:] A configuration-file is nothing other than a normal text-file with .ctl as extension. *.ctl-files are associated with the program. 
\end{description}

\subsection{the table}

First of all you have to create your table. And there are some reglementations if you want to use csvtolatex. Also there are additional commands. Please be aware that this script is tested for \verb=longtable= enviroment.

\subsubsection{Basic commands}

\begin{itemize}
	\item Every table that should be converted for the usage in \latex begins with \verb=/begin{=. This command defines the output-filename of the table. Attention: this script will not check weather a filename is already used or not. Here is an example \verb=/begin{outfile1.csv}=.
	\item	Every line of a table ends with \verb=//=
	\item	Every table ends with \verb=/end=
\end{itemize}

\subsubsection{Additional commands}

\begin{itemize}
	\item You can use \verb=/multicolumn{= like you use \verb=\multicolumn{= in \latex. But this command has to be written in the cell of the row, where the \verb=\multicolumn{= starts. Please be aware, that there is no support for math- or textmode when using \verb=/multicolumn{=. The syntax stays the same as in \latex exept the slash.
	\item	Like \verb=/multicolumn{= you can use \verb=/multirow{= with the same rules. There is no math- or textmode support as well.
	\item	Since tables may have some special shapes you can use \verb=/cline{= or \verb=\cline{= after the double slash. There is also the possibility to have more than one \verb=/cline{= or \verb=\cline{= in one line, but all commands have to be in the same cell as the double slash for linebreak. Example: \verb=// \cline{2-3} /cline{5-7}=
	\item	You can write \verb=/hline= in the same cell as the double-backslash (\verb=//=) to make a double \verb=\hline= after this row, this may be useful to separate the head from the rest of the table.
	\item	There may be some problems when using \verb=/multirow{= or \verb=/multicolumn{=. If there is a cell too much use \verb=/blank= to remove the cell.
	\item Since a csv-table uses semicola \verb=;= as cell seperator you cannot use a simple semicolon in your text. Use \verb=/.,= to have a semicolon in your text.
	\item	Since this script is supports the \verb=longtable=-enviroment (other enviroments are also supported) you can define the head of the table with \verb=/endhead=. \verb=/endhead= has to be written in the same cell as the linebreak (\verb=//=) after it. Example: \verb=// /endhead=
\end{itemize}


\subsection{the configuration-file}
\label{sec:configfile}

If you decided to use the program life will be easier.\\
There are just four keywords! The order of these keywords does not matter at all.
\begin{description}
	\item[input=] defines the input-path and the input-csv
	\item[output=]	defines the output-path if necessary
	\item[mode=]	defines weather it should be the mathmode or textmode
	\item[options=] defines options
\end{description}

A configuration-file is a text-file with the extension .ctl which is associated with csvtolatex. You can also use configcreator-ctl.vbs to create a configuration file.

\subsubsection{input}
\verb+input=+ is necessary for conversion but you have two options:
\begin{enumerate}
	\item You can use the full path. Example: \verb+input=C:\Users\documents\input.csv+
	\item You use a relative path to the configuration-file: Example: \verb+input=\tables\input.csv+ \\
		This is the best version since it will be properly read on every PC you are using.
\end{enumerate}
 
\subsubsection{output}
\verb+output=+ is optional You have three options:
\begin{enumerate}
	\item If the converted files should be in the same folder as the input-file (input.csv) you can leave this out.
	\item	If the converted files should be in an other folder as the input-file (input.csv) you can use a relative path
	\begin{enumerate}
		\item to your input-file folder using \verb+output=+. Example: \verb+output=\outtables\+
		\item to your config-file folder using \verb+output=config=+. Example: \verb+output=config=\outtables\+
	\end{enumerate}
	\item You can also use the full path.
\end{enumerate}

\subsubsection{mode}
\verb+mode=+ is optional. You have three options:
\begin{enumerate}
	\item leave it out for mathmode
	\item write \verb+mode=math+ for mathmode
	\item or write \verb+mode=text+ for textmode
\end{enumerate}

\subsubsection{options}
\verb+options=+ is optional. There is two options possible for now:
\begin{enumerate}
	\item leave it out, to have at the end of every line an \verb+\hline+
	\item	write \verb+options=nolines+ to have no lines between rows and columns
\end{enumerate}

\subsection{comma/point replacement}
With csvtolatex you can easily replace the decimal dividers. You can choose:
\begin{enumerate}
	\item leave it out: there will be no replacement
	\item	write \verb+commatopoint+ and the program will replace all commas to points
	\item write \verb+pointtocomma+ and the program will replace all points to commas
\end{enumerate}


%\begin{enumerate}
%	\item leave it out to have in every line an \verb+\hline+ at the end of every line
%	\item	write \verb+option=nohlines+ to have no \verb+\hline+ at the end of every line, except you place it with \verb+/hline+
%	\item	or write \verb+option=headhlines+ to have an \verb+\hline+ just at \verb+\endhead+, or at the place you want
%\end{enumerate}

\subsection{the \latex input}

There is a simplified \latex input since Version 1.0.\\

To have \latex display your table converted by csvtolatex use the following \LaTeX-Code:

\begin{verbatim}
\begin{longtable}{|c|c|c|c|c|c|c|c|c|c|c|}
\input{tables/output1.csv}
\end{longtable}
\end{verbatim}

Of course you have to customize\\
\verb=\input{tables/output1.csv}=\\
to your own projectpath and projectoutputfilename. And \\
\verb=\begin{longtable}{|c|c|c|c|c|c|c|c|c|c|c|}=\\
to the number of the columns used in your table. Since version 1.2 you can see a suggetion and the number of columns in the outpufile.

\section{configcreator-ctl}

This script is written for simple creation of configuration files.\\

Just start this script (using the link in the startmenu) follow the instructions given in this script and the rules given in section \ref{sec:configfile} on page \eqref{sec:configfile}.

\section{information}
\label{sec:info}

Since I know the limits of using csv-tables for conversion I am working on tabs4latex, that uses html-files as inputfiles. This program will be written in \verb=C#= and there will be a linux version too. There is another project of mine, called htmltabstolatex, which will do the same as tabs4latex but is written in java. If you are interested in working with me on this project, send an e-mail to \href{mailto:tabs4latex@t-online.de}{tabs4latex@t-online.de}.\\

So I do not have the time to work for both projects I will not force new features for csvtolatex, some minor stuff will be added. If there are bugs or incompabilities send me an e-mail to \href{mailto:csvtolatex@t-online.de}{csvtolatex@t-online.de} and I will try to make it better. Maybe someone is interested in updating this script/program. If you want this please tell me.




\subsection{the script-file}

The script is no longer supported (since version 1.1) so please use the program.\\

If you are using the program you can leave this section out.\\

In this section you learn how to adapt the script for your project. You can use every texteditor (e.g. notepad++) for adaption.\\

Please read also the comments given in the script file.

\subsubsection{Inputfile}
First of all you define the inputfile. For that you customize the following line:

\lstinputlisting[firstline=9, lastline=9, firstnumber=9]{csvtolatex.vbs}

This is line 9 and here you have to write your own path to the inputfile including the inputfile name, like the example shows. It is important, that all \verb="= remain where they are and that there are no unnecessary blank spaces.

\subsubsection{Outputpath}

At line 10 you define your output\emph{path}.

\lstinputlisting[firstline=13, lastline=13, firstnumber=13]{csvtolatex.vbs}

\subsubsection{outputfiles}

Since Version 1.1 there is no output\emph{file} definition in the script-file necessary.

\subsubsection{math- or textmode}

You have the opportunity to choose between text- or mathmode. That means weather all cells are in mathmode (e.g. \verb+$ 1 - 3 = 4 $+) or textmode (e.g. \verb=text=). To do this write \verb="$"= for mathmode or \verb=""= for textmode at line 19:

\lstinputlisting[firstline=19, lastline=19, firstnumber=19]{csvtolatex.vbs}

\section{used program}

\begin{description}
	\item[Notepad++]	Editing the script, my configuration File, the README
	\item[\latex]	writing the documentation, and testing the script/program
	\item[Microsoft Visual Studio 2010]	writing and compiling the program
	\item[Venis IX]	Creation of the NSIS script
	\item[NSIS]	creation of the installer
	\item[7-zip]	creation and updating the .zip-files
\end{description}

\section{README}

\lstinputlisting[firstline=1]{README.txt}


\end{document}
