diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_doc.tex')
| -rw-r--r-- | Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_doc.tex | 135 |
1 files changed, 113 insertions, 22 deletions
diff --git a/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_doc.tex b/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_doc.tex index 2039e39d55b..4be0f8154df 100644 --- a/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_doc.tex +++ b/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_doc.tex @@ -1,5 +1,5 @@ -%% LaTeX package xassoccnt - version 0.5 (2016/02/27 -- 19/52/22) -%% Documentation file for xassoccnt.sty +%% LaTeX package xassoccnt - version 0.6 (2016/03/05 -- 14/44/15) +%% Documentation file for xassoccnt.sty %% %% %% ------------------------------------------------------------------------------------------- @@ -284,8 +284,9 @@ } \newcommand{\versionzerofourdate}{2016-01-26} -\newcommand{\currentversiondate}{2016-02-27} -\newcommand{\versionzerofivedate}{\currentversiondate} +\newcommand{\versionzerofivedate}{2016-02-27} +\newcommand{\currentversiondate}{2016-03-05} +\newcommand{\versionzerosixdate}{\currentversiondate} \begin{document} \mmddyyyydate @@ -406,7 +407,7 @@ For potential problems see \cref{subsection:incompatibilities} \subsection{Package options}\label{subsection:packageoptions} -As of version \packageversion\ \CHDocPackage{\PackageDocName} supports the option +As of version \packageversion\ \CHDocPackage{\PackageDocName} supports the package options \begin{docKey}{autodefinecounters}{=\meta{true,false}}{initially false} Setting this package option to \texttt{true}, all counters used with the special package macros will be autodefined, unless disabled locally. See the commands @@ -416,6 +417,9 @@ As of version \packageversion\ \CHDocPackage{\PackageDocName} supports the optio \end{itemize} \end{docKey} +\begin{docKey}{nonumberofruns}{}{initially not set}\tcbdocmarginnote{\tcbdocnew{\versionzerosixdate}} + Using this package option the super total counter \CHDocCounter{numberofruns} counter will not be defined. See \cref{subsection:numberofruns} about this feature. +\end{docKey} \section{Documentation of Macros} @@ -485,10 +489,18 @@ This document has \number\totvalue{totalpages} (note: \number\totvalue{anotherto \end{dispExample} \begin{itemize} - \item Current version state: + \item Current version (\packageversion) rules: \begin{itemize} \item No checking whether the 2nd and 3rd arguments hold counter names is applied. \item Mutually cross - association of two counters is not supported! The compilation will stop on this! + \tcbdocmarginnote{\tcbdocupdated{\versionzerosixdate}} + + A driver counter, say, \CHDocCounter{foo}) of, say \CHDocCounter{foobar} can not be an associated counter of \CHDocCounter{foobar}, which in turn can be a driver counter of other counters, of course. + + A contrary feature are the \CHDocTag{coupled counters} -- If some counters should share a common base, i.e. increasing one arbitrary member counter of a group of counters then all should be increased, this called coupling of counters -- all group members are on an equal footing. See \cref{sec::coupledcounters} about this feature. + + On the other side, \CHDocTag{associated counters} belong to a hierarchy. The driver counter dominates the associated counters. + \end{itemize} \item A self-association of the driver counter to itself is ignored internally as this would lead to inconsistent counter values. \item The order of the specification of associated counters in the 2nd arguments is of no importance. @@ -1165,36 +1177,109 @@ Occasionally there are requests where the figure or table environment should use This can be achieved with the concept of coupled counters. As usual, those counters belonging to a 'group' should be declared first in the preamble. In some sense coupled counters are similar to associated counters. +\subsection[Common options for coupled counters]{Common options for most of the coupled counter macros}\label{subsection:options_coupledcounters} + +\begin{docKey}{name}{=\meta{name of a list}}{}\tcbdocmarginnote{\tcbdocnew{\versionzerosixdate}} + This option has the name of the counter group that should be coupled, say ``figuretablegroup'' etc. +\end{docKey} + +\begin{docKey}{multiple}{=\meta{true,false}}{initially false}\tcbdocmarginnote{\tcbdocnew{\versionzerosixdate}} + This option allows to add a counter multiple times to a counter group. In general, using this style is not recommended. +\end{docKey} + +\subsection[Macros for coupled counters]{Macros for declaring, adding and removing coupled counters} + + + \begin{docCommand}{DeclareCoupledCounters}{\oarg{options}\marg{counter name1, counter name2, \dots}}\tcbdocmarginnote{\tcbdocnew{\versionzerofivedate}} \begin{codeoptionsenum} - \item \oarg{options}: As of version \packageversion, this option is not used so far. - \item \marg{counter name 1, counter name2, \dots}: The list of counters that should should be stepped together. + \item \oarg{options}: See \cref{subsection:options_coupledcounters} for a explanation about available options. + \item \marg{counter name 1, counter name2, \dots}: The list of counters that should should be stepped together for the given counter group. \end{codeoptionsenum} This macro is a preamble-only command. \end{docCommand} -\begin{marker} -\begin{itemize} -\item As of version \packageversion\ only one coupled counter list is possible. -\item There is no \cs{ClearCoupledCounterList} macro yet. -\end{itemize} -\end{marker} +\begin{docCommand}{DeclareCoupledCountersGroup}{\marg{counter group name}}\tcbdocmarginnote{\tcbdocnew{\versionzerofivedate}} +This macro defines a name for a counter group and allocates a new group list for the counter names. If the name already exists, nothing is done. +\begin{codeoptionsenum} +\item \marg{counter group name}: The name of the counter group. +\end{codeoptionsenum} + +This macro is a preamble-only command and does not add counters to the group container. Use \refCom{DeclareCoupledCounters} or \refCom{AddCoupledCounters} to add counters to the relevant group. + +\end{docCommand} \begin{docCommand}{RemoveCoupledCounters}{\oarg{options}\marg{counter name1, counter name2, \dots}}\tcbdocmarginnote{\tcbdocnew{\versionzerofivedate}} -This removes the listed counter names from the coupled counter list. +This removes the comma separated counter names from the coupled counter list given in the \refKey{name} option. +\begin{codeoptionsenum} + \item \oarg{options}: As of version \packageversion{} the only recognized option is \refKey{name}. + \item \marg{counter name 1, counter name2, \dots}: The list of counters that should should removed from the given counter group. +\end{codeoptionsenum} + +\begin{marker} + \begin{itemize} + \item The list name itself is still available + \item If the list given by the \refKey{name} option does not exist, \refCom{RemoveCoupledCounters} issues a warning on the console and ignores this list then. + \end{itemize} +\end{marker} + +If all counters from a group name should be removed, this is equal to clearing -- just use \refCom{ClearCoupledCounters} for simpler usage of this feature. -The option is not used, the counter name list has the same meaning as in \refCom{DeclareCoupledCounters}. \end{docCommand} \begin{docCommand}{AddCoupledCounters}{\oarg{options}\marg{counter name1, counter name2, \dots}}\tcbdocmarginnote{\tcbdocnew{\versionzerofivedate}} +\tcbdocmarginnote{\tcbdocupdated{\versionzerosixdate}} +This adds the listed counter names to coupled counter list. It acts like \refCom{DeclareCoupledCounters}, but does not setup new counter groups. Please use \refCom{DeclareCoupledCounters} first, then apply \cs{AddCoupledCounters} later on. -This adds the listed counter names to coupled counter list. Please use \refCom{RemoveCoupledCounters} first, then apply \cs{AddCoupledCounters} +\begin{codeoptionsenum} + \item \oarg{options}: See \cref{subsection:options_coupledcounters} for a explanation about available options. + \item \marg{counter name 1, counter name2, \dots}: The list of counters that should should be stepped together for the given counter group. +\end{codeoptionsenum} +\begin{marker} + If the list given by the \refKey{name} option does not exist, \refCom{AddCoupledCounters} issues a warning on the console and ignores this list then. The counters are not added to any list at all. +\end{marker} + + +\end{docCommand} + +\begin{docCommand}{ClearCoupledCounters}{\marg{options}}\tcbdocmarginnote{\tcbdocnew{\versionzerosixdate}} + This removes all names from the given name of a group of coupled counters. + \begin{codeoptionsenum} + \item \oarg{options}: As of version \packageversion{} the only recognized option is \refKey{name}. +\end{codeoptionsenum} +After clearing a list, the coupling stops for the counters on that list (unless they are part of another list, which is possible, but not recommended). using \refCom{AddCoupledCounters} with the relevant \refKey{name} option adds counters again to the list and the coupling is active again, however, for different counters (eventually). + +In order to clear all coupled counter lists, use \refCom{ClearAllCoupledCounters} instead. + +\begin{marker} + \begin{itemize} + \item The list name itself is still available + \item If the list given by the \refKey{name} option does not exist, \refCom{ClearCoupledCounters} issues a warning on the console and ignores this list then. + \end{itemize} +\end{marker} +\end{docCommand} + + +\begin{docCommand}{ClearAllCoupledCounters}{}\tcbdocmarginnote{\tcbdocnew{\versionzerosixdate}} + This removes all coupled counter groups, but not the group names, i.e. the list names can be used later on to add counter names again. In order to clear a specific list, use \refCom{ClearCoupledCounters}. +\end{docCommand} + + +\begin{docCommand}{IsCoupledCounterTF}{\marg{counter name}\marg{true branch}\marg{false branch}}\tcbdocmarginnote{\tcbdocnew{\versionzerosixdate}} +This macro tests if a counter is under the administration of the coupled counter commands and expands to the relevant branch then. There are two short-circuit commands \refCom{IsCoupledCounterT} and \refCom{IsCoupledCounterF}. \end{docCommand} +\begin{docCommand}{IsCoupledCounterT}{\marg{counter name}\marg{true branch}}\tcbdocmarginnote{\tcbdocnew{\versionzerosixdate}} +This macro tests if a counter is under the administration of the coupled counter commands and executes the true branch then. There are two related commands \refCom{IsCoupledCounterTF} and \refCom{IsCoupledCounterF}. +\end{docCommand} + +\begin{docCommand}{IsCoupledCounterF}{\marg{counter name}\marg{false branch}}\tcbdocmarginnote{\tcbdocnew{\versionzerosixdate}} +This macro tests if a counter is under the administration of the coupled counter commands and executes the false branch then if this is not the case. There are two related commands \refCom{IsCoupledCounterTF} and \refCom{IsCoupledCounterT}. +\end{docCommand} \section{Total counters}\tcbdocmarginnote{\tcbdocnew{2015-11-27}} @@ -1325,7 +1410,7 @@ This macro checks if a counter is under the administration of the super total co \subsection{The \CHDocCounter{numberofruns} counter}\label{subsection:numberofruns} -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}. +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}. Use the \refKey{nonumberofruns} package option to prevent the definition of this counter. \section[Counter backup/restoration]{Backup and restore of counter values}\tcbdocmarginnote{\tcbdocnew{\versionzerofourdate}} @@ -1445,14 +1530,13 @@ However, there is a solution to this problem: The hypertarget anchors are built \section{To - Do list} \begin{itemize} +\item Switch to the container support for all features -- this is a major task and will be done in (tiny) steps. +\item Add counter group support for the \CHDocTag{backup} feature, i.e. define a symbolic name for a group of counters that should be controlled by the backup feature. This will allow multiple backup groups, which might be necessary. \item Better counter definition/copy counter routines \(\longrightarrow\) another package perhaps \item More examples \item Some macro names might be non-intuitive \item Improve documentation \item Hooks for conditionals on \CHDocCounter*{numberofruns} (see \cref{subsection:numberofruns}) -%\item Allow for specific counter to be resumed from suspension instead of resuming all -%\item Allow for an associated counter to have multiple masters -%\item Complete redesign and rewrite with \CHDocPackage{expl3} -- this will provide better list features \end{itemize} If you @@ -1496,10 +1580,17 @@ write this documentation. \section{Version history} \begin{itemize} +\item +Version 0.6 + +\begin{itemize}[label={$\checkmark$}] + \item The coupled counters allow to specify a counter group to which all relevant counters belong, this allows several coupled counter groups then \tcbdocmarginnote{\tcbdocnew{\versionzerosixdate}} + \item Fixed a small bug within backup counter support -- the resetting was not done any more \tcbdocmarginnote{\tcbdocnew{\versionzerosixdate}} +\end{itemize} \item Version 0.5 \begin{itemize}[label={$\checkmark$}] -\item Added support (very experimental!) for coupled counters, see \cref{sec::coupledcounters} about this feature! \tcbdocmarginnote{\tcbdocnew{\versionzerofivedate}} +\item Added support (very experimental!) for the \CHDocTag{coupled counters} feature, see \cref{sec::coupledcounters} about this feature! \tcbdocmarginnote{\tcbdocnew{\versionzerofivedate}} \item Added \cs{RegisterTotalDocumentCounter} and improved \cs{TotalValue} support\tcbdocmarginnote{\tcbdocnew{\versionzerofivedate}} \end{itemize} \item |