%% LaTeX package xcntperchap - version 0.2 (2016/06/07 -- 09/05/23)
%% Documentation file for xcntperchap.sty
%%
%%
%% -------------------------------------------------------------------------------------------
%% Copyright (c) 2016 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`
%%
%%

\documentclass[12pt,a4paper]{article}




\usepackage[lmargin=2cm,rmargin=2cm,headheight=15pt]{geometry}
\usepackage{savesym}
\usepackage{bbding}
\savesymbol{Cross}

\usepackage{blindtext}
\usepackage[x11names]{xcolor}
\usepackage{imakeidx}
\usepackage{fontawesome}
\usepackage[most,documentation]{tcolorbox}
\usepackage[tikz]{bclogo}
\usepackage{marginnote}
\usepackage{fancyhdr}
\usepackage{datetime}
\usepackage{array}
\usepackage{xkeyval}
\usepackage{xparse}
\usepackage{totcount}
\usepackage{enumitem}
\usepackage{microtype}
\usepackage{caption}
\usepackage[T1]{fontenc}
\usepackage[scaled=0.92]{helvet}

\newlist{codeoptionsenum}{enumerate}{1}
\setlist[codeoptionsenum,1]{label={\textcolor{blue}{\#\arabic*}}}

\renewcommand{\rmdefault}{\sfdefault}

\newcolumntype{C}[1]{>{\centering\arraybackslash}p{#1}}

\makeatletter
\define@key{chdoc}{packageauthor}{%
  \def\KVchdocpackageauthor{#1}%
}

\define@key{chdoc}{packageauthormail}{%
  \def\KVchdocpackageauthormail{#1}%
}

\define@key{chdoc}{filepurpose}{%
  \def\KVchdocfilepurpose{#1}%
}


\newcommand{\chdocextractversion}[1]{%
  \@nameuse{#1}%
}


\@namedef{xcntperchapversion0.1}{v0.1 2016-05-22}
\@namedef{xcntperchapversion0.2}{v0.2 2016-06-07}


\makeatother






\fancypagestyle{plain}{%
\fancyfoot[L]{\begin{tabular}[t]{l}\PackageDocName\ \packageversion \tabularnewline \textcopyright\ Dr. Christian Hupfer\end{tabular}}%
\fancyfoot[C]{\thepage}%
\fancyfoot[R]{\today}%
\renewcommand{\headrule}{{\color{blue}%
\hrule width\headwidth height\headrulewidth \vskip-\headrulewidth}}
\renewcommand{\footrule}{{\color{blue}\vskip-\footruleskip\vskip-\footrulewidth
\hrule width\headwidth height\footrulewidth\vskip\footruleskip}}
\renewcommand{\footrulewidth}{2pt}
\renewcommand{\headrulewidth}{2pt}
}



\newtcolorbox{CHPackageTitleBox}[1][]{%
  enhanced jigsaw,
  drop lifted shadow,
  colback=yellow!30!white,
  width=0.8\textwidth,
  #1
}


\presetkeys{chdoc}{packageauthor={Christian Hupfer}}{}%
\NewDocumentCommand{\CHPackageTitlePage}{O{}mO{}}{%
  \setkeys{chdoc}{packageauthor={Christian Hupfer},filepurpose={Documentation},#1}%
  \begin{center}
    \begin{CHPackageTitleBox}[#3]
      \large \bfseries%
      \begin{center}%
        \begin{tabular}{C{0.9\textwidth}}%
          \scshape \PackageDocName \tabularnewline
          \tabularnewline
          #2 \tabularnewline
          \tabularnewline
          \KVchdocfilepurpose \tabularnewline
          \tabularnewline
          Version \packageversion \tabularnewline
          \tabularnewline
          \today \tabularnewline
          \tabularnewline
          \addtocounter{footnote}{2}
          Author: \KVchdocpackageauthor\(^\mathrm{\fnsymbol{footnote}}\)
          \tabularnewline
        \end{tabular}
      \end{center}
    \end{CHPackageTitleBox}
    \renewcommand{\thefootnote}{\fnsymbol{footnote}}%
    \footnotetext{\mymailtoaddress}%
  \end{center}
}

\newtcolorbox{docCommandArgs}[1]{colbacktitle={blue},coltitle={white},title={Description of arguments of command \cs{#1}}}


\newcommand{\tcolorboxdoclink}{http://mirrors.ctan.org/macros/latex/contrib/tcolorbox/tcolorbox.pdf}

% 'Stolen' from tcolorbox documentation ;-)

\newtcolorbox{marker}[1][]{enhanced,
  before skip=2mm,after skip=3mm,
  boxrule=0.4pt,left=5mm,right=2mm,top=1mm,bottom=1mm,
  colback=yellow!50,
  colframe=yellow!20!black,
  sharp corners,rounded corners=southeast,arc is angular,arc=3mm,
  underlay={%
    \path[fill=tcbcol@back!80!black] ([yshift=3mm]interior.south east)--++(-0.4,-0.1)--++(0.1,-0.2);
    \path[draw=tcbcol@frame,shorten <=-0.05mm,shorten >=-0.05mm] ([yshift=3mm]interior.south east)--++(-0.4,-0.1)--++(0.1,-0.2);
    \path[fill=yellow!50!black,draw=none] (interior.south west) rectangle node[white]{\Huge\bfseries !} ([xshift=4mm]interior.north west);
    },
    drop fuzzy shadow,#1}


%%%% Documentation macros


\NewDocumentCommand{\packagename}{sm}{%
  \textcolor{blue}{\textbf{\faEnvelopeO~#2}}%
  \IfBooleanF{#1}{%
    \index{Package!#2}
  }%
}

\NewDocumentCommand{\classname}{sm}{%
  \textcolor{brown}{\textbf{\faBriefcase~#2}}%
  \IfBooleanF{#1}{%
    \index{Package!#2}%
  }%
}


\NewDocumentCommand{\CHDocPackage}{sm}{%
  \textcolor{blue}{\textbf{\faEnvelopeO~#2}}%
  \IfBooleanF{#1}{%
    \index{Package!#2}
  }%
}




\NewDocumentCommand{\CHDocClass}{sm}{%
  \textcolor{brown}{\textbf{\faBriefcase~#2}}%
  \IfBooleanF{#1}{%
    \index{Package!#2}%
  }%
}

\NewDocumentCommand{\CHDocKey}{sm}{%
  \textcolor{red}{\textbf{\faKey~#2}}%
  \IfBooleanF{#1}{%
      \index{Option!#2}%
  }%
}

\newcommand{\handrightnote}{\tcbdocmarginnote{\ding{43}}}


\NewDocumentCommand{\CHDocCounter}{sm}{%
  \textcolor{Green4}{\textbf{\faCalculator~#2}}%
  \IfBooleanF{#1}{%
    \index{Counter!#2}%
  }%	
}


\NewDocumentCommand{\CHDocTag}{sm}{%
  \textcolor{violet}{\faTag~#2}%
  \IfBooleanF{#1}{%
    \index{Feature!#2}%
  }%	
}


\NewDocumentCommand{\CHDocFileExt}{sm}{%
    \faFile~#2%
}

\NewDocumentCommand{\CHDocFiles}{sm}{%
    \faFilesO~#2%
}


\NewDocumentCommand{\CHDocConventions}{}{%
  \section*{\centering Typographical conventions}
  Throughout this documentation following symbols and conventions are used:
  \begin{itemize}
  \item \CHDocClass*{foo} means a the class \texttt{foo}
  \item \CHDocPackage*{foo} names a package \texttt{foo}
  \item \CHDocCounter*{foo} indicates a counter named \texttt{foo}
  \item \CHDocFileExt*{foo} will indicate either a file named \texttt{foo} or a file extension \texttt{foo}
  \item \CHDocFiles*{foo} will indicate some files 
  \item \CHDocTag*{foo} names a special feature or tag \texttt{foo}
  \item \CHDocKey*{foo} deals with a command or package option named \texttt{foo}
  \end{itemize}
}

\usepackage{xcntperchap}


\newcommand{\PackageDocName}{xcntperchap}%



\newcommand{\mymailtoaddress}{%
  christian.hupfer@yahoo.de
}


\def\packageversion{\xcntperchappackageversion}%

\makeindex[intoc]

\RegisterCounters{section}{subsection,subsubsection,table,figure}

\hypersetup{breaklinks=true}



\hypersetup{breaklinks=true,
  pdftitle={\jobname.pdf -- version \packageversion},
  pdfauthor={PACKAGEAUTHOR},
  pdfsubject={Documentation of \PackageDocName\ package},
  pdfkeywords={LaTeX, counters},
  pdfcreator={LaTeX}
}


\begin{document}
\mmddyyyydate


\setlength{\parindent}{0pt}

\thispagestyle{empty}%
\CHPackageTitlePage[packageauthor={Christian Hupfer}]{Store counter values per chapter (or other track levels)}
\clearpage
\tableofcontents
\clearpage

\CHDocConventions
\clearpage

\pagestyle{plain}

\setcounter{footnote}{0}

\pagestyle{plain}



\section{Disclaimer}
This package as of its version \packageversion\ is a rewrite of the former \CHDocPackage{cntperchap} by the same author, is under constant development and as such subject to macro interface changes as well as renaming of macros. Not all features of the previous package has been incorporated so far -- if some functionality of your document depends on \CHDocPackage{assoccnt}, continue using the older version and shift gradually to \CHDocPackage{\PackageDocName} please.

\begin{marker}
Most times class and package authors will benefit of this package, but there might be usual documents that need the features of |\PackageDocName||
\end{marker}

\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 predefined track level, for example per chapters. The values are stored at the beginning of such a new track level, say \cs{chapter} and written to a \CHDocFileExt{jobname.cpc} file.

\begin{marker}
  Since the \CHDocCounter*{page} counter is an unrealiable 'friend' it is not advised to use this counter as a track level. 
\end{marker}


As of version \packageversion\ there is no default version of a track level.

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}. 



\section{Package options}%
\label{section::package_options}

As of version \packageversion~ the package has no package options.


\section{Requirements and incompatibilities}%

\subsection{Required packages}

Since \CHDocPackage{\PackageDocName} is written using \CHDocPackage{expl3}, it requires the \CHDocPackage{xparse} package. It relies on the features of associated counters introduced by \CHDocPackage{xassoccnt}, this package is also needed%

\begin{itemize}
\item \CHDocPackage{expl3}%
\item \CHDocPackage{xparse}%
\item \CHDocPackage{xassoccnt}%
\end{itemize}

The package \CHDocPackage{xparse} is already loaded by \CHDocPackage{assoccnt} and does not need to be specified again. 

\subsection{Incompatibilities}

This package has been tested with the standard classes \classname{article}, \classname{book} and \classname{report} as well as with \classname{memoir} and the relevant \classname{KOMA} equivalents. As of version \packageversion\ for those classes there are no known incompatibilities with the general behaviour of the package, however, there is an issue with \CHDocPackage{assoccnt} and \CHDocPackage{xifthen} which is not solved so far. 

\marginnote{\bcbombe} It would be nice to adapt the package for usage on a per frame base with the \classname{beamer} class, but this seems both not really necessary as well as quite difficult, since \classname{beamer} follows different strategies about the usage of ``pages'' or ``sections'', see \ref{section::todo}


\clearpage


\section{Documentation of Macros}

\subsection{Preamble only commands}

\begin{docCommand}{RegisterCounters}{\marg{track counter}\marg{counter1, counter2,...}} \tcbdocmarginnote{\tcbdocnew{\chdocextractversion{xcntperchapversion0.1}}}

This provides the means to let the package know that the counters should be tracked for values inside a certain track level -- specify this in the document preamble.

\begin{docCommandArgs}{RegisterCounters}%
  \begin{itemize}
  \item \marg{track counter}
    This contains the counter name which is the track level, e.g. \CHDocCounter*{section}
  \item \marg{counter1, counter2,...}
    This marks the counters to be tracked inside the track level, e.g. \CHDocCounter*{subsection}, \CHDocCounter*{subsubsection}
\end{itemize}
\end{docCommandArgs}

\end{docCommand}%


\section{User commands}


\begin{docCommand}{ObtainTrackedValue}{\oarg{counter value}\marg{track level}\marg{tracked counter}} \tcbdocmarginnote{\tcbdocnew{\chdocextractversion{xcntperchapversion0.1}}}

This command prints the value of the tracked counter of a track counter, i.e. the number of subsections in a specific chapter, say, the 5th chapter can be obtained by

\begin{dispExample}{listings only}
  \ObtainTrackedValue[5]{chapter}{subsection}
\end{dispExample}

\begin{codeoptionsenum}
  \item \oarg{options}: As of version \packageversion, the only option is a counter value, say 5 for the 5th chapter. This must be the total number of the relevant track counter, i.e. the 17th total section etc. 
  \item \marg{track counter name}: The name of the track level, i.e. \CHDocCounter*{section}. 
  \item \marg{tracked counter name}: The name of the tracked counter, i.e. \CHDocCounter*{figure}. 
\end{codeoptionsenum}

Please note that the number of entities per track level might be reported wrongly for floats, since those are shifted to some other places. If this should be prevented, a \cs{FloatBarrier} from \CHDocPackage{placeins} might be necessary (see the example file \verb!xcntperchap_driver.tex!)

\begin{marker}\tcbdocmarginnote{\tcbdocupdated{\chdocextractversion{xcntperchapversion0.2}}}
  This macro is not expandable -- for an expandable version use \refCom{ObtainTrackedValueExp} instead.
\end{marker}

\end{docCommand}
\clearpage

\begin{docCommand}{ObtainTrackedValueExp}{\oarg{counter value}\marg{track level}\marg{tracked counter}} \tcbdocmarginnote{\tcbdocnew{\chdocextractversion{xcntperchapversion0.2}}}

This command is the expandable version of \refCom{ObtainTrackedValue} and should be used if are calculations, comparisions and write - operations to files are requested.

The meaning of arguments is the same as in \refCom{ObtainTrackedValue}. 
\end{docCommand}

\section{Examples}

\subsection[Item count of enumerate]{Count the items of an enumerate}


\tcbset{breakable}
\begin{dispListing}
\documentclass{article}

\usepackage{xcntperchap}
\usepackage{enumitem}



\RegisterCounters{section}{enumi}
\RegisterCounters{subsection}{enumi}

\begin{document}
\tableofcontents

\section{Section 1 -- with \ObtainTrackedValueExp{section}{enumi} items}
    \begin{enumerate}[resume]
        \item Item 1
        \item Item 2
        \item Item 3
    \end{enumerate}

\subsection{Another subsection with \ObtainTrackedValueExp{subsection}{enumi} }

\begin{enumerate}[resume]
\item Item 4
\item Item 5
\end{enumerate}


\section{Section 2 -- with \ObtainTrackedValueExp{section}{enumi} items}
\begin{enumerate}[resume]
\item Item 6
\item Item 7
\end{enumerate}

\subsection{Another subsection with \ObtainTrackedValueExp[2]{subsection}{enumi} Items } % Second total subsection to be used. 

\begin{enumerate}[resume]
\item Item 8
\item Item 9
\item Item 10
\item Item 11
\item Item 12
\item Item 13
\end{enumerate}

\end{document}
\end{dispListing}


\clearpage

\section{To-Do list}\label{section::todo}

\begin{itemize}
\item Better error handling (no checks for many features so far).
\item More options for fine control of the behaviour package and macros.
\item Easy - adaption for other documentclasses, especially for \classname{beamer}
\item Improve documentation
\item More examples
\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 tex.stackexchange.com, especially to

\begin{itemize}
  \item Paulo Roberto Massa Cereda
  \item Enrico Gregorio
  \item Joseph Wright
  \item David Carlisle
  \item Werner Grundlingh
  \item Gonzalo Medina
\end{itemize}

for their invaluable help on many questions on macros.

\vspace{2\baselineskip}
\begin{marker}
A special gratitude goes to Prof. Dr. Dr. Thomas Sturm for providing the wonderful \CHDocPackage{tcolorbox} package which was used to
write this documentation.
\end{marker}


\section{Version history}

\begin{itemize}
\item 
Version \chdocextractversion{xcntperchapversion0.2} \tcbdocmarginnote{\tcbdocnew{\chdocextractversion{xcntperchapversion0.2}}}
\begin{itemize}
\item Added the expandable version of \cs{ObtainTrackedValues} 
\item Removed the bug concerning the missing reset of the associated counters
\end{itemize}

\item 
Version \chdocextractversion{xcntperchapversion0.1} \tcbdocmarginnote{\tcbdocnew{\chdocextractversion{xcntperchapversion0.1}}}

Bootstrap version, rewrite of previous \CHDocPackage{cntperchap} with LaTeX - 3 - Kernel features

\end{itemize}




\clearpage
\printindex



\end{document}

