% \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}
