176 lines
7.8 KiB
TeX
176 lines
7.8 KiB
TeX
% \LaTeX-Main\
|
|
% !TeX encoding=UTF-8
|
|
%% The LaTeX package csvsimple - version 2.5.0 (2023/10/16)
|
|
%% csvsimple.tex: Manual
|
|
%%
|
|
%% -------------------------------------------------------------------------------------------
|
|
%% Copyright (c) 2008-2023 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,
|
|
University of the Bundeswehr Munich, 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}
|