summaryrefslogtreecommitdiff
path: root/support/csvtolatex/Source/csvtolatex-documentation.tex
blob: 39dc35421d980bcf96a983931be63676ff529d84 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
\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}