summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_doc.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2017-03-04 23:13:23 +0000
committerKarl Berry <karl@freefriends.org>2017-03-04 23:13:23 +0000
commit7bd517903406aa8d487340f84350c10826ff5e54 (patch)
tree2a5c6a5c16afd9f96e3b1f6e3f4582255930fcfa /Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_doc.tex
parente59da762242ab80e65849560ed7777e46ddd77da (diff)
xassoccnt (4mar17)
git-svn-id: svn://tug.org/texlive/trunk@43396 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_doc.tex')
-rw-r--r--Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_doc.tex125
1 files changed, 108 insertions, 17 deletions
diff --git a/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_doc.tex b/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_doc.tex
index 60a1a2d8d08..2ecf4cb802c 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.1 (2016/10/29 -- 13:34:52)
+%% LaTeX package xassoccnt - version 1.2 (2017/03/04 -- 00:46:43)
%% Documentation file for xassoccnt.sty
%%
%%
%% -------------------------------------------------------------------------------------------
-%% Copyright (c) 2015 -- 2016 by Dr. Christian Hupfer <typography dot with dot latex at gmail dot com>
+%% Copyright (c) 2015 -- 2017 by Dr. Christian Hupfer <typography dot with dot latex at gmail dot com>
%% -------------------------------------------------------------------------------------------
%%
%% This work may be distributed and/or modified under the
@@ -97,6 +97,10 @@
\@namedef{xassoccntversion1.1}{v1.1 2016-10-29}
+\@namedef{xassoccntversion1.2}{v1.2 2017-03-03}
+
+\newcommand{\authorname}{Autor}
+
\makeatother
@@ -147,7 +151,7 @@
\today \tabularnewline
\tabularnewline
\addtocounter{footnote}{2}
- Author: \KVchdocpackageauthor\(^\mathrm{\fnsymbol{footnote}}\)
+ \authorname: \KVchdocpackageauthor\(^\mathrm{\fnsymbol{footnote}}\)
\tabularnewline
\end{tabular}
\end{center}
@@ -302,6 +306,19 @@
}%
}
+
+\newcommand{\CHDocExperimentalFeature}[1][Experimental]{%
+ \tcbdocmarginnote[doclang/new={N},
+ colframe=yellow!50!blue,
+ halign=left,
+ colback={blue!10!yellow},
+ fontupper={\tiny}
+ ]{%
+ #1%
+ }%
+}
+
+
\usepackage{graphicx}%
\usepackage[autodefinecounters=true]{xassoccnt}
\usepackage{amsmath}
@@ -311,13 +328,14 @@
\usepackage{bookmark}
\usepackage{cleveref}
\usetikzlibrary{mindmap}
+\usepackage{url}
\setcounter{tocdepth}{3}
\newcommand{\PackageDocName}{xassoccnt}%
\newcommand{\mymailtoaddress}{%
- typography.with.latex@gmail.com
+ typography.with.latex@gmail.com%
}
\doparttoc
@@ -535,6 +553,12 @@ As of version \packageversion\ \CHDocPackage{\PackageDocName} supports the packa
Using this package option the super total counter \CHDocCounter{numberofruns} counter will not be defined. See \cref{subsection:numberofruns} about this feature.
\end{docKey}
+\begin{docKey}{redefinelabel}{=\meta{true,false}}{initially \meta{true}}\CHDocNew{1.2}
+\CHDocExperimentalFeature This is an experimental feature as of version \packageversion.
+
+Enables the redefinition of the \refCom{label} command and takes care of the optional argument of \refCom{label} if \CHDocPackage{cleveref} is used. This will provide \refCom{label} with a final optional argument that can be used to allow labels for associated counters (either all or only a specified list of counters), for more on this see \refCom{label} in \namecref{subsec::associated_counters_experimental} \nameref{subsec::associated_counters_experimental}.
+\end{docKey}
+
\clearpage
\part{Tools for counters}
@@ -560,17 +584,20 @@ As of \packageversion, there is only one option used:
\subsection[\LaTeXe\ additions]{Additions to \LaTeXe\ commands}
-\begin{docCommand}{NewDocumentCounter}{\oarg{options}\marg{counter}\oarg{resetting counter}}
+\begin{docCommand}{NewDocumentCounter}{\oarg{options}\marg{counter1,counter2,\dots}\oarg{resetting counter}}
This command is a new interface to \cs{newcounter} and behaves effectively the same. %The first optional argument is reserved for later purposes but not used as of version \packageversion.
\begin{docKey}{initial}{=\meta{integer value}}{initially 0}
This is used for the start value of the new counter.
\end{docKey}
+\CHDocUpdate{1.2}This command allows multiple counters (specified as a comma separated list) to be defined at once, but all have the same resetting counter then and initial value is the same for all those counters (if those options are given).
+
\end{docCommand}%
\begin{docCommand}{DeclareDocumentCounter}{\oarg{options}\marg{counter}\oarg{resetting counter}}
This command is the preamble-only version of \refCom{NewDocumentCounter}.
+ \CHDocUpdate{1.2}This command allows multiple counters (specified as a comma separated list) to be defined at once, but all have the same resetting counter then and initial value is the same for all those counters (if those options are given), i.e. the behaviour is like in \refCom{NewDocumentCounter}.
\end{docCommand}%
@@ -872,20 +899,20 @@ The package \CHDocPackage{chngcntr} offers the possibility of add or remove coun
\begin{docCommand}[before={\CHDocNew{1.0}}\par]{RemoveFromReset}{\marg{counter name}\marg{driver counter name}}
This macro removes the counter given in the first argument from the reset list of the driver counter given in the 2nd argument.
-If the 2nd argument does not point to a LaTeXe\ counter name an error message is shipped and the compilation fails.
+If the 2nd argument does not point to a \LaTeXe\ counter name an error message is shipped and the compilation fails.
\end{docCommand}
\begin{docCommand}[before={\CHDocNew{1.0}}]{RemoveFromFullReset}{\marg{counter name}\marg{driver counter name}}
This macro removes the counter given in the first argument and all of its own reset list from the reset list of the driver counter given in the 2nd argument.
-If the 2nd argument does not point to a LaTeXe\ counter name an error message is shipped and the compilation fails.
+If the 2nd argument does not point to a \LaTeXe\ counter name an error message is shipped and the compilation fails.
\end{docCommand}
\begin{docCommand}[before={\CHDocNew{1.0}}]{AddToReset}{\marg{counter name}\marg{driver counter name}}
This macro adds the counter given in the first argument to the reset list of the driver counter given in the 2nd argument.
-If the 2nd argument does not point to a LaTeXe\ counter name an error message is shipped and the compilation fails.
+If the 2nd argument does not point to a \LaTeXe\ counter name an error message is shipped and the compilation fails.
\end{docCommand}
@@ -983,9 +1010,9 @@ The 2nd argument value is added (or subtracted) to the counters given in the lis
\item \marg{counter1, counter2,\dots}
Holds the comma separated list of counter names
\item \marg{counter increment/decrement}
- Specifies the value to be added or subtracted
+ Specifies the value to be added or subtracted.
- No check is performed whether \textbf{is} or \textbf{expands} to an integer value.
+ No check is performed whether \#2 \textbf{is} or \textbf{expands} to an integer value.
\end{codeoptionsenum}
%\end{docCommandArgs}
@@ -1129,7 +1156,7 @@ This command will print the value of the counter using uppercase hexadecimal dig
\begin{docCommand}{OctalValue}{\marg{counter name}} \CHDocNew{0.7}
-This command will print the value of the counter using uppercase hexadecimal digits.
+This command will print the value of the counter using octal digits.
\end{docCommand}
@@ -1234,7 +1261,6 @@ The usage of this macro is similar to \refCom{DeclareAssociatedCounters}; if it
Using \refCom{AddAssociatedCounters} in the document body automated generation of counters is disabled.
-% You have to use \refCom{DeclareAssociatedCounters} first, to set up the driver counter hook.
\begin{docCommandArgs}{AddAssociatedCounters}
@@ -1287,6 +1313,14 @@ If the driver counter and all its associated counters should be removed, use \re
\end{docCommand}
+\begin{docCommand}[before={\CHDocNew{1.2}}]{DeclareTotalAssociatedCounters}{\oarg{options}\marg{driver counter}\marg{associated counters list}}
+This command combines the features of \CHDocTag{associated counters} and \CHDocTag{total counters}, i.e. the associated counters are defined with \refCom{NewTotalDocumentCounter} and associated to the driver counter.
+
+See \cref{sec::totalcounters} for more information on \CHDocTag{total counters}.
+\end{docCommand}
+
+
+
\clearpage
@@ -1461,8 +1495,54 @@ This commands tests, whether a given counter name is a driver counter and expand
\end{docCommand}%
+\subsection{Associated counters -- Experimental features}\label{subsec::associated_counters_experimental}
+\begin{marker}
+\marginnote{\bcbombe}
+The content here is only of experimental nature and there is no guarantee that the feature will be maintained in future releases.
+\end{marker}
+
+\begin{marker}
+To enable the redefined \refCom{label} macro, specify the package option \refKey{redefinelabel}
+\end{marker}
+
+
+
+\begin{docCommand}[before={\CHDocNew{1.2}}]{label}{\oarg{cleveref-counter-overrule}\marg{label name}\oarg{options for associated counters}}
+ \begin{docKey}{all}{=\meta{true,false}}{initially \meta{false}}\CHDocNew{1.2}
+ This will enable that all associated counters to a driver counter will cause the generation of a label too. By default this option is \meta{false}.
+ This option deliberately overrules \refKey{select}, the value of the option \refKey{prefix} is disregarded.
+ \end{docKey}
+ \begin{docKey}{select}{={counter1, counter2,\dots}}{initially empty}\CHDocNew{1.2}
+ Select only some of the associated counters to be able to be labeled.
+ As of version \packageversion{} there is no check whether the given names refer to counters at all or are associated counters to the last counter that has been used with \cs{refstepcounter}.
+ \end{docKey}
+ \begin{docKey}{prefix}{=\meta{text}}{initially empty}\CHDocNew{1.2}
+ This gives the prefix of the label of the associated counter. If the option \refKey{all} is enabled, the label name is generated from the name of the associated counter, the value of \refKey{prefix-sep} and the value of the 2nd argument.
+ \newcounter{morefoobar}
+ \begin{dispExample*}{listing only}
+ % Assume that some counter has the associated counters foobar, morefoobar and yetanotherfoobar
+ \label{foo}[prefix=assoc,all]
+ \end{dispExample*}
+ will cause a label named \texttt{foobar::foo}, \texttt{morefoobar::foo} and \texttt{yetanotherfoobar::foo}, whereas
+ \begin{dispExample*}{listing only}
+ \label{foo}[prefix=assoc,select=morefoobar]
+ \end{dispExample*}
+ would generate the label \texttt{assocc::foobar} only and will be tied to the value of the counter \texttt{morefoobar}
+ \end{docKey}
+ \begin{docKey}{prefix-sep}{=\meta{text}}{initially ::}\CHDocNew{1.2}
+ Defines the separator between the \refKey{prefix} and the label name for the driver counter, i.e. the 2nd argument of the \refCom{label} command.
+ \end{docKey}
+\end{docCommand}
-\section[Counter backup/restoration]{Backup and restore of counter values}\label{section::new_backuprestore}\CHDocNew{1.0}
+
+\begin{marker}
+\marginnote{\bcbombe}
+If the package option \refKey{redefinelabel} is set to \meta{false}, the usage of the third optional argument will leave spurious content at the position \cs{label} was used. The reason is that the content of third optional argument with \texttt{[]} is not recognized as an argument any longer.
+\end{marker}
+
+
+
+\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.
@@ -1698,7 +1778,7 @@ This macro tests if the backup-id exists for the given counter group and execute
\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} -- \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.
+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}.
@@ -2057,7 +2137,7 @@ There are \number\totvalue{totalequations}~equations in here!
-\section{Total counters}\tcbdocmarginnote{\tcbdocnew{2015-11-27}}
+\section{Total counters}\tcbdocmarginnote{\tcbdocnew{2015-11-27}}\label{sec::totalcounters}
@@ -2152,19 +2232,22 @@ In addition to the concept of a total counter, there is also the possibility of
\subsection{Defining super total counters}
-\begin{docCommand}{NewTotalDocumentCounter}{\oarg{options}\marg{total counter name}}
+\begin{docCommand}{NewTotalDocumentCounter}{\oarg{options}\marg{total counter name1, total counter name2,\dots}}
This macro defines a new counter (which mustn't exist before of course) and puts it under control of the total counter features.
\begin{codeoptionsenum}
\item \oarg{options}: As of version \packageversion, only this option is used
\refKey{supertotal} -- this has the same meaning as in \refCom{RegisterTotalDocumentCounter} and defaults to \texttt{false}.
- \item \marg{total counter name}: The name of the total counter. This must not be the same like the name of any already existing counter. Internally another counter is defined which has a prefix to prevent name clashes with counter names defined by the package \CHDocPackage{totalcount}.
+ \item \marg{total counter name1, total counter name2,\dots}: The names of the total counter, separated by a comma. This must not be the same like the name of any already existing counter. Internally another counter is defined which has a prefix to prevent name clashes with counter names defined by the package \CHDocPackage{totalcount}.
\end{codeoptionsenum}
+
If an already existing counter should be tracked with total counter features,
use \refCom{RegisterTotalDocumentCounter} instead.
+\CHDocUpdate{1.2}This command allows multiple counters (specified as a comma separated list) to be defined at once.
+
\end{docCommand}
@@ -2269,6 +2352,14 @@ write this documentation.
\begin{itemize}[itemsep=15pt]
+\item \CHDocFullVersion{1.2}
+\begin{itemize}
+ \item Corrected some typos in the manual.
+ \item The macros \refCom{NewDocumentCounter}, \refCom{DeclareDocumentCounter} and \refCom{NewTotalDocumentCounter} allow multiple counters to be specified and defined.
+ \item Added the macro \refCom{DeclareTotalAssociatedCounters} in order to combine total counters and the associated feature, i.e. the counters are total ones and associated to a driver counter.
+ \item \CHDocExperimentalFeature An extended version of \refCom{label} is provided to allow labels also for associated counters during the stepping process of the driver counter.
+\end{itemize}
+
\item \CHDocFullVersion{1.1}
\begin{itemize}
\item Added some missing basic functions needed after the more restrictive \CHDocPackage{expl3} update from 2016/10/19