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