summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_doc.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_doc.tex')
-rw-r--r--Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_doc.tex257
1 files changed, 14 insertions, 243 deletions
diff --git a/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_doc.tex b/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_doc.tex
index 95fbf028764..b37702b401f 100644
--- a/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_doc.tex
+++ b/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_doc.tex
@@ -1,9 +1,9 @@
-%% LaTeX package xassoccnt - version 1.5 (2017/07/28 -- 12:08:57)
+%% LaTeX package xassoccnt - version 1.6 (2018/01/03 -- 23:27:20)
%% Documentation file for xassoccnt.sty
%%
%%
%% -------------------------------------------------------------------------------------------
-%% Copyright (c) 2015 -- 2017 by Dr. Christian Hupfer <typography dot with dot latex at gmail dot com>
+%% Copyright (c) 2015 -- 2018 by Dr. Christian Hupfer <typography dot with dot latex at gmail dot com>
%% -------------------------------------------------------------------------------------------
%%
%% This work may be distributed and/or modified under the
@@ -109,6 +109,8 @@
\@namedef{xassoccntversion1.5}{v1.5 2017-07-28}
+\@namedef{xassoccntversion1.6}{v1.6 2018-01-03}
+
\newcommand{\authorname}{Autor}
@@ -141,7 +143,6 @@
#1
}
-
\presetkeys{chdoc}{packageauthor={Christian Hupfer}}{}%
\NewDocumentCommand{\CHPackageTitlePage}{O{}mO{}}{%
\setkeys{chdoc}{packageauthor={Christian Hupfer},filepurpose={Documentation},#1}%
@@ -390,7 +391,7 @@
\hypersetup{breaklinks=true,
pdftitle={\jobname.pdf -- version \packageversion},
- pdfauthor={PACKAGEAUTHOR},
+ pdfauthor={Dr. Christian Hupfer},
pdfsubject={Documentation of \PackageDocName\ package},
pdfkeywords={LaTeX, counters},
bookmarksopen=true,
@@ -413,7 +414,7 @@
\bfseries
\node [concept] {Counters}
child[concept color=red!30!yellow,grow=30] { node [concept] {Associated counters}}
- child[grow=85,white,concept color=red!80!blue] { node [concept] {Backup \& Restore of counters}}
+% child[grow=85,white,concept color=red!80!blue] { node [concept] {Backup \& Restore of counters}}
child[grow=300,concept color=yellow!90!red] { node [concept] {Extensions to \LaTeXe} child[grow=230,concept color={yellow!20!green}] {node [concept] {Query macros}}
child[grow=290,concept color={yellow!30!cyan}] {node [concept] {Document counters}}
}
@@ -1758,250 +1759,14 @@ This commands tests, whether a given counter name is a driver counter and expand
\end{docCommand}%
+%\section{Backup and restoration features}
\section[Counter backup/restoration]{Backup and restore of counter values}\CHDocNew{1.0}\label{section::new_backuprestore}
-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{marker}
- Since version \CHDocFullVersion{1.0} the commands and feature behaviour of backup and restoration of counter values has changed.
-
- The old behaviour is still available using the macros \cs{Former...} prefixed macros, see \cref{section::old_backuprestore} for this.
+ This feature is currently disabled!
\end{marker}
-\subsection{Key philosophy in backup/restore}
-
-The basic idea is to provide a scheme that allows easy storage and restoration of counter values. For a single counter this is quite easy, using some other temporary counter, storing the old value there and copy the values back at the right position -- if many counters should be controlled to have a backup this procedure might get tedious, however.
-
-\CHDocPackage{xassoccnt} provides some tools to define groups of counters that should be under control of backup and restoration. A backup counter group can be used multiple times, each using an individual ID, this allows maintaining 'complete' counter states and reinjecting them at any position later on.
-
-Those are the basic steps (in pseudo code) to use the backup feature:
-
-\begin{enumerate}
- \item Define a symbolic backup counter group name
-
- Note that counter group names are providing something like a namespace. A group of coupled counters (see \namecref{sec::coupledcounters} \nameref{sec::coupledcounters}) may have the same name as a group of counters designed to be backed up -- however, each feature has its own namespace. In each namespace there can be only one counter group with a specific name, duplicates are not allowed within the same feature namespace.
- \item Populate the counter group name with counter names
- \item Define a backup state and a corresponding id
- \item Restore at any place
-\end{enumerate}
-
-\subsection{The default counter group "scratch"}
-
-There is a default counter group for backup named "scratch", if no specific counter group name is given using the \refKey{name} option (see \cref{subsubsec::common_options_backuprestore} for a detailed description of available backup/restore options).
-
-\subsection{Description of basic backup/restore macros}
-
-\subsubsection{Common options to (most) of the backup/restore macros} \label{subsubsec::common_options_backuprestore}
-
-\begin{itemize}
-\item
- \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 when the backup command is given. The default value is \meta{true}.
- \end{docKey}
-\item \begin{docKey}[][]{cascading}{=\meta{true/false}}{initially false}
- This key decides whether all counters in the reset list of a driver counter shall be added to the counter group -- the driver counter is added itself too. If the driver counter has no reset list, it is added nevertheless.
-
- Please note that the reset lists of the individual counters are tracked as well -- this is done recursively.
-
- This provides a very convenient feature to backup and restore the value of a certain sectioning level, say \cs{chapter}. Using \refKey{cascading} this would mean\footnote{Assuming \CHDocClass{book} is used, for example!} that \CHDocCounter{chapter}, \CHDocCounter{section}, \CHDocCounter{subsection},\CHDocCounter{subsubsection}, \CHDocCounter{paragraph}, \CHDocCounter{subparagraph}, \CHDocCounter{equation}, \CHDocCounter{figure} and \CHDocCounter{table} would be added to the counter group.
- \end{docKey}
- \item \begin{docKey}[][]{backup-id}{=string}{no default value}
- This key declares a string-like backup id under which the backup of a certain group is stored and can be retrieved later on. The id should be a string containing only alphanumeric characters.
- \end{docKey}
-\item
- \begin{docKey}[][]{restore-id}{=string}{no default value}
- This key declares a string-like restore id for unique \CHDocPackage{hyperref} names. The id should be a string containing only alphanumeric characters. \end{docKey}
- This key is only needed if the same backup-id should be restored more than once and the package \CHDocPackage{hyperref} is used in order to provide unique hyper anchors.
- \item \begin{docKey}[][]{keep-after-restore}{=\meta{true/false}}{initially false}
- This key decides whether the values of a certain backup id (see \refKey{backup-id}) shall be kept after a restore has been issued. The default operation is to remove the \refKey{backup-id} and the values of the counters belonging to the given \refKey{backup-id}.
-
- This option is useful if the same backup state (i.e. \refKey{backup-id}) is to be used more than once.
-
- Reusing the same counter group for restore after having restored them already with the \refKey{keep-after-restore} option being false will be ignored, i.e. the counter values are not changed.
-\end{docKey}
-
-\item \refKey{name}
- The meaning of this key is basically the same as for the \nameref{sec::coupledcounters} feature. However, depending on the stage of the backup/restore process the precise action differs:
- \begin{itemize}
- \item If \refKey{name} is used in \refCom{AssignBackupCounters} the counters are added to group indicated by the value of \refKey{name}.
- \item If \refKey{name} is used either for \refCom{BackupCounterGroup} or in \refCom{RestoreBackupCounterGroup} to indicate the counter group for a certain backup state, either for storing or restoring.
- \end{itemize}
-\end{itemize}
-
-
-\subsubsection{Core backup/restore macros}
-
-\begin{docCommand}[before={\CHDocNew{1.0}}]{BackupCounterGroup}{\oarg{options}\marg{counter group name}}
- Concerning the backup feature this performs the storing of counter values at the position where the command is expanded!
- A backup operation needs
- \begin{itemize}
- \item \refKey{backup-id} to be able to refer to a certain backup state
- \item \refKey{name} to identify the group of counters
- \end{itemize}
-\end{docCommand}
-
-\begin{docCommand}[before={\CHDocNew{1.0}}]{RestoreBackupCounterGroup}{\oarg{options}\marg{counter group name}}
- This command restores the value of the given counter group.
- Useful options are (see \nameref{subsubsec::common_options_backuprestore})
- \begin{itemize}
- \item \refKey{backup-id}
- \item \refKey{keep-after-restore}
- \item \refKey{restore-id}
- \item \refKey{name}
- \end{itemize}
-\end{docCommand}
-
-
-\subsubsection{Declaring counter groups}
-
-\begin{docCommand}[before={\CHDocNew{1.0}}]{DeclareBackupCountersGroupName}{\oarg{}\marg{counter group name}}
- This command declares (better: reserves a name for a backup counter group) -- the name has to be specified as first mandatory argument.
-
- A counter group name consists of alphanumeric characters, special symbols etc. are not allowed. The name must not contain commas!
-
- As of version \packageversion\ the optional argument is not used and reserved for later purposes.
-\end{docCommand}
-
-\subsubsection{Populating counter groups}
-
-\begin{docCommand}[before={\CHDocNew{1.0}}]{AssignBackupCounters}{\oarg{options}\marg{counter name1,counter name2,\dots}}
- This macro populates the counter group (given as optional key - value \refKey{name}) with the comma separated list of counters from the first mandatory argument. The meaning of \refKey{name} is the same as in \nameref{sec::coupledcounters}, but the counter group names are not related to that feature -- the namespace is safe then.
-
- Some important notes about the behaviour of \refCom{AssignBackupCounters}
- \begin{itemize}
- \item If \refKey{name} is not given or empty, the default counter group "scratch" is used.
-
- \item If the counter group given to \refKey{name} does not exist, it will be created automatically.
- \end{itemize}
-
-\end{docCommand}
-
-
-\begin{docCommand}[before={\CHDocNew{1.0}}]{AddBackupCounter}{\oarg{options}\marg{counter name1,counter name2,\dots}}
- This command is similar to \refCom{AssignBackupCounters}, adding counters to a counter group named by \refKey{name} option. If the counter group name does not exist, no action is performed, i.e. the adding operation is ignored.
-\end{docCommand}
-
-
-\subsubsection[Clearing backup states]{Clearing backup states}\label{subsubsec::clearingbackupstates}
-
-It might be necessary to remove a certain backup state, i.e. a collection of counter values to be referred to with a \refKey{backup-id}. This can be done either for a certain counter (with \refCom{ClearCounterBackupState}) in a counter group only or for all counters in group (with \refCom{ClearBackupState}).
-
-\begin{docCommand}[before={\CHDocNew{1.0}}]{ClearCounterBackupState}{\oarg{options}\marg{countergroup name}\marg{counter name}}
- This macro removes the given backup-id state value for a specific counter only. Use the \refKey{backup-id} option in the first optional argument to specify which backup-id should be cleared.
-
- \begin{itemize}
- \item If the backup-id does not exist, the operation is ignored silently.
- \item The counter is still part of the group, but can't be restored to the previous state that was identified with \refKey{backup-id}.
- \end{itemize}
-
- \marginnote{\bcbombe}Use this macro with care!
- \smallskip
-\end{docCommand}
-
-
-\begin{docCommand}[before={\CHDocNew{1.0}}]{ClearBackupState}{\oarg{options}\marg{countergroup name}}
- This macro removes the given backup-id state value for a whole counter group. Use the \refKey{backup-id} option in the first optional argument to specify which backup-id should be cleared.
-
- \begin{itemize}
- \item If the backup-id does not exist, the operation is ignored silently.
- \item The \refKey{backup-id} is removed from the list of possible backup-ids for the relevant countergroup.
- \end{itemize}
-\end{docCommand}
-
-
-
-
-\subsubsection[Clearing backup groups]{Clearing and deleting backup counter groups}\label{subsubsec::clearingdeletingbackupcountergroups}
-
-From time to time it might be necessary to remove counters from a group or to clear the whole group or remove even the whole group. Those operations can be achieved with \refCom{RemoveCountersFromBackupGroup}, \refCom{ClearBackupCounterGroups} and \refCom{DeleteBackupCounterGroups}. All macros remove at least all stored values belonging to a counter group. A \refCom{RestoreBackupCounterGroup} call does nothing after any of the mentioned macros have been issued.
-
-\begin{docCommand}[before={\CHDocNew{1.0}}]{RemoveCountersFromBackupGroup}{\oarg{options}\marg{countergroup name}\marg{counter name 1, counter name 2,\dots}}
- This command removes the given counter names from a counter group. The stored values are deleted completely and are lost afterwards. A non-existing counter group name is ignored as well as counters that do not belong to the given group name.
-
- As of version \packageversion\ the optional argument is not used and reserved for later purposes.
-
- If complete counter groups shall be deleted and be unavailable afterwards, use
-
-\refCom{DeleteBackupCounterGroups} instead.
-\end{docCommand}
-
-
-\begin{docCommand}[before={\CHDocNew{1.0}}]{ClearBackupCounterGroups}{\oarg{options}\marg{countergroup name 1, countergroup name 2,\dots}}
- This command removes all names of the counter groups given as comma separated list in the 2nd argument, the internal storage of counter values is removed as well, i.e. older counter values aren't available any longer. The counter group names remain valid, any subsequent call to \refCom{BackupCounterGroup} or \refCom{RestoreBackupCounterGroup} with one of the provided group names will be ignored.
-
- As of version \packageversion\ the optional argument is not used and reserved for later purposes.
-
- If counter groups shall be deleted and be unavailable, use \refCom{DeleteBackupCounterGroups}.
-\end{docCommand}
-
-
-\begin{docCommand}[before={\CHDocNew{1.0}}]{DeleteBackupCounterGroups}{\oarg{options}\marg{countergroup name 1, countergroup name 2,\dots}}
- This command clears the counter groups given as comma separated list in the 2nd argument with \refCom{ClearBackupCounterGroups} and removes the names as well, i.e. those names are not available any longer.
-
- As of version \packageversion\ the optional argument is not used and reserved for later purposes.
-\end{docCommand}
-
-
-\subsection{Query for backup features}\label{subsec::querybackupmacros}\CHDocNew{1.0}
-
-As usual, some macros to ask whether a certain counter is under backup control or whether a certain \refKey{backup-id} exists might be useful!
-
-
-\subsubsection{Querying for backup counter group existence}\label{subsec::querybackupcountergroup}
-
-\begin{docCommand}[after={\CHDocNew{1.0}\par}]{IsBackupCounterGroupTF}{\marg{counter group name}\marg{true branch}\marg{false branch}}
-This macro tests if the given name is a backup counter group and expands to the \meta{true}/\meta{false} branch accordingly. There are two short-circuit commands: \refCom{IsBackupCounterGroupT} and \refCom{IsBackupCounterGroupF}.
-\end{docCommand}
-
-\begin{docCommand}[after={\CHDocNew{1.0}\par}]{IsBackupCounterGroupT}{\marg{counter group name}\marg{true branch}}
-This macro tests if the given name is a backup counter group and expands to the \meta{true} branch accordingly. There are two related macros: \refCom{IsBackupCounterGroupF} and \refCom{IsBackupCounterGroupTF}.
-\end{docCommand}
-
-\begin{docCommand}[after={\CHDocNew{1.0}\par}]{IsBackupCounterGroupF}{\marg{counter group name}\marg{false branch}}
-This macro tests if the given name is a backup counter group and expands to the \meta{false} branch accordingly. There are two related macros: \refCom{IsBackupCounterGroupT} and \refCom{IsBackupCounterGroupTF}.
-\end{docCommand}
-
-
-
-\subsubsection{Querying for backup counter entity}\label{subsec::querybackupmacros}
-
-\begin{docCommand}[after={\CHDocNew{1.0}\par}]{IsBackupCounterTF}{\marg{counter name}\marg{true branch}\marg{false branch}}
-This macro tests if a counter is under the administration of the backup counter commands and expands to the relevant \meta{true}/\meta{false} branch then. There are two short-circuit commands: \refCom{IsBackupCounterT} and \refCom{IsBackupCounterF}.
-\end{docCommand}
-
-\begin{docCommand}[after={\CHDocNew{1.0}\par}]{IsBackupCounterT}{\marg{counter name}\marg{true branch}}
-This macro tests if a counter is under the administration of the backup counter commands and expands to the \meta{true} branch then. There are related commands: \refCom{IsBackupCounterTF} and \refCom{IsBackupCounterF}.
-\end{docCommand}
-
-\begin{docCommand}[after={\CHDocNew{1.0}\par}]{IsBackupCounterF}{\marg{counter name}\marg{false branch}}
-This macro tests if a counter is under the administration of the backup counter commands and expands to the \meta{false} branch if this not the case. There are related commands: \refCom{IsBackupCounterTF} and \refCom{IsBackupCounterT}.
-\end{docCommand}
-
-
-\subsubsection{Querying for backup state entity}\label{subsec::querybackupstate}
-
-\begin{docCommand}[after={\CHDocNew{1.0}\par}]{IsBackupStateTF}{\marg{counter group name}\marg{counter backup-id}\marg{true branch}\marg{false branch}}
-This macro tests if the backup-id exists for the given counter group and executes the relevant \meta{true}/\meta{false} branch accordingly. There are two short-circuit commands: \refCom{IsBackupStateT} and \refCom{IsBackupStateF}.
-\end{docCommand}
-
-\begin{docCommand}[after={\CHDocNew{1.0}\par}]{IsBackupStateT}{\marg{counter group name}\marg{counter backup-id}\marg{true branch}}
-This macro tests if the backup-id exists for the given counter group and executes the relevant \meta{true} branch accordingly. There are two related: \refCom{IsBackupStateTF} and \refCom{IsBackupStateF}.
-\end{docCommand}
-
-\begin{docCommand}[after={\CHDocNew{1.0}\par}]{IsBackupStateF}{\marg{counter group name}\marg{counter backup-id}\marg{false branch}}
-This macro tests if the backup-id exists for the given counter group and executes the relevant \meta{false} branch accordingly. There are two related: \refCom{IsBackupStateTF} and \refCom{IsBackupStateT}.
-\end{docCommand}
-
-
-\subsection{Some notes on the backup features} \label{subsec::backup_and_hyperref}
-
-Principally backing up counter values and restoring them later on is not really difficult -- with one exception: If the \CHDocPackage{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} -- \CHDocPackage{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. \refCom{BackupCounterGroup} does this resetting automatically in an unique way and \refCom{RestoreBackupCounterGroup} restores as well the old \cs{theH...} macros of all counters that are in the backup list. It tracks the number of calls to \refCom{BackupCounterGroup} and changes the relevant \cs{theH...} macro definitions to use unique anchor names then -- this way multiple \refCom{BackupCounterGroup} calls are possible without destroying the hyperlink facilities with \CHDocPackage{hyperref}.
-
-
\section{Coupled counters}\label{sec::coupledcounters}\CHDocNew{0.5}
\begin{marker}
@@ -2676,6 +2441,12 @@ write this documentation.
\begin{itemize}[itemsep=15pt]
+\item \CHDocFullVersion{1.6}
+ \begin{itemize}
+ \item Maintenance update due to updates to \CHDocPackage{expl3}
+ \item The Backup/Restore feature is currently broken and needs a thorough inspection
+ \end{itemize}
+
\item \CHDocFullVersion{1.5}
Added \refCom{LastRefSteppedCounter} as dummy version which expands to nothing as long as \cs{refstepcounter} has not been called.