Debian Codegraph @

texmf-dist/source/latex/bullcntr/bullcntr.dtx

raw
1 % \iffalse
2 % (This is a META-COMMENT.)
3 %
4 % This is file `bullcntr.dtx'.
5 %
6 % This file is part of a work named "bullcntr package".
7 %
8 % Copyright (C) 2007 by Gustavo MEZZETTI <[email protected]>.
9 %
10 % This file may be distributed and/or modified under the conditions
11 % of the LaTeX Project Public License, either version 1.3 of this
12 % license or (at your option) any later version.
13 % The latest version of this license is in
14 % http://www.latex-project.org/lppl.txt
15 % and version 1.3 or later is part of all distributions of LaTeX
16 % version 2005/12/01 or later.
17 %
18 % The bullcntr package has the LPPL maintenance status
19 % "author-maintained".
20 %
21 % The file `manifest.txt' that comes along with this file specifies
22 % what the bullcntr package consists of; more precisely, it explains
23 % how the locutions "Work" and "Compiled Work", used in the LaTeX
24 % Project Public License, are to be interpreted in the case of this
25 % work.
26 %
27 % Note that the distribution of this file alone is "distribution of
28 % only part of the Work" in the sense of the LaTeX Project Public
29 % License, and should be avoided (see the LaTeX Project Public
30 % Licence for details).
31 %
32 % (End of the META-COMMENT.)
33 % \fi
34 %
35 % \def\filename{bullcntr.dtx}
36 % \def\fileversion{0.04}
37 % \def\filedate{2007/04/02}
38 % \def\docdate {2008/10/10}
39 % \def\doclongdate{October~10, 2008}
40 %
41 % \CheckSum{328}
42 %
43 % \changes{0.01}{2007 Feb 07}{First provisional writing of the code}
44 % \changes{0.02}{2007 Feb 08}{Modified layout of bullets for the
45 % value~4}
46 % \changes{0.03}{2007 Feb 16}{Introduced declarations for the four
47 % predefined bullet styles (\protect\cmnd{smartctrbull} and
48 % siblings)}
49 % \changes{0.03}{2007 Feb 16}{Introduced options corresponding to the
50 % declarations for the four predefined bullet styles
51 % (\protect\opt{smartctrbull} and siblings)}
52 % \changes{0.03}{2007 Feb 16}{Developed the
53 % \protect\packlass{\protect\bullenum} subsidiary package defining
54 % the \protect\env{bullenum} environment}
55 % \changes{0.03}{2007 Feb 16}{Thoroughly reorganized the code to
56 % correct a serious bug regarding labels and references}
57 %
58 %% \CharacterTable
59 %% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
60 %% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
61 %% Digits \0\1\2\3\4\5\6\7\8\9
62 %% Exclamation \! Double quote \" Hash (number) \#
63 %% Dollar \$ Percent \% Ampersand \&
64 %% Acute accent \' Left paren \( Right paren \)
65 %% Asterisk \* Plus \+ Comma \,
66 %% Minus \- Point \. Solidus \/
67 %% Colon \: Semicolon \; Less than \<
68 %% Equals \= Greater than \> Question mark \?
69 %% Commercial at \@ Left bracket \[ Backslash \\
70 %% Right bracket \] Circumflex \^ Underscore \_
71 %% Grave accent \` Left brace \{ Vertical bar \|
72 %% Right brace \} Tilde \~}
73 %
74 % \MakeShortVerb{\"}
75 % \DeleteShortVerb{\|}
76 %
77 % \DoNotIndex{\begin,\end,\def,\let,\else,\fi,\or,\@ifdefinable,\@empty}
78 % \DoNotIndex{\newcommand,\renewcommand}
79 % \DoNotIndex{\newenvironment,\renewenvironment}
80 % \DoNotIndex{\z@,\z@skip,\p@,\@ne,\tw@,\thr@@,\@m,\@M,\m@ne}
81 % \DoNotIndex{\DeclareOption}
82 %
83 % \IndexPrologue{
84 % \section{\indexname}
85 % Numbers in italics refer to the page where the corresponding entry
86 % is described, the ones underlined to the code line of the
87 % definition, the rest to the code lines where the entry is used.
88 % }
89 % \setcounter{IndexColumns}{2}
90 %
91 % \GlossaryPrologue{\section{Change History}}
92 %
93 % \setcounter{StandardModuleDepth}{1}
94 %
95 % \newcommand*{\DS}{\textsf{DocStrip}}
96 % \renewcommand*{\partname}{Part}
97 % \newcommand*{\bullcntr}{bullcntr}
98 % \newcommand*{\bullenum}{bullenum}
99 % \makeatletter
100 % \newcommand*{\myspecialindex}[2]
101 % {\special@index{#1\actualchar#2\encapchar main}}
102 % \makeatother
103 % \newcommand*{\counterindex}[1]{\myspecialindex{#1}{{\string\ttfamily
104 % \space #1} (counter)}\index{counters:\levelchar{\protect\ttfamily
105 % #1}\encapchar usage}}
106 % \newcommand*{\optuseindex}[1]{\SortIndex{#1}{\protect\opt{#1}
107 % (option)\encapchar usage}\index{options:\levelchar
108 % \protect\opt{#1}\encapchar usage}}
109 % \DeclareRobustCommand*{\opt}[1]{{\normalfont\ttfamily #1}}
110 % \newcommand*{\sopt}[1]{\mbox{\opt{#1}}\optuseindex{#1}}
111 % \DeclareRobustCommand*{\packlass}[1]{{\normalfont\sffamily #1}}
112 % \DeclareRobustCommand*{\filedir}[1]{{\normalfont\ttfamily #1}}
113 % \DeclareRobustCommand*{\env}[1]{{\normalfont\ttfamily #1}}
114 % \DeclareRobustCommand*{\ctr}[1]{{\normalfont\ttfamily #1}}
115 % \DeclareRobustCommand*{\cmnd}[1]{\texttt{\bslash #1}}
116 % \newcommand*{\circnumb}[1]{%
117 % \makebox[.6666667em]{\makebox[0pt]{$\bigcirc$}\makebox[0pt]{\small #1}}%
118 % }
119 %
120 % \newcommand*{\oMr}{.13397460}
121 % \newcommand*{\oPr}{1.8660254}
122 %
123 %
124 %
125 % \title{
126 % The \packlass{\bullcntr} package\thanks{This file has version
127 % \fileversion, release date \filedate;
128 % last documentation update: \docdate.
129 % Copyright \copyright~2007 by G.~Mezzetti
130 % (see page~\pageref{S:Copy}).}
131 % }
132 % \author{G. Mezzetti}
133 % \date{\doclongdate}
134 %
135 % \maketitle
136 %
137 % \begin{abstract}
138 % This document describes a \LaTeX\ (former \LaTeXe) package that
139 % defines a new command, similar to "\fnsymbol", for displaying the
140 % value of a counter: this command typesets a number of bullets
141 % equal to the value of the counter, in a nice arrangement. The
142 % value of the counter must lie between 1 and~9.
143 %
144 % An ancillary package, named \env{\bullenum}, defines an
145 % environment, similar to \env{enumerate}, that produces lists
146 % whose items are numbered in this way.
147 % \end{abstract}
148 %
149 % \tableofcontents
150 % \listoffigures
151 %
152 % \clearpage
153 % \begingroup
154 %
155 % \setlength{\parskip}{\medskipamount}
156 % \setlength{\parindent}{0pt}
157 %
158 % \section*{Copyright notice}
159 % \label{S:Copy}
160 % \vspace{-\parskip}
161 %
162 % Copyright \copyright~2007 by Gustavo \textsc{Mezzetti}.
163 % All rights are reserved, except as noted below.
164 %
165 % This document has been produced by feeding to a \LaTeX\
166 % typesetting engine the file \filedir{\filename} version
167 % \fileversion\ (\docdate). This file is part of a work named
168 % ``\packlass{\bullcntr} package'', and may be distributed and/or
169 % modified only as a part thereof. Subsection~\ref{sS:License} on
170 % page~\pageref{sS:License} explains the conditions under which the
171 % \packlass{\bullcntr} package may be distributed and/or modified.
172 %
173 % The \packlass{\bullcntr} package has the LPPL maintenance status
174 % ``author-maintained''.
175 %
176 % Permission is granted to make new printed copies of this document,
177 % by any means (\emph{e.g.}, photocopying, direct printing from the
178 % electronic version, and so on).
179 %
180 % Note, though, that distribution of this document alone is
181 % ``distribution of only part of the Work'' in the sense of the
182 % \LaTeX\ Project Public License, and should therefore be avoided:
183 % please distribute, in addition, the source file
184 % \filedir{\bullcntr.dtx} together with all other files listed in
185 % \filedir{manifest.txt}, as explained as well in
186 % Subsection~\ref{sS:License} and in the file
187 % \filedir{manifest.txt} itself.
188 %
189 % \section*{Author's addresses}
190 % \vspace{-\parskip}
191 %
192 % The recommended way to contact the author is by e-mail; his address is:
193 %
194 % \begin{list}{\setlength{\topsep}{0pt}}\item\relax
195 % \ttfamily
196 % [email protected]
197 % \end{list}
198 %
199 % Please include the \emph{exact} phrase \verb*|bullcntr package| in the
200 % \emph{subject} of your message; otherwise, your message could be
201 % thrown away by a mail filter. In this regard, the weakness of the
202 % laws concerning the protection of privacy forces me to explicitly
203 % forbid the use of the above address for any kind of advertising,
204 % marketing, polling, or similar commercial or statistical contact.
205 %
206 % If you have no e-mail access, write to:
207 %
208 % \begin{list}{\setlength{\topsep}{0pt}}\item\relax
209 % Gustavo \textsc{Mezzetti}\\
210 % L.~A.~S. ``A.~Modigliani''\\
211 % Via E.~Degli Scrovegni, 30\\
212 % I--35131\quad PADOVA\quad PD\\
213 % Italy
214 % \end{list}
215 %
216 % \endgroup
217 %
218 %
219 %
220 % \setcounter{secnumdepth}{0}
221 %
222 %
223 %
224 % \clearpage
225 % \section{Introduction}
226 %
227 % I can't remember exactly where the idea of this package arose
228 % from, but I am pretty sure that the first time I saw a list of
229 % items numbered with an increasing number of bullets was in
230 % certain handwritten notes concerning sheaves cohomology, may be a
231 % decade or so ago. Since then, I had repeatedly thought of
232 % writing a \LaTeX\ package to implement this kind of numbering,
233 % but I had never resolved to do so, until very recently, when I
234 % ^^A ( paren match
235 % suddenly decided to sit down and write the code!~:-)
236 %
237 % Regrettably, shortly after I~uploaded version 0.02 of the package
238 % to the CTAN, I~had to discover a major bug in the macros I~had
239 % dashed off in such a haste, which required an extensive (and more
240 % careful!)\ redesign of the code. I~took this opportunity to
241 % thoroughly reorganize it, making it easier, for the user, to
242 % switch from one style of bullets to another, and also adding an
243 % ancillary package that simplified the creation of lists numbered
244 % with bullets. This led to version 0.03.
245 %
246 % You are now reading the source of version 0.04, which corrects
247 % another pretty serious bug brought in---alas---with the
248 % modifications introduced in version 0.03: the "\@b@ll@@cntr"
249 % macro, called by the "\bullcntr" command, behaved erroneously
250 % when invoked with a value of the counter equal to zero.
251 %
252 % Since I~had to repackage the distribution, I~also decided to
253 % include, along with the other files, a couple of \LaTeX\ sources
254 % that illustrate in practice the use of the
255 % \packlass{\bullcntr}\slash \packlass{\bullenum} packages, and
256 % also the \LaTeX\ source of the user manual, that is, of the file
257 % previously offered on the CTAN\@ sites under the name
258 % \filedir{overview.pdf}; this file has now the base name
259 % \filedir{bullcntr-man}, to make it more easily searchable, and
260 % has been turned into a required part of the \packlass{\bullcntr}
261 % package. In doing all this, I~met some suggestions given me by
262 % the people at CTAN\@.
263 %
264 % \subsection{Disclaimer}
265 %
266 % Although a \LaTeX\ package is a piece of software that executes in a
267 % rather protected environment and should therefore be relatively
268 % incapable of doing serious damages, no warranty is given, as usual with
269 % computer software, that this code will work properly, or even that it
270 % will work at all. To be on the safe side, be aware that using this
271 % code can even result in loss of data and/or damages to your disks and
272 % your storage media. If you use this code, you do so exclusively at
273 % your own risk!
274 %
275 % See Subsection~\ref{sS:License} and the \LaTeX\ Project Public
276 % License for more information.
277 %
278 % \subsection{About this document}
279 %
280 % This document, like many documentation files distributed for
281 % \LaTeX, is divided into two parts.
282 %
283 % The first part, \emph{User's Manual}, contains all the documentation
284 % you need to succesfully \emph{use} the package that this document
285 % presents. Every user of the \packlass{\bullcntr} package will
286 % probably want to read this part.
287 %
288 % The second part, \emph{Implementation}, can be omitted if you
289 % want (explanations on how to omit it are given at the beginning
290 % of the part itself), and contains information that concerns only
291 % ``hackers'' who want to learn how the package that this document
292 % presents is \emph{implemented}. Actually, this part contains the
293 % complete listing of the \LaTeX\ code that implements the macros,
294 % in the usual \DS\ format; if you are not a \LaTeX\ hacker, this
295 % part will probably have little meaning to you.
296 %
297 %
298 %
299 % \setcounter{secnumdepth}{3}
300 %
301 %
302 %
303 % \clearpage
304 % \part{User's Manual}
305 %
306 % \section{About this part}
307 %
308 % This part contains detailed instructions on how to install the
309 % \packlass{\bullcntr} package, how to use it, and how to generate
310 % this documentation. Note that including in this document the
311 % instructions on how to generate the document itself may seem
312 % pretty useless, but actually isn't: you might be reading a copy
313 % obtained from some other source.
314 %
315 % \section{Installing the \packlass{\bullcntr} package and generating this manual}
316 %
317 % As usual for \LaTeX\ distributions, the \packlass{\bullcntr}
318 % package is distributed in the form of a \filedir{.dtx} file,
319 % namely \filedir{\bullcntr.dtx}, and an accompanying
320 % \filedir{.ins} file, namely \filedir{\bullcntr.ins}.
321 %
322 % \subsection{Installation}
323 %
324 % To install the package, run \LaTeX\ (or Plain \TeX) once on the
325 % file \filedir{\bullcntr.ins}. This will generate the following
326 % two \LaTeX\ input files:
327 % \begin{quote}
328 % \ttfamily
329 % \bullcntr.sty\\
330 % \bullenum.sty
331 % \end{quote}
332 % To finish the installation, move them into a \LaTeX\ input
333 % directory. The above listing of the files you need to move is
334 % also displayed on the terminal at the end of the run of the file
335 % \filedir{\bullcntr.ins}. The documentation of your \TeX\
336 % installation should tell you how to find the \LaTeX\ input
337 % directory/ies, and probably also how to create new \LaTeX\ input
338 % directories reserved to contain your private classes and
339 % packages. If your \TeX\ installation offers you the chance of
340 % defining your private \LaTeX\ input directories, I recommend you
341 % exploit this possibility and place the generated files into such
342 % a directory.
343 %
344 % Please note that before using the \packlass{\bullcntr} package
345 % you must read the license (see Subsection~\ref{sS:License}) to
346 % see whether its terms are acceptable for you, especially for what
347 % concerns the lack of any warranty; if they are not, don't use
348 % this program.
349 %
350 % \subsection{Documentation}
351 %
352 % To produce this documentation, run \LaTeX\ three times (for the
353 % table of contents to be correct) on the file
354 % \filedir{\bullcntr.dtx}. This won't produce the index and the
355 % change history, however: for those, you have to run
356 % \emph{MakeIndex} on the files \filedir{\bullcntr.idx} and
357 % \filedir{\bullcntr.glo}, produced during the last of the
358 % aforesaid three \LaTeX\ runs, with the styles \filedir{gind.ist}
359 % and \filedir{gglo.ist}, respectively (these styles are part of
360 % the standard \LaTeX\ distribution); then pass
361 % \filedir{\bullcntr.dtx} through \LaTeX\ twice more.
362 %
363 % The documentation produced by default includes the
364 % \emph{Implementation} part too; see the beginning of this part
365 % for instructions on how to omit it.
366 %
367 % \subsection{License}
368 % \label{sS:License}
369 %
370 % The \packlass{\bullcntr} package is \emph{not} in the public
371 % domain: its author, Gustavo \textsc{Mezzetti}, owns the
372 % copyright, and in general retains all the rights therein; but as
373 % a special exception, the author grants you the permissions
374 % indicated below.
375 %
376 % \subsubsection{Distribution and/or modification}
377 %
378 % The \packlass{\bullcntr} package may be distributed and/or
379 % modified under the conditions of the \LaTeX\ Project Public
380 % License, either version~1.3 of this license or (at your option)
381 % any later version. The latest version of this license is in
382 % \begin{quote}
383 % \ttfamily
384 % http://www.latex-project.org/lppl.txt
385 % \end{quote}
386 % and version~1.3 or later is part of all distributions of \LaTeX\
387 % version 2005/12/01 or later.
388 %
389 % The \packlass{\bullcntr} package has the LPPL maintenance status
390 % ``author-maintained''.
391 %
392 % The file \filedir{manifest.txt} included along with this file
393 % specifies what the \packlass{\bullcntr} package consists of; more
394 % precisely, it explains how the locutions ``Work'' and ``Compiled
395 % Work'', used in the \LaTeX\ Project Public License, are to be
396 % interpreted in the case of this work.
397 %
398 % \subsubsection{Use}
399 %
400 % The use of the \packlass{\bullcntr} package is unrestricted,
401 % provided that you accept the terms and conditions of the \LaTeX\
402 % Project Public License and of the following subsection for what
403 % concerns the absence of any warranty.
404 %
405 % \subsubsection{No warranty}
406 %
407 % There is absolutely no warranty for the \packlass{\bullcntr}
408 % package. The Copyright Holder provides the \packlass{\bullcntr}
409 % package ``as is'', without warranty of any kind, either expressed
410 % or implied, including, but not limited to, the implied warranties
411 % of merchantability and fitness for a particular purpose. The
412 % entire risk as to the quality and performance of the
413 % \packlass{\bullcntr} package is with you. Should the
414 % \packlass{\bullcntr} package prove defective, you assume the cost
415 % of all necessary servicing, repair, or correction.
416 %
417 % In no event will The Copyright Holder, or any other party who may
418 % distribute and/or modify the \packlass{\bullcntr} package as
419 % permitted by the \LaTeX\ Project Public License, be liable to you
420 % for damages, including any general, special, incidental or
421 % consequential damages arising out of any use of the
422 % \packlass{\bullcntr} package or out of inability to use it
423 % (including, but not limited to, loss of data, data being rendered
424 % inaccurate, or losses sustained by anyone as a result of any
425 % failure of the \packlass{\bullcntr} package to operate with any
426 % other programs), even if The Copyright Holder or said other party
427 % has been advised of the possibility of such damages.
428 %
429 % \subsection{Your comments}
430 %
431 % If you have comments, suggestions, etc.\ about the
432 % \packlass{\bullcntr} package, please let me know them: I'll be
433 % happy to read what you think. A point that especially bothers me
434 % is the difficulty of choosing the ``right'' character for the
435 % bullets: "\textbullet" seems too big, while "\textperiodcentered"
436 % looks far too small, at least for me. But let me know your
437 % opinion!
438 %
439 % \section{How to use the \packlass{\bullcntr} package}
440 % \label{S:UsageCntr}
441 %
442 % The main purpose of the \packlass{\bullcntr} package is just to
443 % define the command "\bullcntr" for displaying the value of a
444 % counter. This command is analogous to "\fnsymbol": it works only
445 % if the value of the counter to print lies between 1 and~9
446 % (inclusive), and displays this value using a pleasant arrangement
447 % of bullets (whence the name). The patterns used to display the
448 % values from 1 to~9 are shown in fig.~\ref{fig:patterns}; of
449 % course, the grid lines shown in this picture are not drawn by the
450 % "\bullcntr" command. See fig.~\ref{fig:dimens}, in
451 % Subsection~\ref{sS:MainCode}, for a definition of the exact
452 % proportions of this grid; here it suffices to state that the
453 % triangle in Three is exactly equilateral, and that the hexagon in
454 % Six and Seven is perfectly regular. As it will be explained
455 % below, you can control what characters are drawn in the positions
456 % defined by the above patterns (not only bullets, but, for
457 % instance, hearts).
458 %
459 % \begin{figure}[tbp]
460 % \newcommand*{\bullgrid}[1]{^^A
461 % \linethickness{.2pt}^^A
462 % \multiput(0,0)(.5,0){5}{\line(0,1){2}}^^A
463 % \multiput(0,0)(0,1){3}{\line(1,0){2}}^^A
464 % \put(0,\oMr){\line(1,0){2}}^^A
465 % \put(0,\oPr){\line(1,0){2}}^^A
466 % \put(1,-.1){\makebox(0,0)[t]{\strut #1}}^^A
467 % }
468 % \newcommand*{\bullbull}[2]{^^A
469 % \put(#1,#2){\circle*{.2}}^^A
470 % }
471 % \centering
472 % \setlength{\unitlength}{1cm}
473 % \begin{picture}(10,10.5)
474 % \put(1,9.5){\makebox(0,0){
475 % \begin{picture}(2,2)
476 % \bullgrid{One}
477 % \bullbull{1}{1}
478 % \end{picture}}}
479 % \put(5,9.5){\makebox(0,0){
480 % \begin{picture}(2,2)
481 % \bullgrid{Two}
482 % \bullbull{0}{1}
483 % \bullbull{2}{1}
484 % \end{picture}}}
485 % \put(9,9.5){\makebox(0,0){
486 % \begin{picture}(2,2)
487 % \bullgrid{Three}
488 % \bullbull{0}{\oMr}
489 % \bullbull{2}{\oMr}
490 % \bullbull{1}{\oPr}
491 % \end{picture}}}
492 % \put(1,5.5){\makebox(0,0){
493 % \begin{picture}(2,2)
494 % \bullgrid{Four}
495 % \bullbull{1}{0}
496 % \bullbull{0}{1}
497 % \bullbull{2}{1}
498 % \bullbull{1}{2}
499 % \end{picture}}}
500 % \put(5,5.5){\makebox(0,0){
501 % \begin{picture}(2,2)
502 % \bullgrid{Five}
503 % \bullbull{0}{0}
504 % \bullbull{0}{2}
505 % \bullbull{1}{1}
506 % \bullbull{2}{0}
507 % \bullbull{2}{2}
508 % \end{picture}}}
509 % \put(9,5.5){\makebox(0,0){
510 % \begin{picture}(2,2)
511 % \bullgrid{Six}
512 % \bullbull{.5}{\oMr}
513 % \bullbull{1.5}{\oMr}
514 % \bullbull{0}{1}
515 % \bullbull{2}{1}
516 % \bullbull{.5}{\oPr}
517 % \bullbull{1.5}{\oPr}
518 % \end{picture}}}
519 % \put(1,1.5){\makebox(0,0){
520 % \begin{picture}(2,2)
521 % \bullgrid{Seven}
522 % \bullbull{.5}{\oMr}
523 % \bullbull{1.5}{\oMr}
524 % \bullbull{0}{1}
525 % \bullbull{1}{1}
526 % \bullbull{2}{1}
527 % \bullbull{.5}{\oPr}
528 % \bullbull{1.5}{\oPr}
529 % \end{picture}}}
530 % \put(5,1.5){\makebox(0,0){
531 % \begin{picture}(2,2)
532 % \bullbull{0}{\oMr}
533 % \bullbull{1}{\oMr}
534 % \bullbull{2}{\oMr}
535 % \bullgrid{Eight}
536 % \bullbull{.5}{1}
537 % \bullbull{1.5}{1}
538 % \bullbull{0}{\oPr}
539 % \bullbull{1}{\oPr}
540 % \bullbull{2}{\oPr}
541 % \end{picture}}}
542 % \put(9,1.5){\makebox(0,0){
543 % \begin{picture}(2,2)
544 % \bullgrid{Nine}
545 % \bullbull{0}{0}
546 % \bullbull{0}{1}
547 % \bullbull{0}{2}
548 % \bullbull{1}{0}
549 % \bullbull{1}{1}
550 % \bullbull{1}{2}
551 % \bullbull{2}{0}
552 % \bullbull{2}{1}
553 % \bullbull{2}{2}
554 % \end{picture}}}
555 % \end{picture}
556 % \caption{Arrangement of the bullets for the various counter values}
557 % \label{fig:patterns}
558 % \end{figure}
559 %
560 % The following subsections explain the usage of the
561 % \packlass{\bullcntr} package, which just defines---as said
562 % above---the new command "\bullcntr". If you intend to produce
563 % lists whose items are numbered with bullets, however, you should
564 % \emph{not} use directly this package, but rather the
565 % \packlass{\bullenum} package, which will be discussed in
566 % Section~\ref{S:UsageEnum}. The \packlass{\bullenum} package
567 % loads \packlass{bullcntr} for you, passing to the latter the
568 % options with which you called it.
569 %
570 % Don't forget that the versions of the \packlass{\bullcntr}
571 % package prior to~0.04 (this version) contain some coarse---and
572 % very embarassing!~:-(~---^^A ) paren match
573 % bugs.
574 %
575 % \subsection{Package invocation and options}
576 % \label{sS:InvoCntr}
577 %
578 % You invoke the \packlass{\bullcntr} package with the usual
579 % "\usepackage" declaration put in the preamble of your document.
580 % In this declaration you may specify one of the following,
581 % mutually exclusive options:
582 %^^A
583 % \begin{description}
584 %^^A
585 % \item[\sopt{largectrbull}]
586 % (Relatively) ``large'' bullets are used for all values from 1
587 % through~9. This produces exactly the same effect as a
588 % "\largectrbull" global declaration (see
589 % Subsection~\ref{sS:BullDecl}).
590 %^^A
591 % \item[\sopt{smallctrbull}]
592 % ``Small'' bullets are used for all values from 1 to~9. This has
593 % exactly the same effect as a "\smallctrbull" global declaration
594 % (see Subsection~\ref{sS:BullDecl}).
595 %^^A
596 % \item[\sopt{smartctrbull}]
597 % (Relatively) ``large'' bullets are used for the values from 1
598 % through~5 (inclusive), while ``small'' bullets are used for those
599 % greater than or equal to~6. This produces exactly the same
600 % effect as a "\smartctrbull" global declaration (see
601 % Subsection~\ref{sS:BullDecl}).
602 %^^A
603 % \item[\sopt{heartctrbull}]
604 % Hearts are used (instead of bullets) for all values from 1
605 % through~9. This produces exactly the same effect as a
606 % "\heartctrbull" global declaration (see
607 % Subsection~\ref{sS:BullDecl}).
608 %^^A
609 % \end{description}
610 %^^A
611 % If you don't specify any, the default option is
612 % \opt{smartctrbull}.
613 %
614 % For example, when preparing a valentine you might want to say
615 %\begin{verbatim}
616 %\usepackage[heartctrbull]{bullcntr}
617 %\end{verbatim}
618 % (See Subsection~\ref{sS:InvoEnum}, however, if what you need is
619 % to produce a list whose items are numbered with bullets.)
620 %
621 % Finer control over the appearance of bullets may be obtained by
622 % means of the ``hooks'' described in Subsection~\ref{sS:BullHook}.
623 %
624 % \subsection{The main command}
625 % \label{sS:bullcntr}
626 %
627 % \DescribeMacro{\bullcntr}
628 % This command is strictly analogous to the "\fnsymbol" command
629 % (cf.\ the \textsl{\LaTeX book}
630 % \cite[Subsection~C.8.4]{LaTeXbook}): you may use it directly in
631 % the text, as in
632 % \begin{flushleft}
633 % \small
634 % \ldots\texttt{the counter value displays as}"~\bullcntr{"\meta{ctr}"}"\ldots
635 % \end{flushleft}
636 % (where \meta{ctr} is a counter name, defined with "\newcounter"),
637 % or you may redefine the "\the"\meta{ctr} command, as in
638 % \begin{flushleft}
639 % \small
640 % "\renewcommand*{\the"\meta{ctr}"}{\bullcntr{"\meta{ctr}"}}"
641 % \end{flushleft}
642 % By way of example, in the case of a counter named \ctr{myctr},
643 % the source code in the two cases would be, respectively,
644 %\begin{verbatim}
645 %The counter value displays as~\bullcntr{myctr}.
646 %\end{verbatim}
647 % and
648 %\begin{verbatim}
649 %\renewcommand*{\themyctr}{\bullcntr{myctr}}
650 %\end{verbatim}
651 %
652 % If \( "\value{"\meta{ctr}"}"=0 \), the command
653 % "\bullcntr{"\meta{ctr}"}" tacitly typesets nothing (not even a
654 % space); if \( "\value{"\meta{ctr}"}"<0 \) or \(
655 % "\value{"\meta{ctr}"}">9 \), an error occurs.
656 %
657 % \subsection{Hooks for the bullets}
658 % \label{sS:BullHook}
659 %
660 % The main task of the \packlass{\bullcntr} package is to calculate
661 % the position of the ``bullets'' used to display the value of the
662 % given counter (see fig.~\ref{fig:patterns}); but you are free to
663 % decide what characters are actually drawn in these positions:
664 % they need not necessarily be ``bullets''. Indeed, two ``hooks''
665 % are provided in the package to define the actual characters
666 % employed, and the package simply invokes these hooks.
667 %
668 % \DescribeMacro{\counterlargebullet}
669 % When the value of the counter being displayed is less than~6
670 % (less than~6 bullets need to be drawn), the "\bullcntr" command
671 % invokes the "\counterlargebullet" macro to draw each of them. If
672 % you want, you should redefine this macro (using "\renewcommand")
673 % so that it generates a symbol suitable for arrangements in which
674 % the ``bullets'' are relatively spaced out. For example,
675 %\begin{verbatim}
676 %\renewcommand*{\counterlargebullet}{\textbullet}
677 %\end{verbatim}
678 % You don't \emph{need} to redefine this command: a convenient
679 % default definition is already set by the \packlass{\bullcntr}
680 % package itself.
681 %
682 % \DescribeMacro{\countersmallbullet}
683 % When, on the other hand, the value of the counter being displayed
684 % is greater than or equal to~6 (6~or more bullets need to be
685 % drawn), the "\bullcntr" command calls the "\countersmallbullet"
686 % macro. It is intended that this macro typesets a character
687 % suitable for situations in which the ``bullets'' have to be
688 % grouped in a compact cluster; typically, this means that a
689 % smaller ``bullet'' is used than the one typeset by
690 % "\counterlargebullet", although it is perfectly in order to use
691 % the same character in both situations. If you want (but you
692 % don't \emph{need} to do this, since the \packlass{\bullcntr}
693 % package already defines this macro) you may change the definition
694 % with "\renewcommand", \emph{e.g.}:
695 %\begin{verbatim}
696 %\renewcommand*{\countersmallbullet}{\textperiodcentered}
697 %\end{verbatim}
698 %
699 % Fragile commands used in the definition of both hooks should be
700 % "\protect"'ed.
701 %
702 % ``Macho \TeX\ programmers'' may also use "\def" instead of
703 % "\renewcommand", \emph{e.g.}:
704 %\begin{verbatim}
705 %\def\counterlargebullet{\textbullet}
706 %\def\countersmallbullet{\textperiodcentered}
707 %\end{verbatim}
708 % (Actually, in a case like this, even "\let" could be used.)
709 %
710 % \subsection{Declarations for predefined bullet styles}
711 % \label{sS:BullDecl}
712 %
713 % To spare you the nuisance of redefining the two hooks mentioned
714 % in Subsection~\ref{sS:BullHook}, at least in normal situations,
715 % four basic ``bullet styles'' are already predefined by the
716 % \packlass{\bullcntr} package, covering what the author believes
717 % are the most common cases. You can switch to any of these
718 % predefined styles by means of the following four declarations.
719 %
720 % \DescribeMacro{\largectrbull}
721 % This declaration causes (relatively) ``large'' bullets to be used
722 % for all values from 1 to~9.
723 %
724 % \DescribeMacro{\smallctrbull}
725 % This declaration causes ``small'' bullets to be used for all
726 % values from 1 to~9.
727 %
728 % \DescribeMacro{\smartctrbull}
729 % This declaration causes (relatively) ``large'' bullets to be used
730 % for values from 1 to~5 (inclusive), and ``small'' bullets for
731 % values equal to or above~6.
732 %
733 % \DescribeMacro{\heartctrbull}
734 % With this declaration, little hearts will be used for all values
735 % from 1 to~9.
736 %
737 % These are in all respects normal declarations, obeying to
738 % ordinary scoping rules. The corresponding options described in
739 % Subsection~\ref{sS:InvoCntr} simply set the style at the outer
740 % (global, or document-wide) level.
741 %
742 % \section{How to use the \packlass{\bullenum} package}
743 % \label{S:UsageEnum}
744 %
745 % The \packlass{\bullcntr} package was conceived for the purpose of
746 % imitating in print an unusual way of numbering items in a list,
747 % that the author saw in certain handwritten notes (see the
748 % Introduction). With the "\bullcntr" command at hand, this could
749 % be achieved simply by saying something like
750 %\begin{verbatim}
751 %\begin{enumerate}
752 % \renewcommand*{\theenumi}{\bullcntr{enumi}}
753 % \renewcommand*{\labelenumi}{\theenumi}
754 %\end{verbatim}
755 % \begin{flushleft}
756 % \small
757 % \texttt{\ \ \ \ }\meta{items}
758 % \end{flushleft}
759 %\begin{verbatim}
760 %\end{enumerate}
761 %\end{verbatim}
762 % This, nonetheless, is not perfect, since it breaks if the
763 % \env{enumerate} environment is moved inside another
764 % \env{enumerate}, because of the explicit mention of "\theenumi"
765 % and of "\labelenumi".
766 %
767 % For this reason, and also to facilitate the use of the
768 % "\bullcntr" command for numbering list items, an ancillary
769 % package has been added to the \packlass{\bullcntr} package; this
770 % ancillary package, called \packlass{\bullenum}, simply defines
771 % the \env{bullenum} environment, a variation of \env{enumerate}
772 % which numbers its items using the "\bullcntr" command. Indeed,
773 %\begin{verbatim}
774 %\begin{bullenum}
775 %\end{verbatim}
776 % \begin{flushleft}
777 % \small
778 % \texttt{\ \ \ \ }\meta{items}
779 % \end{flushleft}
780 %\begin{verbatim}
781 %\end{bullenum}
782 %\end{verbatim}
783 % is equivalent to
784 % \begin{flushleft}
785 % \small
786 % "\begin{enumerate}"\\
787 % " \renewcommand*{\theenum"\meta{lvl}"}{\bullcntr{enum"\meta{lvl}"}}"\\
788 % " \renewcommand*{\labelenum"\meta{lvl}"}{\theenum"\meta{lvl}"}"
789 % \end{flushleft}
790 % \begin{flushleft}
791 % \small
792 % \texttt{\ \ \ \ }\meta{items}\\[\topsep]
793 % \end{flushleft}
794 %\begin{verbatim}
795 %\end{enumerate}
796 %\end{verbatim}
797 % where \meta{lvl} is \texttt{i}, \texttt{ii}, \texttt{iii},
798 % or~\texttt{iv}, depending on the current level of the
799 % \env{enumerate} environment.
800 %
801 % In other words, \env{bullenum} can be used in every place where
802 % \env{enumerate} can, and numbers its items with an increasing
803 % number of bullets, regardless of the current definition of
804 % "\theenum"\meta{lvl} and "\labelenum"\meta{lvl}. Of course, the
805 % environment must contain no more than 9~items. Moreover, if you
806 % use "\label" to set up a reference, subsequent "\ref"'s will
807 % typeset the reference as a ``bulletted'' number, using, for the
808 % ``bullets'', the character that was current at the time the
809 % "\label" was encountered (in brief, they will do the right
810 % thing).
811 %
812 % Notice that you should \emph{not} load the \packlass{\bullcntr}
813 % package if you invoke \packlass{\bullenum}, because the latter
814 % calls the former. As explained below, you may pass to
815 % \packlass{\bullenum} the options that you would require from
816 % \packlass{\bullcntr}: the outer package will forward them to the
817 % inner one. Actually, most users will just use the
818 % \packlass{\bullenum} package, and never call \packlass{\bullcntr}
819 % directly.
820 %
821 % \subsection{Package invocation and options}
822 % \label{sS:InvoEnum}
823 %
824 % You invoke the \packlass{\bullenum} package with the usual
825 % "\usepackage" declaration put in the preamble of your document.
826 % In this declaration you may specify exactly the same options that
827 % you would pass to the \packlass{\bullcntr} package, with the same
828 % meaning. The \packlass{\bullenum} package calls
829 % \packlass{bullcntr} for you, just passing on to it the options
830 % you asked for.
831 %
832 % Continuing our example of valentines: if what you actually want
833 % is to produce a list numbered with hearts, you should \emph{not}
834 % say
835 %\begin{verbatim}
836 %\usepackage[heartctrbull]{bullcntr}
837 %\end{verbatim}
838 % as deceitfully suggested in Subsection~\ref{sS:InvoCntr} (well,
839 % actually we had not spoken of lists there, had we?), but rather
840 %\begin{verbatim}
841 %\usepackage[heartctrbull]{bullenum}
842 %\end{verbatim}
843 %
844 % \subsection{The main environment}
845 % \label{sS:bullenum}
846 %
847 % \DescribeEnv{bullenum}
848 % This environment is syntactically analogous to \env{enumerate},
849 % but numbers its items with an increasing number of bullets (using
850 % the "\bullcntr" command). You must include no more than 9~items
851 % in this environment. The style of the bullets is governed by the
852 % declarations described in Subsection~\ref{sS:BullDecl}, according
853 % to ordinary scoping rules. A change local to the environment
854 % being employed can be obtained by simply enclosing the relevant
855 % declaration inside the environment itself; \emph{e.g.},
856 %\begin{verbatim}
857 %\begin{bullenum}
858 % \smallctrbull
859 %\end{verbatim}
860 % \begin{flushleft}
861 % \small
862 % \texttt{\ \ \ \ }\meta{items}
863 % \end{flushleft}
864 %\begin{verbatim}
865 %\end{bullenum}
866 %\end{verbatim}
867 % will use ``small'' bullets regardless of whatever style might
868 % have been in force outside the \env{bullenum} environment.
869 %
870 % If you want finer control over the appearance of the ``bullets'',
871 % just redefine the hooks of
872 % Subsection~\ref{sS:BullHook}; doing this inside the environment
873 % itself will keep changes to the hooks local. For example, you
874 % might say
875 %\begin{verbatim}
876 %\begin{bullenum}
877 % \renewcommand*{\counterlargebullet}{$\scriptscriptstyle \diamondsuit$}
878 % \renewcommand*{\countersmallbullet}{\counterlargebullet}
879 %\end{verbatim}
880 % \begin{flushleft}
881 % \small
882 % \texttt{\ \ \ \ }\meta{items}
883 % \end{flushleft}
884 %\begin{verbatim}
885 %\end{bullenum}
886 %\end{verbatim}
887 % (yes, ``macho \TeX\ programmers'' may also use "\def", or "\let"
888 % where appropriate).
889 %
890 % Of course, this environment does not affect the definition of
891 % "\theenum"\meta{lvl} and of "\labelenum"\meta{lvl} that are valid
892 % outside the environment itself, for \( \meta{lvl} =
893 % \texttt{i}\ldots\texttt{iv} \).
894 %
895 % \StopEventually{
896 % \setcounter{secnumdepth}{0}
897 % \providecommand*\bysame{\leavevmode\hbox to3em{\hrulefill}\thinspace}
898 %
899 % \clearpage
900 % \begin{thebibliography}{9}
901 % \addcontentsline{toc}{section}{\refname}
902 %
903 % \bibitem{LaTeXbook}
904 % L.~Lamport, \emph{\LaTeX---A Document Preparation System---User's
905 % Guide and Reference Manual}, 2nd~edition, Addison-Wesley,
906 % Reading, 1994.
907 %
908 % \end{thebibliography}
909 % }
910 %
911 %
912 %
913 % \clearpage
914 % \part{Implementation}
915 %
916 % \section{About this part}
917 %
918 % This part is of interest only to \LaTeX\ hackers; to avoid
919 % having this part printed, look in the file \filedir{\filename}
920 % for a line that looks \emph{exactly} like this
921 % \begin{verbatim}%% \OnlyDescription % uncomment to discard Implementation part\end{verbatim}
922 % and remove the two leading percent signs ("%%").
923 %
924 % \section{A driver for this document}
925 %
926 % This part of the file is \emph{not} included in any generated file:
927 % it is simply the driver.
928 % \begin{macrocode}
929 %<*driver>
930 % \end{macrocode}
931 %
932 % To begin with, we load the \packlass{ltxdoc} class.
933 % \begin{macrocode}
934 \documentclass[a4paper]{ltxdoc}
935 % \end{macrocode}
936 % We now set a few typesetting options.
937 % First of all, we want a history listing and a full index, the latter
938 % organized by line numbers.
939 % \begin{macrocode}
940 \RecordChanges
941 \EnableCrossrefs
942 \CodelineIndex
943 % \end{macrocode}
944 % If you don't want to include the second part of this document,
945 % \emph{Implementation}, uncomment the line containing the command
946 % "\OnlyDescription".
947 % \begin{macrocode}
948 %% \OnlyDescription % uncomment to discard Implementation part
949 % \end{macrocode}
950 % Finally, setting "\hfuzz" and "\vfuzz" to 0~points is only one
951 % of the many neurotic symptoms of the author!
952 % \begin{macrocode}
953 \hfuzz = 0pt
954 \vfuzz = 0pt
955 % \end{macrocode}
956 % Now input this same file, using \DS\ conventions.
957 % \begin{macrocode}
958 \begin{document}
959 \DocInput{bullcntr.dtx}
960 % \end{macrocode}
961 % Then print the change list and the index. We put these commands in
962 % the driver, rather than in the comments of this file, because
963 % producing the change list and the index is somewhat cumbersome, and some
964 % users could prefer to omit them: such users should simply use a
965 % different driver.
966 % \begin{macrocode}
967 % \clearpage % attach Change History below References
968 \PrintChanges
969 \clearpage \PrintIndex
970 % \end{macrocode}
971 % When this file is read directly by \LaTeX\ without the intervention
972 % of \DS, the following line will make \TeX\ stop
973 % reading.
974 % \begin{macrocode}
975 \end{document}
976 % \end{macrocode}
977 % End of driver module.
978 % \begin{macrocode}
979 %</driver>
980 % \end{macrocode}
981 %
982 % \section{The code for the \packlass{\bullcntr} package}
983 %
984 % This part of the file goes into \filedir{\bullcntr.sty}.
985 % \begin{macrocode}
986 %<*bullcntr>
987 % \end{macrocode}
988 %
989 % \subsection{Identification}
990 %
991 % The usual identification. Is there a real need for this version
992 % of \LaTeXe?
993 % \begin{macrocode}
994 \NeedsTeXFormat{LaTeX2e}[1998/06/01] % LaTeX2e is required!
995 \ProvidesPackage{bullcntr}
996 [2007/04/02 v0.04 (**development**)]
997 % \end{macrocode}
998 %
999 % \subsection{Initial code}
1000 %
1001 % The code pertaining to the bullet styles is needed in the option
1002 % processing phase, so it must be defined here.
1003 %
1004 % \subsubsection{Hooks for the bullets}
1005 % \label{sS:BullHookImpl}
1006 %
1007 % Here we set the default definitions. Actually, these defaults
1008 % will be re-established (or possibly changed, in future versions)
1009 % by "\ExecuteOptions", below; nonetheless, I think it's always
1010 % better to do things twice than to run the risk of not doing them
1011 % at all!
1012 %
1013 % \begin{macro}{\counterlargebullet}
1014 % The \packlass{\bullcntr} package invokes this macro to draw the
1015 % bullets, when the value of the counter being displayed is less
1016 % than six. The default definition is a "\bullet" in script
1017 % style~($\scriptstyle\bullet$), but the user is free to change it
1018 % with "\renewcommand" (macho \TeX\ programmers may also use
1019 % "\def", or even "\let").
1020 % \begin{macrocode}
1021 \newcommand*\counterlargebullet{$\scriptstyle \bullet$}
1022 % \end{macrocode}
1023 % \end{macro}
1024 %
1025 % \begin{macro}{\countersmallbullet}
1026 % This is the command invoked to draw the bullets when the value of
1027 % the counter being displayed is greater or equal than six.
1028 % Defaults to a "\bullet" in scriptscript
1029 % style~($\scriptscriptstyle \bullet$), but may be changed with
1030 % "\renewcommand" (or "\def", or "\let").
1031 % \begin{macrocode}
1032 \newcommand*\countersmallbullet{$\scriptscriptstyle \bullet$}
1033 % \end{macrocode}
1034 % \end{macro}
1035 %
1036 % The question arises, whether these definitions are appropriate.
1037 % Their main drawback is that they bypass the machinery set up for
1038 % using symbols from an extended character set when they are
1039 % available. The problem is that "\textbullet" is simply too
1040 % large, and "\textperiodcentered" far too small\ldots
1041 %
1042 % Precautions have been taken to assure that these macros are
1043 % \emph{fully} expanded, without stopping to the first-level
1044 % expansion, when a reference to a counter displayed using
1045 % "\bullcntr" is generated. This is important in situations in
1046 % which the user has done something like this (which looks
1047 % absolutely natural):
1048 %^^A
1049 % \begin{flushleft}
1050 % \small
1051 % "\renewcommand*{\counterlargebullet}{"\meta{some code}"}"\\
1052 % "\renewcommand*{\countersmallbullet}{\counterlargebullet}"
1053 % \end{flushleft}
1054 %^^A
1055 % If "\countersmallbullet" were expanded just to the first level,
1056 % this would result in using the definition of
1057 % "\counterlargebullet" that is in force when the \emph{reference},
1058 % and not the counter value, is typeset.
1059 %
1060 % \subsubsection{Declarations for predefined bullet styles}
1061 %
1062 % Each of the following commands, intended to be used as a
1063 % declaration without arguments, sets a convenient definition for
1064 % the hooks defined in Subsection~\ref{sS:BullHookImpl}.
1065 %
1066 % \begin{macro}{\heartctrbull}
1067 % Use hearts for all values from 1 to~9.
1068 % \begin{macrocode}
1069 \newcommand*\heartctrbull{%
1070 \def\counterlargebullet{$\scriptscriptstyle \heartsuit$}%
1071 \let\countersmallbullet\counterlargebullet
1072 }
1073 % \end{macrocode}
1074 % \end{macro}
1075 %
1076 % \begin{macro}{\smallctrbull}
1077 % Use ``small'' bullets for all values from 1 to~9.
1078 % \begin{macrocode}
1079 \newcommand*\smallctrbull{%
1080 \def\counterlargebullet{$\scriptscriptstyle \bullet$}%
1081 \let\countersmallbullet\counterlargebullet
1082 }
1083 % \end{macrocode}
1084 % \end{macro}
1085 %
1086 % \begin{macro}{\largectrbull}
1087 % Use ``large'' bullets for all values from 1 to~9.
1088 % \begin{macrocode}
1089 \newcommand*\largectrbull{%
1090 \def\counterlargebullet{$\scriptstyle \bullet$}%
1091 \let\countersmallbullet\counterlargebullet
1092 }
1093 % \end{macrocode}
1094 % \end{macro}
1095 %
1096 % \begin{macro}{\smartctrbull}
1097 % Use ``large'' bullets for values from 1 to~5, and ``small'' ones
1098 % for values from 6 to~9.
1099 % \begin{macrocode}
1100 \newcommand*\smartctrbull{%
1101 \def\counterlargebullet{$\scriptstyle \bullet$}%
1102 \def\countersmallbullet{$\scriptscriptstyle \bullet$}
1103 }
1104 % \end{macrocode}
1105 % \end{macro}
1106 %
1107 % \subsection{Declaration of options}
1108 %
1109 % As a general rule, options pertaining to the same functional group
1110 % are declared in reverse order of desirability, the default option of
1111 % the group being declared last. This assures that if more than
1112 % one option of the same group is erroneously asked for by the
1113 % user, the ``most desirable'' one (whatever this means) is
1114 % executed last, thereby remaining in effect.
1115 %
1116 % Here we just have the options for setting the bullet style. Each
1117 % of them simply invokes its corresponding declaration.
1118 %
1119 % \begin{macrocode}
1120 \DeclareOption{heartctrbull}{\heartctrbull}
1121 \DeclareOption{smallctrbull}{\smallctrbull}
1122 \DeclareOption{largectrbull}{\largectrbull}
1123 \DeclareOption{smartctrbull}{\smartctrbull}
1124 % \end{macrocode}
1125 %
1126 % \subsection{Option processing}
1127 %
1128 % Nothing special to note here.
1129 %
1130 % \begin{macrocode}
1131 \ExecuteOptions{smartctrbull}
1132 \ProcessOptions\relax
1133 % \end{macrocode}
1134 %
1135 % \subsection{Package loading}
1136 %
1137 % This package requires no helper packages.
1138 %
1139 % \subsection{Main code}
1140 % \label{sS:MainCode}
1141 %
1142 % Fig.~\ref{fig:dimens} shows the exact (theoretical) dimensions of
1143 % the grid used to place the bullets; we already saw in
1144 % fig.~\ref{fig:patterns}, in Section~\ref{S:UsageCntr}, on which
1145 % nodes of this grid the bullets are placed for each value of the
1146 % counter being displayed. The grid is used assuming a unit of
1147 % measure equal to 1~ex.
1148 %
1149 % \begin{figure}[tbp]
1150 % \centering
1151 % \setlength{\unitlength}{3cm}
1152 % \begin{picture}(3.1666667,3.2)(0,-.8333333)
1153 % \thicklines
1154 % \multiput(0,0)(.5,0){5}{\line(0,1){2}}
1155 % \multiput(0,0)(0,1){3}{\line(1,0){2}}
1156 % \put(0,\oMr){\line(1,0){2}}
1157 % \put(0,\oPr){\line(1,0){2}}
1158 % \linethickness{.2pt}
1159 % \multiput(0,0)(2,0){2}{\line(0,-1){.77}}
1160 % \multiput(.5,0)(.5,0){3}{\line(0,-1){.43}}
1161 % \multiput(.3,-.3333333)(.5,0){4}{\vector(-1,0){.3}}
1162 % \multiput(.2,-.3333333)(.5,0){4}{\vector(1,0){.3}}
1163 % \multiput(.25,-.5)(.5,0){4}{\makebox(0,0)[b]{$\frac{1}{2}$}}
1164 % \put(1.5,-.6666667){\vector(-1,0){1.5}}
1165 % \put(.5,-.6666667){\vector(1,0){1.5}}
1166 % \put(1,-.6666667){\makebox(0,0)[t]{\strut $2$}}
1167 % \multiput(2,0)(0,2){2}{\line(1,0){1.1}}
1168 % \put(2,\oMr){\line(1,0){.43}}
1169 % \put(2,\oPr){\line(1,0){.43}}
1170 % \put(2,1){\line(1,0){.77}}
1171 % \put(2.3333333,.7){\vector(0,-1){.5660254}}
1172 % \put(2.3333333,.3){\vector(0,1){.7}}
1173 % \put(2.3333333,1.7){\vector(0,-1){.7}}
1174 % \put(2.3333333,1.3){\vector(0,1){.5660254}}
1175 % \put(2.3333333,.5669873){\makebox(0,0)[l]{$\,\frac{\sqrt{3}}{2}$}}
1176 % \put(2.3333333,1.4330127){\makebox(0,0)[l]{$\,\frac{\sqrt{3}}{2}$}}
1177 % \multiput(2.6666667,.4)(0,1){2}{\vector(0,1){.6}}
1178 % \multiput(2.6666667,.6)(0,1){2}{\vector(0,-1){.6}}
1179 % \multiput(2.6666667,.5)(0,1){2}{\makebox(0,0)[l]{$\,1$}}
1180 % \put(3,.5){\vector(0,1){1.5}}
1181 % \put(3,1.5){\vector(0,-1){1.5}}
1182 % \put(3,1){\makebox(0,0)[l]{$\,2$}}
1183 % \multiput(0,2)(.5,0){5}{\line(0,1){.1666667}}
1184 % \multiput(0,2.2666667)(.5,0){5}{\circle{.2}}
1185 % \put(0 ,2.2666667){\makebox(0,0){1}}
1186 % \put( .5,2.2666667){\makebox(0,0){2}}
1187 % \put(1 ,2.2666667){\makebox(0,0){3}}
1188 % \put(1.5,2.2666667){\makebox(0,0){4}}
1189 % \put(2 ,2.2666667){\makebox(0,0){5}}
1190 % \end{picture}
1191 % \caption{Dimensions of the grid defining the position of the bullets}
1192 % \label{fig:dimens}
1193 % \end{figure}
1194 %
1195 % \subsubsection{Basic drawing macros}
1196 %
1197 % \begin{macro}{\@b@ll@box}
1198 % The task of this macro is simply to hide its argument in a
1199 % zero-dimensional box. I know, \LaTeX\ kernel commands should be
1200 % used for this purpose, but\ldots
1201 % \begin{macrocode}
1202 \@ifdefinable\@b@ll@box{\def\@b@ll@box#1{%
1203 \hb@xt@ \z@ {%
1204 \hss\vbox to \z@ {%
1205 \vss\hbox{#1}\vss
1206 }\hss
1207 }%
1208 }}
1209 % \end{macrocode}
1210 % \end{macro}
1211 %
1212 % \begin{macro}{\@b@ll@kernem}
1213 % Two convenient abbreviations for sparing tokens in subsequent
1214 % macros: the first\ldots
1215 % \begin{macrocode}
1216 \@ifdefinable\@b@ll@kernem{\def\@b@ll@kernem{\kern 1ex }}
1217 % \end{macrocode}
1218 % \end{macro}
1219 % \begin{macro}{\@b@ll@kernen}
1220 % \ldots\ and the second.
1221 % \begin{macrocode}
1222 \@ifdefinable\@b@ll@kernen{\def\@b@ll@kernen{\kern .5ex }}
1223 % \end{macrocode}
1224 % \end{macro}
1225 %
1226 % \begin{macro}{\@b@ll@full@row}
1227 % This macro constructs a zero-height (and zero-depth) "\hbox" with
1228 % three inner zero-dimensional boxes, each containing one of the
1229 % three arguments. These inner boxes are spaced out so as to place
1230 % them in the columns marked \circnumb{1}, \circnumb{3}
1231 % and~\circnumb{5} in fig.~\ref{fig:dimens}. The idea is that this
1232 % macro produces a row of bullets.
1233 % \begin{macrocode}
1234 \@ifdefinable\@b@ll@full@row{\def\@b@ll@full@row#1#2#3{%
1235 \hbox{%
1236 \thinspace
1237 \@b@ll@box{#1}%
1238 \@b@ll@kernem
1239 \@b@ll@box{#2}%
1240 \@b@ll@kernem
1241 \@b@ll@box{#3}%
1242 \thinspace
1243 }%
1244 }}
1245 % \end{macrocode}
1246 % \end{macro}
1247 %
1248 % \begin{macro}{\@b@ll@half@row}
1249 % This macro is similar to "\@b@ll@full@row": it produces a row of
1250 % bullets as well, but with only two boxes, that end up in the
1251 % columns marked \circnumb{2} and~\circnumb{4} in
1252 % fig.~\ref{fig:dimens}.
1253 % \begin{macrocode}
1254 \@ifdefinable\@b@ll@half@row{\def\@b@ll@half@row#1#2{%
1255 \hbox{%
1256 \thinspace\@b@ll@kernen
1257 \@b@ll@box{#1}%
1258 \@b@ll@kernem
1259 \@b@ll@box{#2}%
1260 \thinspace\@b@ll@kernen
1261 }%
1262 }}
1263 % \end{macrocode}
1264 % \end{macro}
1265 %
1266 % \begin{macro}{\@b@ll@full@skip}
1267 % When the rows produced by "\@b@ll@full@row" or by
1268 % "\@b@ll@half@row" are being stacked to compose the desired
1269 % pattern, this macro is invoked to separate them with a vertical
1270 % space of $1$~unit (that is, $1$~ex).
1271 % \begin{macrocode}
1272 \@ifdefinable\@b@ll@full@skip{\def\@b@ll@full@skip{%
1273 \vskip 1ex \relax
1274 }}
1275 % \end{macrocode}
1276 % \end{macro}
1277 %
1278 % \begin{macro}{\@b@ll@redu@skip}
1279 % Similar to the above, but the vertical space measures
1280 % $\frac{\sqrt{3}}{2}$~units (that is, $\frac{\sqrt{3}}{2}$~ex).
1281 % \begin{macrocode}
1282 \@ifdefinable\@b@ll@redu@skip{\def\@b@ll@redu@skip{%
1283 \vskip .866025403785ex \relax
1284 }}
1285 % \end{macrocode}
1286 % \end{macro}
1287 %
1288 % \subsubsection{Macros for drawing the bullet patterns}
1289 %
1290 % When setting a reference, "\@currentlabel" is set by means of a
1291 % (protected) "\edef"; hence, if we have redefined "\the"\meta{ctr}
1292 % (where \meta{ctr} is the counter being referenced) as
1293 % "\bullcntr{"\meta{ctr}"}", the "\bullcntr" command is expanded,
1294 % and indeed \emph{has} to be expanded (so, defining it with
1295 % "\DeclareRobustCommand" is absolutely pointless). In previous
1296 % versions, this command broke down miserably in such circumstance.
1297 % So, let us rethink the whole thing with more ponderation, trying
1298 % not to confuse expansion and digestion like a newbie.
1299 %
1300 % The general idea runs as depicted in the following list.
1301 %
1302 % \begin{enumerate}
1303 %
1304 % \item
1305 % "\bullcntr" calls "\@b@ll@cntr", converting the counter name into
1306 % the corresponding internal register (expansion).
1307 %
1308 % \item\label{item:b@ll@}
1309 % "\@b@ll@cntr" tests whether the counter value is below~6
1310 % (expansion) and calls "\@b@ll@@cntr" passing the appropriate
1311 % "\counter"$\,*\,$\texttt{bullet} command.
1312 %
1313 % \item\label{item:b@ll@@}
1314 % "\@b@ll@@cntr" selects which pattern to draw, depending on the
1315 % counter value (expansion), and calls the appropriate macro among
1316 % the ones defined below. At this point the call could also be
1317 % "\protect"'ed, since no further expansion is required, when
1318 % setting a reference, in order to select the correct number (and
1319 % type) of bullets. The "\@b@ll@@cntr" macro receives in~\#1 the
1320 % macro to be used to draw the bullets and in~\#2 the internal
1321 % count register.
1322 %
1323 % \item
1324 % "\ensuremath" and everything that has to be digested is put in
1325 % the macros defined below.
1326 %
1327 % \end{enumerate}
1328 %
1329 % Steps \ref{item:b@ll@} and~\ref{item:b@ll@@} could be combined,
1330 % thus eliminating one macro, but I feel that the code is more
1331 % readable if the two steps are kept separate.
1332 %
1333 % We continue our bottom-up approach in ordering the macro
1334 % definitions.
1335 %
1336 % \begin{macro}{\@b@ll@vcent}
1337 % The command that ultimately does the typesetting. It might be
1338 % called either from outside or from inside math mode; so
1339 % "\ensuremath" for the "\vcenter" that aligns the box of bullets
1340 % on the math axis. The boxes themselves are produced by the
1341 % macros passed in argument~\#1.
1342 % \begin{macrocode}
1343 \@ifdefinable\@b@ll@vcent{\def\@b@ll@vcent#1{%
1344 \ensuremath{\vcenter{\offinterlineskip #1}}%
1345 }}
1346 % \end{macrocode}
1347 % \end{macro}
1348 %
1349 % A series of macros follows, each of which typesets a specific
1350 % bullet pattern. They all invoke "\@b@ll@vcent", passing in its
1351 % argument the appropriate macros. In their own argument, they
1352 % receive the code that has to be employed to produce the bullets
1353 % (the \emph{expansion} of "\counter"$\,*\,$\texttt{bullet}). To
1354 % avoid proliferation of macros, we do not define them with
1355 % "\DeclareRobustCommand"; rather, we shall "\protect" them when
1356 % invoking them, below. (\emph{Begin to think:} why not to make
1357 % these macros accessible at the user level, calling them,
1358 % \emph{e.g.}, "\bullcntrone", "\bullcntrtwo", etc.? In this case,
1359 % "\DeclareRobustCommand" could be considered.)
1360 %
1361 % \begin{macro}{\@b@ll@one}
1362 % Macro for value~1. Just one row with a bullet in the middle:
1363 % \begin{macrocode}
1364 \@ifdefinable\@b@ll@one{\def\@b@ll@one#1{\@b@ll@vcent{%
1365 \@b@ll@full@row{}{#1}{}%
1366 }}}
1367 % \end{macrocode}
1368 % \end{macro}
1369 %
1370 % \begin{macro}{\@b@ll@two}
1371 % Macro for value~2. Just one row with two bullets at both ends:
1372 % \begin{macrocode}
1373 \@ifdefinable\@b@ll@two{\def\@b@ll@two#1{\@b@ll@vcent{%
1374 \@b@ll@full@row{#1}{}{#1}%
1375 }}}
1376 % \end{macrocode}
1377 % \end{macro}
1378 %
1379 % \begin{macro}{\@b@ll@three}
1380 % Macro for value~3. One row with a centered bullet and one with
1381 % two bullets at the ends, separated by a vertical space of
1382 % $\sqrt{3}$~units:
1383 % \begin{macrocode}
1384 \@ifdefinable\@b@ll@three{\def\@b@ll@three#1{\@b@ll@vcent{%
1385 \@b@ll@full@row{}{#1}{}%
1386 \@b@ll@redu@skip
1387 \@b@ll@redu@skip
1388 \@b@ll@full@row{#1}{}{#1}%
1389 }}}
1390 % \end{macrocode}
1391 % \end{macro}
1392 %
1393 % \begin{macro}{\@b@ll@four}
1394 % And so on: macro for value~4\ldots
1395 % \begin{macrocode}
1396 \@ifdefinable\@b@ll@four{\def\@b@ll@four#1{\@b@ll@vcent{%
1397 \@b@ll@full@row{}{#1}{}%
1398 \@b@ll@full@skip
1399 \@b@ll@full@row{#1}{}{#1}%
1400 \@b@ll@full@skip
1401 \@b@ll@full@row{}{#1}{}%
1402 }}}
1403 % \end{macrocode}
1404 % \end{macro}
1405 %
1406 % \begin{macro}{\@b@ll@five}
1407 % \ldots for value~5\ldots
1408 % \begin{macrocode}
1409 \@ifdefinable\@b@ll@five{\def\@b@ll@five#1{\@b@ll@vcent{%
1410 \@b@ll@full@row{#1}{}{#1}%
1411 \@b@ll@full@skip
1412 \@b@ll@full@row{}{#1}{}%
1413 \@b@ll@full@skip
1414 \@b@ll@full@row{#1}{}{#1}%
1415 }}}
1416 % \end{macrocode}
1417 % \end{macro}
1418 %
1419 % \begin{macro}{\@b@ll@six}
1420 % \ldots for~6\ldots
1421 % \begin{macrocode}
1422 \@ifdefinable\@b@ll@six{\def\@b@ll@six#1{\@b@ll@vcent{%
1423 \@b@ll@half@row{#1}{#1}%
1424 \@b@ll@redu@skip
1425 \@b@ll@full@row{#1}{}{#1}%
1426 \@b@ll@redu@skip
1427 \@b@ll@half@row{#1}{#1}%
1428 }}}
1429 % \end{macrocode}
1430 % \end{macro}
1431 %
1432 % \begin{macro}{\@b@ll@seven}
1433 % \ldots 7\ldots
1434 % \begin{macrocode}
1435 \@ifdefinable\@b@ll@seven{\def\@b@ll@seven#1{\@b@ll@vcent{%
1436 \@b@ll@half@row{#1}{#1}%
1437 \@b@ll@redu@skip
1438 \@b@ll@full@row{#1}{#1}{#1}%
1439 \@b@ll@redu@skip
1440 \@b@ll@half@row{#1}{#1}%
1441 }}}
1442 % \end{macrocode}
1443 % \end{macro}
1444 %
1445 % \begin{macro}{\@b@ll@eight}
1446 % \ldots 8\ldots
1447 % \begin{macrocode}
1448 \@ifdefinable\@b@ll@eight{\def\@b@ll@eight#1{\@b@ll@vcent{%
1449 \@b@ll@full@row{#1}{#1}{#1}%
1450 \@b@ll@redu@skip
1451 \@b@ll@half@row{#1}{#1}%
1452 \@b@ll@redu@skip
1453 \@b@ll@full@row{#1}{#1}{#1}%
1454 }}}
1455 % \end{macrocode}
1456 % \end{macro}
1457 %
1458 % \begin{macro}{\@b@ll@nine}
1459 % \ldots and~9:
1460 % \begin{macrocode}
1461 \@ifdefinable\@b@ll@nine{\def\@b@ll@nine#1{\@b@ll@vcent{%
1462 \@b@ll@full@row{#1}{#1}{#1}%
1463 \@b@ll@full@skip
1464 \@b@ll@full@row{#1}{#1}{#1}%
1465 \@b@ll@full@skip
1466 \@b@ll@full@row{#1}{#1}{#1}%
1467 }}}
1468 % \end{macrocode}
1469 % \end{macro}
1470 %
1471 % \subsubsection{The main command}
1472 %
1473 % \begin{macro}{\bullcntr}
1474 % User-level command: simply invokes its inner-level counterpart,
1475 % using the internal name of the counter (the \meta{countdef
1476 % token}, right below).
1477 % \begin{macrocode}
1478 \newcommand*\bullcntr[1]{\expandafter\@b@ll@cntr\csname c@#1\endcsname}
1479 % \end{macrocode}
1480 % \end{macro}
1481 %
1482 % \begin{macro}{\@b@ll@cntr}
1483 % This macro expands either to
1484 % \begin{center}
1485 % "\@b@ll@@cntr \counterlargebullet "\meta{countdef token}
1486 % \end{center}
1487 % or to
1488 % \begin{center}
1489 % "\@b@ll@@cntr \countersmallbullet "\meta{countdef token}
1490 % \end{center}
1491 % depending on the counter value. Note that \#1 must be a single
1492 % token (as it is).
1493 % \begin{macrocode}
1494 \@ifdefinable\@b@ll@cntr{\def\@b@ll@cntr#1{%
1495 \expandafter\expandafter\expandafter \@b@ll@@cntr
1496 \ifnum #1<6
1497 \expandafter\counterlargebullet
1498 \else
1499 \expandafter\countersmallbullet
1500 \fi
1501 #1%
1502 }}
1503 % \end{macrocode}
1504 % \end{macro}
1505 %
1506 % \begin{macro}{\@b@ll@@cntr}
1507 % This macro selects the pattern to draw. The following is a
1508 % typical switch on the counter value, but pay attention to the
1509 % "\protect"\slash "\expandafter" mechanism: after this macro, and
1510 % hence the "\ifcase", have been expanded, the token flow will look
1511 % like this (if the value of the counter is, say, 2 and the
1512 % argument passed in~\#1 is, consequently, "\counterlargebullet"):
1513 % \begin{center}
1514 % "\protect \@b@ll@two {\counterlargebullet }"
1515 % \end{center}
1516 % Therefore, in the context of a "\protected@edef", the
1517 % "\protect"'ed "\@b@ll@two" will not be expanded, but
1518 % "\counterlargebullet" will be (fully).
1519 % \changes{0.04}{2007/04/02}{Corrected erroneous behavior for case~0,
1520 % argument \#1 must be \protect\cmnd{@gobble}'d in this case}
1521 % \begin{macrocode}
1522 \@ifdefinable\@b@ll@@cntr{\def\@b@ll@@cntr#1#2{%
1523 \ifcase #2\expandafter\@gobble
1524 \or
1525 \expandafter\protect \expandafter\@b@ll@one
1526 \or
1527 \expandafter\protect \expandafter\@b@ll@two
1528 \or
1529 \expandafter\protect \expandafter\@b@ll@three
1530 \or
1531 \expandafter\protect \expandafter\@b@ll@four
1532 \or
1533 \expandafter\protect \expandafter\@b@ll@five
1534 \or
1535 \expandafter\protect \expandafter\@b@ll@six
1536 \or
1537 \expandafter\protect \expandafter\@b@ll@seven
1538 \or
1539 \expandafter\protect \expandafter\@b@ll@eight
1540 \or
1541 \expandafter\protect \expandafter\@b@ll@nine
1542 % \end{macrocode}
1543 % For larger values we simply invoke the error-handling macro of
1544 % the kernel; strictly speaking, this is not correct, since this is
1545 % not a ``\LaTeX\ error'', but an error from this package. Anyway,
1546 % I think no user will be surprised by this behavior.
1547 % \begin{macrocode}
1548 \else
1549 \expandafter\@ctrerr
1550 % \end{macrocode}
1551 % The argument intended for "\@b@ll@"\meta{number} follows, that
1552 % "\@ctrerr" doesn't want, so we follow it with a "\@gobble"; note
1553 % that this is \emph{not} "\protect"'ed, thus, during a
1554 % "\protected@edef", the espansion of "\@b@ll@@cntr" in this ``out
1555 % of range'' case will leave nothing in the token flow.
1556 % \begin{macrocode}
1557 \expandafter\@gobble
1558 % \end{macrocode}
1559 % After selecting the appropriate macro, we insert the argument:
1560 % \begin{macrocode}
1561 \fi
1562 {#1}%
1563 }}
1564 % \end{macrocode}
1565 % \end{macro}
1566 %
1567 % End of the module for the \packlass{\bullcntr} package.
1568 % \begin{macrocode}
1569 %</bullcntr>
1570 % \end{macrocode}
1571 %
1572 % \section{The code for the \packlass{\bullenum} package}
1573 %
1574 % This part of the file goes into \filedir{\bullenum.sty}.
1575 % \begin{macrocode}
1576 %<*bullenum>
1577 % \end{macrocode}
1578 %
1579 % \subsection{Identification}
1580 %
1581 % The usual identification. Is there a real need for this version
1582 % of \LaTeXe?
1583 % \begin{macrocode}
1584 \NeedsTeXFormat{LaTeX2e}[1998/06/01] % LaTeX2e is required!
1585 \ProvidesPackage{bullenum}
1586 [2007/04/02 v0.04 (**development**)]
1587 % \end{macrocode}
1588 %
1589 % \subsection{Initial code}
1590 %
1591 % This package has no initial code.
1592 %
1593 % \subsection{Declaration of options}
1594 %
1595 % Just pass every option on to the \packlass{\bullcntr} package.
1596 %
1597 % \begin{macrocode}
1598 \DeclareOption*{\PassOptionsToPackage{\CurrentOption}{bullcntr}}
1599 % \end{macrocode}
1600 %
1601 % \subsection{Option processing}
1602 %
1603 % Nothing special to note here.
1604 %
1605 % \begin{macrocode}
1606 \ProcessOptions\relax
1607 % \end{macrocode}
1608 %
1609 % \subsection{Package loading}
1610 %
1611 % Neither here.
1612 %
1613 % \begin{macrocode}
1614 \RequirePackage{bullcntr}[2007/04/02]
1615 % \end{macrocode}
1616 %
1617 % \subsection{Main code}
1618 %
1619 % The purpose of this package is simply to define the
1620 % \env{bullenum} environment.
1621 %
1622 % \begin{environment}{bullenum}
1623 % This is just an \env{enumerate} environment in which we say
1624 %^^A
1625 % \begin{flushleft}
1626 % "\def\the"\meta{enum~$\ell$}"{\bullcntr{"\meta{enum~$\ell$}"}}"\\
1627 % "\def\label"\meta{enum~$\ell$}"{\the"\meta{enum~$\ell$}"}"
1628 % \end{flushleft}
1629 %^^A
1630 % at the beginning, where \( \meta{enum~$\ell$} =
1631 % \mbox{eval(}"\@enumctr"\mbox{)} \) (\emph{i.e.}, \(
1632 % \meta{enum~$\ell$} = \texttt{enumi},\linebreak[0]
1633 % \texttt{enumii},\ldots \), according to the current value of
1634 % "\@enumdepth").
1635 % \begin{macrocode}
1636 \newenvironment*{bullenum}{%
1637 \enumerate
1638 \expandafter\edef \csname the\@enumctr\endcsname {%
1639 \noexpand\bullcntr{\@enumctr}%
1640 }%
1641 \expandafter\edef \csname label\@enumctr\endcsname {%
1642 \expandafter\noexpand \csname the\@enumctr\endcsname
1643 }%
1644 }{\endenumerate}
1645 % \end{macrocode}
1646 % \end{environment}
1647 %
1648 % End of the module for the \packlass{\bullenum} package.
1649 % \begin{macrocode}
1650 %</bullenum>
1651 % \end{macrocode}
1652 %
1653 % \section{End of input}
1654 %
1655 % The usual "\endinput" which prevents the \DS\ program from putting
1656 % garbage into the generated files.
1657 % \begin{macrocode}
1658 \endinput
1659 % \end{macrocode}
1660 %
1661 % \Finale
1662 %