summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/csvsimple/csvsimple.tex
blob: 968c43bc0cfde2b15977ede488aeb86ad3ae22f3 (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
% \LaTeX-Main\
% !TeX encoding=UTF-8
%% The LaTeX package csvsimple - version 2.2.0 (2021/09/09)
%% csvsimple.tex: Manual
%%
%% -------------------------------------------------------------------------------------------
%% Copyright (c) 2008-2021 by Prof. Dr. Dr. Thomas F. Sturm <thomas dot sturm at unibw dot de>
%% -------------------------------------------------------------------------------------------
%%
%% 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.
%%
%% This work has the LPPL maintenance status `author-maintained'.
%%
%% This work consists of all files listed in README.md
%%
\documentclass[a4paper,11pt]{ltxdoc}
\usepackage{csvsimple-doc}

\usepackage{\csvpkgprefix csvsimple-legacy}

\hypersetup{
  pdftitle={Manual for the csvsimple package},
  pdfauthor={Thomas F. Sturm},
  pdfsubject={csv file processing with LaTeX},
  pdfkeywords={csv file, comma separated values, key value syntax}
}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{document}
\begin{center}
\begin{tcolorbox}[enhanced,hbox,tikznode,left=8mm,right=8mm,boxrule=0.4pt,
  colback=white,colframe=black!50!yellow,
  drop lifted shadow=black!50!yellow,arc is angular,
  before=\par\vspace*{5mm},after=\par\bigskip]
{\bfseries\LARGE The \texttt{csvsimple} package}\\[3mm]
{\large Manual for version \version\ (\datum)}
\end{tcolorbox}
{\large Thomas F.~Sturm%
  \footnote{Prof.~Dr.~Dr.~Thomas F.~Sturm, Institut f\"{u}r Mathematik und Informatik,
    Universit\"{a}t der Bundeswehr M\"{u}nchen, D-85577 Neubiberg, Germany;
     email: \href{mailto:thomas.sturm@unibw.de}{thomas.sturm@unibw.de}}\par\medskip
\normalsize\url{https://www.ctan.org/pkg/csvsimple}\par
\url{https://github.com/T-F-S/csvsimple}
}
\end{center}
\bigskip
\begin{absquote}
  \begin{center}\bfseries Abstract\end{center}
  |csvsimple| provides a simple \LaTeX\ interface for the processing of files with
  comma separated values (CSV). |csvsimple| relies heavily on a key value
  syntax which results in an easy way of usage.
  Filtering and table generation is especially supported. Since the package
  is considered as a lightweight tool, there is no support for data sorting
  or data base storage.
\end{absquote}

\section{Package Options}%

|csvsimple| is a stub which merely selects to load exclusively one of the
following packages:
\begin{itemize}
\item \href{csvsimple-l3.pdf}{\flqq The |csvsimple-l3| package\frqq}:\\
  This is the pure \LaTeX3 version of |csvsimple|. It is considered
  to be the \emph{current} version.
  New documents are encouraged to use this package.\par
  |csvsimple-l3| is loaded with \emph{one} of the following
  alternatives inside the preamble:
\begin{dispListing}
\usepackage[l3]{csvsimple}
   % or alternatively (not simultaneously!)
\usepackage{csvsimple-l3}
\end{dispListing}
\medskip

\item \href{csvsimple-legacy.pdf}{\flqq The |csvsimple-legacy| package\frqq}:\\
  This is the \LaTeXe{} version of |csvsimple|. It is considered
  to be the \emph{superseded} version identical to version 1.22 of |csvsimple|.
  Documents based on that former version do \emph{not have to be changed}
  and stay compilable in future.\par
  |csvsimple-legacy| is loaded with \emph{one} of the following
  alternatives inside the preamble:
\begin{dispListing}
\usepackage{csvsimple}
   % or alternatively (not simultaneously!)
\usepackage[legacy]{csvsimple}
   % or alternatively (not simultaneously!)
\usepackage{csvsimple-legacy}
\end{dispListing}
\end{itemize}


\clearpage
\section{Differences between \texttt{csvsimple-l3} and \texttt{csvsimple-legacy}}
This section is intended for users who know |csvsimple| before version~2.00.

|csvsimple-l3| is a \emph{nearly} drop-in replacement for
|csvsimple-legacy|. Although old documents have no \emph{need} to be changed,
adopting the new \LaTeX3 version for existing documents should impose not
too much effort. Actually, it depends on how intense |pgfkeys| specific
styles were used.

That brings us to the differences between the two packages and a more precise
understanding what \emph{nearly} drop-in replacement means. The following enumeration
does not list new features of \texttt{csvsimple-l3} (if any), but takes an
upgrade point of view.

\begin{itemize}
\item Any patches or additions using undocumented internals of |csvsimple-legacy|
  will stop to function, because |csvsimple-l3| has a completely implementation.
\item |csvsimple-l3| is programmed in |expl3| code using the \LaTeX3 interfaces.
  No additional packages are loaded or needed with exception of several options
  which allow to access methods from |ifthen|, |etoolbox|, |longtable|, etc.
  On the other hand, |csvsimple-legacy| is programmed in \LaTeXe{} with
  dirty tricks from here and there.
\item The most significant change of the user interface is that the key value
  engine of |csvsimple-legacy| is |pgfkeys| (root \docAuxKey*[csv]{}) while |csvsimple-l3| uses
  |l3keys| (root \docAuxKey*[csvsim]{}).
  Names and usage of the keys are \emph{unchanged}.
  But, if
  you made own |pgfkeys| \emph{styles} using the |pgfkeys| style handler,
  these \emph{styles} have to be adapted to |.meta| keys of |l3keys|.
  The good news is that styles
  made with \docAuxCommand*{csvstyle} become |.meta| keys automatically.
\item The macro \docAuxCommand*{csvheadset} is removed. It is not supportable
  by the new implementation. I never used it and I forgot why I ever wrote it
  -- I hope the same is true for you. If not, |csvsimple-legacy| can be
  used for documents which needs it.
\item Option \docAuxKey*[csv]{filter} is removed. Instead, \docAuxKey*[csvsim]{filter ifthen}
  can be used (also true with \docAuxKey*[csv]{filter ifthen} for the old version).
\item The deprecated options
  \docAuxKey*[csv]{nofilter} and \docAuxKey*[csv]{nohead} are removed.
  They were not documented any more since years. Obviously, use
  \docAuxKey*[csvsim]{no filter} and \docAuxKey*[csvsim]{no head} instead.
\item Compilation problems are to be expected, if an |S| column of the |siunitx| package
  is used as first or last column. Documents neglecting this rule successfully
  for |csvsimple-legacy|, may fail to compile with |csvsimple-l3.|
\item The \LaTeX{} counters \docCounter*{csvinputline}
  and \docCounter*{csvrow}
  are replaced by \LaTeX3 integers
  \docCounter*{g_csvsim_inputline_int}
  and \docCounter*{g_csvsim_row_int}, but accessors
  \docAuxCommand*{thecsvinputline} and
  \docAuxCommand*{thecsvrow} are still valid.
\item The packages |pgfrcs|, |pgfkeys|, |ifthen|, |etoolbox|, and |shellesc|
  are not included anymore (include manually, if needed).
\item
  \docAuxCommand*{csviffirstrow} and
  \docAuxCommand*{csvifoddrow} are deprecated and replaced by
  \docAuxCommand*{ifcsvfirstrow}
  \docAuxCommand*{ifcsvoddrow}
  which are more consistent in nomenclature.
\item For |csvsimple-l3|, data lines are allowed to begin with an backslash.
\item Assigned macros like |\myname| for e.g. the third column contain
  not |\csvcoliii| anymore, but are equal to the content of |\csvcoliii| now.
\item Character code changes with \docAuxKey*[csvsim]{respect percent} etc.
  and the tabulator as separator should work for |csvsimple-l3| as expected in every
  situation (not always worked for |csvsimple-legacy|).
\item A drawback of |csvsimple-l3| against |csvsimple-legacy| is
  a higher compilation time. This may vary by used compiler.
  An example document of 5061 pages using a CSV file with 166 992 lines
  took about 28 seconds with |csvsimple-legacy| and
  about 51 seconds with |csvsimple-l3| on my machine
  (just a singular observation, no scientific analysis at all).
\end{itemize}




\end{document}