summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/cntperchap/cntperchap_doc.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2015-05-11 21:07:46 +0000
committerKarl Berry <karl@freefriends.org>2015-05-11 21:07:46 +0000
commit40dd5938ded99176abd37cee3b6271722fe30f24 (patch)
tree32fc861b8b9d82adc01046752124645bf06a617c /Master/texmf-dist/doc/latex/cntperchap/cntperchap_doc.tex
parentab4dd52002d9e6cb47a9f2906192bf65d5af6cc1 (diff)
cntperchap (10may15)
git-svn-id: svn://tug.org/texlive/trunk@37338 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/cntperchap/cntperchap_doc.tex')
-rw-r--r--Master/texmf-dist/doc/latex/cntperchap/cntperchap_doc.tex220
1 files changed, 169 insertions, 51 deletions
diff --git a/Master/texmf-dist/doc/latex/cntperchap/cntperchap_doc.tex b/Master/texmf-dist/doc/latex/cntperchap/cntperchap_doc.tex
index f71eaed4059..d361b412caf 100644
--- a/Master/texmf-dist/doc/latex/cntperchap/cntperchap_doc.tex
+++ b/Master/texmf-dist/doc/latex/cntperchap/cntperchap_doc.tex
@@ -1,6 +1,6 @@
%% Documentation for cntperchap.sty
%%
-%% Version 0.1 (2015/05/04}
+%% Version 0.2 (2015/05/09}
%%
%%
%% -------------------------------------------------------------------------------------------
@@ -15,15 +15,15 @@
%% 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 has the LPPL maintenance status `maintained'.
%%
%% This work consists of all files listed in README
%%
-\documentclass[12pt,english]{book}
+\documentclass[12pt,english]{ltxdoc}
\usepackage{scrlayer-scrpage}
-\usepackage[lmargin=2cm,rmargin=2cm,a4paper]{geometry}
+\usepackage[lmargin=3cm,rmargin=3cm,a4paper]{geometry}
\usepackage{savesym}%
\usepackage{bbding}%
\savesymbol{Cross}%
@@ -37,39 +37,33 @@
\usepackage[most]{tcolorbox}
\usepackage{cntperchap}
-\RegisterCountersPerChapter{page,section,subsection,subsubsection,table,figure}
+\RegisterCounters{page,section,subsection,subsubsection,table,figure}
\tcbuselibrary{documentation}
+\tcbset{color command={blue}}
-\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{\tcolorboxdoclink}{http://mirrors.ctan.org/macros/latex/contrib/tcolorbox/tcolorbox.pdf}
+\newcommand{\packagename}[1]{\fbox{\textcolor{blue}{\textbf{\ding{41}~#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}}}%
-}%
+\newcommand{\handrightnote}{\tcbdocmarginnote{\ding{43}}}
\newtcolorbox{docCommandArgs}[1]{colbacktitle={blue},coltitle={white},title={Description of arguments of command \cs{#1}}}
-\def\packageversion{0.1}%
+\def\packageversion{0.2}%
\makeindex
-\newcommand{\PackageDocName}{cntperchap.sty}%
+\newcommand{\PackageDocName}{\cpspackagename.sty}%
\hypersetup{breaklinks=true}
@@ -90,6 +84,7 @@
\textsc{\PackageDocName} \tabularnewline
\tabularnewline
Store counter values per chapter \tabularnewline
+(or other section levels) \tabularnewline
\tabularnewline
Version \packageversion \tabularnewline
\tabularnewline
@@ -120,56 +115,84 @@ Author: Christian Hupfer\(^\mathrm{\fnsymbol{footnote}}\)
\setcounter{footnote}{0}
-\chapter{Documentation}
-
+\section{Disclaimer}
+This package as of its version \packageversion\ is under constant development and as such subject to macro interface changes as well as renaming of macros.
\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.
+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 section level, for example per chapters. 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. The section level can be one of standard levels
+\begin{itemize}
+ \item \cs{part}
+ \item \cs{chapter}
+ \item \cs{section}
+ \item \cs{subsection}
+ \item \cs{subsubsection}
+ \item \cs{paragraph}
+ \item \cs{subparagraph}
+\end{itemize}
+
+The section level can be specified as an option (see \ref{section::package_options}), but is preconfigured on the underlying document class. For \classname{book}-like classes, the section level defaults to \cs{chapter}, for \classname{article}-like documentclasses it defaults to \cs{section}.
+
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
+\ShowStatistics[1]
\end{tcolorbox}
\subsection{Basic usage}
+\tcbdocmarginnote{\ding{43}} If \refAuxcs{nofiles} is used, no package related files are generated or included, similar to the behaviour for \refAuxcs{tableofcontents} etc.
+
\begin{tcblisting}{listing only}
\documentclass{book}
-\usepackage{cntpersec}
+\usepackage{cntperchap}
-\RegisterCountersPerChapter{page,section,subsection,subsubsection,table,%
- figure}
+\RegisterCounters{page,section,subsection,subsubsection,table,figure}
\begin{document}
-\chapter{First}
-\ShowStatistics
\section{First section}
-
+\ShowStatistics
\end{document}
\end{tcblisting}
\section{Package options}%
+\label{section::package_options}
-\newcommand{\mk}[1]{%
-}
+As of version \packageversion~ the package has only following options so far:
-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}
+
+\item \begin{docKey}{autodefine}{}{}
+ This option enables the automatic counter definition if some undefined counter is specified during the registration process.
+ \end{docKey}
+
+\item \begin{docKey}{draft}{}{default is draft}
This option enables the explicit statistics
\end{docKey}
-\item \begin{docKey}{final}{\meta{}}{default is off}
+\item \begin{docKey}{final}{}{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.
+ \item \begin{docKey}{noendclose}{}{default is false}
+ This option prevents the explicit closing of output files and provides the means to enter a hook into the \cs{AfterEndDocument} command.
+ \end{docKey}
+
+
+\item \begin{docKey}{tracklevel}{\meta{=chapter}}{chapter}
+ This option sets the sectioning level under supervision (tracked). If not specified, the counters are stored on a per chapter base, if set to \texttt{section}, the counter values are stored on a per section level etc. The section level has to be specified without the blackslash $\backslash$.
+
+Unknown section levels will lead to a compilation error.
+ \end{docKey}
+
+
+\item \begin{docKey}{verbose}{}{}
+ This option enables verbose output during compilation.
\end{docKey}
+
\end{itemize}
\section{Requirements and incompatibilities}%
@@ -185,26 +208,30 @@ As of version \packageversion~ the package has only the \oarg{draft,final,autode
\item \packagename{xparse}%
\end{itemize}
-The packages \packagename{etoolbox} and \packagename{xkeyval} are already loaded by \packagename{assocnt}.
+The packages \packagename{etoolbox} and \packagename{xkeyval} are already loaded by \packagename{assoccnt}.
\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.
+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 \packagename{assoccnt} and \packagename{xifthen} which is not solved so far.
+
+It would be nice to adapt the package for usage on a per frame base with the \classname{beamer} class, see \ref{section::todo}
+
+
+%This package will 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} and the relevant \classname{KOMA} equivalents.
\section{Documentation of Macros}
-\tcbset{color command={blue}}
\subsection{Preamble only commands}
-\begin{docCommand}{RegisterCounterPerChapter}{\oarg{options}\marg{counter}}
+\begin{docCommand}{RegisterCounter}{\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{docCommandArgs}{RegisterCounter}%
\begin{enumerate}[label={\textcolor{blue}{\#\arabic*}}]
\item \oarg{options}:
@@ -220,11 +247,11 @@ This provides the means to let the package know that a counter should be tracked
\end{docCommand}%
-\begin{docCommand}{RegisterCountersPerChapter}{\marg{counter1,counter2,...}}
+\begin{docCommand}{RegisterCounters}{\marg{counter1,counter2,...}}
-This macro allows for specification of a CSV list of counter names -- internally this will call \refCom{RegisterCounterPerChapter}
+This macro allows for specification of a CSV list of counter names -- internally this will call \refCom{RegisterCounter}
-\begin{docCommandArgs}{RegisterCountersPerChapter}%
+\begin{docCommandArgs}{RegisterCounters}%
\begin{itemize}
\item \marg{counter1,counter2,...}
\end{itemize}
@@ -233,7 +260,22 @@ This macro allows for specification of a CSV list of counter names -- internally
\end{docCommand}
-Please note, that both \refCom{RegisterCounterPerChapter} and \refCom{RegisterCountersPerChapter} can be used only in the preamble of a document.
+\handrightnote Please note, that both \refCom{RegisterCounter} and \refCom{RegisterCounters} can be used only in the preamble of a document.
+
+\handrightnote It is safe to use \refCom{RegisterCounters} with just one counter name.
+
+\begin{docCommand}{PrepareTocCommand}{\marg{toc command}}
+This command disables the usage of the automatic counter storage for ToC - like macros (\cs{tableofcontents},\cs{listoffigures},\cs{listoftables}, since those use \cs{chapter*} and confuse the tracking counter thereby.
+
+\begin{docCommandArgs}{PrepareTocCommand}
+ \marg{toc command} This is intented to be a command such as \cs{tableofcontents} etc., but it could be any command actually.
+\end{docCommandArgs}
+
+Please use this command with care!
+
+By default, \cs{tableofcontents},\cs{listoffigures},\cs{listoftables} and \cs{printindex} are used with this feature.
+\tcbdocmarginnote{\tcbdocnew{2015-05-08}}
+\end{docCommand}
\subsection{User macros}
@@ -268,7 +310,7 @@ This returns the total value of the counter (specified as 2nd argument) per chap
\begin{docCommand}{ShowStatistics}{\oarg{chapter number}}
-This returns the all total values of the counters registered by \refCom{RegisterCounterPerChapter} or \refCom{RegisterCountersPerChapter} per chapter.
+This returns the all total values of the counters registered by \refCom{RegisterCounter} or \refCom{RegisterCounters} per chapter.
\begin{docCommandArgs}{ShowStatistics}
\begin{itemize}
\item \oarg{chapter number}
@@ -282,12 +324,76 @@ Both \refCom{ShowStatistics} and \refCom{IndividualCounterStatistics} are define
\end{docCommand}
-\begin{docCommand}{StoreCountersPerChapter}{}
+\begin{docCommand}{Fullstatistics}{}
+\tcbdocmarginnote{\tcbdocnew{2015-05-07}}
+ This will show an overview of all registered counters throughout the document (unless storage was locally disabled).
+\end{docCommand}
+
+\begin{tcblisting}{}
+\Fullstatistics
+\end{tcblisting}
+
+
+
+\begin{docCommand}{StoreCounters}{}
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.
+%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.
+\textit{Remark: This command was named \cs{StoreCountersPerChapter} in previous versions}
+\end{docCommand}
+
+\begin{docCommand}{StopCounting}{}
+
+This macro stores all registrated counter values to the file.
+
+This command is automatically called at the end of the document, but can be used before too. It is useful, if there is some \cs{printindex} etc. at the end and only one chapter. In this case, the finalizing storage would not be done automatically.
+
+% 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}
+
+\begin{docCommand}{RestoreCounter}{\marg{counter}}
+This macro restores the counter \marg{counter} to zero.
+
+\handrightnote It is not necessary to use this macro directly in almost any case.
+\end{docCommand}
+
+
+\begin{docCommand}{RestoreCounters}{}
+This macro restores all registrated counters to zero. This happens every time if a new driving section level is used.
+\end{docCommand}
+
+\section{Informational macros}
+
+\begin{docCommand}{numberofstoredcounters}{}
+This macro just returns the number of registered counters. It will not return the internal counter name which holds the number.
+\end{docCommand}
+
+\section{Conditionals}
+
+The package knows some conditionals:
+
+\begin{docCommand}{ifcpsstorage}{}
+\tcbdocmarginnote{\tcbdocnew{2015-05-08}}
+ This status variable enables or disables the storage of counters per chapter (section,$\ldots$). It is a classical \TeX\ \cs{newif} statement and can be set to true by saying \cs{cpsstoragetrue} or false \cs{cpsstorefalse}. However, there are two small macros to wrap this enabling or disabling into to more memorable names: \refCom{EnableCPSStorage} and \refCom{DisableCPSStorage}.
+
+\end{docCommand}
+
+\begin{docCommand}{EnableCPSStorage}{}
+Enables the storage of counters per chapter (etc.)
+\tcbdocmarginnote{\tcbdocnew{2015-05-08}}
+\end{docCommand}
+
+\begin{docCommand}{DisableCPSStorage}{}
+Enables the storage of counters per chapter (etc.)
+\tcbdocmarginnote{\tcbdocnew{2015-05-08}}
+\end{docCommand}
+
+\begin{docCommand}{ifcpsdraftmode}{}
+ This is a classical \TeX\ conditional defined by \cs{newif}. It can be used to enable draft mode locally by saying \cs{cpsdraftmodetrue} and disable in return using \cs{cpsdraftmodefalse}.
+\tcbdocmarginnote{\tcbdocnew{2015-05-03}}
\end{docCommand}
@@ -296,14 +402,15 @@ This command is automatically called before a new chapter starts and at the end
\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}
+\section{To-Do list}\label{section::todo}
\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 Easy - adaption for other documentclasses, especially for \classname{beamer}
\item Improve documentation
+
\end{itemize}
If you
@@ -330,12 +437,13 @@ to the users at \url{tex.stackexchange.com}, especially to
\item David Carlisle
\item Paulo Roberto Massa Cereda
\item Werner Doe (;-))
+ \item Johannes B\"ottcher (for some remarks/checking on KOMA related issues)
\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
+A special gratitude goes to Prof. Dr. Dr. Thomas Sturm for providing the wonderful \packagename{tcolorbox} package which was used to
write this documentation.
\clearpage
@@ -343,6 +451,17 @@ write this documentation.
\section{Version history}
\begin{itemize}
+\item 0.2:
+ \begin{itemize}
+ \item Introduced the possibility to disable the storage temporarily
+ \item Fixed a severe bug concerning the file handle generation
+ \item Added support for `tracklevel=option`, allowing for arbitray section levels as watch
+ \item Renamed some macros which had `Chapter` in name
+ \item Added a check if the relevant section level sequence exists at all
+ \item Added a total counter for the section level and limited the `\cs{GetTotalCounters}` max value
+ \item Fixed typos in documentation
+ \end{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
@@ -350,8 +469,7 @@ write this documentation.
\end{itemize}
\clearpage
-\StoreCountersPerChapter
-%\chapter{Dummy}
+\StopCounting
%%%% Index of commands