Debian Codegraph @

texmf-dist/source/latex/ncctools/dcounter.dtx

raw
1 % \iffalse
2 %%
3 %% File: dcounter.dtx Copyright (C) 1998-2005 by Alexander I. Rozhenko
4 %%
5 %<package>\NeedsTeXFormat{LaTeX2e}
6 %<package>\ProvidesPackage{dcounter}
7 %<package> [2005/04/25 v1.2 Dynamic Counters (NCC)]
8 %
9 % \changes{v1.0}{1998/12/19}{Initial version}
10 % \changes{v1.1}{2004/11/23}{Minor corrections of the documentation}
11 % \changes{v1.2}{2005/04/25}{Emulate dynamic style for non-dynamic counters}
12 %
13 %<*driver>
14 \let\makeindex\relax
15 \documentclass{ltxdoc}
16 \usepackage{dcounter}
17 \GetFileInfo{dcounter.sty}
18 \begin{document}
19 \title{The \textsf{dcounter} package\thanks{This file
20 has version number \fileversion, last
21 revised \filedate.}}
22 \author{Alexander I. Rozhenko\\[email protected]}
23 \date{\filedate}
24 \maketitle
25 \DocInput{dcounter.dtx}
26 \end{document}
27 %</driver>
28 % \fi
29 % This package implements a concept of \emph{dynamic counters}. The
30 % counter declared as dynamic is really created at the first use
31 % and receives at that moment the \emph{count style} which was
32 % established by the |\countstyle| command. For example,
33 % if |\countstyle{section}| is established, all dynamically created
34 % counters will be subordinated to |section| counter (i.e., reset
35 % to zero when |section| counter is stepped) and their typesetting
36 % command |\the|\emph{foo} will be equal to
37 % |\thesection.\arabic{|\emph{foo}|}|. This package is compatible with
38 % |calc| package.
39 %
40 % \section{User Interface}
41 %
42 % \DescribeMacro\DeclareDynamicCounter
43 % To declare a dynamic counter \meta{foo} you have to write
44 % \begin{quote}
45 % |\DeclareDynamicCounter|\marg{foo}
46 % \end{quote}
47 % If the \meta{foo} counter does not exist, its name is added to the list of
48 % dynamic counters. This allows create a counter at the first use
49 % with one of the following commands
50 % \begin{tabbing}
51 % | \setcounter|\marg{foo}\marg{number}\qquad\qquad\=
52 % |\stepcounter|\marg{foo}\\
53 % | \addtocounter|\marg{foo}\marg{number}\>
54 % |\refstepcounter|\marg{foo}
55 % \end{tabbing}
56 % If the \meta{foo} counter exists, it will emulate the dynamic style.
57 % I use the following trick for such counters: let |\the|\meta{foo} command
58 % empty and test it at the beginning of document; if it is empty, the
59 % count style of this counter is redefined on the base of dynamic
60 % style.\footnote{This trick was added in version 1.2 of the package.}
61 % This allows work with existing counters by the same manner as with
62 % ``true dynamic'' counters.
63 %
64 % \DescribeMacro\countstyle
65 % To specify a count style you have to use the command
66 % \begin{quote}
67 % |\countstyle|\marg{counter}
68 % \end{quote}
69 % The parameter \meta{counter} have to be existing counter, or dynamic
70 % counter, or empty. Empty \meta{counter} means the \emph{plain} count
71 % style without subordination. If \meta{counter} not exists and is
72 % dynamic it is created here within the previously specified count style.
73 % The default count style is the plain style.
74 %
75 % The |\counstyle| command has an optional parameter useful for
76 % special purposes. If you want to create some counters in another style
77 % that is specified by |\countstyle| command, you can write
78 % \begin{quote}
79 % |\countstyle|\oarg{list of counters}\marg{another counter}
80 % \end{quote}
81 % Here \meta{list of counters} is the list of comma separated counters
82 % whose count style you want to subordinate to
83 % \meta{another counter}. This command creates all undefined counters of
84 % the list. The list may contain not only undefined counters but also
85 % existing counters. If counter in the list
86 % exists, its count style will be modified to be subordinated to
87 % \meta{another counter}. Note, that if this counter was subordinated
88 % before to any other counter, \emph{the previous subordination will be
89 % rejected}. For example, let you want to use the |book| document class
90 % and set |\Roman| enumeration of chapters, independent arabic
91 % enumeration of sections and to subordinate enumeration of figures,
92 % tables and equations to the \emph{section} counter. You can write
93 % \begin{quote}
94 % |\documentclass{book}|\\
95 % |\usepackage{dcounter}|\\
96 % |\renewcommand\thechapter{\Roman{chapter}}|\\
97 % |\countstyle[section]{}|\\
98 % |\countstyle[figure,table,equation]{section}|
99 % \end{quote}
100 % After that the \emph{chapter} counter will not affect on
101 % \emph{section} counter, and all figure, table, and equation numbers
102 % will typeset as |\thesection.\arabic{|\emph{foo}|}|.
103 %
104 % \DescribeMacro\DynamicCount
105 % The command
106 % \begin{quote}
107 % |\DynamicCount|\marg{counter}
108 % \end{quote}
109 % sets the count style for \meta{counter} exactly the same as for
110 % dynamically created counters and creates this counter if it is
111 % undefined. This command is internally used in emulation of dynamic
112 % counters and in the |\countstyle| command with optional parameter.
113 % Since version 1.2, this command is obsolete, but it is saved for
114 % backward compatibility.
115 %
116 % \textbf{Note}. All described commands are used in the preamble.
117 %
118 % \StopEventually{}
119 %
120 % \section{The Basic Implementation Part}
121 %
122 % \begin{macro}{\DCNT@list}
123 % \begin{macro}{\DCNT@elist}
124 % We begin from the initialization of the list of dynamic counters.
125 % |\DCNT@list| contains a list of undeclared counters and
126 % |\DCNT@elist| contains a list of existing counters that are declared
127 % as dynamic counters.
128 % \begin{macrocode}
129 %<*package>
130 \def\DCNT@list{}
131 \def\DCNT@elist{}
132 \@onlypreamble\DCNT@elist
133 % \end{macrocode}
134 % Their items will have the form |\@elt|\marg{counter}
135 % \end{macro}
136 % \end{macro}
137 %
138 % \begin{macro}{\DCNT@in}
139 % The macro |\DCNT@in|\marg{list}\marg{yes}\marg{no}
140 % tests the list of counters \meta{list} to contain the counter
141 % |\DCNT@foo| and after testing executes \meta{yes}-sequence if
142 % |\DCNT@foo| found or \meta{no}-sequence if not. To restrict
143 % the scope of internal modifications made by this macro we always
144 % enclose it into a group. While processing the list of counters the
145 % command executes |\DCNT@noteq|\marg{counter} hook for every
146 % counter which name is distinct from the tested name.
147 % \begin{macrocode}
148 \def\DCNT@in#1#2#3{\@tempswafalse
149 \let\@elt\DCNT@elt #1%
150 \if@tempswa #2\else #3\fi
151 }
152 \def\DCNT@elt#1{\def\DCNT@name{#1}%
153 \ifx\DCNT@name\DCNT@foo \@tempswatrue \else \DCNT@noteq{#1}\fi
154 }
155 % \end{macrocode}
156 % \end{macro}
157 %
158 % \begin{macro}{\DCNT@define}
159 % The command |\DCNT@define|\marg{command}\marg{foo}
160 % tests the counter \meta{foo} to be undefined and, if it is true,
161 % tries to create it dynamically. After that it executes \meta{command}
162 % with the \meta{foo} parameter.
163 % \begin{macrocode}
164 \def\DCNT@define#1#2{%
165 \@ifundefined{c@#2}%
166 {{\edef\DCNT@foo{#2}\let\DCNT@noteq\@gobble
167 \DCNT@in\DCNT@list{\newcounter{#2}\DCNT@the{#2}}{}%
168 }}{}%
169 #1{#2}%
170 }
171 % \end{macrocode}
172 % \end{macro}
173 %
174 % \begin{macro}{\DCNT@the}
175 % The command |\DCNT@the|\marg{foo} redefines |\the|\meta{foo}
176 % command to typeset it in the count style subordinated to |\DCNT@main|
177 % counter. It also adds the name \meta{foo} to the resetting list of\/
178 % |\DCNT@main| counter.
179 % \begin{macrocode}
180 \def\DCNT@the#1{%
181 \ifx\DCNT@main\@empty
182 \expandafter\xdef\csname the#1\endcsname
183 {\noexpand\@arabic \expandafter\noexpand \csname c@#1\endcsname}%
184 \else
185 \expandafter\xdef\csname the#1\endcsname
186 {\expandafter\noexpand \csname the\DCNT@main\endcsname
187 .\noexpand\@arabic \expandafter\noexpand \csname c@#1\endcsname}%
188 \@addtoreset{#1}\DCNT@main
189 \fi
190 }
191 \let\DCNT@main\@empty
192 % \end{macrocode}
193 % \end{macro}
194 %
195 % \section{The Preamble Only Commands}
196 %
197 % \begin{macro}{\DeclareDynamicCounter}
198 % The following command tests the counter and adds it to the list of
199 % dynamic counters if it does not exist or to the list
200 % of emulated counters if it already exists. In the last case,
201 % |\the|\meta{counter} command is defined as empty command. It will be
202 % redefined later at the beginning of document.
203 % \begin{macrocode}
204 \newcommand*{\DeclareDynamicCounter}[1]{%
205 \begingroup
206 \edef\DCNT@foo{#1}%
207 \ifx\DCNT@foo\@empty
208 \PackageError{dcounter}%
209 {Cannot declare a dynamic counter with empty name}{}%
210 \fi
211 \let\DCNT@noteq\@gobble
212 \@ifundefined{c@#1}%
213 {\DCNT@in\DCNT@list{}{\@cons\DCNT@list{{#1}}}}%
214 {\DCNT@in\DCNT@elist{}{\@cons\DCNT@elist{{#1}}}%
215 \expandafter\global\expandafter\let
216 \csname the#1\endcsname\@empty}%
217 \endgroup
218 }
219 \@onlypreamble\DeclareDynamicCounter
220 % \end{macrocode}
221 % \end{macro}
222 %
223 % \begin{macro}{\countstyle}
224 % Now we implement |\countstyle| command which redefines |\DCNT@main|
225 % macro to new main counter. It tests the counter to be defined and
226 % tries to define it if\/ not.
227 % \begin{macrocode}
228 \newcommand{\countstyle}{\@ifnextchar[{\DCNT@lcstyle}{\DCNT@cstyle}}
229 \@onlypreamble\countstyle
230 \def\DCNT@cstyle#1{\edef\DCNT@foo{#1}%
231 \ifx\DCNT@foo\@empty \else
232 \DCNT@define\@gobble{#1}%
233 \@ifundefined{c@#1}{\@nocounterr{#1}}{}%
234 \fi
235 \let\DCNT@main\DCNT@foo
236 }
237 \@onlypreamble\DCNT@cstyle
238 % \end{macrocode}
239 % The special variant of this command with optional parameter locally
240 % sets the special count style and redefines all counters in list via
241 % the |\DynamicCount| command.
242 % \begin{macrocode}
243 \def\DCNT@lcstyle[#1]#2{%
244 {\DCNT@cstyle{#2}\@for\@tempa:=#1\do{\DynamicCount\@tempa}}%
245 }
246 \@onlypreamble\DCNT@lcstyle
247 % \end{macrocode}
248 % \end{macro}
249 %
250 % \begin{macro}{\DynamicCount}
251 % The macro |\DynamicCount|\marg{foo} modifies the count style of
252 % the counter \meta{foo} and defines this counter if it is undefined.
253 % \begin{macrocode}
254 \newcommand*{\DynamicCount}[1]{%
255 \@ifundefined{c@#1}%
256 {\newcounter{#1}}%
257 % \end{macrocode}
258 % If the counter is already defined, we check all resetting lists and
259 % remove all references to this counter.
260 % \begin{macrocode}
261 {{\edef\DCNT@foo{#1}\let\DCNT@noteq\DCNT@add
262 \let\@elt\DCNT@remove \cl@@ckpt
263 }}%
264 \DCNT@the{#1}%
265 }
266 \@onlypreamble\DynamicCount
267 % \end{macrocode}
268 % \end{macro}
269 %
270 % \begin{macro}{\DCNT@remove}
271 % The |\DCNT@remove|\marg{foo} command removes all references
272 % to |\DCNT@foo| counter from the |\cl@|\meta{foo} list of counters.
273 % \begin{macrocode}
274 \def\DCNT@remove#1{\expandafter\DCNT@remlist\csname cl@#1\endcsname}
275 \def\DCNT@remlist#1{%
276 {\let\@tempa\@empty \DCNT@in#1{\global\let#1\@tempa}{}}%
277 }
278 \@onlypreamble\DCNT@remove
279 \@onlypreamble\DCNT@remlist
280 % \end{macrocode}
281 % \end{macro}
282 %
283 % \begin{macro}{\DCNT@add}
284 % The |\DCNT@add|\marg{counter} command locally adds
285 % |\@elt|\marg{counter} to |\@tempa|.
286 % \begin{macrocode}
287 \def\DCNT@add#1{%
288 \let\@elt\relax\edef\@tempa{\@tempa\@elt{#1}}\let\@elt\DCNT@elt
289 }
290 \@onlypreamble\DCNT@add
291 % \end{macrocode}
292 % \end{macro}
293 %
294 % \begin{macro}{\DCNT@eltemu}
295 % The |\DCNT@emu|\marg{counter} command test |\the|\meta{counter}
296 % command to be empty and redefines the counter in the dynamic style.
297 % This command is applied to all existing counters that are emulated as
298 % dynamic counters.
299 % \begin{macrocode}
300 \def\DCNT@emu#1{%
301 \expandafter\ifx\csname the#1\endcsname\@empty
302 \DynamicCount{#1}\fi
303 }
304 \@onlypreamble\DCNT@emu
305 % \end{macrocode}
306 % \end{macro}
307 %
308 % \section{Final Modifications}
309 %
310 % Finally, we modify |\setcounter| and |\addtocounter| commands.
311 % We do it at the beginning of the document to avoid conflict with
312 % the |calc| package. If\/ the list of dynamic counters is empty,
313 % we delete all commands of the package. We also define all
314 % dynamically emulated counters if their |\the| command is empty.
315 % \begin{macrocode}
316 \AtBeginDocument{%
317 \ifx\DCNT@list\@empty
318 \@onlypreamble\DCNT@list
319 \@onlypreamble\DCNT@in
320 \@onlypreamble\DCNT@elt
321 \@onlypreamble\DCNT@define
322 \@onlypreamble\DCNT@the
323 \@onlypreamble\DCNT@main
324 \@onlypreamble\DCNT@name
325 \@onlypreamble\DCNT@foo
326 \@onlypreamble\DCNT@noteq
327 \else
328 \let\DCNT@setcounter\setcounter
329 \def\setcounter{\DCNT@define\DCNT@setcounter}
330 \let\DCNT@addtocounter\addtocounter
331 \def\addtocounter{\DCNT@define\DCNT@addtocounter}
332 \fi
333 {\let\@elt\DCNT@emu \DCNT@elist}%
334 }
335 %</package>
336 % \end{macrocode}
337 \endinput