diff options
author | Karl Berry <karl@freefriends.org> | 2017-03-05 21:39:46 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2017-03-05 21:39:46 +0000 |
commit | 80eb6890ed8748ee4e3da233c40143094c31c971 (patch) | |
tree | 57023688fe2bc5c84e2ca687959c4b14dd1050d4 /Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_doc.tex | |
parent | b285d50cc7e7b5dd13f1ba3f1859b9f6dc5abb02 (diff) |
xassoccnt (5mar17)
git-svn-id: svn://tug.org/texlive/trunk@43408 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.tex | 192 |
1 files changed, 136 insertions, 56 deletions
diff --git a/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_doc.tex b/Master/texmf-dist/doc/latex/xassoccnt/xassoccnt_doc.tex index 2ecf4cb802c..f2d7dfc8798 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 1.2 (2017/03/04 -- 00:46:43) +%% LaTeX package xassoccnt - version 1.3 (2017/03/05 -- 18:08:47) %% Documentation file for xassoccnt.sty %% %% @@ -99,6 +99,8 @@ \@namedef{xassoccntversion1.2}{v1.2 2017-03-03} +\@namedef{xassoccntversion1.3}{v1.3 2017-03-04} + \newcommand{\authorname}{Autor} @@ -382,7 +384,7 @@ pdfsubject={Documentation of \PackageDocName\ package}, pdfkeywords={LaTeX, counters}, bookmarksopen=true, - bookmarksopenlevel=4, + bookmarksopenlevel=2, bookmarksnumbered=true, pdfcreator={LaTeX} } @@ -390,7 +392,7 @@ \begin{document} -\mmddyyyydate +\yyyymmdddate \setlength{\parindent}{0em} @@ -401,7 +403,7 @@ \bfseries \node [concept] {Counters} child[concept color=red!30!yellow,grow=30] { node [concept] {Associated counters}} - child[grow=80,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}} } @@ -410,7 +412,8 @@ child[grow=170,concept color=red!30!yellow] { node [concept] {Total} child[concept color=yellow!30!,grow=150] {node[concept] {Super total counters}}} child[grow=260,concept color=red!30!green] { node [concept] {Loops on counters}} child[grow=200,concept color=red!30!green] { node [concept] {Counter output}} - child[grow=230,concept color=red!20!cyan] { node [concept] {Coupled counters} child [grow=250,concept color=cyan!50!blue] {node[concept] {Coupled counter groups}}}; + child[grow=230,concept color=red!20!cyan] { node [concept] {Coupled counters} child [grow=250,concept color=cyan!50!blue] {node[concept] {Coupled counter groups}}} + child[grow=57,concept color=red!20!yellow] { node [concept] {Label}}; \end{tikzpicture} \CHPackageTitlePage[packageauthor={Christian Hupfer}]{Associated counters stepping simultaneously\\ (and other gadgets)} @@ -791,7 +794,7 @@ The optional argument is not used as of version \packageversion\ for none of tho On occasions it might be important to have some information which counter has been changed last. Since there are four commands manipulating counter values, there are four corresponding routines for this: -\begin{docCommand}{LastAddedToCounter}{} +\begin{docCommand}[before={\CHDocExpCommand\par\CHDocUpdate{1.3}}]{LastAddedToCounter}{} This command has no arguments and expands to the name of the counter which was used last in \cs{addtocounter}. There is no further typesetting done with the countername. \begin{dispExample} @@ -808,18 +811,21 @@ This command has no arguments and expands to the name of the counter which was u \end{marker} -\begin{docCommand}{LastSteppedCounter}{} +\begin{docCommand}[before={\CHDocExpCommand\par\CHDocUpdate{1.3}}]{LastSteppedCounter}{} + This command has no arguments and expands to the name of the counter which was stepped last using \cs{stepcounter}. There is no further typesetting done with the countername. + \begin{dispExample} \stepcounter{SomeCounter} - The last counter being stepped was \LastSteppedCounter. \end{dispExample}% \end{docCommand}% -\begin{docCommand}{LastRefSteppedCounter}{} +\begin{docCommand}[before={\CHDocExpCommand\par\CHDocUpdate{1.3}}]{LastRefSteppedCounter}{} + +This macro gives the last counter being used in \cs{refstepcounter} and is expandable.%{\ChDocVersion{1.3}} \begin{dispExample} \begin{equation} @@ -830,13 +836,14 @@ This command has no arguments and expands to the name of the counter which was s The last counter being refstepped was \LastRefSteppedCounter. \end{dispExample}% + \end{docCommand}% -\begin{docCommand}{LastSetCounter}{} +\begin{docCommand}[before={\CHDocExpCommand\par\CHDocUpdate{1.3}}]{LastSetCounter}{} This command has no arguments and expands to the name of the counter which was set last using \cs{setcounter}. There is no further typesetting done with the countername. \begin{dispExample} @@ -986,6 +993,24 @@ This command displays the reset list of a counter on the terminal as the \cs{sho \end{docCommand} +\begin{docCommand}[before={\CHDocNew{1.3}}]{GetAllResetLists}{} + This determines all reset lists and stores the information internally. It should be called right before \cs{begin{document}} or at any time inside the document environment, when new counters are added there (which is not recommended) + +The information can be retrieved with \refCom{GetParentCounter}. + +\end{docCommand} + +\begin{docCommand}[before={\CHDocExpCommand\par\CHDocNew{1.3}}]{GetParentCounter}{\marg{counter}} +This macro tries to detect the counter that was responsible for the resetting of the counter named \marg{counter} and is expandable. +In order to minimize the amount of searching and maintaining expandability, the counter reset data must be stored beforehand, i.e. with \refCom{GetAllResetLists}. + +\begin{marker} +If a counter has been added to more than one parent counter as their resetting driver counter, only the most recent addition is in action. This may be correct in some occasions but there is no guarantee that the given counter name really caused the last reset of the counter given as argument. +\end{marker} +\end{docCommand} + + + \section[Loops on multiple counters]{Performing the same action for many counters} \CHDocNew{0.7} Sometimes it might be necessary to set the values of many counters at once. This can be done with consecutive \cs{setcounter} statements, for example. This poses no problem, but might become tedious if there are more than three counters or if this task occurs more than once. \CHDocPackage{\PackageDocName} provides some macros that can do the usual operations like stepping, refstepping, adding to, resetting or setting counter values. @@ -1495,51 +1520,6 @@ 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} - - -\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} @@ -2281,7 +2261,99 @@ 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}. Use the \refKey{nonumberofruns} package option to prevent the definition of this counter. -\clearpage{ + +\section{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} + + +\subsection{Labels} + + + +\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} + + +\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} + + +\begin{docCommand}[before={\CHDocNew{1.3}}]{LaTeXLabel}{\oarg{cleveref-counter-overrule}\marg{label name}} + This is the default label macro, either with the \CHDocPackage{cleveref} extension or the classical \LaTeX2e\ macro (eventually modified by \CHDocPackage{hyperref}) and is not modified by this package. + + +The feature of label hooks from \refCom{RegisterPreLabelHook} or \refCom{RegisterPostLabelHook} is not used here. +\end{docCommand} + + +\subsection{Hooks} + + +This feature is experimental and only realized for the modified \refCom{label} command until now. See \nolinkurl{xassoccnt_getparentcounter_example.tex} as an example of usage. + +\begin{docCommand}[before={\CHDocNew{1.3}}]{RegisterPreLabelHook}{\marg{command name1, command name2,\dots}} + +This macro declares a possible list of hooks (commands) that should be executed \textbf{before} the traditional \cs{label} command is applied. If the hook name refers to some unknown macro, nothing is done. + +The hook names must be given with the \textbackslash as command sequence indicator, i.e. \cs{zlabel}, more than one macro name is possible by using comma as separator. + +As of version \packageversion\ the hook macro does not allow more than one argument, which is automatically used from the surrounding \cs{label} call and is the usual label name. + + +\end{docCommand} + +\begin{docCommand}[before={\CHDocNew{1.3}}]{RegisterPostLabelHook}{\marg{command name1, command name2,\dots}} + +This macro declares a possible list of hooks (commands) that should be executed after the traditional \cs{label} command is applied. If the hook name refers to some unknown macro, nothing is done. + +The hook names must be given with the \textbackslash as command sequence indicator, i.e. \cs{zlabel}, more than one macro name is possible by using comma as separator. + +As of version \packageversion\ the hook macro does not allow more than one argument, which is automatically used from the surrounding \cs{label} call and is the usual label name. + +\end{docCommand} + + + + + +\clearpage \part{Meta-Information} \parttoc @@ -2352,6 +2424,14 @@ write this documentation. \begin{itemize}[itemsep=15pt] +\item \CHDocFullVersion{1.3} +\begin{itemize} + \item Provided the \refCom{LaTeXLabel} macro to access the non-xassoccnt version of the \refCom{label} command. + \item \CHDocExperimentalFeature Added the concept of label hooks, see \cref{subsec::associated_counters_experimental} for more information. + \item The macros \cs{Last...} are defined with \CHDocPackage{expl3} methods. + \item Added \refCom{GetAllResetLists} and \refCom{GetParentCounter} for information on parent (or driver) counters. +\end{itemize} + \item \CHDocFullVersion{1.2} \begin{itemize} \item Corrected some typos in the manual. |