xassoccnt (26jan15)

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

7 files changed, 173 insertions, 16 deletions

diff --git a/Master/texmf-dist/doc/latex/xassoccnt/README b/Master/texmf-dist/doc/latex/xassoccnt/README
index ef3c189c836..be977393375 100644
--- a/Master/texmf-dist/doc/latex/xassoccnt/README
+++ b/Master/texmf-dist/doc/latex/xassoccnt/README
@@ -1,4 +1,4 @@
-%% LaTeX package xassoccnt - version 0.3 (2016/01/08 -- 10/54/13)
+%% LaTeX package xassoccnt - version 0.4 (2016/01/26 -- 10/46/26)
 %% README file for xassoccnt.sty
 %%
 %%
@@ -26,7 +26,7 @@ the associated counters as well. This package can be regarded as a supplement
 to the totcount package by Vasileios Koutavas (http://www.ctan.org/pkg/totcount), but
 can be used without it too.
 
-As of 2016/01/08 xassoccnt does not supersede the package assoccnt by the same author, however, 
-the older package isn't declared obsolete as of 2016/01/08
+As of 2016/01/26 xassoccnt does not supersede the package assoccnt by the same author, however, 
+the older package isn't declared obsolete as of 2016/01/26
 
 
diff --git a/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_doc.pdf b/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_doc.pdf
index 5b1de0a2cb8..927a086cb3a 100644
--- a/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_doc.pdf
+++ b/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_doc.pdf
diff --git a/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_doc.tex b/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_doc.tex
index 88476486033..ec06144523f 100644
--- a/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_doc.tex
+++ b/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_doc.tex
@@ -1,4 +1,4 @@
-%% LaTeX package xassoccnt - version 0.3 (2016/01/08 -- 10/54/13)
+%% LaTeX package xassoccnt - version 0.4 (2016/01/26 -- 10/46/26)
 %% Documentation file for xassoccnt.sty
 %%
 %%
@@ -42,8 +42,9 @@
 \usepackage{xkeyval}
 \usepackage{xparse}
 \usepackage{totcount}
-\usepackage{enumitem}%
+\usepackage{enumitem}
 \usepackage{microtype}
+\usepackage{caption}
 \usepackage[scaled=0.92]{helvet}
 
 \newlist{codeoptionsenum}{enumerate}{1}
@@ -260,6 +261,9 @@
 \newtotcounter{totalsubsections}%
 \newtotcounter{othertotalsubsections}%
 
+\DeclareDocumentCounter{foocntr}%
+\DeclareDocumentCounter{foobarcntr}%
+
 
 %%%% Declare all the counters here -- 
 \DeclareAssociatedCounters{subsection}{totalsubsections}%
@@ -342,7 +346,7 @@ Please note, that this package does not provide means for simultaneous stepping
 
 \subsection{Required packages and \TeX\ engine}
 
-The package does not require features from Xe\LaTeX\ or Lua\LaTeX but can be run with those features as well as with \LaTeX\ or pdf\LaTeX. The compilation documentation requires however pdf\LaTeX as of version \packageversion. 
+The package does not require features from Xe\LaTeX\ or Lua\LaTeX\ but can be run with those features as well as with \LaTeX\ or pdf\LaTeX. The compilation documentation requires however pdf\LaTeX as of version \packageversion. 
 
 \begin{itemize}
 \item \CHDocPackage{xcolor}  
@@ -350,7 +354,7 @@ The package does not require features from Xe\LaTeX\ or Lua\LaTeX but can be run
 \item \CHDocPackage{l3keys2e}
 \end{itemize}
 
-The documentation file requires some more packages such as \CHDocPackage{tcolorbox} but those packages are available on CTAN, MikTeX and TeXLive as well and are basically widely available. 
+The documentation file requires some more packages such as \CHDocPackage{tcolorbox} but those packages are widely available on CTAN, MikTeX and TeXLive as well.
 
 \subsection{Loading of the package}
 
@@ -427,7 +431,7 @@ The main purpose of this package is co-stepping of counters, but there are some
 
 \subsection[Association macros]{Associated counters commands}\label{subsection::associatedcounterscmds}
 
-All macros have the general rule, that the driver counter is specified as 1st mandatory argument to the macro, which is in almost case the 2nd argument of the macro
+All macros have the general rule, that the driver counter is specified as 1st mandatory argument to the macro, which is in almost all cases the 2nd argument of the macro.
 
 
 \begin{docCommand}{DeclareAssociatedCounters}{\oarg{options}\marg{driver counter}\marg{associated counters list}}
@@ -947,9 +951,9 @@ If a driver counter is suspended, all counters associated to it are suspended to
 E_{0} = mc^2
 \end{equation}
 
-Now suspend the totalequations:
+Now suspend the equations:
 
-\SuspendCounters{totalequations}
+\SuspendCounters{equation}
 \begin{equation}
 E^2 = \left({ pc}\right)^2 + E^{2}_{0}
 \end{equation}
@@ -958,7 +962,7 @@ E^2 = \left({ pc}\right)^2 + E^{2}_{0}
   m(v) = \frac{m_{0}}{\sqrt{1-\frac{v^2}{c^2}}} 
 \end{equation}
 
-And resume it: \ResumeSuspendedCounters{totalequations}
+And resume it: \ResumeSuspendedCounters{equation}
 
 \begin{equation}
   E = h \nu
@@ -966,7 +970,6 @@ And resume it: \ResumeSuspendedCounters{totalequations}
 
 There are \number\totvalue{totalequations}~equations in here!
 
-%\end{document}
 \end{dispExample}
 
 
@@ -1024,7 +1027,41 @@ Some notes on \refCom{SetDocumentCounter}
     \item The option keys \refKey{associatedtoo} and \refKey{onlycounters} are mutually exclusive! %
     \item The counter to be set can be either a driver counter or an otherwise associated counter. 
 \end{itemize}
+\end{docCommand}%
+
+\begin{docCommand}{StepDownCounter}{\oarg{options}\marg{counter}}\tcbdocmarginnote{\tcbdocnew{2016-01-11}}
 
+This macro subtracts the value of 1 from the counter and is the counterpart of \cs{stepcounter}. 
+
+\begin{docCommandArgs}{StepDownCounter}%
+
+
+\begin{codeoptionsenum}
+  \item \oarg{options}: As of version \packageversion, this option is not used% the key value argument
+  \item \marg{counter} 
+    Holds the name of the first counter.
+  \end{codeoptionsenum}
+\end{docCommandArgs}
+
+\end{docCommand}%
+
+
+\begin{docCommand}{SubtractFromCounter}{\oarg{options}\marg{counter}\marg{delta value}}\tcbdocmarginnote{\tcbdocnew{2016-01-11}}
+
+This macro subtracts the (positive) delta value from the counter and is the counterpart of \cs{addtocounter}
+
+\begin{docCommandArgs}{SubtractFromCounter}%
+
+
+\begin{codeoptionsenum}
+  \item \oarg{options}: As of version \packageversion, this option is not used% the key value argument
+
+  \item \marg{counter 1} 
+    Holds the name of the first counter.
+  \item \marg{delta value}
+    Holds the (positive) value to be subtracted from the counter value. 
+  \end{codeoptionsenum}
+\end{docCommandArgs}
 
 \end{docCommand}%
 
@@ -1086,6 +1123,35 @@ This document synchronizes the driver counter value to the associated values. It
 
 \end{docCommand}%
 
+\begin{dispExample}{breakable=true}
+  \SetDocumentCounter{foocntr}{17}
+  \SetDocumentCounter{foobarcntr}{20}
+
+\begin{itemize}
+\item Displaying counters
+
+  \thefoocntr\ and \thefoobarcntr
+\item Swapping counters
+
+  \SwapDocumentCounters{foocntr}{foobarcntr}
+
+  \thefoocntr\ and \thefoobarcntr
+
+\item Step down counters
+
+\StepDownCounter{foocntr}
+\StepDownCounter{foobarcntr}
+
+  \thefoocntr\ and \thefoobarcntr
+
+\item Subtracting some value from the counters
+  \SubtractFromCounter{foocntr}{5}
+  \SubtractFromCounter{foobarcntr}{10}
+
+  \thefoocntr\ and \thefoobarcntr
+\end{itemize}
+\end{dispExample}
+
 \section{Total counters}\tcbdocmarginnote{\tcbdocnew{2015-11-27}}
 
 Similarly to the package \CHDocPackage{totcount} or the features of \CHDocPackage{totalcount} by Axel Sommerfeldt this package provides the possibility of defining a counter that stores its finally value to the auxiliary file and starts from this value then, if not set otherwise to another value. 
@@ -1103,7 +1169,7 @@ The declaration of a total counter is a preamble - only event and \refCom{NewTot
 
 
 \begin{docCommand}{TotalCounterInternalName}{\marg{counter name}}
-This command reports the internal name of a total counter or the usual name if this counter is a total one. 
+This command reports the internal name of a total counter or the usual name if this counter is not a total one. 
 \end{docCommand}
 
 \begin{dispExample}
@@ -1202,6 +1268,74 @@ This macro checks if a counter is under the administration of the super total co
 This package adds a counter of its own: \CHDocCounter{numberofruns} which is a super total counter and is stepped each compilation run. It's added in \cs{AtBeginDocument} and can be retrieved with \refCom{TotalValue}. 
 
 
+\section{Backup and restore of counter values}\tcbdocmarginnote{\tcbdocnew{2016-01-16}}
+
+It might be necessary to interrupt the current sectioning, e.g. including another document's structure (an external paper, for example) such that the counting should start again and after finishing of the external structure the old values should be restored.  
+
+\begin{docCommand}{BackupCounterValues}{\oarg{options}\marg{counter name1, counter name2,...}}
+This macro adds counter names (separated by a comma) to a list and stores the current values of the counters to another list. The values are used from the current state where this command is used, not a previous or a later state is stored. 
+
+All counters in the list will be reset to zero (after storing the values) for the next usage, unless the \refKey{resetbackup} key is set to \meta{false}.
+
+
+\begin{docKey}[][]{resetbackup}{=\meta{true/false}}{initially true}
+This key decides whether \textbf{all} counters in the backup list should be reset to zero or should keep the current value. The default value is \meta{true}.
+\end{docKey}
+
+\begin{marker}
+If a specific counter name is suffixed with an \textasteriskcentered\ at its end the resetting is disabled for this particular counter, regardless whether \refKey{resetbackup} is set to true or not.\tcbdocmarginnote{\tcbdocnew{2016-01-24}}
+\end{marker}
+
+
+Please note: If a name does not belong to a counter register the compilation aborts with an error message!
+\end{docCommand}%
+
+
+
+\begin{docCommand}{RestoreCounterValues}{\oarg{options}}
+This macro restores the stored counter values corresponding to the counter names. Afterwards the internal backup lists are cleared. 
+
+As of version \packageversion\ the optional argument isn't reserved for later purposes. 
+
+The backup list is cleared after the restoring has been finished. 
+\end{docCommand}
+
+\begin{dispExample}
+
+  \captionof{figure}{A dummy figure}
+
+  \captionof{table}{A dummy table}
+
+
+\BackupCounterValues{figure,table*}
+
+  \captionof{figure}{Another dummy figure}
+
+  \captionof{table}{Another dummy table}
+
+  \captionof{figure}{Even another dummy figure}
+
+  \captionof{table}{Even another dummy table}
+
+Before restoring: \thefigure\ and \thetable
+
+\RestoreCounterValues
+
+Restored the values: \thefigure\ and \thetable
+
+\captionof{figure}{Yet another dummy figure}
+\captionof{table}{Yet another dummy table}
+
+
+\end{dispExample}
+
+
+\subsection*{Some notes on the backup features}
+
+Principally backing up counter values and restoring them later on is not really difficult -- with one exception: If the \packagename{hyperref} package is used, the counter values form up the hypertarget anchors, for example \texttt{chapter.1} for the first chapter. If the chapter counter is reset, there would be a chapter with number one again and as well an anchor name \texttt{chapter.1} -- \packagename{hyperref} will complain 'only' about this but it will put the wrong hyperlink as well, for example for the table of contents and the bookmarks -- this is an undesirable feature.
+
+However, there is a solution to this problem: The hypertarget anchors are built up from the specifications of a macro \cs{theH...} where the ellipses stands for the counter name. If for example \cs{theHchapter} is changed after a counter was reset the hypertargets will again be correct, since this will provide a different target name. \cs{BackupCounterValues} does this resetting automatically in an unique way and \cs{RestoreCounterValues} restores as well the old \cs{theH...} macros of all counters that are in the backup list. It tracks the number of calls to \cs{BackupCounterValues} and changes the relevant \cs{theH...} macro definitions to use unique anchor names then -- this way multiple \cs{BackupCounterValues} calls are possible without destroying the hyperlink facicilities with \packagename{hyperref}. 
+
 
 \clearpage
 \section{To - Do list}
@@ -1258,6 +1392,12 @@ write this documentation.
 \section{Version history}
 
 \begin{itemize}
+\item
+Version 0.4
+\begin{itemize}[label={$\checkmark$}]
+\item Added \cs{BackupCounterValues} and \cs{RestoreCounterValues} support\tcbdocmarginnote{\tcbdocnew{2016-01-16}}
+\item Added \cs{StepDownCounter} and \cs{SubtractFromCounter} macros\tcbdocmarginnote{\tcbdocnew{2016-01-11}}
+\end{itemize}
 \item 
 Version 0.3
 \begin{itemize}[label={$\checkmark$}]
diff --git a/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_driver.pdf b/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_driver.pdf
index 129e063b48f..79f867e5b2d 100644
--- a/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_driver.pdf
+++ b/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_driver.pdf
diff --git a/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_driver.tex b/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_driver.tex
index 564d1b569a6..d8faac0e3ec 100644
--- a/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_driver.tex
+++ b/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_driver.tex
@@ -1,4 +1,4 @@
-%% LaTeX package xassoccnt - version 0.3 (2016/01/08 -- 10/54/13)
+%% LaTeX package xassoccnt - version 0.4 (2016/01/26 -- 10/46/26)
 %% Driver file for xassoccnt.sty
 %%
 %%
@@ -190,7 +190,24 @@ Internal name: \TotalCounterInternalName{equations}
 \caption{table}
 \end{table}
 
-%\RemoveSuperTotalCounter{numberofruns}
+
+\BackupCounterValues{chapter,section,equation}
+
+\chapter{A new chapter}
+
+\begin{equation}
+  E=mc^2
+\end{equation}
+
+\RestoreCounterValues
+
+\chapter{Another new chapter}
+
+\begin{equation}
+  E=mc^2
+\end{equation}
+
+
 
 
 \end{document}
\ No newline at end of file
diff --git a/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_example.pdf b/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_example.pdf
index 39b79bfe016..4b00bccb27e 100644
--- a/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_example.pdf
+++ b/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_example.pdf
diff --git a/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_example.tex b/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_example.tex
index f89bb7c1967..86453af56cf 100644
--- a/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_example.tex
+++ b/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_example.tex
@@ -1,4 +1,4 @@
-%% LaTeX package xassoccnt - version 0.3 (2016/01/08 -- 10/54/13)
+%% LaTeX package xassoccnt - version 0.4 (2016/01/26 -- 10/46/26)
 %% Example file for xassoccnt.sty
 %%
 %%