csvsimple (7jul14)

git-svn-id: svn://tug.org/texlive/trunk@34544 c570f23f-e606-0410-a88d-b1316a301751

11 files changed, 629 insertions, 75 deletions

diff --git a/Master/texmf-dist/doc/latex/csvsimple/CHANGES b/Master/texmf-dist/doc/latex/csvsimple/CHANGES
index 2b040d4a3a0..37a0a7b1fba 100644
--- a/Master/texmf-dist/doc/latex/csvsimple/CHANGES
+++ b/Master/texmf-dist/doc/latex/csvsimple/CHANGES
@@ -1,7 +1,7 @@
-%% The LaTeX package csvsimple - version 1.07 (2013/09/25)
+%% The LaTeX package csvsimple - version 1.10 (2014/07/07)
 %%
 %% -------------------------------------------------------------------------------------------
-%% Copyright (c) 2008-2013 by Prof. Dr. Dr. Thomas F. Sturm <thomas dot sturm at unibw dot de>
+%% Copyright (c) 2008-2014 by Prof. Dr. Dr. Thomas F. Sturm <thomas dot sturm at unibw dot de>
 %% -------------------------------------------------------------------------------------------
 %%
 %% This work may be distributed and/or modified under the
@@ -62,3 +62,19 @@ version 1.07 (2013/09/25):
 - internal macro '\TrimSpaces' renamed to avoid name clashed with 'xparse'
 - new option 'separator' to set the data value separator to
   'comma', 'semicolon', or 'pipe'
+
+version 1.10 (2014/07/07):
+- bug fix: table head names in curly brackets were not recognized for some cases
+- changed: if a CSV file is not found, csvsimple stops with an error message instead of a warning
+- external sorting specifically supported for the CSV-Sorter tool with the new options
+ 'csvsorter command', 'csvsorter configpath', 'csvsorter log',
+ 'sort by', 'new sorting rule'
+- new automatic tabular settings with booktabs:
+  '\csvautotabular' and '\csvautolongtable'
+- new keys for respecting special characters:
+  'respect tab', 'respect percent', 'respect sharp', 'respect dollar',
+  'respect and', 'respect backslash', 'respect underscore', 'respect tilde',
+  'respect circumflex', 'respect leftbrace', 'respect rightbrace',
+ 'respect all', 'respect none'
+- new value 'tab' for the 'separator' option to use a tabulator signs
+  as separator.
diff --git a/Master/texmf-dist/doc/latex/csvsimple/README b/Master/texmf-dist/doc/latex/csvsimple/README
index ff38a38ef59..b96a090f22d 100644
--- a/Master/texmf-dist/doc/latex/csvsimple/README
+++ b/Master/texmf-dist/doc/latex/csvsimple/README
@@ -1,7 +1,7 @@
-%% The LaTeX package csvsimple - version 1.07 (2013/09/25)
+%% The LaTeX package csvsimple - version 1.10 (2014/07/07)
 %%
 %% -------------------------------------------------------------------------------------------
-%% Copyright (c) 2008-2013 by Prof. Dr. Dr. Thomas F. Sturm <thomas dot sturm at unibw dot de>
+%% Copyright (c) 2008-2014 by Prof. Dr. Dr. Thomas F. Sturm <thomas dot sturm at unibw dot de>
 %% -------------------------------------------------------------------------------------------
 %%
 %% This work may be distributed and/or modified under the
@@ -33,6 +33,10 @@ Contents of the package
   'csvsimple-example.tex'     Example file for package usage
   'csvsimple-example.csv'     CSV file as part of the example
   'csvsimple-example.pdf'     Compiled example
+  'amountsort.xml'            csvsorter configuration file (example)
+  'gradesort.xml'             csvsorter configuration file (example)
+  'matriculationsort.xml'     csvsorter configuration file (example)
+  'namesort.xml'              csvsorter configuration file (example)
 
 Installation
 ============
diff --git a/Master/texmf-dist/doc/latex/csvsimple/amountsort.xml b/Master/texmf-dist/doc/latex/csvsimple/amountsort.xml
new file mode 100644
index 00000000000..1f37624a7d7
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/csvsimple/amountsort.xml
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<csv>
+  <bracket empty="true" />
+  <sortlines>
+    <column name="amount" order="descending" type="double"/>
+    <column name="land" order="ascending" type="string"/>
+  </sortlines>
+</csv>
diff --git a/Master/texmf-dist/doc/latex/csvsimple/csvsimple-example.pdf b/Master/texmf-dist/doc/latex/csvsimple/csvsimple-example.pdf
index ca491ced639..0fefb4f6003 100644
--- a/Master/texmf-dist/doc/latex/csvsimple/csvsimple-example.pdf
+++ b/Master/texmf-dist/doc/latex/csvsimple/csvsimple-example.pdf
diff --git a/Master/texmf-dist/doc/latex/csvsimple/csvsimple-example.tex b/Master/texmf-dist/doc/latex/csvsimple/csvsimple-example.tex
index 8680f26f52d..4f2c263abad 100644
--- a/Master/texmf-dist/doc/latex/csvsimple/csvsimple-example.tex
+++ b/Master/texmf-dist/doc/latex/csvsimple/csvsimple-example.tex
@@ -1,8 +1,8 @@
-%% The LaTeX package csvsimple - version 1.07 (2013/09/25)
+%% The LaTeX package csvsimple - version 1.10 (2014/07/07)
 %% csvsimple-example.tex: an example for csvsimple
 %%
 %% -------------------------------------------------------------------------------------------
-%% Copyright (c) 2008-2011 by Prof. Dr. Dr. Thomas F. Sturm <thomas dot sturm at unibw dot de>
+%% Copyright (c) 2008-2014 by Prof. Dr. Dr. Thomas F. Sturm <thomas dot sturm at unibw dot de>
 %% -------------------------------------------------------------------------------------------
 %%
 %% This work may be distributed and/or modified under the
@@ -18,6 +18,7 @@
 %% This work consists of all files listed in README
 %%
 \documentclass{article}
+\usepackage{array,booktabs}
 \usepackage{csvsimple}
 
 \begin{document}
@@ -64,10 +65,10 @@
 %----------------------------------------------------------
 \section{More filter fun}
 
-\csvreader[my names, filter=\birthyear<1980, centered tabular=|r|l|l|r|,
-  table head=\multicolumn{4}{c}{\bfseries People born before 1980}\\\hline
-     \# & Name & Postal address & input line no.\\\hline\hline,
-     late after line=\\, late after last line=\\\hline]%
+\csvreader[my names, filter=\birthyear<1980, centered tabular=rllr,
+  table head=\multicolumn{4}{c}{\bfseries People born before 1980}\\\toprule
+     \# & Name & Postal address & input line no.\\\midrule,
+     late after line=\\, late after last line=\\\bottomrule]%
   {csvsimple-example.csv}{}{%
     \thecsvrow & \givenname\ \surname & \zip\ \address & \thecsvinputline
 }
diff --git a/Master/texmf-dist/doc/latex/csvsimple/csvsimple.pdf b/Master/texmf-dist/doc/latex/csvsimple/csvsimple.pdf
index c5b455bdc87..6745314a8e8 100644
--- a/Master/texmf-dist/doc/latex/csvsimple/csvsimple.pdf
+++ b/Master/texmf-dist/doc/latex/csvsimple/csvsimple.pdf
diff --git a/Master/texmf-dist/doc/latex/csvsimple/csvsimple.tex b/Master/texmf-dist/doc/latex/csvsimple/csvsimple.tex
index aff18dbd3a9..08dfd1f648f 100644
--- a/Master/texmf-dist/doc/latex/csvsimple/csvsimple.tex
+++ b/Master/texmf-dist/doc/latex/csvsimple/csvsimple.tex
@@ -1,9 +1,9 @@
 % \LaTeX-Main\
-%% The LaTeX package csvsimple - version 1.07 (2013/09/25)
-%% csvsimple.sty: Simple LaTeX CSV file processing
+%% The LaTeX package csvsimple - version 1.10 (2014/07/07)
+%% csvsimple.tex: Manual
 %%
 %% -------------------------------------------------------------------------------------------
-%% Copyright (c) 2008-2013 by Prof. Dr. Dr. Thomas F. Sturm <thomas dot sturm at unibw dot de>
+%% Copyright (c) 2008-2014 by Prof. Dr. Dr. Thomas F. Sturm <thomas dot sturm at unibw dot de>
 %% -------------------------------------------------------------------------------------------
 %%
 %% This work may be distributed and/or modified under the
@@ -52,10 +52,16 @@
 \addbibresource{\jobname.bib}
 
 \usepackage[most,documentation]{tcolorbox}
-\tcbset{skin=enhanced}
-\usepackage{longtable}
+\usepackage{longtable,booktabs}
 \usepackage{csvsimple}
 
+\tcbset{skin=enhanced,
+  doc head={colback=yellow!10!white,interior style=fill},
+  doc head key={colback=magenta!5!white,interior style=fill},
+  color key=DarkViolet,
+  color value=Teal,
+  color color=Teal,
+  index colorize,index annotate}
 
 \lstdefinestyle{mydocumentation}{style=tcbdocumentation,
   classoffset=0,
@@ -67,6 +73,7 @@
     csvset,csvreader,csvautotabular,csvloop,csvautolongtable,csvstyle,
     csvnames,csvheadset,csviffirstrow,csvifoddrow,csvfilteraccept,
     csvfilterreject,csvline,thecsvrow,thecsvinputline,csvlinetotablerow,
+    csvautobooktabular,csvautobooklongtable,
     },
   texcsstyle=\color{Definition}\bfseries,
   classoffset=2,
@@ -82,15 +89,20 @@
     bicolor,colbacklower=ExampleBack!5!white,drop fuzzy shadow},
 }
 
+
+
 \tcbmakedocSubKey{docCsvKey}{csv}
 
-\newcommand{\csvlisting}[1]{%
-  \tcbinputlisting{docexample,listing style=tcbdocumentation,
-  listing only,title={CSV file \texttt{#1.csv}},listing file=#1.csv}}
+\NewDocumentCommand{\csvsorter}{}{\textsf{\bfseries\color{red!20!black}CSV-Sorter}}
+
+\newtcbinputlisting{\csvlisting}[1]{docexample,listing style=tcbdocumentation,fonttitle=\bfseries,
+  listing only,title={CSV file \flqq\texttt{\detokenize{#1.csv}}\frqq},listing file=#1.csv}
+
+\newtcbinputlisting{\xmllisting}[1]{docexample,listing options={style=tcbdocumentation,language=XML},
+  fonttitle=\bfseries,listing only,title={Configuration file \flqq\texttt{\detokenize{#1.xml}}\frqq},listing file=#1.xml}
 
-\makeatletter
-\newcommand{\auxCommand}[1]{\disp@com{\cs{#1}}\index@Com{#1}}
-\makeatother
+\NewTotalTCBox{\verbbox}{m}{enhanced,on line,size=fbox,frame empty,colback=red!5!white,
+  colupper=red!85!black,fontupper=\bfseries\ttfamily}{\detokenize{"}#1\detokenize{"}}
 
 \hypersetup{
   pdftitle={Manual for the csvsimple package},
@@ -99,8 +111,8 @@
   pdfkeywords={csv file, comma separated values, key value syntax}
 }
 
-\def\version{1.07}%
-\def\datum{2013/09/25}%
+\def\version{1.10}%
+\def\datum{2014/07/07}%
 \makeindex
 
 
@@ -132,30 +144,33 @@
 
 \tableofcontents
 
-\enlargethispage*{1cm}
+\clearpage
 \section{Introduction}%
 The |csvsimple| package is applied to the processing of
 CSV\footnote{CSV file: file with comma separated values.} files.
 This processing is controlled by key value assignments according to the
-syntax of |pgfkeys| \cite{tantau:2010c}. Sample applications of the package
+syntax of |pgfkeys| \cite{tantau:2013a}. Sample applications of the package
 are tabular lists, serial letters, and charts.
 
-An alternative to |csvsimple| is the |datatool| package \cite{talbot:2012a}
-which provides considerably more functions like exchange of separator and
-delimiter symbols or sorting of data.
+An alternative to |csvsimple| is the |datatool| package \cite{talbot:2014a}
+which provides considerably more functions and allows sorting of data by \LaTeX.
 |csvsimple| has a different approach for the user interface and
 is deliberately restricted to some basic functions with fast
-processing speed.
-
+processing speed. Sorting is not supported directly but can be done
+with external tools, see Section~\ref{sec:Sorting} on page~\pageref{sec:Sorting}.
 
 \subsection{Loading the Package}
 The package |csvsimple| loads the packages
-|pgfkeys| \cite{tantau:2010c} and |ifthen| \cite{carlisle:2001b}.
+|pgfkeys| \cite{tantau:2013a} and |ifthen| \cite{carlisle:2001b}.
 |csvsimple| itself is loaded in the usual manner in the preamble:
 \begin{dispListing}
 \usepackage{csvsimple}
 \end{dispListing}
 
+Not automatically loaded, but used for many examples are the packages
+|longtable| \cite{carlisle:2004a}
+and
+|booktabs| \cite{fear:2005a}.
 
 \subsection{First Steps}
 Every line of a processable CSV file has to contain an identical amount of
@@ -171,11 +186,13 @@ name,givenname,matriculation,gender,grade
 Maier,Hans,12345,m,1.0
 Huber,Anna,23456,f,2.3
 Wei\ss{}b\"{a}ck,Werner,34567,m,5.0
+Bauer,Maria,19202,f,3.3
 \end{tcbverbatimwrite}
 %-- end embedded file --
 
 \csvlisting{grade}
 
+
 The most simple way to display a CSV file in tabular form is the processing
 with the \refCom{csvautotabular} command.
 
@@ -183,12 +200,14 @@ with the \refCom{csvautotabular} command.
 \csvautotabular{grade.csv}
 \end{dispExample}
 
+
 Typically, one would use \refCom{csvreader} instead of |\csvautotabular| to
 gain full control over the interpretation of the included data.
 
 In the following example, the entries of the header line are automatically
 assigned to \TeX\ macros which may be used deliberately.
 
+
 \begin{dispExample}
 \begin{tabular}{|l|c|}\hline%
 \bfseries Person & \bfseries Matr.~No.
@@ -198,7 +217,7 @@ assigned to \TeX\ macros which may be used deliberately.
 \end{tabular}
 \end{dispExample}
 
-\newpage
+
 |\csvreader| is controlled by a plenty of options. For example, for table
 applications line breaks are easily inserted by
 \refKey{/csv/late after line}. This defines a macro execution just before
@@ -215,7 +234,7 @@ way.
 \end{tabular}
 \end{dispExample}
 
-An even more comfortable way to create a table is setting
+An even more comfortable and preferrable way to create a table is setting
 appropriate option keys. Note, that this gives you the possibility to create a
 |pgfkeys| style which contains the whole table creation.
 
@@ -227,6 +246,7 @@ appropriate option keys. Note, that this gives you the possibility to create a
   {\thecsvrow & \firstname~\name & \matnumber}%
 \end{dispExample}
 
+\clearpage
 The next example shows such a style definition with the convenience macro
 \refCom{csvstyle}. Here, we see again the automated assignment of header
 entries to column names by \refKey{/csv/head to column names}.
@@ -244,7 +264,7 @@ above.
   {\thecsvrow & \givenname~\name & \matriculation}%
 \end{dispExample}
 
-\newpage
+
 Another way to address columns is to use their roman numbers.
 The direct addressing is done by |\csvcoli|, |\csvcolii|, |\csvcoliii|, \ldots:
 
@@ -267,6 +287,7 @@ for the assignment:
   {\thecsvrow & \firstname~\name & \matnumber}%
 \end{dispExample}
 
+\clearpage
 For recurring applications, the |pgfkeys| syntax allows to create own styles
 for a consistent and centralized design. The following example is easily
 modified to obtain more or less option settings.
@@ -286,7 +307,7 @@ modified to obtain more or less option settings.
 {\thecsvrow & \firstname~\name & \grade}%
 \end{dispExample}
 
-\newpage
+
 Alternatively, column names can be set by \refCom{csvnames}
 and style definitions by \refCom{csvstyle}.
 With this, the last example is rewritten as follows:
@@ -304,6 +325,7 @@ With this, the last example is rewritten as follows:
 {\thecsvrow & \firstname~\name & \grade}%
 \end{dispExample}
 
+\clearpage
 The data lines of a CSV file can also be filtered. In the following example,
 a certificate is printed only for students with grade unequal to 5.0.
 
@@ -343,9 +365,9 @@ a certificate is printed only for students with grade unequal to 5.0.
   The \meta{command list} is executed for every accepted data line. Inside the
   \meta{command list} is applicable:
   \begin{itemize}
-  \item \auxCommand{thecsvrow} or the counter |csvrow| which contains the number of the
+  \item \docAuxCommand{thecsvrow} or the counter |csvrow| which contains the number of the
     current data line (starting with 1).
-  \item \auxCommand{csvcoli}, \auxCommand{csvcolii}, \auxCommand{csvcoliii}, \ldots,
+  \item \docAuxCommand{csvcoli}, \docAuxCommand{csvcolii}, \docAuxCommand{csvcoliii}, \ldots,
     which contain the contents of the column entries of the current data line.
     Alternatively can be used:
   \item \meta{macro} from the \meta{assignments} to have a logical
@@ -414,6 +436,35 @@ is useless for |\csvreader|.
 \csvautolongtable{grade.csv}
 \end{docCommand}
 
+\clearpage
+
+\begin{docCommand}{csvautobooktabular}{\oarg{options}\marg{file name}}
+  |\csvautotabular| is an abbreviation for the application of the option key
+  \refKey{/csv/autobooktabular} together with other \meta{options} to \refCom{csvloop}.
+  This macro reads the whole CSV file denoted by \meta{file name}
+  with an automated formatting.
+  For application, the package |booktabs| is required which has to be
+  loaded in the preamble.
+\begin{dispExample}
+\csvautobooktabular{grade.csv}
+\end{dispExample}
+\end{docCommand}
+
+
+\begin{docCommand}{csvautobooklongtable}{\oarg{options}\marg{file name}}
+  |csvautobooklongtable| is an abbreviation for the application of the option key
+  \refKey{/csv/autobooklongtable} together with other \meta{options} to \refCom{csvloop}.
+  This macro reads the whole CSV file denoted by \meta{file name}
+  with an automated formatting.
+  For application, the packages |booktabs| and |longtable| are required which have to be
+  loaded in the preamble.
+\begin{dispListing}
+\csvautobooklongtable{grade.csv}
+\end{dispListing}
+\csvautobooklongtable{grade.csv}
+\end{docCommand}
+
+
 
 \clearpage
 
@@ -500,6 +551,7 @@ The |\csvifoddrow| macro may be used for striped tables:
   {\thecsvrow & \givenname~\name & \matriculation & \grade}%
 \end{dispExample}
 
+\enlargethispage*{1cm}
 Alternatively, |\rowcolors| from the |xcolor| package can be used for this
 purpose:
 
@@ -566,7 +618,7 @@ purpose:
 
 \begin{docCommand}{csvlinetotablerow}{}
   Typesets the current processed data line with |&| between the entries.
-  Most users will never apply this command.
+  %Most users will never apply this command.
 \end{docCommand}
 
 
@@ -684,7 +736,7 @@ see section \ref{subsec:tabsupport} from page
 
 \subsection{Header Processing and Column Name Assignment}%
 
-\begin{docCsvKey}{head}{\colOpt{=\meta{boolean value}}}{default |true|, initially |true|}
+\begin{docCsvKey}{head}{\colOpt{=true\textbar false}}{default |true|, initially |true|}
   If this key is set, the first line of the CSV file is treated as a header
   line which can be used for column name assignments.
 \end{docCsvKey}
@@ -693,6 +745,9 @@ see section \ref{subsec:tabsupport} from page
 \begin{docCsvKey}{no head}{}{no value}
   Abbreviation for |head=false|, i.\,e. the first line of the CSV file is
   treated as data line.
+  Note that this option cannot be used in combination with
+  \refCom{csvautotabular}, \refKey{/csv/autotabular}, and similar automated commands/options.
+  See Section~\ref{noheader} on page~\pageref{noheader} for assistance.
 \end{docCsvKey}
 
 \begin{docCsvKey}{column names}{=\meta{assignments}}{no default, initially empty}
@@ -706,7 +761,7 @@ see section \ref{subsec:tabsupport} from page
 \end{docCsvKey}
 
 
-\begin{docCsvKey}{head to column names}{\colOpt{=\meta{boolean value}}}{default |true|, initially |false|}
+\begin{docCsvKey}{head to column names}{\colOpt{=true\textbar false}}{default |true|, initially |false|}
   If this key is set, the entries of the header line are used automatically
   as macro names for the columns. This option can be used only, if
   the header entries do not contain spaces and special characters to be
@@ -717,7 +772,7 @@ see section \ref{subsec:tabsupport} from page
 \clearpage
 \subsection{Consistency Check and Filtering}%
 
-\begin{docCsvKey}{check column count}{\colOpt{=\meta{boolean value}}}{default |true|, initially |true|}
+\begin{docCsvKey}{check column count}{\colOpt{=true\textbar false}}{default |true|, initially |true|}
   This key defines, if the number of entries in a data line is checked against
   an expected value.\\
   If |true|, every non consistent line is ignored without announcement.\\
@@ -860,36 +915,111 @@ Additionally, the commands defined by the key values of
 \end{docCsvKey}
 
 
+\begin{docCsvKey}{autobooktabular}{=\meta{file name}}{no default}
+  Reads the whole CSV file denoted \meta{file name} with an automated formatting
+  using the required |booktabs| package.
+\end{docCsvKey}
+
+
+\begin{docCsvKey}{autobooklongtable}{=\meta{file name}}{no default}
+  Reads the whole CSV file denoted \meta{file name} with an automated formatting
+  using the required |booktabs| and |longtable| packages.
+\end{docCsvKey}
+
+
 \clearpage
-\subsection{Miscellaneous}%
+\subsection{Special Characters}\label{subsec:specchar}
+Be default, the CSV content is treated like normal \LaTeX\ text, see
+Subsection~\ref{macrocodexample} on page~\pageref{macrocodexample}.
+But, \TeX\ special characters of the CSV content may also be interpreted
+as normal characters, if one or more of the following options are used.
+
+\begin{docCsvKey}{respect tab}{\colOpt{=true\textbar false}}{default |true|, initially |false|}
+  If this key is set, every
+  tabulator sign
+  inside the CSV content is a normal character.
+\end{docCsvKey}
 
-\begin{docCsvKey}{every csv}{}{style, initially empty}
-  A style definition which is used for every following CSV file.
-  This definition can be overwritten with user code.
-\begin{dispListing}
-% Sets a warning message for unfeasible data lines.
-\csvset{every csv/.style={warn on column count error}}
-% Alternatively:
-\csvstyle{every csv}{warn on column count error}
-\end{dispListing}
+\begin{docCsvKey}{respect percent}{\colOpt{=true\textbar false}}{default |true|, initially |false|}
+  If this key is set, every
+  percent sign \verbbox{\%}
+  inside the CSV content is a normal character.
 \end{docCsvKey}
 
-\begin{docCsvKey}{default}{}{style}
-  A style definition which is used for every following CSV file which
-  resets all settings to default values\footnote{\texttt{default} is used
-  because of the global nature of most settings.}.
-  This key should not be used or changed by the user if there is not a
-  really good reason (and you know what you do).
+\begin{docCsvKey}{respect sharp}{\colOpt{=true\textbar false}}{default |true|, initially |false|}
+  If this key is set, every
+  sharp sign \verbbox{\#}
+  inside the CSV content is a normal character.
+\end{docCsvKey}
+
+\begin{docCsvKey}{respect dollar}{\colOpt{=true\textbar false}}{default |true|, initially |false|}
+  If this key is set, every
+  dollar sign \verbbox{\$}
+  inside the CSV content is a normal character.
+\end{docCsvKey}
+
+\begin{docCsvKey}{respect and}{\colOpt{=true\textbar false}}{default |true|, initially |false|}
+  If this key is set, every
+  and sign \verbbox{\&}
+  inside the CSV content is a normal character.
+\end{docCsvKey}
+
+\begin{docCsvKey}{respect backslash}{\colOpt{=true\textbar false}}{default |true|, initially |false|}
+  If this key is set, every
+  backslash sign \verbbox{\textbackslash}
+  inside the CSV content is a normal character.
 \end{docCsvKey}
 
+\begin{docCsvKey}{respect underscore}{\colOpt{=true\textbar false}}{default |true|, initially |false|}
+  If this key is set, every
+  underscore sign \verbbox{\_}
+  inside the CSV content is a normal character.
+\end{docCsvKey}
+
+\begin{docCsvKey}{respect tilde}{\colOpt{=true\textbar false}}{default |true|, initially |false|}
+  If this key is set, every
+  tilde sign \verbbox{\textasciitilde}
+  inside the CSV content is a normal character.
+\end{docCsvKey}
+
+\begin{docCsvKey}{respect circumflex}{\colOpt{=true\textbar false}}{default |true|, initially |false|}
+  If this key is set, every
+  circumflex sign \verbbox{\textasciicircum}
+  inside the CSV content is a normal character.
+\end{docCsvKey}
+
+\begin{docCsvKey}{respect leftbrace}{\colOpt{=true\textbar false}}{default |true|, initially |false|}
+  If this key is set, every
+  left brace sign \verbbox{\textbraceleft}
+  inside the CSV content is a normal character.
+\end{docCsvKey}
 
+\begin{docCsvKey}{respect rightbrace}{\colOpt{=true\textbar false}}{default |true|, initially |false|}
+  If this key is set, every
+  right brace sign \verbbox{\textbraceright}
+  inside the CSV content is a normal character.
+\end{docCsvKey}
+
+\begin{docCsvKey}{respect all}{}{style, no value, initially unset}
+  Set all special characters from above to normal characters. This means
+  a quite verbatim interpretation of the CSV content.
+\end{docCsvKey}
+
+\begin{docCsvKey}{respect none}{}{style, no value, initially set}
+  Do not change any special character from above to normal character.
+\end{docCsvKey}
+
+\clearpage
+\subsection{Separators}%
 \begin{docCsvKey}{separator}{=\meta{sign}}{no default, initially |comma|}
   \catcode `|=12
   Sets the \meta{sign} which is treates as separator between the data values
   of a data line. Feasible values are:
   \begin{itemize}
-  \item\texttt{comma}: This is the initial value with '\texttt{,}' as separator.
-  \item\texttt{semicolon}: Sets the separator to '\texttt{;}'.
+  \item\docValue{comma}: This is the initial value with '\texttt{,}' as separator.
+  \medskip
+
+  \item\docValue{semicolon}: Sets the separator to '\texttt{;}'.
 \begin{dispExample}
 % \usepackage{tcolorbox} for tcbverbatimwrite
 \begin{tcbverbatimwrite}{testsemi.csv}
@@ -899,10 +1029,11 @@ Additionally, the commands defined by the key values of
   Wei\ss{}b\"{a}ck;Werner;34567;m;5.0
 \end{tcbverbatimwrite}
 
-\csvautotabular[separator=semicolon]{testsemi.csv}
+\csvautobooktabular[separator=semicolon]{testsemi.csv}
 \end{dispExample}
+\medskip
 
-  \item\texttt{pipe}: Sets the separator to '\texttt{|}'.
+\item\docValue{pipe}: Sets the separator to '\texttt{|}'.
 \begin{dispExample}
 % \usepackage{tcolorbox} for tcbverbatimwrite
 \begin{tcbverbatimwrite}{pipe.csv}
@@ -912,18 +1043,44 @@ Additionally, the commands defined by the key values of
   Wei\ss{}b\"{a}ck|Werner|34567|m|5.0
 \end{tcbverbatimwrite}
 
-\csvautotabular[separator=pipe]{pipe.csv}
+\csvautobooktabular[separator=pipe]{pipe.csv}
 \end{dispExample}
+\medskip
+
+\item\docValue{tab}: Sets the separator to the tabulator sign.
+  Automatically, \refKey{/csv/respect tab} is set also.
   \end{itemize}
 \end{docCsvKey}
 
 \clearpage
+\subsection{Miscellaneous}%
+
+\begin{docCsvKey}{every csv}{}{style, initially empty}
+  A style definition which is used for every following CSV file.
+  This definition can be overwritten with user code.
+\begin{dispListing}
+% Sets a warning message for unfeasible data lines.
+\csvset{every csv/.style={warn on column count error}}
+% Alternatively:
+\csvstyle{every csv}{warn on column count error}
+\end{dispListing}
+\end{docCsvKey}
+
+\begin{docCsvKey}{default}{}{style}
+  A style definition which is used for every following CSV file which
+  resets all settings to default values\footnote{\texttt{default} is used
+  because of the global nature of most settings.}.
+  This key should not be used or changed by the user if there is not a
+  really good reason (and you know what you do).
+\end{docCsvKey}
+
+
 \begin{docCsvKey}{file}{=\meta{file name}}{no default, initially |unknown.csv|}
   Sets the \meta{file name} of the CSV file to be processed.
 \end{docCsvKey}
 
 
-\begin{docCsvKey}{preprocessed file}{=\meta{file name}}{no default, initially unused}
+\begin{docCsvKey}{preprocessed file}{=\meta{file name}}{no default, initially \texttt{\textbackslash\detokenize{jobname_sorted.csv}}}
   Sets the \meta{file name} of the CSV file which is the output of a
   preprocessor.
 \end{docCsvKey}
@@ -951,6 +1108,8 @@ Additionally, the commands defined by the key values of
   % do something
 }
 \end{dispListing}
+See Subsection~\ref{sec:Sorting} on page~\pageref{sec:Sorting} for a
+concrete sorting preprocessing implemented with an external tool.
 \end{docCsvKey}
 
 
@@ -961,6 +1120,173 @@ Additionally, the commands defined by the key values of
 
 
 \clearpage
+\subsection{Sorting}\label{sec:Sorting}%
+\TeX/\LaTeX\ was not born under a sorting planet. |csvsimple| provides no
+sorting of data lines by \LaTeX-methods since sorting can be done much faster
+and much better by external tools.
+
+First, one should consider the appropriate \emph{place} for sorting:
+\begin{itemize}
+\item CSV files may be sorted by a tool \emph{before} the \LaTeX\ document is processed
+  at all. If the CSV data is not likely to change, this is the most efficient method.
+\item CSV files may be sorted by a tool every time before the \LaTeX\ document is compiled.
+  This could be automated by a shell script or some processing tool like |arara|.
+\item CSV files may be sorted on-the-fly by a tool during compilation of
+  a \LaTeX\ document. This is the most elegant but not the most efficient way.
+\end{itemize}
+
+The first two methods are decoupled from anything concerning |csvsimple|.
+For the third method, the \refKey{/csv/preprocessor} option is made for.
+This allows to access an external tool for sorting.
+\emph{Which tool} is your choice.
+
+\csvsorter\footnote{\url{http://T-F-S.github.io/csvsorter/}\quad or\quad
+  \url{https://github.com/T-F-S/csvsorter}} \cite{sturm:2014j}
+was written as a companion tool for |csvsimple|.
+It is an open source Java command-line tool for sorting CSV files.  It can be
+used for all three sorting approaches described above.
+There is special support for on-the-fly sorting with \csvsorter\ using the
+following options.
+
+\begin{enumerate}\bfseries
+\item To use the sorting options, you have to install \csvsorter\ \cite{sturm:2014j} before!
+\item You have to give permission to call external tools during
+  compilation, i.\,e.\ the command-line options for |latex| have to include
+  |-shell-escape|.
+\end{enumerate}
+
+\bigskip
+
+\begin{docCsvKey}{csvsorter command}{=\meta{system command}}{no default, initially |csvsorter|}
+  The \meta{system command} specifies the system call for \csvsorter\ (without the options).
+  If \csvsorter\ was completely installed following its documentation, there is
+  nothing to change here. If the |csvsorter.jar| file is inside the same
+  directory as the \LaTeX\ source file, you may configure:% preferrably inside the preamble:
+  \begin{dispListing}
+  \csvset{csvsorter command=java -jar csvsorter.jar}
+  \end{dispListing}
+\end{docCsvKey}
+
+\begin{docCsvKey}{csvsorter configpath}{=\meta{path}}{no default, initially |.|}
+  Sorting with \csvsorter\ is done using XML configuration files. If these files
+  are not stored inside the same directory as the \LaTeX\ source file, a
+  \meta{path} to access them can be configured:
+  \begin{dispListing}
+  \csvset{csvsorter configpath=xmlfiles}
+  \end{dispListing}
+  Here, the configuration files would be stored in a subdirectory named |xmlfiles|.
+\end{docCsvKey}
+
+\begin{docCsvKey}{csvsorter log}{=\meta{file name}}{no default, initially |csvsorter.log|}
+  Sets the log file of \csvsorter\ to the given \meta{file name}.
+  \begin{dispListing}
+  \csvset{csvsorter log=outdir/csvsorter.log}
+  \end{dispListing}
+  Here, the log file is written to a subdirectory named |outdir|.
+\end{docCsvKey}
+
+
+\clearpage
+\begin{docCsvKey}{sort by}{=\meta{file name}}{style, initially unset}
+  The \meta{file name} denotes an XML configuration file for \csvsorter.
+  Setting this option inside \refCom{csvreader} or
+  \refCom{csvloop} will issue a system call to \csvsorter.
+  \begin{itemize}
+  \item \csvsorter\ uses the given CSV file as input file.
+  \item \csvsorter\ uses \meta{file name} as configuration file.
+  \item The output CSV file is denoted by \refKey{/csv/preprocessed file}
+     which is by default \texttt{\textbackslash\detokenize{jobname_sorted.csv}}.
+     This output file is this actual file processed by \refCom{csvreader} or \refCom{csvloop}.
+  \item \csvsorter\ also generates a log file denoted by \refKey{/csv/csvsorter log} which is by default |csvsorter.log|.
+  \end{itemize}
+
+\par\medskip\textbf{First example:}
+  To sort our example |grade.csv| file according to |name| and |givenname|, we
+  use the following XML configuration file. Since \csvsorter\ uses double quotes
+  as default brackets for column values, we remove bracket recognition to avoid
+  a clash with the escaped umlauts of the example CSV file.\par\smallskip
+
+\xmllisting{namesort}
+\begin{dispExample}
+% \usepackage{booktabs}
+\csvreader[sort by=namesort.xml,
+  head to column names,
+  tabular=>{\color{red}}lllll,
+  table head=\toprule Name & Given Name & Matriculation & Gender & Grade\\\midrule,
+  late after line=\\,
+  late after last line=\\\bottomrule]
+  {grade.csv}{}{\csvlinetotablerow}
+\end{dispExample}
+
+\clearpage\textbf{Second example:}
+  To sort our example |grade.csv| file according to |grade|, we
+  use the following XML configuration file. Further, persons with the same |grade|
+  are sorted by |name| and |givenname|. Since \csvsorter\ uses double quotes
+  as default brackets for column values, we remove bracket recognition to avoid
+  a clash with the escaped umlauts of the example CSV file.\par\smallskip
+
+\xmllisting{gradesort}
+\begin{dispExample}
+% \usepackage{booktabs}
+\csvreader[sort by=gradesort.xml,
+  head to column names,
+  tabular=llll>{\color{red}}l,
+  table head=\toprule Name & Given Name & Matriculation & Gender & Grade\\\midrule,
+  late after line=\\,
+  late after last line=\\\bottomrule]
+  {grade.csv}{}{\csvlinetotablerow}
+\end{dispExample}
+
+\clearpage\textbf{Third example:}
+  To generate a matriculation/grade list, we sort our example |grade.csv| file
+  using the following XML configuration file.
+  Again, since \csvsorter\ uses double quotes
+  as default brackets for column values, we remove bracket recognition to avoid
+  a clash with the escaped umlauts of the example CSV file.\par\smallskip
+
+\xmllisting{matriculationsort}
+\begin{dispExample}
+% \usepackage{booktabs}
+\csvreader[sort by=matriculationsort.xml,
+  head to column names,
+  tabular=>{\color{red}}ll,
+  table head=\toprule Matriculation & Grade\\\midrule,
+  late after line=\\,
+  late after last line=\\\bottomrule]
+  {grade.csv}{}{\matriculation & \grade}
+\end{dispExample}
+\end{docCsvKey}
+
+
+\clearpage
+\begin{docCsvKey}{new sorting rule}{=\marg{name}\marg{file name}}{style, initially unset}
+This is a convenience option to generate a new shortcut for often used
+\refKey{/csv/sort by} applications. It also adds a more semantic touch.
+The new shortcut option is
+\tcbox[on line,size=small,colback=white,colframe=red]{|sort by| \meta{name}} which expands to
+\tcbox[on line,size=small,colback=white,colframe=red]{|sort by=|\marg{file name}}.\par\medskip
+
+Consider the following example:
+\begin{dispExample}
+\csvautotabular[sort by=namesort.xml]{grade.csv}
+\end{dispExample}
+A good place for setting up a new sorting rule would be inside the preamble:
+
+\csvset{new sorting rule={name}{namesort.xml}}
+\begin{dispListing}
+\csvset{new sorting rule={name}{namesort.xml}}
+\end{dispListing}
+
+Now, we can use the new rule:
+\begin{dispExample}
+\csvautotabular[sort by name]{grade.csv}
+\end{dispExample}
+
+\end{docCsvKey}
+
+
+
+\clearpage
 \section{Examples}%
 
 \subsection{A Serial Letter}%
@@ -1035,10 +1361,11 @@ Hessen,B,2100
 \csvlisting{data}
 
 Firstly, we survey the file content using
-|\csvautotabular|.
+|\csvautobooktabular|.
 
 \begin{dispExample}
-\csvautotabular{data.csv}
+% needs the booktabs package
+\csvautobooktabular{data.csv}
 \end{dispExample}
 
 The amount values are presented in the following diagram by bars where
@@ -1057,6 +1384,33 @@ the group classification is given using different colors.
 \end{tikzpicture}
 \end{dispExample}
 
+
+\clearpage
+It would be nice to sort the bars by length, i.\,e.\ to sort the CSV file
+by the |amount| column. If the \csvsorter\ program is properly installed,
+see Subsection~\ref{sec:Sorting} on page~\pageref{sec:Sorting},
+this can be done with the following configuration file for \csvsorter:
+
+\xmllisting{amountsort}
+
+Now, we just have to add an option |sort by=amountsort.xml|:
+\begin{dispExample}
+% This example requires the package tikz
+% Also, the CSV-Sorter tool has to be installed
+\begin{tikzpicture}[Group/A/.style={left color=red!10,right color=red!20},
+                    Group/B/.style={left color=blue!10,right color=blue!20}]
+\csvreader[head to column names,sort by=amountsort.xml]{data.csv}{}{%
+  \begin{scope}[yshift=-\thecsvrow cm]
+  \path [draw,Group/\group] (0,-0.45)
+    rectangle node[font=\bfseries] {\amount} (\amount/1000,0.45);
+  \node[left] at (0,0) {\land};
+  \end{scope}  }
+\end{tikzpicture}
+\end{dispExample}
+
+
+
+
 \clearpage
 Next, we create a pie chart by calling |\csvreader| twice.
 In the first step, the total sum of amounts is computed, and in the second
@@ -1127,7 +1481,7 @@ Every item is piled upon the appropriate stack.
 
 
 \clearpage
-\subsection{Macro code inside the data}%
+\subsection{Macro code inside the data}\label{macrocodexample}%
 
 If needed, the data file may contain macro code. Note that the first character
 of a data line is not allowed to be the backslash '|\|'.
@@ -1144,10 +1498,10 @@ M,\textbf{Another} formula,        $\displaystyle \lim\limits_{n\to\infty} \frac
 \csvlisting{macrodata}
 
 Firstly, we survey the file content using
-|\csvautotabular|.
+|\csvautobooktabular|.
 
 \begin{dispExample}
-\csvautotabular{macrodata.csv}
+\csvautobooktabular{macrodata.csv}
 \end{dispExample}
 
 
@@ -1165,17 +1519,131 @@ Now, formulas only:
 \end{dispExample}
 
 
+
+\clearpage
+\subsection{CSV data without header line}\label{noheader}%
+CSV files with a header line are more semantic than files without header,
+but it's no problem to work with headless files.
+
+For this example, we use again some artificial statistical data given by a CSV file
+but this time without header.
+
+%-- file embedded for simplicity --
+\begin{tcbverbatimwrite}{data_headless.csv}
+Bayern,A,1700
+Baden-W\"{u}rttemberg,A,2300
+Sachsen,B,1520
+Th\"{u}ringen,A,1900
+Hessen,B,2100
+\end{tcbverbatimwrite}
+%-- end embedded file --
+
+\csvlisting{data_headless}
+
+Note that you cannot use the \refKey{/csv/no head} option for the auto tabular
+commands. If no options are given, the first line is interpreted as header line
+which gives an unpleasant result:
+
+\begin{dispExample}
+\csvautobooktabular{data_headless.csv}
+\end{dispExample}
+
+To get the expected result, one can redefine \refKey{/csv/table head}
+using \refCom{csvlinetotablerow} which holds the first line data for the
+|\csvauto...| commands:
+
+\begin{dispExample}
+\csvautobooktabular[table head=\toprule\csvlinetotablerow\\]{data_headless.csv}
+\end{dispExample}
+
+This example can be extended to insert a table head for this headless data:
+
+\begin{dispExample}
+\csvautobooktabular[table head=\toprule\bfseries Land & \bfseries Group
+  & \bfseries Amount\\\midrule\csvlinetotablerow\\]{data_headless.csv}
+\end{dispExample}
+
+\clearpage
+
+For the normal \refCom{csvreader} command, the \refKey{/csv/no head} option
+should be applied. Of course, we cannot use \refKey{/csv/head to column names}
+because there is no head, but the columns can be addressed by their numbers:
+
+\begin{dispExample}
+\csvreader[no head,
+  tabular=lr,
+  table head=\toprule\bfseries Land & \bfseries Amount\\\midrule,
+  late after line=\\,
+  late after last line=\\\bottomrule]
+  {data_headless.csv}
+  {1=\land,3=\amount}
+  {\land & \amount}
+\end{dispExample}
+
+
+\clearpage
+\subsection{Imported CSV data}\label{importeddata}%
+If data is important from other applications, there is not always a choice
+to format in comma separated values with curly brackets.
+
+Consider the following example data file:
+
+%-- file embedded for simplicity --
+\begin{tcbverbatimwrite}{imported.csv}
+"name";"address";"email"
+"Frank Smith";"Yellow Road 123, Brimblsby";"frank.smith@organization.org"
+"Mary May";"Blue Alley 2a, London";"mmay@maybe.uk"
+"Hans Meier";"Hauptstrasse 32, Berlin";"hans.meier@corporation.de"
+\end{tcbverbatimwrite}
+%-- end embedded file --
+
+\csvlisting{imported}
+
+If the \csvsorter\ program is properly installed,
+see Subsection~\ref{sec:Sorting} on page~\pageref{sec:Sorting},
+this can be transformed on-the-fly
+with the following configuration file for \csvsorter:
+
+\xmllisting{transform}
+
+Now, we just have to add an option |sort by=transform.xml| to transform
+the input data. Here, we actually do not sort.
+
+\begin{dispExample}
+% \usepackage{booktabs,array}
+% Also, the CSV-Sorter tool has to be installed
+\newcommand{\Header}[1]{\normalfont\bfseries #1}
+
+\csvreader[
+  sort by=transform.xml,
+  tabular=>{\itshape}ll>{\ttfamily}l,
+  table head=\toprule\Header{Name} & \Header{Address} & \Header{email}\\\midrule,
+  late after line=\\,
+  late after last line=\\\bottomrule]
+  {imported.csv}{}{\csvlinetotablerow}
+\end{dispExample}
+
+The file which is generated on-the-fly and which is actually read by
+|csvsimple| is the following:
+
+\tcbinputlisting{docexample,listing style=tcbdocumentation,fonttitle=\bfseries,
+  listing only,listing file=\jobname_sorted._csv}
+
+
+\clearpage
+
 % Actually, it is not a good idea to include the references like this!
 % Do not follow this bad example ...
 \begin{tcbverbatimwrite}{\jobname.bib}
-@manual{tantau:2010c,
+@manual{tantau:2013a,
    author    = {Till Tantau},
    title     = {The TikZ and PGF Packages},
-   subtitle  = {Manual for version 2.10},
-   url       = {http://mirror.ctan.org/graphics/pgf/base/doc/generic/pgf/pgfmanual.pdf},
-   date      = {2010-10-25},
+   subtitle  = {Manual for version 3.0.0},
+   url       = {http://sourceforge.net/projects/pgf/},
+   date      = {2013-12-20},
 }
 
+
 @manual{carlisle:2001b,
    author    = {David Carlisle},
    title     = {The ifthen package},
@@ -1187,12 +1655,38 @@ Now, formulas only:
    language  = {english}
 }
 
-@manual{talbot:2012a,
+@manual{talbot:2014a,
   author    = {Nicola L. C. Talbot},
-  title     = {datatool v 2.11: Databases and data manipulation},
+  title     = {User Manual for the datatool bundle version 2.20},
   url       = {http://mirror.ctan.org/macros/latex/contrib/datatool/datatool.pdf},
-  date      = {2012-09-25},
+  date      = {2014-02-03},
+}
+
+@manual{sturm:2014j,
+   author      = {Thomas F. Sturm},
+   title       = {The CSV-Sorter program},
+   subtitle    = {Manual for version 0.91 beta},
+   url         = {http://T-F-S.github.io/csvsorter/csvsorter.pdf},
+   date        = {2014-07-05},
+   language    = {english}
+}
+
+@manual{carlisle:2004a,
+   author    = {David Carlisle},
+   title     = {The longtable package},
+   url       = {http://mirror.ctan.org/macros/latex/required/tools/longtable.pdf},
+   date      = {2004-02-01},
+   language  = {english}
 }
+
+@manual{fear:2005a,
+   author    = {Simon Fear},
+   title     = {Publication quality tables in \LaTeX},
+   url       = {http://mirror.ctan.org/macros/latex/contrib/booktabs/booktabs.pdf},
+   date      = {2005-04-15},
+   language  = {english}
+}
+
 \end{tcbverbatimwrite}
 
 
diff --git a/Master/texmf-dist/doc/latex/csvsimple/gradesort.xml b/Master/texmf-dist/doc/latex/csvsimple/gradesort.xml
new file mode 100644
index 00000000000..32c2741735c
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/csvsimple/gradesort.xml
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<csv>
+  <bracket empty="true" />
+  <sortlines>
+    <column name="grade" order="ascending" type="double"/>
+    <column name="name" order="ascending" type="string"/>
+    <column name="givenname" order="ascending" type="string"/>
+  </sortlines>
+</csv>
diff --git a/Master/texmf-dist/doc/latex/csvsimple/matriculationsort.xml b/Master/texmf-dist/doc/latex/csvsimple/matriculationsort.xml
new file mode 100644
index 00000000000..be19e9e760b
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/csvsimple/matriculationsort.xml
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<csv>
+  <bracket empty="true" />
+  <sortlines>
+    <column name="matriculation" order="ascending" type="integer"/>
+  </sortlines>
+</csv>
diff --git a/Master/texmf-dist/doc/latex/csvsimple/namesort.xml b/Master/texmf-dist/doc/latex/csvsimple/namesort.xml
new file mode 100644
index 00000000000..6c17bd4d2a2
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/csvsimple/namesort.xml
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<csv>
+  <bracket empty="true" />
+  <sortlines>
+    <column name="name" order="ascending" type="string"/>
+    <column name="givenname" order="ascending" type="string"/>
+  </sortlines>
+</csv>
diff --git a/Master/texmf-dist/doc/latex/csvsimple/transform.xml b/Master/texmf-dist/doc/latex/csvsimple/transform.xml
new file mode 100644
index 00000000000..4111c31b53e
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/csvsimple/transform.xml
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<csv>
+  <bracket leftsymbol="doublequote" rightsymbol="doublequote" />
+  <delimiter signsymbol="semicolon" />
+  <outBracket leftsymbol="braceleft" rightsymbol="braceright" />
+  <outDelimiter signsymbol="comma" />
+</csv>