path: root/Master/texmf-dist/source/latex/bullcntr/bullcntr.dtx

% \iffalse
%   (This is a META-COMMENT.)
%
%   This is file `bullcntr.dtx'.
%
%   This file is part of a work named "bullcntr package".
%
%   Copyright (C) 2007 by Gustavo MEZZETTI <gustavo.mezzetti@istruzione.it>.
%
%   This file may be distributed and/or modified under the conditions
%   of the LaTeX Project Public License, either version 1.3 of this
%   license or (at your option) any later version.
%   The latest version of this license is in
%     http://www.latex-project.org/lppl.txt
%   and version 1.3 or later is part of all distributions of LaTeX
%   version 2005/12/01 or later.
%
%   The bullcntr package has the LPPL maintenance status
%     "author-maintained".
%
%   The file `manifest.txt' that comes along with this file specifies
%   what the bullcntr package consists of; more precisely, it explains
%   how the locutions "Work" and "Compiled Work", used in the LaTeX
%   Project Public License, are to be interpreted in the case of this
%   work.
%
%   Note that the distribution of this file alone is "distribution of
%   only part of the Work" in the sense of the LaTeX Project Public
%   License, and should be avoided (see the LaTeX Project Public
%   Licence for details).
%
%   (End of the META-COMMENT.)
% \fi
%
% \def\filename{bullcntr.dtx}
% \def\fileversion{0.04}
% \def\filedate{2007/04/02}
% \def\docdate {2007/10/01}
% \def\doclongdate{October~1, 2007}
%
% \CheckSum{328}
%
% \changes{0.01}{2007 Feb 07}{First provisional writing of the code}
% \changes{0.02}{2007 Feb 08}{Modified layout of bullets for the
%   value~4}
% \changes{0.03}{2007 Feb 16}{Introduced declarations for the four
%   predefined bullet styles (\protect\cmnd{smartctrbull} and
%   siblings)}
% \changes{0.03}{2007 Feb 16}{Introduced options corresponding to the
%   declarations for the four predefined bullet styles
%   (\protect\opt{smartctrbull} and siblings)}
% \changes{0.03}{2007 Feb 16}{Developed the
%   \protect\packlass{\protect\bullenum} subsidiary package defining
%   the \protect\env{bullenum} environment}
% \changes{0.03}{2007 Feb 16}{Thoroughly reorganized the code to
%   correct a serious bug regarding labels and references}
%
%% \CharacterTable
%%  {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
%%   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
%%   Digits        \0\1\2\3\4\5\6\7\8\9
%%   Exclamation   \!     Double quote  \"     Hash (number) \#
%%   Dollar        \$     Percent       \%     Ampersand     \&
%%   Acute accent  \'     Left paren    \(     Right paren   \)
%%   Asterisk      \*     Plus          \+     Comma         \,
%%   Minus         \-     Point         \.     Solidus       \/
%%   Colon         \:     Semicolon     \;     Less than     \<
%%   Equals        \=     Greater than  \>     Question mark \?
%%   Commercial at \@     Left bracket  \[     Backslash     \\
%%   Right bracket \]     Circumflex    \^     Underscore    \_
%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%%   Right brace   \}     Tilde         \~}
%
% \MakeShortVerb{\"}
% \DeleteShortVerb{\|}
%
% \DoNotIndex{\begin,\end,\def,\let,\else,\fi,\or,\@ifdefinable,\@empty}
% \DoNotIndex{\newcommand,\renewcommand}
% \DoNotIndex{\newenvironment,\renewenvironment}
% \DoNotIndex{\z@,\z@skip,\p@,\@ne,\tw@,\thr@@,\@m,\@M,\m@ne}
% \DoNotIndex{\DeclareOption}
%
% \IndexPrologue{
%   \section{\indexname}
%   Numbers in italics refer to the page where the corresponding entry
%   is described, the ones underlined to the code line of the
%   definition, the rest to the code lines where the entry is used.
% }
% \setcounter{IndexColumns}{2}
%
% \GlossaryPrologue{\section{Change History}}
%
% \setcounter{StandardModuleDepth}{1}
%
% \newcommand*{\DS}{\textsf{DocStrip}}
% \renewcommand*{\partname}{Part}
% \newcommand*{\bullcntr}{bullcntr}
% \newcommand*{\bullenum}{bullenum}
% \makeatletter
% \newcommand*{\myspecialindex}[2]
%    {\special@index{#1\actualchar#2\encapchar main}}
% \makeatother
% \newcommand*{\counterindex}[1]{\myspecialindex{#1}{{\string\ttfamily
%    \space #1} (counter)}\index{counters:\levelchar{\protect\ttfamily
%    #1}\encapchar usage}}
% \newcommand*{\optuseindex}[1]{\SortIndex{#1}{\protect\opt{#1}
%    (option)\encapchar usage}\index{options:\levelchar
%    \protect\opt{#1}\encapchar usage}}
% \DeclareRobustCommand*{\opt}[1]{{\normalfont\ttfamily #1}}
% \newcommand*{\sopt}[1]{\mbox{\opt{#1}}\optuseindex{#1}}
% \DeclareRobustCommand*{\packlass}[1]{{\normalfont\sffamily #1}}
% \DeclareRobustCommand*{\filedir}[1]{{\normalfont\ttfamily #1}}
% \DeclareRobustCommand*{\env}[1]{{\normalfont\ttfamily #1}}
% \DeclareRobustCommand*{\ctr}[1]{{\normalfont\ttfamily #1}}
% \DeclareRobustCommand*{\cmnd}[1]{\texttt{\bslash #1}}
% \newcommand*{\circnumb}[1]{%
%   \makebox[.6666667em]{\makebox[0pt]{$\bigcirc$}\makebox[0pt]{\small #1}}%
% }
%
% \newcommand*{\oMr}{.13397460}
% \newcommand*{\oPr}{1.8660254}
%
%
%
% \title{
%    The \packlass{\bullcntr} package\thanks{This file has version
%    \fileversion, release date \filedate;
%    last documentation update: \docdate.
%    Copyright \copyright~2007 by G.~Mezzetti
%    (see page~\pageref{S:Copy}).}
% }
% \author{G. Mezzetti}
% \date{\doclongdate}
%
% \maketitle
%
% \begin{abstract}
%    This document describes a \LaTeX\ (former \LaTeXe) package that
%    defines a new command, similar to "\fnsymbol", for displaying the
%    value of a counter: this command typesets a number of bullets
%    equal to the value of the counter, in a nice arrangement.  The
%    value of the counter must lie between 1 and~9.
%
%    An ancillary package, named \env{\bullenum}, defines an
%    environment, similar to \env{enumerate}, that produces lists
%    whose items are numbered in this way.
% \end{abstract}
%
% \tableofcontents
% \listoffigures
%
% \clearpage
% \begingroup
%
%    \setlength{\parskip}{\medskipamount}
%    \setlength{\parindent}{0pt}
%
% \section*{Copyright notice}
%    \label{S:Copy}
%    \vspace{-\parskip}
%
%    Copyright \copyright~2007 by Gustavo \textsc{Mezzetti}.
%    All rights are reserved, except as noted below.
%
%    This document has been produced by feeding to a \LaTeX\
%    typesetting engine the file \filedir{\filename} version
%    \fileversion\ (\docdate).  This file is part of a work named
%    ``\packlass{\bullcntr} package'', and may distributed and/or
%    modified only as a part thereof.  Subsection~\ref{sS:License} on
%    page~\pageref{sS:License} explains the conditions under which the
%    \packlass{\bullcntr} package may be distributed and/or modified.
%
%    The \packlass{\bullcntr} package has the LPPL maintenance status
%    ``author-maintained''.
%
%    Permission is granted to make new printed copies of this document,
%    by any means (\emph{e.g.}, photocopying, direct printing from the
%    electronic version, and so on).
%
%    Note, though, that distribution of this document alone is
%    ``distribution of only part of the Work'' in the sense of the
%    \LaTeX\ Project Public License, and should therefore be avoided:
%    please distribute, in addition, the source file
%    \filedir{\bullcntr.dtx} together with all other files listed in
%    \filedir{manifest.txt}, as explained as well in
%    Subsection~\ref{sS:License} and in the file
%    \filedir{manifest.txt} itself.
%
% \section*{Author's addresses}
%    \vspace{-\parskip}
%
%    The recommended way to contact the author is by e-mail; his address is:
%
%    \begin{list}{\setlength{\topsep}{0pt}}\item\relax
%      \ttfamily
%      gustavo.mezzetti@istruzione.it
%    \end{list}
%
%    Please include the \emph{exact} phrase \verb*|bullcntr package| in the
%    \emph{subject} of your message; otherwise, your message could be
%    thrown away by a mail filter.  In this regard, the weakness of the
%    laws concerning the protection of privacy forces me to explicitly
%    forbid the use of the above address for any kind of advertising,
%    marketing, polling, or similar commercial or statistical contact.
%
%    If you have no e-mail access, write to:
%
%    \begin{list}{\setlength{\topsep}{0pt}}\item\relax
%      Gustavo \textsc{Mezzetti}\\
%      L.~A.~S. ``A.~Modigliani''\\
%      Via E.~Degli Scrovegni, 30\\
%      I--35121\quad PADOVA\quad PD\\
%      Italy
%    \end{list}
%
% \endgroup
%
%
%
% \setcounter{secnumdepth}{0}
%
%
%
% \clearpage
% \section{Introduction}
%
%    I can't remember exactly where the idea of this package arose
%    from, but I am pretty sure that the first time I saw a list of
%    items numbered with an increasing number of bullets was in
%    certain handwritten notes concerning sheaves cohomology, may be a
%    decade or so ago.  Since then, I had repeatedly thought of
%    writing a \LaTeX\ package to implement this kind of numbering,
%    but I had never resolved to do so, until very recently, when I
%    ^^A ( paren match
%    suddenly decided to sit down and write the code!~:-)
%
%    Regrettably, shortly after I~uploaded version 0.02 of the package
%    to the CTAN, I~had to discover a major bug in the macros I~had
%    dashed off in such a haste, which required an extensive (and more
%    careful!)\ redesign of the code.  I~took this opportunity to
%    thoroughly reorganize it, making it easier, for the user, to
%    switch from one style of bullets to another, and also adding an
%    ancillary package that simplified the creation of lists numbered
%    with bullets.  This led to version 0.03.
%
%    You are now reading the source of version 0.04, which corrects
%    another pretty serious bug brought in---alas---with the
%    modifications introduced in version 0.03: the "\@b@ll@@cntr"
%    macro, called by the "\bullcntr" command, behaved erroneously
%    when invoked with a value of the counter equal to zero.
%
%    Since I~had to repackage the distribution, I~also decided to
%    include, along with the other files, a couple of \LaTeX\ sources
%    that illustrate in practice the use of the
%    \packlass{\bullcntr}\slash \packlass{\bullenum} packages, and
%    also the \LaTeX\ source of the user manual, that is, of the file
%    previously offered on the CTAN\@ sites under the name
%    \filedir{overview.pdf}; this file has now the base name
%    \filedir{bullcntr-man}, to make it more easily searchable, and
%    has been turned into a required part of the \packlass{\bullcntr}
%    package.  In doing all this, I~met some suggestions given me by
%    the people at CTAN\@.
%
%    \subsection{Disclaimer}
%
%    Although a \LaTeX\ package is a piece of software that executes in a
%    rather protected environment and should therefore be relatively
%    incapable of doing serious damages, no warranty is given, as usual with
%    computer software, that this code will work properly, or even that it
%    will work at all.  To be on the safe side, be aware that using this
%    code can even result in loss of data and/or damages to your disks and
%    your storage media.  If you use this code, you do so exclusively at
%    your own risk!
%
%    See Subsection~\ref{sS:License} and the \LaTeX\ Project Public
%    License for more information.
%
%    \subsection{About this document}
%
%    This document, like many documentation files distributed for
%    \LaTeX, is divided into two parts.
%
%    The first part, \emph{User's Manual}, contains all the documentation
%    you need to succesfully \emph{use} the package that this document
%    presents.  Every user of the \packlass{\bullcntr} package will
%    probably want to read this part.
%
%    The second part, \emph{Implementation}, can be omitted if you
%    want (explanations on how to omit it are given at the beginning
%    of the part itself), and contains information that concerns only
%    ``hackers'' who want to learn how the package that this document
%    presents is \emph{implemented}.  Actually, this part contains the
%    complete listing of the \LaTeX\ code that implements the macros,
%    in the usual \DS\ format; if you are not a \LaTeX\ hacker, this
%    part will probably have little meaning to you.
%
%
%
% \setcounter{secnumdepth}{3}
%
%
%
% \clearpage
% \part{User's Manual}
%
% \section{About this part}
%
%    This part contains detailed instructions on how to install the
%    \packlass{\bullcntr} package, how to use it, and how to generate
%    this documentation.  Note that including in this document the
%    instructions on how to generate the document itself may seem
%    pretty useless, but actually isn't: you might be reading a copy
%    obtained from some other source.
%
% \section{Installing the \packlass{\bullcntr} package and generating this manual}
%
%    As usual for \LaTeX\ distributions, the \packlass{\bullcntr}
%    package is distributed in the form of a \filedir{.dtx} file,
%    namely \filedir{\bullcntr.dtx}, and an accompanying
%    \filedir{.ins} file, namely \filedir{\bullcntr.ins}.
%
%    \subsection{Installation}
%
%    To install the package, run \LaTeX\ (or Plain \TeX) once on the
%    file \filedir{\bullcntr.ins}.  This will generate the following
%    two \LaTeX\ input files:
%    \begin{quote}
%      \ttfamily
%      \bullcntr.sty\\
%      \bullenum.sty
%    \end{quote}
%    To finish the installation, move them into a \LaTeX\ input
%    directory.  The above listing of the files you need to move is
%    also displayed on the terminal at the end of the run of the file
%    \filedir{\bullcntr.ins}.  The documentation of your \TeX\
%    installation should tell you how to find the \LaTeX\ input
%    directory/ies, and probably also how to create new \LaTeX\ input
%    directories reserved to contain your private classes and
%    packages.  If your \TeX\ installation offers you the chance of
%    defining your private \LaTeX\ input directories, I recommend you
%    exploit this possibility and place the generated files into such
%    a directory.
%
%    Please note that before using the \packlass{\bullcntr} package
%    you must read the license (see Subsection~\ref{sS:License}) to
%    see whether its terms are acceptable for you, especially for what
%    concerns the lack of any warranty; if they are not, don't use
%    this program.
%
%    \subsection{Documentation}
%
%    To produce this documentation, run \LaTeX\ three times (for the
%    table of contents to be correct) on the file
%    \filedir{\bullcntr.dtx}.  This won't produce the index and the
%    change history, however: for those, you have to run
%    \emph{MakeIndex} on the files \filedir{\bullcntr.idx} and
%    \filedir{\bullcntr.glo}, produced during the last of the
%    aforesaid three \LaTeX\ runs, with the styles \filedir{gind.ist}
%    and \filedir{gglo.ist}, respectively (these styles are part of
%    the standard \LaTeX\ distribution); then pass
%    \filedir{\bullcntr.dtx} through \LaTeX\ twice more.
%
%    The documentation produced by default includes the
%    \emph{Implementation} part too; see the beginning of this part
%    for instructions on how to omit it.
%
%    \subsection{License}
%    \label{sS:License}
%
%    The \packlass{\bullcntr} package is \emph{not} in the public
%    domain: its author, Gustavo \textsc{Mezzetti}, owns the
%    copyright, and in general retains all the rights therein; but as
%    a special exception, the author grants you the permissions
%    indicated below.
%
%    \subsubsection{Distribution and/or modification}
%
%    The \packlass{\bullcntr} package may be distributed and/or
%    modified under the conditions of the \LaTeX\ Project Public
%    License, either version~1.3 of this license or (at your option)
%    any later version.  The latest version of this license is in
%    \begin{quote}
%      \ttfamily
%      http://www.latex-project.org/lppl.txt
%    \end{quote}
%    and version~1.3 or later is part of all distributions of \LaTeX\
%    version 2005/12/01 or later.
%
%    The \packlass{\bullcntr} package has the LPPL maintenance status
%    ``author-maintained''.
%
%    The file \filedir{manifest.txt} included along with this file
%    specifies what the \packlass{\bullcntr} package consists of; more
%    precisely, it explains how the locutions ``Work'' and ``Compiled
%    Work'', used in the \LaTeX\ Project Public License, are to be
%    interpreted in the case of this work.
%
%    \subsubsection{Use}
%
%    The use of the \packlass{\bullcntr} package is unrestricted,
%    provided that you accept the terms and conditions of the \LaTeX\
%    Project Public License and of the following subsection for what
%    concerns the absence of any warranty.
%
%    \subsubsection{No warranty}
%
%    There is absolutely no warranty for the \packlass{\bullcntr}
%    package.  The Copyright Holder provides the \packlass{\bullcntr}
%    package ``as is'', without warranty of any kind, either expressed
%    or implied, including, but not limited to, the implied warranties
%    of merchantability and fitness for a particular purpose.  The
%    entire risk as to the quality and performance of the
%    \packlass{\bullcntr} package is with you.  Should the
%    \packlass{\bullcntr} package prove defective, you assume the cost
%    of all necessary servicing, repair, or correction.
%
%    In no event will The Copyright Holder, or any other party who may
%    distribute and/or modify the \packlass{\bullcntr} package as
%    permitted by the \LaTeX\ Project Public License, be liable to you
%    for damages, including any general, special, incidental or
%    consequential damages arising out of any use of the
%    \packlass{\bullcntr} package or out of inability to use it
%    (including, but not limited to, loss of data, data being rendered
%    inaccurate, or losses sustained by anyone as a result of any
%    failure of the \packlass{\bullcntr} package to operate with any
%    other programs), even if The Copyright Holder or said other party
%    has been advised of the possibility of such damages.
%
%    \subsection{Your comments}
%
%    If you have comments, suggestions, etc.\ about the
%    \packlass{\bullcntr} package, please let me know them: I'll be
%    happy to read what you think.  A point that especially bothers me
%    is the difficulty of choosing the ``right'' character for the
%    bullets: "\textbullet" seems too big, while "\textperiodcentered"
%    looks far too small, at least for me.  But let me know your
%    opinion!
%
% \section{How to use the \packlass{\bullcntr} package}
% \label{S:UsageCntr}
%
%    The main purpose of the \packlass{\bullcntr} package is just to
%    define the command "\bullcntr" for displaying the value of a
%    counter.  This command is analogous to "\fnsymbol": it works only
%    if the value of the counter to print lies between 1 and~9
%    (inclusive), and displays this value using a pleasant arrangement
%    of bullets (whence the name).  The patterns used to display the
%    values from 1 to~9 are shown in fig.~\ref{fig:patterns}; of
%    course, the grid lines shown in this picture are not drawn by the
%    "\bullcntr" command.  See fig.~\ref{fig:dimens}, in
%    Subsection~\ref{sS:MainCode}, for a definition of the exact
%    proportions of this grid; here it suffices to state that the
%    triangle in Three is exactly equilateral, and that the hexagon in
%    Six and Seven is perfectly regular.  As it will be explained
%    below, you can control what characters are drawn in the positions
%    defined by the above patterns (not only bullets, but, for
%    instance, hearts).
%
%    \begin{figure}[tbp]
%      \newcommand*{\bullgrid}[1]{^^A
%        \linethickness{.2pt}^^A
%        \multiput(0,0)(.5,0){5}{\line(0,1){2}}^^A
%        \multiput(0,0)(0,1){3}{\line(1,0){2}}^^A
%        \put(0,\oMr){\line(1,0){2}}^^A
%        \put(0,\oPr){\line(1,0){2}}^^A
%        \put(1,-.1){\makebox(0,0)[t]{\strut #1}}^^A
%      }
%      \newcommand*{\bullbull}[2]{^^A
%        \put(#1,#2){\circle*{.2}}^^A
%      }
%      \centering
%      \setlength{\unitlength}{1cm}
%      \begin{picture}(10,10.5)
%        \put(1,9.5){\makebox(0,0){
%          \begin{picture}(2,2)
%            \bullgrid{One}
%            \bullbull{1}{1}
%          \end{picture}}}
%        \put(5,9.5){\makebox(0,0){
%          \begin{picture}(2,2)
%            \bullgrid{Two}
%            \bullbull{0}{1}
%            \bullbull{2}{1}
%          \end{picture}}}
%        \put(9,9.5){\makebox(0,0){
%          \begin{picture}(2,2)
%            \bullgrid{Three}
%            \bullbull{0}{\oMr}
%            \bullbull{2}{\oMr}
%            \bullbull{1}{\oPr}
%          \end{picture}}}
%        \put(1,5.5){\makebox(0,0){
%          \begin{picture}(2,2)
%            \bullgrid{Four}
%            \bullbull{1}{0}
%            \bullbull{0}{1}
%            \bullbull{2}{1}
%            \bullbull{1}{2}
%          \end{picture}}}
%        \put(5,5.5){\makebox(0,0){
%          \begin{picture}(2,2)
%            \bullgrid{Five}
%            \bullbull{0}{0}
%            \bullbull{0}{2}
%            \bullbull{1}{1}
%            \bullbull{2}{0}
%            \bullbull{2}{2}
%          \end{picture}}}
%        \put(9,5.5){\makebox(0,0){
%          \begin{picture}(2,2)
%            \bullgrid{Six}
%            \bullbull{.5}{\oMr}
%            \bullbull{1.5}{\oMr}
%            \bullbull{0}{1}
%            \bullbull{2}{1}
%            \bullbull{.5}{\oPr}
%            \bullbull{1.5}{\oPr}
%          \end{picture}}}
%        \put(1,1.5){\makebox(0,0){
%          \begin{picture}(2,2)
%            \bullgrid{Seven}
%            \bullbull{.5}{\oMr}
%            \bullbull{1.5}{\oMr}
%            \bullbull{0}{1}
%            \bullbull{1}{1}
%            \bullbull{2}{1}
%            \bullbull{.5}{\oPr}
%            \bullbull{1.5}{\oPr}
%          \end{picture}}}
%        \put(5,1.5){\makebox(0,0){
%          \begin{picture}(2,2)
%            \bullbull{0}{\oMr}
%            \bullbull{1}{\oMr}
%            \bullbull{2}{\oMr}
%            \bullgrid{Eight}
%            \bullbull{.5}{1}
%            \bullbull{1.5}{1}
%            \bullbull{0}{\oPr}
%            \bullbull{1}{\oPr}
%            \bullbull{2}{\oPr}
%          \end{picture}}}
%        \put(9,1.5){\makebox(0,0){
%          \begin{picture}(2,2)
%            \bullgrid{Nine}
%            \bullbull{0}{0}
%            \bullbull{0}{1}
%            \bullbull{0}{2}
%            \bullbull{1}{0}
%            \bullbull{1}{1}
%            \bullbull{1}{2}
%            \bullbull{2}{0}
%            \bullbull{2}{1}
%            \bullbull{2}{2}
%          \end{picture}}}
%      \end{picture}
%      \caption{Arrangement of the bullets for the various counter values}
%      \label{fig:patterns}
%    \end{figure}
%
%    The following subsections explain the usage of the
%    \packlass{\bullcntr} package, which just defines---as said
%    above---the new command "\bullcntr".  If you intend to produce
%    lists whose items are numbered with bullets, however, you should
%    \emph{not} use directly this package, but rather the
%    \packlass{\bullenum} package, which will be discussed in
%    Section~\ref{S:UsageEnum}.  The \packlass{\bullenum} package
%    loads \packlass{bullcntr} for you, passing to the latter the
%    options with which you called it.
%
%    The \packlass{\bullcntr} has been extensively rewritten to
%    correct a coarse---and very embarassing!~:-(~---^^A ) paren match
%    bug concerning references to counters displayed with "\bullcntr".
%
%    \subsection{Package invocation and options}
%    \label{sS:InvoCntr}
%
%    You invoke the \packlass{\bullcntr} package with the usual
%    "\usepackage" declaration put in the preamble of your document.
%    In this declaration you may specify one of the following,
%    mutually exclusive options:
%^^A
%    \begin{description}
%^^A
%    \item[\sopt{largectrbull}]
%    (Relatively) ``large'' bullets are used for all values from 1
%    through~9.  This produces exactly the same effect as a
%    "\largectrbull" global declaration (see
%    Subsection~\ref{sS:BullDecl}).
%^^A
%    \item[\sopt{smallctrbull}]
%    ``Small'' bullets are used for all values from 1 to~9.  This has
%    exactly the same effect as a "\smallctrbull" global declaration
%    (see Subsection~\ref{sS:BullDecl}).
%^^A
%    \item[\sopt{smartctrbull}]
%    (Relatively) ``large'' bullets are used for the values from 1
%    through~5 (inclusive), while ``small'' bullets are used for those
%    greater than or equal to~6.  This produces exactly the same
%    effect as a "\smartctrbull" global declaration (see
%    Subsection~\ref{sS:BullDecl}).
%^^A
%    \item[\sopt{heartctrbull}]
%    Hearts are used (instead of bullets) for all values from 1
%    through~9.  This produces exactly the same effect as a
%    "\heartctrbull" global declaration (see
%    Subsection~\ref{sS:BullDecl}).
%^^A
%    \end{description}
%^^A
%    If you don't specify any, the default option is
%    \opt{smartctrbull}.
%
%    For example, when preparing a valentine you might want to say
%\begin{verbatim}
%\usepackage[heartctrbull]{bullcntr}
%\end{verbatim}
%    (See Subsection~\ref{sS:InvoEnum}, however, if what you need is
%    to produce a list whose items are numbered with bullets.)
%
%    Finer control over the appearance of bullets may be obtained by
%    means of the ``hooks'' described in Subsection~\ref{sS:BullHook}.
%
%    \subsection{The main command}
%    \label{sS:bullcntr}
%
%    \DescribeMacro{\bullcntr}
%    This command is strictly analogous to the "\fnsymbol" command
%    (cf.\ the \textsl{\LaTeX book}
%    \cite[Subsection~C.8.4]{LaTeXbook}): you may use it directly in
%    the text, as in
%    \begin{flushleft}
%      \small
%      \ldots\texttt{the counter value displays as}"~\bullcntr{"\meta{ctr}"}"\ldots
%    \end{flushleft}
%    (where \meta{ctr} is a counter name, defined with "\newcounter"),
%    or you may redefine the "\the"\meta{ctr} command, as in
%    \begin{flushleft}
%      \small
%      "\renewcommand*{\the"\meta{ctr}"}{\bullcntr{"\meta{ctr}"}}"
%    \end{flushleft}
%    By way of example, in the case of a counter named \ctr{myctr},
%    the source code in the two cases would be, respectively,
%\begin{verbatim}
%The counter value displays as~\bullcntr{myctr}.
%\end{verbatim}
%    and
%\begin{verbatim}
%\renewcommand*{\themyctr}{\bullcntr{myctr}}
%\end{verbatim}
%
%    If \( "\value{"\meta{ctr}"}"=0 \), the command
%    "\bullcntr{"\meta{ctr}"}" tacitly typesets nothing (not even a
%    space); if \( "\value{"\meta{ctr}"}"<0 \) or \(
%    "\value{"\meta{ctr}"}">9 \), an error occurs.
%
%    \subsection{Hooks for the bullets}
%    \label{sS:BullHook}
%
%    The main task of the \packlass{\bullcntr} package is to calculate
%    the position of the ``bullets'' used to display the value of the
%    given counter (see fig.~\ref{fig:patterns}); but you are free to
%    decide what characters are actually drawn in these positions:
%    they need not necessarily be ``bullets''.  Indeed, two ``hooks''
%    are provided in the package to define the actual characters
%    employed, and the package simply invokes these hooks.
%
%    \DescribeMacro{\counterlargebullet}
%    When the value of the counter being displayed is less than~6
%    (less than~6 bullets need to be drawn), the "\bullcntr" command
%    invokes the "\counterlargebullet" macro to draw each of them.  If
%    you want, you should redefine this macro (using "\renewcommand")
%    so that it generates a symbol suitable for arrangements in which
%    the ``bullets'' are relatively spaced out.  For example,
%\begin{verbatim}
%\renewcommand*{\counterlargebullet}{\textbullet}
%\end{verbatim}
%    You don't \emph{need} to redefine this command: a convenient
%    default definition is already set by the \packlass{\bullcntr}
%    package itself.
%
%    \DescribeMacro{\countersmallbullet}
%    When, on the other hand, the value of the counter being displayed
%    is greater than or equal to~6 (6~or more bullets need to be
%    drawn), the "\bullcntr" command calls the "\countersmallbullet"
%    macro.  It is intended that this macro typesets a character
%    suitable for situations in which the ``bullets'' have to be
%    grouped in a compact cluster; typically, this means that a
%    smaller ``bullet'' is used than the one typeset by
%    "\counterlargebullet", although it is perfectly in order to use
%    the same character in both situations.  If you want (but you
%    don't \emph{need} to do this, since the \packlass{\bullcntr}
%    package already defines this macro) you may change the definition
%    with "\renewcommand", \emph{e.g.}:
%\begin{verbatim}
%\renewcommand*{\countersmallbullet}{\textperiodcentered}
%\end{verbatim}
%
%    Fragile commands used in the definition of both hooks should be
%    "\protect"'ed.
%
%    ``Macho \TeX\ programmers'' may also use "\def" instead of
%    "\renewcommand", \emph{e.g.}:
%\begin{verbatim}
%\def\counterlargebullet{\textbullet}
%\def\countersmallbullet{\textperiodcentered}
%\end{verbatim}
%    (Actually, in a case like this, even "\let" could be used.)
%
%    \subsection{Declarations for predefined bullet styles}
%    \label{sS:BullDecl}
%
%    To spare you the nuisance of redefining the two hooks mentioned
%    in Subsection~\ref{sS:BullHook}, at least in normal situations,
%    four basic ``bullet styles'' are already predefined by the
%    \packlass{\bullcntr} package, covering what the author believes
%    are the most common cases.  You can switch to any of these
%    predefined styles by means of the following four declarations.
%
%    \DescribeMacro{\largectrbull}
%    This declaration causes (relatively) ``large'' bullets to be used
%    for all values from 1 to~9.
%
%    \DescribeMacro{\smallctrbull}
%    This declaration causes ``small'' bullets to be used for all
%    values from 1 to~9.
%
%    \DescribeMacro{\smartctrbull}
%    This declaration causes (relatively) ``large'' bullets to be used
%    for values from 1 to~5 (inclusive), and ``small'' bullets for
%    values equal to or above~6.
%
%    \DescribeMacro{\heartctrbull}
%    With this declaration, little hearts will be used for all values
%    from 1 to~9.
%
%    These are in all respects normal declarations, obeying to
%    ordinary scoping rules.  The corresponding options described in
%    Subsection~\ref{sS:InvoCntr} simply set the style at the outer
%    (global, or document-wide) level.
%
% \section{How to use the \packlass{\bullenum} package}
% \label{S:UsageEnum}
%
%    The \packlass{\bullcntr} package was conceived for the purpose of
%    imitating in print an unusual way of numbering items in a list,
%    that the author saw in certain handwritten notes (see the
%    Introduction).  With the "\bullcntr" command at hand, this could
%    be achieved simply by saying something like
%\begin{verbatim}
%\begin{enumerate}
%    \renewcommand*{\theenumi}{\bullcntr{enumi}}
%    \renewcommand*{\labelenumi}{\theenumi}
%\end{verbatim}
%    \begin{flushleft}
%      \small
%      \texttt{\ \ \ \ }\meta{items}
%    \end{flushleft}
%\begin{verbatim}
%\end{enumerate}
%\end{verbatim}
%    This, nonetheless, is not perfect, since it breaks if the
%    \env{enumerate} environment is moved inside another
%    \env{enumerate}, because of the explicit mention of "\theenumi"
%    and of "\labelenumi".
%
%    For this reason, and also to facilitate the use of the
%    "\bullcntr" command for numbering list items, an ancillary
%    package has been added to the \packlass{\bullcntr} package; this
%    ancillary package, called \packlass{\bullenum}, simply defines
%    the \env{bullenum} environment, a variation of \env{enumerate}
%    which numbers its items using the "\bullcntr" command.  Indeed,
%\begin{verbatim}
%\begin{bullenum}
%\end{verbatim}
%    \begin{flushleft}
%      \small
%      \texttt{\ \ \ \ }\meta{items}
%    \end{flushleft}
%\begin{verbatim}
%\end{bullenum}
%\end{verbatim}
%    is equivalent to
%    \begin{flushleft}
%      \small
%      "\begin{enumerate}"\\
%      "    \renewcommand*{\theenum"\meta{lvl}"}{\bullcntr{enum"\meta{lvl}"}}"\\
%      "    \renewcommand*{\labelenum"\meta{lvl}"}{\theenum"\meta{lvl}"}"
%    \end{flushleft}
%    \begin{flushleft}
%      \small
%      \texttt{\ \ \ \ }\meta{items}\\[\topsep]
%    \end{flushleft}
%\begin{verbatim}
%\end{enumerate}
%\end{verbatim}
%    where \meta{lvl} is \texttt{i}, \texttt{ii}, \texttt{iii},
%    or~\texttt{iv}, depending on the current level of the
%    \env{enumerate} environment.
%
%    In other words, \env{bullenum} can be used in every place where
%    \env{enumerate} can, and numbers its items with an increasing
%    number of bullets, regardless of the current definition of
%    "\theenum"\meta{lvl} and "\labelenum"\meta{lvl}.  Of course, the
%    environment must contain no more than 9~items.  Moreover, if you
%    use "\label" to set up a reference, subsequent "\ref"'s will
%    typeset the reference as a ``bulletted'' number, using, for the
%    ``bullets'', the character that was current at the time the
%    "\label" was encountered (in brief, they will do the right
%    thing).
%
%    Notice that you should \emph{not} load the \packlass{\bullcntr}
%    package if you invoke \packlass{\bullenum}, because the latter
%    calls the former.  As explained below, you may pass to
%    \packlass{\bullenum} the options that you would require from
%    \packlass{\bullcntr}: the outer package will forward them to the
%    inner one.  Actually, most users will just use the
%    \packlass{\bullenum} package, and never call \packlass{\bullcntr}
%    directly.
%
%    \subsection{Package invocation and options}
%    \label{sS:InvoEnum}
%
%    You invoke the \packlass{\bullenum} package with the usual
%    "\usepackage" declaration put in the preamble of your document.
%    In this declaration you may specify exactly the same options that
%    you would pass to the \packlass{\bullcntr} package, with the same
%    meaning.  The \packlass{\bullenum} package calls
%    \packlass{bullcntr} for you, just passing on to it the options
%    you asked for.
%
%    Continuing our example of valentines: if what you actually want
%    is to produce a list numbered with hearts, you should \emph{not}
%    say
%\begin{verbatim}
%\usepackage[heartctrbull]{bullcntr}
%\end{verbatim}
%    as deceitfully suggested in Subsection~\ref{sS:InvoCntr} (well,
%    actually we had not spoken of lists there, had we?), but rather
%\begin{verbatim}
%\usepackage[heartctrbull]{bullenum}
%\end{verbatim}
%
%    \subsection{The main environment}
%    \label{sS:bullenum}
%
%    \DescribeEnv{bullenum}
%    This environment is syntactically analogous to \env{enumerate},
%    but numbers its items with an increasing number of bullets (using
%    the "\bullcntr" command).  You must include no more than 9~items
%    in this environment.  The style of the bullets is governed by the
%    declarations described in Subsection~\ref{sS:BullDecl}, according
%    to ordinary scoping rules.  A change local to the environment
%    being employed can be obtained by simply enclosing the relevant
%    declaration inside the environment itself; \emph{e.g.},
%\begin{verbatim}
%\begin{bullenum}
%    \smallctrbull
%\end{verbatim}
%    \begin{flushleft}
%      \small
%      \texttt{\ \ \ \ }\meta{items}
%    \end{flushleft}
%\begin{verbatim}
%\end{bullenum}
%\end{verbatim}
%    will use ``small'' bullets regardless of whatever style might
%    have been in force outside the \env{bullenum} environment.
%
%    If you want finer control over the appearance of the ``bullets'',
%    just redefine the hooks of
%    Subsection~\ref{sS:BullHook}; doing this inside the environment
%    itself will keep changes to the hooks local.  For example, you
%    might say
%\begin{verbatim}
%\begin{bullenum}
%    \renewcommand*{\counterlargebullet}{$\scriptscriptstyle \diamondsuit$}
%    \renewcommand*{\countersmallbullet}{\counterlargebullet}
%\end{verbatim}
%    \begin{flushleft}
%      \small
%      \texttt{\ \ \ \ }\meta{items}
%    \end{flushleft}
%\begin{verbatim}
%\end{bullenum}
%\end{verbatim}
%    (yes, ``macho \TeX\ programmers'' may also use "\def", or "\let"
%    where appropriate).
%
%    Of course, this environment does not affect the definition of
%    "\theenum"\meta{lvl} and of "\labelenum"\meta{lvl} that are valid
%    outside the environment itself, for \( \meta{lvl} =
%    \texttt{i}\ldots\texttt{iv} \).
%
% \StopEventually{
%    \setcounter{secnumdepth}{0}
%    \providecommand*\bysame{\leavevmode\hbox to3em{\hrulefill}\thinspace}
%
%    \clearpage
%    \begin{thebibliography}{9}
%    \addcontentsline{toc}{section}{\refname}
%
%    \bibitem{LaTeXbook}
%    L.~Lamport, \emph{\LaTeX---A Document Preparation System---User's
%       Guide and Reference Manual}, 2nd~edition, Addison-Wesley,
%       Reading, 1994.
%
%    \end{thebibliography}
% }
%
%
%
% \clearpage
% \part{Implementation}
%
% \section{About this part}
%
%    This part is of interest only to \LaTeX\ hackers; to avoid
%    having this part printed, look in the file \filedir{\filename}
%    for a line that looks \emph{exactly} like this
%    \begin{verbatim}%% \OnlyDescription % uncomment to discard Implementation part\end{verbatim}
%    and remove the two leading percent signs ("%%").
%
% \section{A driver for this document}
%
%    This part of the file is \emph{not} included in any generated file:
%    it is simply the driver.
%    \begin{macrocode}
%<*driver>
%    \end{macrocode}
%
%    To begin with, we load the \packlass{ltxdoc} class.
%    \begin{macrocode}
\documentclass[a4paper]{ltxdoc}
%    \end{macrocode}
%    We now set a few typesetting options.
%    First of all, we want a history listing and a full index, the latter
%    organized by line numbers.
%    \begin{macrocode}
\RecordChanges
\EnableCrossrefs
\CodelineIndex
%    \end{macrocode}
%    If you don't want to include the second part of this document,
%    \emph{Implementation}, uncomment the line containing the command
%    "\OnlyDescription".
%    \begin{macrocode}
%% \OnlyDescription % uncomment to discard Implementation part
%    \end{macrocode}
%    Finally, setting "\hfuzz" and "\vfuzz" to 0~points is only one
%    of the many neurotic symptoms of the author!
%    \begin{macrocode}
\hfuzz = 0pt
\vfuzz = 0pt
%    \end{macrocode}
%    Now input this same file, using \DS\ conventions.
%    \begin{macrocode}
\begin{document}
  \DocInput{bullcntr.dtx}
%    \end{macrocode}
%    Then print the change list and the index.  We put these commands in
%    the driver, rather than in the comments of this file, because
%    producing the change list and the index is somewhat cumbersome, and some
%    users could prefer to omit them: such users should simply use a
%    different driver.
%    \begin{macrocode}
  % \clearpage % attach Change History below References
  \PrintChanges
  \clearpage \PrintIndex
%    \end{macrocode}
%    When this file is read directly by \LaTeX\ without the intervention
%    of \DS, the following line will make \TeX\ stop
%    reading.
%    \begin{macrocode}
\end{document}
%    \end{macrocode}
%    End of driver module.
%    \begin{macrocode}
%</driver>
%    \end{macrocode}
%
% \section{The code for the \packlass{\bullcntr} package}
%
%    This part of the file goes into \filedir{\bullcntr.sty}.
%    \begin{macrocode}
%<*bullcntr>
%    \end{macrocode}
%
%    \subsection{Identification}
%
%    The usual identification.  Is there a real need for this version
%    of \LaTeXe?
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}[1998/06/01] % LaTeX2e is required!
\ProvidesPackage{bullcntr}
                [2007/04/02 v0.04 (**development**)]
%    \end{macrocode}
%
%    \subsection{Initial code}
%
%    The code pertaining to the bullet styles is needed in the option
%    processing phase, so it must be defined here.
%
%    \subsubsection{Hooks for the bullets}
%    \label{sS:BullHookImpl}
%
%    Here we set the default definitions.  Actually, these defaults
%    will be re-established (or possibly changed, in future versions)
%    by "\ExecuteOptions", below; nonetheless, I think it's always
%    better to do things twice than to run the risk of not doing them
%    at all!
%
%    \begin{macro}{\counterlargebullet}
%    The \packlass{\bullcntr} package invokes this macro to draw the
%    bullets, when the value of the counter being displayed is less
%    than six.  The default definition is a "\bullet" in script
%    style~($\scriptstyle\bullet$), but the user is free to change it
%    with "\renewcommand" (macho \TeX\ programmers may also use
%    "\def", or even "\let").
%    \begin{macrocode}
\newcommand*\counterlargebullet{$\scriptstyle \bullet$}
%    \end{macrocode}
%    \end{macro}
%
%    \begin{macro}{\countersmallbullet}
%    This is the command invoked to draw the bullets when the value of
%    the counter being displayed is greater or equal than six.
%    Defaults to a "\bullet" in scriptscript
%    style~($\scriptscriptstyle \bullet$), but may be changed with
%    "\renewcommand" (or "\def", or "\let").
%    \begin{macrocode}
\newcommand*\countersmallbullet{$\scriptscriptstyle \bullet$}
%    \end{macrocode}
%    \end{macro}
%
%    The question arises, whether these definitions are appropriate.
%    Their main drawback is that they bypass the machinery set up for
%    using symbols from an extended character set when they are
%    available.  The problem is that "\textbullet" is simply too
%    large, and "\textperiodcentered" far too small\ldots
%
%    Precautions have been taken to assure that these macros are
%    \emph{fully} expanded, without stopping to the first-level
%    expansion, when a reference to a counter displayed using
%    "\bullcntr" is generated.  This is important in situations in
%    which the user has done something like this (which looks
%    absolutely natural):
%^^A
%    \begin{flushleft}
%      \small
%      "\renewcommand*{\counterlargebullet}{"\meta{some code}"}"\\
%      "\renewcommand*{\countersmallbullet}{\counterlargebullet}"
%    \end{flushleft}
%^^A
%    If "\countersmallbullet" were expanded just to the first level,
%    this would result in using the definition of
%    "\counterlargebullet" that is in force when the \emph{reference},
%    and not the counter value, is typeset.
%
%    \subsubsection{Declarations for predefined bullet styles}
%
%    Each of the following commands, intended to be used as a
%    declaration without arguments, sets a convenient definition for
%    the hooks defined in Subsection~\ref{sS:BullHookImpl}.
%
%    \begin{macro}{\heartctrbull}
%    Use hearts for all values from 1 to~9.
%    \begin{macrocode}
\newcommand*\heartctrbull{%
  \def\counterlargebullet{$\scriptscriptstyle \heartsuit$}%
  \let\countersmallbullet\counterlargebullet
}
%    \end{macrocode}
%    \end{macro}
%
%    \begin{macro}{\smallctrbull}
%    Use ``small'' bullets for all values from 1 to~9.
%    \begin{macrocode}
\newcommand*\smallctrbull{%
  \def\counterlargebullet{$\scriptscriptstyle \bullet$}%
  \let\countersmallbullet\counterlargebullet
}
%    \end{macrocode}
%    \end{macro}
%
%    \begin{macro}{\largectrbull}
%    Use ``large'' bullets for all values from 1 to~9.
%    \begin{macrocode}
\newcommand*\largectrbull{%
  \def\counterlargebullet{$\scriptstyle \bullet$}%
  \let\countersmallbullet\counterlargebullet
}
%    \end{macrocode}
%    \end{macro}
%
%    \begin{macro}{\smartctrbull}
%    Use ``large'' bullets for values from 1 to~5, and ``small'' ones
%    for values from 6 to~9.
%    \begin{macrocode}
\newcommand*\smartctrbull{%
  \def\counterlargebullet{$\scriptstyle \bullet$}%
  \def\countersmallbullet{$\scriptscriptstyle \bullet$}
}
%    \end{macrocode}
%    \end{macro}
%
%    \subsection{Declaration of options}
%
%    As a general rule, options pertaining to the same functional group
%    are declared in reverse order of desirability, the default option of
%    the group being declared last.  This assures that if more than
%    one option of the same group is erroneously asked for by the
%    user, the ``most desirable'' one (whatever this means) is
%    executed last, thereby remaining in effect.
%
%    Here we just have the options for setting the bullet style.  Each
%    of them simply invokes its corresponding declaration.
%
%    \begin{macrocode}
\DeclareOption{heartctrbull}{\heartctrbull}
\DeclareOption{smallctrbull}{\smallctrbull}
\DeclareOption{largectrbull}{\largectrbull}
\DeclareOption{smartctrbull}{\smartctrbull}
%    \end{macrocode}
%
%    \subsection{Option processing}
%
%    Nothing special to note here.
%
%    \begin{macrocode}
\ExecuteOptions{smartctrbull}
\ProcessOptions\relax
%    \end{macrocode}
%
%    \subsection{Package loading}
%
%    This package requires no helper packages.
%
%    \subsection{Main code}
%    \label{sS:MainCode}
%
%    Fig.~\ref{fig:dimens} shows the exact (theoretical) dimensions of
%    the grid used to place the bullets; we already saw in
%    fig.~\ref{fig:patterns}, in Section~\ref{S:UsageCntr}, on which
%    nodes of this grid the bullets are placed for each value of the
%    counter being displayed.  The grid is used assuming a unit of
%    measure equal to 1~ex.
%
%    \begin{figure}[tbp]
%      \centering
%        \setlength{\unitlength}{3cm}
%        \begin{picture}(3.1666667,3.2)(0,-.8333333)
%          \thicklines
%          \multiput(0,0)(.5,0){5}{\line(0,1){2}}
%          \multiput(0,0)(0,1){3}{\line(1,0){2}}
%          \put(0,\oMr){\line(1,0){2}}
%          \put(0,\oPr){\line(1,0){2}}
%          \linethickness{.2pt}
%          \multiput(0,0)(2,0){2}{\line(0,-1){.77}}
%          \multiput(.5,0)(.5,0){3}{\line(0,-1){.43}}
%          \multiput(.3,-.3333333)(.5,0){4}{\vector(-1,0){.3}}
%          \multiput(.2,-.3333333)(.5,0){4}{\vector(1,0){.3}}
%          \multiput(.25,-.5)(.5,0){4}{\makebox(0,0)[b]{$\frac{1}{2}$}}
%          \put(1.5,-.6666667){\vector(-1,0){1.5}}
%          \put(.5,-.6666667){\vector(1,0){1.5}}
%          \put(1,-.6666667){\makebox(0,0)[t]{\strut $2$}}
%          \multiput(2,0)(0,2){2}{\line(1,0){1.1}}
%          \put(2,\oMr){\line(1,0){.43}}
%          \put(2,\oPr){\line(1,0){.43}}
%          \put(2,1){\line(1,0){.77}}
%          \put(2.3333333,.7){\vector(0,-1){.5660254}}
%          \put(2.3333333,.3){\vector(0,1){.7}}
%          \put(2.3333333,1.7){\vector(0,-1){.7}}
%          \put(2.3333333,1.3){\vector(0,1){.5660254}}
%          \put(2.3333333,.5669873){\makebox(0,0)[l]{$\,\frac{\sqrt{3}}{2}$}}
%          \put(2.3333333,1.4330127){\makebox(0,0)[l]{$\,\frac{\sqrt{3}}{2}$}}
%          \multiput(2.6666667,.4)(0,1){2}{\vector(0,1){.6}}
%          \multiput(2.6666667,.6)(0,1){2}{\vector(0,-1){.6}}
%          \multiput(2.6666667,.5)(0,1){2}{\makebox(0,0)[l]{$\,1$}}
%          \put(3,.5){\vector(0,1){1.5}}
%          \put(3,1.5){\vector(0,-1){1.5}}
%          \put(3,1){\makebox(0,0)[l]{$\,2$}}
%          \multiput(0,2)(.5,0){5}{\line(0,1){.1666667}}
%          \multiput(0,2.2666667)(.5,0){5}{\circle{.2}}
%          \put(0  ,2.2666667){\makebox(0,0){1}}
%          \put( .5,2.2666667){\makebox(0,0){2}}
%          \put(1  ,2.2666667){\makebox(0,0){3}}
%          \put(1.5,2.2666667){\makebox(0,0){4}}
%          \put(2  ,2.2666667){\makebox(0,0){5}}
%        \end{picture}
%      \caption{Dimensions of the grid defining the position of the bullets}
%      \label{fig:dimens}
%    \end{figure}
%
%    \subsubsection{Basic drawing macros}
%
%    \begin{macro}{\@b@ll@box}
%    The task of this macro is simply to hide its argument in a
%    zero-dimensional box.  I know, \LaTeX\ kernel commands should be
%    used for this purpose, but\ldots
%    \begin{macrocode}
\@ifdefinable\@b@ll@box{\def\@b@ll@box#1{%
  \hb@xt@ \z@ {%
    \hss\vbox to \z@ {%
      \vss\hbox{#1}\vss
    }\hss
  }%
}}
%    \end{macrocode}
%    \end{macro}
%
%    \begin{macro}{\@b@ll@kernem}
%    Two convenient abbreviations for sparing tokens in subsequent
%    macros: the first\ldots
%    \begin{macrocode}
\@ifdefinable\@b@ll@kernem{\def\@b@ll@kernem{\kern 1ex }}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\@b@ll@kernen}
%    \ldots\ and the second.
%    \begin{macrocode}
\@ifdefinable\@b@ll@kernen{\def\@b@ll@kernen{\kern .5ex }}
%    \end{macrocode}
%    \end{macro}
%
%    \begin{macro}{\@b@ll@full@row}
%    This macro constructs a zero-height (and zero-depth) "\hbox" with
%    three inner zero-dimensional boxes, each containing one of the
%    three arguments.  These inner boxes are spaced out so as to place
%    them in the columns marked \circnumb{1}, \circnumb{3}
%    and~\circnumb{5} in fig.~\ref{fig:dimens}.  The idea is that this
%    macro produces a row of bullets.
%    \begin{macrocode}
\@ifdefinable\@b@ll@full@row{\def\@b@ll@full@row#1#2#3{%
  \hbox{%
    \thinspace
    \@b@ll@box{#1}%
    \@b@ll@kernem
    \@b@ll@box{#2}%
    \@b@ll@kernem
    \@b@ll@box{#3}%
    \thinspace
  }%
}}
%    \end{macrocode}
%    \end{macro}
%
%    \begin{macro}{\@b@ll@half@row}
%    This macro is similar to "\@b@ll@full@row": it produces a row of
%    bullets as well, but with only two boxes, that end up in the
%    columns marked \circnumb{2} and~\circnumb{4} in
%    fig.~\ref{fig:dimens}.
%    \begin{macrocode}
\@ifdefinable\@b@ll@half@row{\def\@b@ll@half@row#1#2{%
  \hbox{%
    \thinspace\@b@ll@kernen
    \@b@ll@box{#1}%
    \@b@ll@kernem
    \@b@ll@box{#2}%
    \thinspace\@b@ll@kernen
  }%
}}
%    \end{macrocode}
%    \end{macro}
%
%    \begin{macro}{\@b@ll@full@skip}
%    When the rows produced by "\@b@ll@full@row" or by
%    "\@b@ll@half@row" are being stacked to compose the desired
%    pattern, this macro is invoked to separate them with a vertical
%    space of $1$~unit (that is, $1$~ex).
%    \begin{macrocode}
\@ifdefinable\@b@ll@full@skip{\def\@b@ll@full@skip{%
  \vskip 1ex \relax
}}
%    \end{macrocode}
%    \end{macro}
%
%    \begin{macro}{\@b@ll@redu@skip}
%    Similar to the above, but the vertical space measures
%    $\frac{\sqrt{3}}{2}$~units (that is, $\frac{\sqrt{3}}{2}$~ex).
%    \begin{macrocode}
\@ifdefinable\@b@ll@redu@skip{\def\@b@ll@redu@skip{%
  \vskip .866025403785ex \relax
}}
%    \end{macrocode}
%    \end{macro}
%
%    \subsubsection{Macros for drawing the bullet patterns}
%
%    When setting a reference, "\@currentlabel" is set by means of a
%    (protected) "\edef"; hence, if we have redefined "\the"\meta{ctr}
%    (where \meta{ctr} is the counter being referenced) as
%    "\bullcntr{"\meta{ctr}"}", the "\bullcntr" command is expanded,
%    and indeed \emph{has} to be expanded (so, defining it with
%    "\DeclareRobustCommand" is absolutely pointless).  In previous
%    versions, this command broke down miserably in such circumstance.
%    So, let us rethink the whole thing with more ponderation, trying
%    not to confuse expansion and digestion like a newbie.
%
%    The general idea runs as depicted in the following list.
%
%    \begin{enumerate}
%
%    \item
%    "\bullcntr" calls "\@b@ll@cntr", converting the counter name into
%    the corresponding internal register (expansion).
%
%    \item\label{item:b@ll@}
%    "\@b@ll@cntr" tests whether the counter value is below~6
%    (expansion) and calls "\@b@ll@@cntr" passing the appropriate
%    "\counter"$\,*\,$\texttt{bullet} command.
%
%    \item\label{item:b@ll@@}
%    "\@b@ll@@cntr" selects which pattern to draw, depending on the
%    counter value (expansion), and calls the appropriate macro among
%    the ones defined below.  At this point the call could also be
%    "\protect"'ed, since no further expansion is required, when
%    setting a reference, in order to select the correct number (and
%    type) of bullets.  The "\@b@ll@@cntr" macro receives in~\#1 the
%    macro to be used to draw the bullets and in~\#2 the internal
%    count register.
%
%    \item
%    "\ensuremath" and everything that has to be digested is put in
%    the macros defined below.
%
%    \end{enumerate}
%
%    Steps \ref{item:b@ll@} and~\ref{item:b@ll@@} could be combined,
%    thus eliminating one macro, but I feel that the code is more
%    readable if the two steps are kept separate.
%
%    We continue our bottom-up approach in ordering the macro
%    definitions.
%
%    \begin{macro}{\@b@ll@vcent}
%    The command that ultimately does the typesetting.  It might be
%    called either from outside or from inside math mode; so
%    "\ensuremath" for the "\vcenter" that aligns the box of bullets
%    on the math axis.  The boxes themselves are produced by the
%    macros passed in argument~\#1.
%    \begin{macrocode}
\@ifdefinable\@b@ll@vcent{\def\@b@ll@vcent#1{%
  \ensuremath{\vcenter{\offinterlineskip #1}}%
}}
%    \end{macrocode}
%    \end{macro}
%
%    A series of macros follows, each of which typesets a specific
%    bullet pattern.  They all invoke "\@b@ll@vcent", passing in its
%    argument the appropriate macros.  In their own argument, they
%    receive the code that has to be employed to produce the bullets
%    (the \emph{expansion} of "\counter"$\,*\,$\texttt{bullet}).  To
%    avoid proliferation of macros, we do not define them with
%    "\DeclareRobustCommand"; rather, we shall "\protect" them when
%    invoking them, below.  (\emph{Begin to think:} why not to make
%    these macros accessible at the user level, calling them,
%    \emph{e.g.}, "\bullcntrone", "\bullcntrtwo", etc.?  In this case,
%    "\DeclareRobustCommand" could be considered.)
%
%    \begin{macro}{\@b@ll@one}
%    Macro for value~1.  Just one row with a bullet in the middle:
%    \begin{macrocode}
\@ifdefinable\@b@ll@one{\def\@b@ll@one#1{\@b@ll@vcent{%
  \@b@ll@full@row{}{#1}{}%
}}}
%    \end{macrocode}
%    \end{macro}
%
%    \begin{macro}{\@b@ll@two}
%    Macro for value~2.  Just one row with two bullets at both ends:
%    \begin{macrocode}
\@ifdefinable\@b@ll@two{\def\@b@ll@two#1{\@b@ll@vcent{%
  \@b@ll@full@row{#1}{}{#1}%
}}}
%    \end{macrocode}
%    \end{macro}
%
%    \begin{macro}{\@b@ll@three}
%    Macro for value~3.  One row with a centered bullet and one with
%    two bullets at the ends, separated by a vertical space of
%    $\sqrt{3}$~units:
%    \begin{macrocode}
\@ifdefinable\@b@ll@three{\def\@b@ll@three#1{\@b@ll@vcent{%
  \@b@ll@full@row{}{#1}{}%
  \@b@ll@redu@skip
  \@b@ll@redu@skip
  \@b@ll@full@row{#1}{}{#1}%
}}}
%    \end{macrocode}
%    \end{macro}
%
%    \begin{macro}{\@b@ll@four}
%    And so on: macro for value~4\ldots
%    \begin{macrocode}
\@ifdefinable\@b@ll@four{\def\@b@ll@four#1{\@b@ll@vcent{%
  \@b@ll@full@row{}{#1}{}%
  \@b@ll@full@skip
  \@b@ll@full@row{#1}{}{#1}%
  \@b@ll@full@skip
  \@b@ll@full@row{}{#1}{}%
}}}
%    \end{macrocode}
%    \end{macro}
%
%    \begin{macro}{\@b@ll@five}
%    \ldots for value~5\ldots
%    \begin{macrocode}
\@ifdefinable\@b@ll@five{\def\@b@ll@five#1{\@b@ll@vcent{%
  \@b@ll@full@row{#1}{}{#1}%
  \@b@ll@full@skip
  \@b@ll@full@row{}{#1}{}%
  \@b@ll@full@skip
  \@b@ll@full@row{#1}{}{#1}%
}}}
%    \end{macrocode}
%    \end{macro}
%
%    \begin{macro}{\@b@ll@six}
%    \ldots for~6\ldots
%    \begin{macrocode}
\@ifdefinable\@b@ll@six{\def\@b@ll@six#1{\@b@ll@vcent{%
  \@b@ll@half@row{#1}{#1}%
  \@b@ll@redu@skip
  \@b@ll@full@row{#1}{}{#1}%
  \@b@ll@redu@skip
  \@b@ll@half@row{#1}{#1}%
}}}
%    \end{macrocode}
%    \end{macro}
%
%    \begin{macro}{\@b@ll@seven}
%    \ldots 7\ldots
%    \begin{macrocode}
\@ifdefinable\@b@ll@seven{\def\@b@ll@seven#1{\@b@ll@vcent{%
  \@b@ll@half@row{#1}{#1}%
  \@b@ll@redu@skip
  \@b@ll@full@row{#1}{#1}{#1}%
  \@b@ll@redu@skip
  \@b@ll@half@row{#1}{#1}%
}}}
%    \end{macrocode}
%    \end{macro}
%
%    \begin{macro}{\@b@ll@eight}
%    \ldots 8\ldots
%    \begin{macrocode}
\@ifdefinable\@b@ll@eight{\def\@b@ll@eight#1{\@b@ll@vcent{%
  \@b@ll@full@row{#1}{#1}{#1}%
  \@b@ll@redu@skip
  \@b@ll@half@row{#1}{#1}%
  \@b@ll@redu@skip
  \@b@ll@full@row{#1}{#1}{#1}%
}}}
%    \end{macrocode}
%    \end{macro}
%
%    \begin{macro}{\@b@ll@nine}
%    \ldots and~9:
%    \begin{macrocode}
\@ifdefinable\@b@ll@nine{\def\@b@ll@nine#1{\@b@ll@vcent{%
  \@b@ll@full@row{#1}{#1}{#1}%
  \@b@ll@full@skip
  \@b@ll@full@row{#1}{#1}{#1}%
  \@b@ll@full@skip
  \@b@ll@full@row{#1}{#1}{#1}%
}}}
%    \end{macrocode}
%    \end{macro}
%
%    \subsubsection{The main command}
%
%    \begin{macro}{\bullcntr}
%    User-level command: simply invokes its inner-level counterpart,
%    using the internal name of the counter (the \meta{countdef
%    token}, right below).
%    \begin{macrocode}
\newcommand*\bullcntr[1]{\expandafter\@b@ll@cntr\csname c@#1\endcsname}
%    \end{macrocode}
%    \end{macro}
%
%    \begin{macro}{\@b@ll@cntr}
%    This macro expands either to
%    \begin{center}
%      "\@b@ll@@cntr \counterlargebullet "\meta{countdef token}
%    \end{center}
%    or to
%    \begin{center}
%      "\@b@ll@@cntr \countersmallbullet "\meta{countdef token}
%    \end{center}
%    depending on the counter value.  Note that \#1 must be a single
%    token (as it is).
%    \begin{macrocode}
\@ifdefinable\@b@ll@cntr{\def\@b@ll@cntr#1{%
  \expandafter\expandafter\expandafter \@b@ll@@cntr
  \ifnum #1<6
    \expandafter\counterlargebullet
  \else
    \expandafter\countersmallbullet
  \fi
  #1%
}}
%    \end{macrocode}
%    \end{macro}
%
%    \begin{macro}{\@b@ll@@cntr}
%    This macro selects the pattern to draw.  The following is a
%    typical switch on the counter value, but pay attention to the
%    "\protect"\slash "\expandafter" mechanism: after this macro, and
%    hence the "\ifcase", have been expanded, the token flow will look
%    like this (if the value of the counter is, say, 2 and the
%    argument passed in~\#1 is, consequently, "\counterlargebullet"):
%    \begin{center}
%      "\protect \@b@ll@two {\counterlargebullet }"
%    \end{center}
%    Therefore, in the context of a "\protected@edef", the
%    "\protect"'ed "\@b@ll@two" will not be expanded, but
%    "\counterlargebullet" will be (fully).
%    \changes{0.04}{2007/04/02}{Corrected erroneous behavior for case~0,
%      argument \#1 must be \protect\cmnd{@gobble}'d in this case}
%    \begin{macrocode}
\@ifdefinable\@b@ll@@cntr{\def\@b@ll@@cntr#1#2{%
  \ifcase #2\expandafter\@gobble
  \or
    \expandafter\protect \expandafter\@b@ll@one
  \or
    \expandafter\protect \expandafter\@b@ll@two
  \or
    \expandafter\protect \expandafter\@b@ll@three
  \or
    \expandafter\protect \expandafter\@b@ll@four
  \or
    \expandafter\protect \expandafter\@b@ll@five
  \or
    \expandafter\protect \expandafter\@b@ll@six
  \or
    \expandafter\protect \expandafter\@b@ll@seven
  \or
    \expandafter\protect \expandafter\@b@ll@eight
  \or
    \expandafter\protect \expandafter\@b@ll@nine
%    \end{macrocode}
%    For larger values we simply invoke the error-handling macro of
%    the kernel; strictly speaking, this is not correct, since this is
%    not a ``\LaTeX\ error'', but an error from this package.  Anyway,
%    I think no user will be surprised by this behavior.
%    \begin{macrocode}
  \else
    \expandafter\@ctrerr
%    \end{macrocode}
%    The argument intended for "\@b@ll@"\meta{number} follows, that
%    "\@ctrerr" doesn't want, so we follow it with a "\@gobble"; note
%    that this is \emph{not} "\protect"'ed, thus, during a
%    "\protected@edef", the espansion of "\@b@ll@@cntr" in this ``out
%    of range'' case will leave nothing in the token flow.
%    \begin{macrocode}
    \expandafter\@gobble
%    \end{macrocode}
%    After selecting the appropriate macro, we insert the argument:
%    \begin{macrocode}
  \fi
    {#1}%
}}
%    \end{macrocode}
%    \end{macro}
%
%    End of the module for the \packlass{\bullcntr} package.
%    \begin{macrocode}
%</bullcntr>
%    \end{macrocode}
%
% \section{The code for the \packlass{\bullenum} package}
%
%    This part of the file goes into \filedir{\bullenum.sty}.
%    \begin{macrocode}
%<*bullenum>
%    \end{macrocode}
%
%    \subsection{Identification}
%
%    The usual identification.  Is there a real need for this version
%    of \LaTeXe?
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}[1998/06/01] % LaTeX2e is required!
\ProvidesPackage{bullenum}
                [2007/04/02 v0.04 (**development**)]
%    \end{macrocode}
%
%    \subsection{Initial code}
%
%    This package has no initial code.
%
%    \subsection{Declaration of options}
%
%    Just pass every option on to the \packlass{\bullcntr} package.
%
%    \begin{macrocode}
\DeclareOption*{\PassOptionsToPackage{\CurrentOption}{bullcntr}}
%    \end{macrocode}
%
%    \subsection{Option processing}
%
%    Nothing special to note here.
%
%    \begin{macrocode}
\ProcessOptions\relax
%    \end{macrocode}
%
%    \subsection{Package loading}
%
%    Neither here.
%
%    \begin{macrocode}
\RequirePackage{bullcntr}[2007/04/02]
%    \end{macrocode}
%
%    \subsection{Main code}
%
%    The purpose of this package is simply to define the
%    \env{bullenum} environment.
%
%    \begin{environment}{bullenum}
%    This is just an \env{enumerate} environment in which we say
%^^A
%    \begin{flushleft}
%      "\def\the"\meta{enum~$\ell$}"{\bullcntr{"\meta{enum~$\ell$}"}}"\\
%      "\def\label"\meta{enum~$\ell$}"{\the"\meta{enum~$\ell$}"}"
%    \end{flushleft}
%^^A
%    at the beginning, where \( \meta{enum~$\ell$} =
%    \mbox{eval(}"\@enumctr"\mbox{)} \) (\emph{i.e.}, \(
%    \meta{enum~$\ell$} = \texttt{enumi},\linebreak[0]
%    \texttt{enumii},\ldots \), according to the current value of
%    "\@enumdepth").
%    \begin{macrocode}
\newenvironment*{bullenum}{%
  \enumerate
  \expandafter\edef \csname the\@enumctr\endcsname {%
    \noexpand\bullcntr{\@enumctr}%
  }%
  \expandafter\edef \csname label\@enumctr\endcsname {%
    \expandafter\noexpand \csname the\@enumctr\endcsname
  }%
}{\endenumerate}
%    \end{macrocode}
%    \end{environment}
%
%    End of the module for the \packlass{\bullenum} package.
%    \begin{macrocode}
%</bullenum>
%    \end{macrocode}
%
% \section{End of input}
%
%    The usual "\endinput" which prevents the \DS\ program from putting
%    garbage into the generated files.
%    \begin{macrocode}
\endinput
%    \end{macrocode}
%
% \Finale
%