cntperchap (4may15)

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

1 files changed, 360 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/cntperchap/cntperchap_doc.tex b/Master/texmf-dist/doc/latex/cntperchap/cntperchap_doc.tex
new file mode 100644
index 00000000000..f71eaed4059
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/cntperchap/cntperchap_doc.tex
@@ -0,0 +1,360 @@
+%% Documentation for cntperchap.sty
+%%
+%% Version 0.1 (2015/05/04}
+%%
+%% 
+%% -------------------------------------------------------------------------------------------
+%% Copyright (c) 2015 by Dr. Christian Hupfer <christian dot hupfer at yahoo 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
+%%
+
+
+\documentclass[12pt,english]{book}
+\usepackage{scrlayer-scrpage}
+\usepackage[lmargin=2cm,rmargin=2cm,a4paper]{geometry}
+\usepackage{savesym}%
+\usepackage{bbding}%
+\savesymbol{Cross}%
+
+\usepackage{blindtext}%
+\usepackage{enumitem}%
+\usepackage{datetime}%
+\usepackage{imakeidx}%
+
+
+\usepackage[most]{tcolorbox}
+\usepackage{cntperchap}
+
+\RegisterCountersPerChapter{page,section,subsection,subsubsection,table,figure}
+
+
+\tcbuselibrary{documentation}
+
+
+
+\newcommand{\tcolorboxdoclink}{http://mirrors.ctan.org/macros/latex/contrib/tcolorbox/tcolorbox.pdf}
+
+
+
+\newcommand{\packagename}[1]{\fbox{\textcolor{blue}{\textbf{\Envelope~#1}}}\index{Package!#1}}%
+
+\newcommand{\classname}[1]{\fbox{\textcolor{brown}{\textbf{\Writinghand~#1}}}\index{Class!#1}}%
+
+
+\newcommand{\MarkupPackageName}[2][lightgray]{%
+\colorbox{#1}{\textcolor{black}{#2}}%
+}%
+
+\newcommand{\MarkupCounterName}[2][yellow]{%
+\colorbox{#1}{\textcolor{black}{\texttt{#2}}}%
+}%
+
+
+\newtcolorbox{docCommandArgs}[1]{colbacktitle={blue},coltitle={white},title={Description of arguments of command \cs{#1}}}
+
+
+\def\packageversion{0.1}%
+
+\makeindex
+
+\newcommand{\PackageDocName}{cntperchap.sty}%
+
+
+\hypersetup{breaklinks=true}
+
+\begin{document}
+\mmddyyyydate
+
+
+\setlength{\parindent}{0pt}
+
+\thispagestyle{empty}%
+
+\begin{center}
+\begin{tcolorbox}[boxrule=1mm,arc=4mm,colback=yellow!30!white,width=0.8\textwidth]
+\large \bfseries%
+\begin{center}%
+\begin{tabular}{c}%
+\textsc{\PackageDocName} \tabularnewline
+\tabularnewline
+Store counter values per chapter \tabularnewline
+\tabularnewline
+Version \packageversion \tabularnewline
+\tabularnewline
+\today \tabularnewline
+\tabularnewline
+\addtocounter{footnote}{2}
+Author: Christian Hupfer\(^\mathrm{\fnsymbol{footnote}}\)
+\tabularnewline
+\end{tabular}
+\end{center}
+\end{tcolorbox}
+\makeatletter
+\renewcommand{\thefootnote}{\fnsymbol{footnote}}%
+\footnotetext{christian.hupfer@yahoo.de}%
+\makeatother
+
+\end{center}
+
+\tableofcontents
+\clearpage
+
+
+
+
+\pagestyle{scrheadings}%
+\setheadsepline{2pt}[\color{blue}]
+
+\setcounter{footnote}{0}
+
+
+\chapter{Documentation}
+
+
+\section{Introduction}
+
+The aim of this package is to provide support for a summary in advance how many sections, subsections, etc. or figures, tables, equations there will be in a chapter. The values are stored at the beginning of a new chapter and written to \cs{jobname.cpsfoo} files, where \docCounter{foo} is short for the relevant counter name. 
+
+This package is the consequence of the question \url{http://tex.stackexchange.com/questions/241559/how-to-count-the-total-number-of-sections-within-a-chapter} by the user \texttt{gsl}. 
+
+\begin{tcolorbox}[title={Statistics of the local chapter},colbacktitle=yellow,coltitle=black]
+\ShowStatistics
+\end{tcolorbox}
+
+\subsection{Basic usage}
+
+\begin{tcblisting}{listing only}
+\documentclass{book}
+\usepackage{cntpersec}
+
+\RegisterCountersPerChapter{page,section,subsection,subsubsection,table,%
+  figure}
+
+\begin{document}
+\chapter{First}
+\ShowStatistics
+\section{First section}
+
+\end{document}
+\end{tcblisting}
+
+\section{Package options}%
+
+\newcommand{\mk}[1]{%
+}
+
+As of version \packageversion~ the package has only the \oarg{draft,final,autodefine} options so far. 
+
+\begin{itemize}
+\item   \begin{docKey}{draft}{\meta{}}{default is draft}
+    This option enables the explicit statistics
+    \end{docKey}
+\item   \begin{docKey}{final}{\meta{}}{default is off}
+    This option disables the explicit statistics
+    \end{docKey}
+
+\item   \begin{docKey}{autodefine}{\meta{}}{initially empty}
+    This option enables the automatic counter definition if some undefined counter is specified during the registration process. 
+  \end{docKey}
+
+
+\end{itemize}
+
+\section{Requirements and incompatibilities}%
+
+\subsection{Required packages}
+
+\begin{itemize}
+\item \packagename{assoccnt}%
+\item \packagename{etoolbox}%
+\item \packagename{ifthen}%
+\item \packagename{morewrites}%
+\item \packagename{xkeyval}%
+\item \packagename{xparse}%
+\end{itemize}
+
+The packages \packagename{etoolbox} and \packagename{xkeyval} are already loaded by \packagename{assocnt}. 
+
+\subsection{Incompatibilities}
+
+This package will not work so far if the document class does not provide the chapter command. It should work with the standard document classes of \classname{book} and \classname{report} as well as with \classname{memoir}, but at the moment it does not work with their \classname{KOMA} equivalents. 
+
+
+\section{Documentation of Macros}
+\tcbset{color command={blue}}
+
+\subsection{Preamble only commands}
+
+
+
+
+\begin{docCommand}{RegisterCounterPerChapter}{\oarg{options}\marg{counter}}
+
+This provides the means to let the package know that a counter should be tracked for values per chapter
+
+\begin{docCommandArgs}{RegisterCounterPerChapter}%
+
+  \begin{enumerate}[label={\textcolor{blue}{\#\arabic*}}]
+  \item \oarg{options}: 
+
+    \begin{docKey}{autodefine}{\meta{true,false}}{false}
+      This will enable the automatic definition of a counter if the name specified as 2nd mandatory argument is not identified as \LaTeX\ counter. 
+    \end{docKey}
+
+ \item \marg{counter}
+   This contains the counter name which should be tracked for counting itself.
+\end{enumerate}
+\end{docCommandArgs}
+
+\end{docCommand}%
+
+\begin{docCommand}{RegisterCountersPerChapter}{\marg{counter1,counter2,...}}
+
+This macro allows for specification of a CSV list of counter names -- internally this will call \refCom{RegisterCounterPerChapter}
+
+\begin{docCommandArgs}{RegisterCountersPerChapter}%
+\begin{itemize}
+  \item \marg{counter1,counter2,...}
+  \end{itemize}
+  This contains a comma separated list of counter names which should be tracked for counting itself.
+\end{docCommandArgs}
+
+\end{docCommand}
+
+Please note, that both \refCom{RegisterCounterPerChapter} and \refCom{RegisterCountersPerChapter} can be used only in the preamble of a document. 
+
+\subsection{User macros}
+
+\begin{docCommand}{GetTotalCounter}{\oarg{chapter number}\marg{counter}}
+This returns the total value of the counter (specified as 2nd argument) per chapter. This macro should be expandable. 
+\begin{docCommandArgs}{GetTotalCounter}%
+\begin{itemize}
+  \item \oarg{chapter number}
+    This optional argument contains the number of the chapter from which the counter value should be extracted. If this is not given, the current chapter is used. 
+  \item \marg{counter}
+    This is the name of of the counter whose per chapter value should be displayed.
+  \end{itemize}
+\end{docCommandArgs}
+
+
+
+
+\end{docCommand}
+
+\begin{docCommand}{IndividualCounterStatistics}{\oarg{chapter number}\marg{counter}}
+This returns the total value of the counter (specified as 2nd argument) per chapter. 
+\begin{docCommandArgs}{IndividualCounterStatistics}
+\begin{itemize}
+\item \oarg{chapter number}
+    This optional argument contains the number of the chapter from which the counter value should be extracted. If this is not given, the current chapter is used. 
+  \item \marg{counter}
+    This is the name of of the counter whose per chapter value should be displayed together with the counter name. 
+  \end{itemize}
+\end{docCommandArgs}
+
+\end{docCommand}
+
+
+\begin{docCommand}{ShowStatistics}{\oarg{chapter number}}
+This returns the all total values of the counters registered by \refCom{RegisterCounterPerChapter} or \refCom{RegisterCountersPerChapter} per chapter. 
+\begin{docCommandArgs}{ShowStatistics}
+\begin{itemize}
+\item \oarg{chapter number}
+    This optional argument contains the number of the chapter from which the counter value should be extracted. If this is not given, the current chapter is used. 
+  \end{itemize}
+\end{docCommandArgs}
+
+Both \refCom{ShowStatistics} and \refCom{IndividualCounterStatistics} are defined to provide nothing if \refKey{final} is given as package option. 
+
+
+\end{docCommand}
+
+
+\begin{docCommand}{StoreCountersPerChapter}{}
+
+This macro stores all registrated counter values to the file. 
+
+This command is automatically called before a new chapter starts and at the end of the document, but if there is only one chapter in file and some \cs{printindex} - like command pretty near the document end, the last counter values are not stored correctly. In this case, it's better to issue this command before \cs{printindex} manually, but not in other setups. 
+
+\end{docCommand}
+
+
+
+\clearpage
+\section{Generated files}
+
+The package uses the same approach as \LaTeX commands to write content to the table of content files. It creates \texttt{.cpsfoo} files, where \cs{foo} is the name of the relevant counter. Those files are constantly updated if the main document has been changed. It's safe to delete those files, however, the correct values appear only after the 2nd and consecutive runs. 
+\section{To-Do list}
+
+\begin{itemize}
+\item Better error handling (no checks for many features so far).
+\item Squeeze the usage of multiple files for each counter value into a more sophisticated approach.
+\item More options for fine control of the behaviour package and macros.
+\item Easy - adaption for other documentclasses.
+\item Improve documentation
+\end{itemize}
+
+If you 
+
+\begin{itemize}
+  \item find bugs
+  \item errors in the documentation
+  \item have suggestions
+  \item have feature requests
+\end{itemize}
+
+don't hesitate and contact me via \makeatletter christian.hupfer@yahoo.de\makeatother
+
+\clearpage
+
+\section{Acknowledgments}
+
+I would like to express my gratitudes to the developpers of fine \LaTeX{} packages and of course
+to the users at \url{tex.stackexchange.com}, especially to
+
+\begin{itemize}
+  \item Enrico Gregorio
+  \item Joseph Wright
+  \item David Carlisle
+  \item Paulo Roberto Massa Cereda
+  \item Werner Doe (;-))
+\end{itemize}
+
+for their invaluable help on many questions on macros.
+
+\vspace{2\baselineskip}
+A special gratitude goes to Prof. Dr. Dr. Thomas Sturm for providing the wonderful \MarkupPackageName{tcolorbox} package which was used to
+write this documentation.
+
+\clearpage
+
+\section{Version history}
+\begin{itemize}
+
+\item 0.1: Initial version, fixed errors with \cs{dolistcsloop} for getting the counter values and replaced it with \cs{forlistcsloop}
+\item 0.01: Bootstrap version
+
+
+\end{itemize}
+
+\clearpage
+\StoreCountersPerChapter
+%\chapter{Dummy}
+
+%%%% Index of commands
+
+\printindex
+
+\end{document}
\ No newline at end of file