summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/bullcntr
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/bullcntr
Initial commit
Diffstat (limited to 'macros/latex/contrib/bullcntr')
-rw-r--r--macros/latex/contrib/bullcntr/00readme.txt254
-rw-r--r--macros/latex/contrib/bullcntr/README56
-rw-r--r--macros/latex/contrib/bullcntr/bullcntr-man.pdfbin0 -> 774038 bytes
-rw-r--r--macros/latex/contrib/bullcntr/bullcntr-man.tex1614
-rw-r--r--macros/latex/contrib/bullcntr/bullcntr-sam.tex310
-rw-r--r--macros/latex/contrib/bullcntr/bullcntr.dtx1662
-rw-r--r--macros/latex/contrib/bullcntr/bullcntr.ins106
-rw-r--r--macros/latex/contrib/bullcntr/bullenum-sam.tex688
-rw-r--r--macros/latex/contrib/bullcntr/manifest.txt101
9 files changed, 4791 insertions, 0 deletions
diff --git a/macros/latex/contrib/bullcntr/00readme.txt b/macros/latex/contrib/bullcntr/00readme.txt
new file mode 100644
index 0000000000..3c1df276fc
--- /dev/null
+++ b/macros/latex/contrib/bullcntr/00readme.txt
@@ -0,0 +1,254 @@
+
+This is file `00readme.txt'.
+(Start your first tour of the bullcntr package by reading this file.)
+
+This file is part of a work named "bullcntr package".
+
+Copyright (C) 2007 by Gustavo MEZZETTI <gustavo.mezzetti@istruzione.it>.
+
+The 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
+ 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.
+
+This file, after giving a brief description of the bullcntr package,
+explains how to install it and how to generate its documentation.
+
+October 10, 2008 (vers. 0.04)
+
+
+
+CONTENTS
+========
+
+- Brief description of the software
+- Installation in a snapshot
+- Checking the contents of the distribution
+- How to install the bullcntr package
+- How to generate the main documentation
+- Ancillary files and documentation
+
+
+
+BRIEF DESCRIPTION OF THE SOFTWARE
+=================================
+
+This software is named after its primary component, but it actually
+contains _two_ packages: the bullcntr package and the bullenum package.
+
+The bullcntr package defines the command "\bullcntr", which can be thought
+of as an analogue of the "\fnsymbol" command: like the latter, it displays
+the value of a counter lying between 1 and 9, but uses, for the purpose, a
+regular pattern of bullets.
+
+The bullenum package--which also loads the bullcntr package as part of its
+own initialization--defines the environment "bullenum", a list-making
+environment similar to "enumerate", which numbers its item using the
+"\bullcntr" command. Most users will simply use this package and never
+call the bullcntr package directly.
+
+
+
+INSTALLATION IN A SNAPSHOT
+==========================
+
+The bullcntr package is distributed in the usual .dtx + .ins format. The
+main file is `bullcntr.dtx', with installation script `bullcntr.ins'. Do
+the usual things to install it and to generate the documentation. If you
+do not know what the usual things are, read below. Note that in order to
+generate the documentation you should do the following:
+
+latex; latex; makeindex (.idx); makeindex (.glo); latex; latex.
+
+The distribution also includes three files with extension `.tex': these are
+sample source files that illustrate how to use the abovementioned packages,
+and should simply be copied to the same location where the documentation is
+put.
+
+
+
+CHECKING THE CONTENTS OF THE DISTRIBUTION
+=========================================
+
+Before installing the bullcntr package and generating its documentation, it
+is a good idea to read the file `manifest.txt', which lists all the files
+that make up the distribution, to check that you don't lack any of them (in
+particular, that you have the file `manifest.txt' itself!). If you do find
+that some files are missing, don't hesitate to complain to the distributor
+from whom you obtained the others: this person, company, or institution is
+infringing the copyright (actually, the copyleft) of the bullcntr package.
+Please remember, however, that in order to comply with the copyright a
+distributor is only requested to supply the files listed in `manifest.txt'
+under the title "MEANING OF THE TERM `Work'", but not those listed under
+"MEANING OF THE TERM `Compiled Work'".
+
+
+
+HOW TO INSTALL THE BULLCNTR PACKAGE
+===================================
+
+To install the bullcntr package, follow these steps:
+
+1) Make sure that the files `bullcntr.dtx' and `bullcntr.ins' are placed in
+the same directory; below, we shall indicate this directory as "the current
+directory".
+
+2) Run LaTeX (or Plain TeX) once on the file `bullcntr.ins'. This will
+generate, in the current directory, the following two LaTeX input files:
+
+ bullcntr.sty
+ bullenum.sty
+
+3) Move the files listed in 2) from the current directory to a LaTeX input
+directory--see b) and c) below.
+
+4) If you wish, delete the file `bullcntr.log' to save disk space.
+
+Installation is now finished! The following comments may be useful:
+
+a) 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 `bullcntr.ins'.
+
+b) 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 hold 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.
+
+c) If you are not able to find the LaTeX input directories, or you are not
+allowed to modify them and cannot create your personal LaTeX input
+directories, do this: place the files listed under 2) above in any
+directory of your choice (a newly created, empty directory would be the
+best choice, however); then put all the LaTeX source files that you want to
+typeset using the bullcntr package in that same directory. Of course, this
+solution becomes impractical if the number of such source files exceeds a
+dozen or so; but for a few files you can do this way, at least until you
+decide to finally learn how to create your private LaTeX input directories!
+:-)
+
+d) You may also choose to install the bullcntr package within the main
+texmf tree of your TeX installation (as opposed to installing it inside a
+directory devoted to private classes and packages). In this case, note
+that the **proposed** (but not yet approved!) TDS-compliant location for
+the bullcntr package, that is, the directory inside which you should put
+the files listed in 2), is
+
+ $TEXMF/tex/latex/bullcntr/
+
+The **proposed** location for the documentation, on the other hand, is
+
+ $TEXMF/doc/latex/bullcntr/
+
+We shall describe below in detail which files should be put in this place.
+Of course, in order to do all this you must have appropriate access
+priviledges to the texmf tree of your site.
+
+
+
+HOW TO GENERATE THE MAIN DOCUMENTATION
+======================================
+
+An alternative form of the documentation, already typeset and packaged in
+PDF format, is given in the file `bullcntr-man.pdf' that you might have
+found on some sites (e.g., the CTAN sites). This file, however, is not
+part of the bullcntr package and distributors are not requested to include
+it among the distributed files. Moreover, it does not contain any
+implementation notes (in which most users are not at all interested).
+
+If the distributor from whom you obtained the bullcntr package did not
+provide the file `bullcntr-man.pdf', or if you want the full documentation,
+complete with all implementation notes, you can generate it by following
+these steps:
+
+1) Run LaTeX (_not_ Plain TeX) _twice_ on the file `bullcntr.dtx'. This,
+among other things, will generate the files `bullcntr.idx' and
+`bullcntr.glo' in the same directory as the file `bullcntr.dtx'.
+
+2) Run MakeIndex on the file `bullcntr.idx' obtained in 1), using the style
+file `gind.sty', which is part of the standard LaTeX distribution.
+
+3) Run MakeIndex on the file `bullcntr.glo' obtained in 1), using the style
+file `gglo.sty', which is part of the standard LaTeX distribution.
+
+4) Run LaTeX _two_ more times on the file `bullcntr.dtx'.
+
+5) If you wish, you may now delete the following files, to save disk space:
+
+ bullcntr.aux
+ bullcntr.glo
+ bullcntr.gls
+ bullcntr.idx
+ bullcntr.ilg
+ bullcntr.ind
+ bullcntr.lof
+ bullcntr.log
+ bullcntr.toc
+
+After step 4), you should get the documentation in DVI format in the file
+`bullcntr.dvi', located in the same directory as `bullcntr.dtx', with all
+indexes, table of contents, etc. correctly set.
+
+However, if you are neurotic (as I am), you could run LaTeX three or four
+times, instead of two, in step 1)... :-)
+
+Other LaTeX typesetting engines should work in the same way, perhaps
+producing the output in a different format; for example, you may use
+pdflatex in place of LaTeX to obtain the documentation in PDF format
+(doing so, of course, produces a file named `bullcntr.pdf').
+
+When you have typeset the documentation, in either format (or in both
+formats, why not), you might want to install it in the main texmf tree of
+your site; as said above,
+
+ $TEXMF/doc/latex/bullcntr/
+
+is the **proposed** location for this purpose, that is, the directory
+inside which you should put the files `bullcntr.dvi' and/or `bullcntr.pdf',
+or equivalent files in other formats, should you have produced any. This
+is also the place where ancillary files and documentation, described in the
+next section, should be put.
+
+
+
+ANCILLARY FILES AND DOCUMENTATION
+=================================
+
+If you want to distribute a "Compiled Work" (see manifest.txt), you are
+bound to make the following files available to your users:
+
+ 00readme.txt
+ manifest.txt
+ bullcntr-man.tex
+ bullcntr-sam.tex
+ bullenum-sam.tex
+
+These files are best placed together with the compiled documentation
+(files `bullcntr.dvi' and/or `bullcntr.pdf'), possibly under
+
+ $TEXMF/doc/latex/bullcntr/
+
+Any compiled version of the above files that you wish to include in your
+distribution of a "Compiled Work" (e.g., the file `bullcntr-man.pdf') also
+belongs here. Remember, however, that you are not obliged to distribute
+such compiled files, except--always in the case of a "Compiled Work"--for
+the result of typesetting `bullcntr.dtx'; for other files, distributing
+their sources suffices to comply with the license. Once again, see
+`manifest.txt' and the LaTeX Project Public License for precise
+instructions.
+
+
+
+Have fun with the bullcntr package!
+
diff --git a/macros/latex/contrib/bullcntr/README b/macros/latex/contrib/bullcntr/README
new file mode 100644
index 0000000000..c648c94313
--- /dev/null
+++ b/macros/latex/contrib/bullcntr/README
@@ -0,0 +1,56 @@
+The bullcntr package defines the command "\bullcntr", which can be thought
+of as an analogue of the "\fnsymbol" command: like the latter, it displays
+the value of a counter lying between 1 and 9, but uses, for the purpose, a
+regular pattern of bullets. Approximately, these nine patterns of bullets
+are laid down as follows:
+
+
+ *
+ * * *
+ * *
+ 1 2 3
+
+
+
+ * * * * *
+* * * * *
+ * * * * *
+ 4 5 6
+
+
+
+ * * * * * * * *
+* * * * * * * *
+ * * * * * * * *
+ 7 8 9
+
+
+An ancillary package is included along with the bullcntr package: the
+bullenum package. This is a "wrapper" that calls bullcntr and, in
+addition, defines a new environment, called "bullenum", that lets you
+create enumeration lists numbered via the "\bullcntr" command.
+
+I wrote this package as an amusing exercise during a boring afternoon in
+which I had nothing better to do!
+
+The bullcntr package may be distributed and/or modified under the
+conditions of the LaTeX Project Public License, available at
+ http://www.latex-project.org/lppl.txt
+See the files `00readme.txt' and `manifest.txt' for further details.
+
+For more information, read the following files:
+
+00readme.txt -- start by reading this file
+bullcntr-man.pdf -- general information on the bullcntr package (PDF)
+
+Other files that make up the distribution are:
+
+manifest.txt -- legal stuff
+bullcntr.dtx -- main source file
+bullcntr.ins -- installation script
+bullcntr-man.tex -- LaTeX source of `bullcntr-man.pdf'
+bullcntr-sam.tex -- sample code that uses the bullcntr package
+bullenum-sam.tex -- sample code that uses the bullenum package
+
+See the file `manifest.txt' for a more precise specification of what files
+constitutes a LPPL-compliant distribution.
diff --git a/macros/latex/contrib/bullcntr/bullcntr-man.pdf b/macros/latex/contrib/bullcntr/bullcntr-man.pdf
new file mode 100644
index 0000000000..5f09f6a740
--- /dev/null
+++ b/macros/latex/contrib/bullcntr/bullcntr-man.pdf
Binary files differ
diff --git a/macros/latex/contrib/bullcntr/bullcntr-man.tex b/macros/latex/contrib/bullcntr/bullcntr-man.tex
new file mode 100644
index 0000000000..c4559a3e0b
--- /dev/null
+++ b/macros/latex/contrib/bullcntr/bullcntr-man.tex
@@ -0,0 +1,1614 @@
+%
+% Copyright (C) 2007 by Gustavo MEZZETTI <gustavo.mezzetti@istruzione.it>.
+%
+% This file is part of a work named "bullcntr package".
+%
+% The 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
+% 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).
+%
+\documentclass[a4paper]{article}
+\usepackage{bullenum}
+\usepackage[bookmarksnumbered]{hyperref}
+
+\title{Overview\\of \tbull
+ \thanks{This document describes version \bullvers\ (\bulldate).
+ Copyright \copyright~2007 by G.~Mezzetti
+ (see page~\pageref{S:Copyright} for details).}}
+\author{G.~Mezzetti\\{\ttfamily\normalsize
+ gustavo.mezzetti@istruzione.it}}
+\date{October~10, 2008}
+
+\newcommand*{\bullvers}{0.04}
+\newcommand*{\bulldate}{2007/04/02}
+\newcommand*{\filename}{bullcntr-man.tex}
+
+\DeclareRobustCommand*{\command}[1]{%
+ {\texorpdfstring{\normalfont\ttfamily \char\escapechar}{\pdfbslash}#1}%
+}
+\DeclareRobustCommand*{\packlass}[1]{%
+ {\texorpdfstring{\normalfont \sffamily}{}#1}%
+}
+\DeclareRobustCommand*{\meta}[1]{\mbox{\(\langle\textit{#1}\rangle\)}}
+\DeclareRobustCommand*{\filedir}[1]{{\normalfont\ttfamily #1}}
+\DeclareRobustCommand*{\env}[1]{\texttt{#1}}
+\DeclareRobustCommand*{\cnt}[1]{\texttt{#1}}
+\DeclareRobustCommand*{\opt}[1]{{\normalfont\ttfamily #1}}
+\newcommand*{\Bullcntr}{bullcntr}
+\newcommand*{\bull}{\packlass{\Bullcntr}}
+\newcommand*{\tbull}{the \bull\ package}
+\newcommand*{\Bullenum}{bullenum}
+\newcommand*{\benu}{\packlass{\Bullenum}}
+\newcommand*{\tbenu}{the \benu\ package}
+\newcommand*{\hreff}[1]{\href{#1}{\texttt{#1}}}
+\newcommand*{\Enumerat}{enumerate}
+\newcommand*{\beenv}{\env{\Bullenum}}
+\newcommand*{\enenv}{\env{\Enumerat}}
+
+\newcommand*{\pdfbslash}{}
+{\catcode`\|=0 |catcode`|\=12 |gdef|pdfbslash{\\}}
+
+\makeatletter
+\newcommand*\hyref[1]{% actually two arguments, <label> and <text>
+ \@ifundefined{r@#1}{% #1 is <label>
+ \G@refundefinedtrue % \protect seems superfluous in our context
+ \@latex@warning{Reference `#1' on page \thepage \space undefined}%
+ \@firstofone % returns <text> (removing braces)
+ }{%
+ \expandafter\@hyref\expandafter{\csname r@#1\endcsname}%
+ }%
+}
+\@ifdefinable\@hyref{\def\@hyref#1{%
+ \expandafter\@@hyref#1%
+}}
+\@ifdefinable\@@hyref{\def\@@hyref#1#2#3#4#5{%
+ \hyperlink{#4}% <text> follows and becomes the second argument
+}}
+\makeatother
+
+\hfuzz = 0pt
+\vfuzz = 0pt
+
+
+
+\begin{document}
+
+\maketitle
+
+\begin{abstract}
+ We describe a \LaTeX\ package which defines a new command, similar
+ to \verb|\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, inclusive.
+
+ We also present an ancillary package which defines a new
+ environment, similar to \enenv, for creating lists of items
+ numbered in this way.
+\end{abstract}
+
+
+
+\tableofcontents
+
+
+
+\begingroup
+
+\setlength{\parskip}{\medskipamount}
+\setlength{\parindent}{0pt}
+
+\section*{Copyright notice}
+\label{S:Copyright}
+\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}. This file is part of a work
+named ``\bull\ package'', and may be distributed and/or modified only
+as a part thereof. Subsection~\ref{SS:License} on
+page~\pageref{SS:License} explains the conditions under which \tbull\
+may be distributed and/or modified.
+
+Permission is granted to make 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
+\href{http://www.latex-project.org/lppl.txt}{\LaTeX\ Project Public
+License}, and should be avoided: please distribute, in addition, the
+source file \filedir{\filename} 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.
+
+\endgroup
+
+
+
+\clearpage
+\setcounter{secnumdepth}{0}
+
+\section{Introduction}
+\label{S:Intro}
+
+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 about 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 actually
+do so, until very recently, when I~suddenly decided to sit down and
+% ( paren match
+write the code!~:-)
+
+Regrettably, I~had to discover a major bug in the macros I~had dashed
+off in such a haste, which required extensive (and more careful!)\
+redesign of the code. I~took this opportunity to thoroughly
+reorganize the package, making it easier, for the user, to switch from
+one style of bullets to another, and also adding an ancillary package
+that simplifies the creation of lists numbered with bullets.
+
+This document describes \tbull\ version \textbf{\bullvers}
+(\textbf{\bulldate}).
+
+
+
+\setcounter{secnumdepth}{3}
+
+\section{Installing \tbull}
+
+As usual for \LaTeX\ distributions, \tbull\ 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 \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 \tbull\ 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 it.
+
+
+
+\subsection{Documentation}
+
+To produce the 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.
+
+
+
+\subsection{License}
+\label{SS:License}
+
+The \bull\ 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 \bull\ package may be distributed and/or modified under the
+conditions of the \href{http://www.latex-project.org/lppl.txt}{\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}
+ \hreff{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 \bull\ package has the LPPL maintenance status
+``author-maintained''.
+% Switching to the ``maintained'' status (which
+% is the status recommended by the \TeX\ community) is currently being
+% considered, but for now I~still prefer to keep my tiny unfledged
+% % ( paren match
+% creation under my protecting wing\ldots~:-)\spacefactor=\sfcode`.
+% \space Leaving jokes apart, I'm waiting to see if other ``disastrous''
+% mistakes are still lurking in the code, and whether there is an
+% interest of the \LaTeX\ community into this silly package that
+% justifies maintaining it in a more efficient way.
+
+The file \filedir{manifest.txt} included in \tbull\ specifies what
+this 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 \tbull\ is unrestricted, provided that you accept the terms
+and conditions of the
+\href{http://www.latex-project.org/lppl.txt}{\LaTeX\ Project Public
+License} and of the \hyref{SSS:NoWarranty}{following subsection} for
+what concerns the absence of any warranty.
+
+
+
+\subsubsection{No warranty}
+\label{SSS:NoWarranty}
+
+There is absolutely no warranty for \tbull. The Copyright Holder
+provides \tbull\ ``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 \tbull\ is with
+you. Should \tbull\ 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 \tbull\ 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
+\tbull\ 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 \tbull\ 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 \tbull, please let me
+know them: I'll be happy to read what you think. My e-mail address is
+indicated under the title of this document. Please include the
+\emph{exact} phrase \verb*|bullcntr package| in the \emph{subject} of
+your message; otherwise, it could be thrown away by a mail filter.
+
+
+
+\section{Using \tbull}
+
+Version \bullvers\ of \tbull\ is a bit more elaborate than its
+predecessor: in addition to the
+\hyref{SS:bullcntr}{\command{\Bullcntr} main command} and to the
+\hyref{SS:Hooks}{hooks for the bullets}, it now features
+\hyref{SS:CntrInvo}{options} and \hyref{SS:BullStyl}{predefined bullet
+styles}.
+
+
+
+\subsection{Package invocation and options}
+\label{SS:CntrInvo}
+
+You load \tbull\ by means of the usual \verb|\usepackage| declaration:
+%
+\begin{flushleft}
+ \verb|\usepackage|\meta{options}\verb|{bullcntr}|
+\end{flushleft}
+%
+You may specify one of the following, mutually exclusive options,
+which affect the size (or the type) of the bullets used by
+\verb|\bullcntr| command:
+%
+\begin{description}
+%
+\item[\opt{largectrbull}]
+(Relatively) ``large'' bullets are used for all values from 1 to~9.
+This has exactly the same effect as a \verb|\largectrbull| global
+declaration (see Subsection~\ref{SS:BullStyl}).
+%
+\item[\opt{smallctrbull}]
+The opposite: ``small'' bullets are used for all values from 1 to~9.
+This has exactly the same effect as a \verb|\smallctrbull| global
+declaration (see Subsection~\ref{SS:BullStyl}).
+%
+\item[\opt{smartctrbull}]
+(Relatively) ``large'' bullets are used for values from 1 through~5
+(inclusive), while ``small'' ones are used for those greater than or
+equal to~6. This has exactly the same effect as a
+\verb|\smartctrbull| global declaration (see
+Subsection~\ref{SS:BullStyl}).
+%
+\item[\opt{heartctrbull}]
+Hearts are used (instead of bullets) for all values from 1 to~9. This
+has exactly the same effect as a \verb|\heartctrbull| global
+declaration (see Subsection~\ref{SS:BullStyl}).
+%
+\end{description}
+%
+If you don't specify any, the default option is \opt{smartctrbull}.
+
+
+
+
+\subsection{The \command{\Bullcntr} command}
+\label{SS:bullcntr}
+
+This is a command analogous to the \verb|\fnsymbol| command (see the
+\textsl{\LaTeX book} \cite[Subsection~C.8.4]{LaTeXbook}): you may use
+it directly in the text, as in
+%
+\begin{flushleft}
+ \ldots\texttt{the counter value displays as}\verb|~\bullcntr{|\meta{ctr}\verb|}|\ldots
+\end{flushleft}
+%
+(where \meta{ctr} is a counter name, defined with \verb|\newcounter|),
+or you may redefine the \verb|\the|\meta{ctr} command, as in
+%
+\begin{flushleft}
+ \verb|\renewcommand*{\the|\meta{ctr}\verb|}{\bullcntr{|\meta{ctr}\verb|}}|
+\end{flushleft}
+%
+By way of example, in the case of a counter named \cnt{myctr}, you
+would write
+%
+\begin{verbatim}
+The counter value displays as~\bullcntr{myctr}.
+\end{verbatim}
+%
+directly in the text, or the following to redefine the
+\verb|\themyctr| command:
+%
+\begin{verbatim}
+\renewcommand*{\themyctr}{\bullcntr{myctr}}
+\end{verbatim}
+%
+
+When \( \verb|\value{|\meta{ctr}\verb|}|=0 \), the command
+\verb|\bullcntr{|\meta{ctr}\verb|}| silently typesets nothing (not
+even a space); but when \( \verb|\value{|\meta{ctr}\verb|}|<0 \) or \(
+\verb|\value{|\meta{ctr}\verb|}|>9 \), an error is generated.
+
+
+
+\subsection{Hooks for the bullets}
+\label{SS:Hooks}
+
+The main task of \tbull\ is to calculate the position of the
+``bullets'' used to display the value of the given counter; 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.
+
+If the value of the counter being displayed is less than~6 (less
+than~6 bullets need to be drawn), the \verb|\bullcntr| command invokes
+the \verb|\counterlargebullet| macro to draw each of them. If you
+want, you should redefine this macro (using \verb|\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 \tbull\ itself.
+
+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
+\verb|\bullcntr| command calls the \verb|\countersmallbullet| macro.
+It is intended that this macro typeset 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 \verb|\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 \tbull\ already
+defines this macro) you may change the definition with
+\verb|\renewcommand|, \emph{e.g.}:
+%
+\begin{verbatim}
+\renewcommand*{\countersmallbullet}{\textperiodcentered}
+\end{verbatim}
+%
+
+For both hooks, it is best to \verb|\protect| fragile commands that
+appear in the code used in their (re)definition.
+
+``Macho \TeX\ programmers'' may also use \verb|\def| instead of
+\verb|\renewcommand|; for example:
+%
+\begin{verbatim}
+\def\counterlargebullet{\textbullet}
+\def\countersmallbullet{\textperiodcentered}
+\end{verbatim}
+%
+(Actually, in a case like this, even \verb|\let| could be used.)
+
+
+
+\subsection{Predefined bullet styles}
+\label{SS:BullStyl}
+
+To spare you the nuisance of redefining the hooks mentioned in
+Subsection~\ref{SS:Hooks}, at least in normal situations, four
+``bullet styles'' are already predefined by \tbull, 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.
+
+\begin{description}
+
+\item[\command{largectrbull}]
+This declaration causes (relatively) ``large'' bullets to be used for
+all values from 1 to~9.
+
+\item[\command{smallctrbull}]
+This declaration causes ``small'' bullets to be used for all values
+from 1 to~9.
+
+\item[\command{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.
+
+\item[\command{heartctrbull}]
+This declaration causes little hearts (instead of bullets) to be used
+for all values from 1 to~9.
+
+\end{description}
+
+These are in all respects normal declarations, obeying to ordinary
+scoping rules. The corresponding options described in
+Subsection~\ref{SS:CntrInvo} simply set the style at the outer
+(global, or document-wide) level.
+
+
+
+\subsection{Cross-references}
+\label{SS:CrossRef}
+
+Cross-references now work fine with the \verb|\bullcntr| command. You
+may use \verb|\label| (preceded by \verb|\refstepcounter| if
+necessary) in the usual way to label, for example, an item in a list
+numbered via \verb|\bullcntr| (recall that \verb|\item| calls
+\verb|\refstepcounter| by itself), and elsewhere cross-reference that
+item with \verb|\ref|: the reference will be typeset correctly, using
+the same bullet style that was in effect at the spot where
+\verb|\label| (and not \verb|\ref|) was used.
+
+Examples of such cross-references are shown later, in
+Subsection~\ref{SS:CrossXmp}.
+
+
+
+\section{Using \tbenu}
+
+The \bull\ 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 \hyref{S:Intro}{Introduction}).
+With the \verb|\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}
+ \texttt{\ \ \ \ }\meta{items}
+\end{flushleft}
+\begin{verbatim}
+\end{enumerate}
+\end{verbatim}
+%
+This, nonetheless, is not perfect, since it breaks if the \enenv\
+environment is moved inside another \enenv, because of the explicit
+mention of \verb|\theenumi| and of \verb|\labelenumi|.
+
+For this reason, and also to facilitate the use of the
+\verb|\bullcntr| command for numbering list items, a new package has
+been added to \tbull; this helper package, called \benu, simply
+defines the \beenv\ environment, a variation of \enenv\ that numbers
+its items using the \verb|\bullcntr| command. Indeed,
+%
+\begin{verbatim}
+\begin{bullenum}
+\end{verbatim}
+\begin{flushleft}
+ \texttt{\ \ \ \ }\meta{items}
+\end{flushleft}
+\begin{verbatim}
+\end{bullenum}
+\end{verbatim}
+%
+is equivalent to
+\begin{flushleft}
+ \verb|\begin{enumerate}|\\
+ \verb| \renewcommand*{\theenum|\meta{lvl}\verb|}{\bullcntr{enum|\meta{lvl}\verb|}}|\\
+ \verb| \renewcommand*{\labelenum|\meta{lvl}\verb|}{\theenum|\meta{lvl}\verb|}|
+\end{flushleft}
+\begin{flushleft}
+ \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 \enenv\
+environment.
+
+In other words, \beenv\ can be used in every place where \enenv\ can,
+and numbers its items with an increasing number of bullets, regardless
+of the definition of \verb|\theenum|\meta{lvl} and
+\verb|\labelenum|\meta{lvl}. Of course, the environment must contain
+no more than 9~items. Moreover, if you use \verb|\label| to set up a
+reference, subsequent \verb|\ref|'s will typeset the reference as a
+``bulletted'' number, using, for the ``bullets'', the character that
+was current at the time the \verb|\label| was encountered (in brief,
+they will do the right thing).
+
+Notice that you should \emph{not} load \tbull\ if you invoke \benu,
+because the latter calls the former. As explained below, you may pass
+to \tbenu\ the options that you would require from \bull: the outer
+package will forward them to the inner one. Actually, most users will
+just use \tbenu, and never call \bull\ directly.
+
+
+
+\subsection{Package invocation and options}
+\label{SS:EnumInvo}
+
+You invoke \tbenu\ with the usual \verb|\usepackage| declaration put
+in the preamble of your document. In this declaration you may specify
+exactly the same options that you would pass to \tbull, with the same
+meaning (see Subsection~\ref{SS:CntrInvo}). The \benu\ package then
+calls \bull\ for you, just passing on to it the options, if any, you
+asked for.
+
+% For example, if, when preparing a valentine, you want to use the
+% \beenv\ environment to create list numbered with hearts, you might
+% say
+% %
+% \begin{verbatim}
+% \usepackage[heartctrbull]{bullenum}
+% \end{verbatim}
+% %
+% at the beginning of your preamble.
+
+
+
+\subsection{The \beenv\ environment}
+\label{SS:EnumEnvi}
+
+This environment is syntactically analogous to \enenv, but numbers its
+items with an increasing number of bullets (using the \verb|\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:BullStyl}, according to ordinary scoping rules. A
+change local to the environment being employed can be obtained by
+enclosing the relevant declaration inside the environment itself; for
+example,
+%
+\begin{verbatim}
+\begin{bullenum}
+ \smallctrbull
+\end{verbatim}
+\begin{flushleft}
+ \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 \beenv\ environment.
+
+\pagebreak[2]
+
+If you want finer control over the appearance of the ``bullets'', just
+redefine the hooks of Subsection~\ref{SS:Hooks}; 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}
+ \texttt{\ \ \ \ }\meta{items}
+\end{flushleft}
+\begin{verbatim}
+\end{bullenum}
+\end{verbatim}
+%
+(yes, ``macho \TeX\ programmers'' may also use \verb|\def|, or
+\verb|\let| where appropriate).
+
+Of course, this environment respects the definitions of
+\verb|\theenum|\meta{lvl} and of \verb|\labelenum|\meta{lvl} in force
+outside the environment itself, for \( \meta{lvl} =
+\texttt{i},\ldots,\texttt{iv} \).
+
+
+
+\subsection{Nesting \beenv\ environments}
+\label{SS:Nesting}
+
+Because a \beenv\ environment is nothing more than a modified \enenv,
+it can be nested in the same way, up to four levels deep.
+
+For what concerns the syntax, it is perfectly in order to nest one
+\beenv\ environment inside another; it is from the viewpoint of the
+resulting visual appearance that this is not recommendable, unless
+quite different bullet styles are used for the two enumerations, so as
+to sharply mark the visual distinction between their respective
+labels. Of course, this problem does not arise if you nest a \beenv\
+environment inside an \enenv, or viceversa.
+
+Examples of such nested environments will be presented in
+Subsection~\ref{SS:NestXmp}.
+
+
+
+\section{Examples}
+
+A few examples follow, illustrating the usage of the \bull\slash\benu\
+packages.
+
+
+
+\subsection{A sample list}
+
+Here we illustrate the use of the \beenv\ environment to produce lists
+whose items are numbered with the \verb|\bullcntr| command.
+
+The lists in the various examples are produced by the following source
+code:
+%
+\begin{verbatim}
+\begin{bullenum}
+\end{verbatim}
+\begin{flushleft}
+\texttt{\ \ \ \ }\meta{items}
+\end{flushleft}
+\begin{verbatim}
+\end{bullenum}
+\end{verbatim}
+%
+
+We shall now show a few variations of a list of the above kind,
+changing the definition of the commands \verb|\counterlargebullet| and
+\verb|\countersmallbullet| among the various examples, so as to
+illustrate the use of several bullet sizes. In three examples out of
+five, however, this will be actually done by means of the declarations
+described in Subsection~\ref{SS:BullStyl}, thus falling back on one of
+the predefined bullet styles.
+
+
+
+\subsubsection{The standard sizes (\command{smartctrbull})}
+\label{SSS:Xmp-Standard}
+
+In our first example, actually, we do not alter the default
+definitions of the two hooks that typeset the bullets (see
+Subsection~\ref{SS:Hooks}). The following is the output the
+\bull\slash\benu\ packages will produce by themselves, if you invoke
+either of them without options and do not alter the default bullet
+style; in any case, it corresponds to the style selected by
+\verb|\smartctrbull|.
+
+\begin{bullenum}
+ \item
+ This is the first item of the list, that is, item~\#1. It is
+ therefore numbered with a single bullet. Poor bullet! How
+ lonely it must feel!
+
+ \item
+ This is the second item of the list, that is, item~\#2. It is
+ therefore numbered with two bullets, one on the left and one
+ on the right. If you are a romantic nature, you might even
+ think of them as Romeo and Juliet\ldots
+
+ \item\label{Standard-3}
+ This is the third item of the list, that is---guess
+ what?---item~\#3. Not surprisingly, it is numbered with three
+ bullets neatly arranged in the shape of an equilateral
+ triangle.
+
+ \item
+ This is the fourth item, item~\#4. A square has exactly four
+ vertices, so it seems quite appropriate to lay out the four
+ bullets that must be used to number this item exactly in this
+ form, as you can see in the label.
+
+ \item
+ If you have not lost the track, you will agree that this is
+ the fifth item of the list. A regular pentagon would probably
+ have been the optimal choice for displaying this value of the
+ counter, but for some reason the arrangement shown in the
+ label of this item has been preferred by the author of \tbull.
+
+ \item\label{Standard-6}
+ Sixth item! Item~\#6! A regular hexagon is used here! Note,
+ however, that the bullets have shrunk to a smaller size,
+ because the size used so far would have made the bullet
+ cluster look a bit too crowded.
+
+ \item
+ In the opinion of the author, the shape used to display the
+ value~7 is even more pleasant than the regular hexagon used
+ for the value~6; indeed, this is a regular hexagon too, but
+ with the center marked by an additional bullet, which makes
+ the figure look more symmetric.
+
+ \item
+ If 7~was the perfect number of bullets, here we face the
+ disruption of this perfection. The solution adopted for
+ arranging 8~bullets, which you can see here, is, in the
+ author's opinion, the less inelegant among all possibilities.
+
+ \item
+ Item~\#9, the last value that the \verb|\bullcntr| command can
+ display. The bullets are just stacked in a $3\times3$ square
+ pattern---the obvious choice!
+\end{bullenum}
+
+
+
+\subsubsection{Big bullets}
+\label{SSS:Xmp-Big}
+
+You might think that the \verb|\textbullet| character is fitter for
+labelling list items; this is probably true for item numbers that do
+not exceede three, but begins to become questionable for higher
+values. In any case, here is an extreme example: \verb|\textbullets|
+is used for all values from 1 to~9. To achieve this, the following
+source code should be used:
+%
+\begin{verbatim}
+\begin{bullenum}
+ \renewcommand*{\counterlargebullet}{\textbullet}
+ \renewcommand*{\countersmallbullet}{\textbullet}
+\end{verbatim}
+\begin{flushleft}
+ \texttt{\ \ \ \ }\meta{items}
+\end{flushleft}
+\begin{verbatim}
+\end{bullenum}
+\end{verbatim}
+%
+This is what we write below.
+
+\begin{bullenum}
+ \renewcommand*{\counterlargebullet}{\textbullet}
+ \renewcommand*{\countersmallbullet}{\textbullet}
+
+ \item
+ This is the first item of the list, that is, item~\#1. It is
+ therefore numbered with a single bullet. Poor bullet! How
+ lonely it must feel!
+
+ \item\label{Big-2}
+ This is the second item of the list, that is, item~\#2. It is
+ therefore numbered with two bullets, one on the left and one
+ on the right. If you are a romantic nature, you might even
+ think of them as Romeo and Juliet\ldots
+
+ \item\label{Big-3}
+ This is the third item of the list, that is---guess
+ what?---item~\#3. Not surprisingly, it is numbered with three
+ bullets neatly arranged in the shape of an equilateral
+ triangle.
+
+ \item
+ This is the fourth item, item~\#4. A square has exactly four
+ vertices, so it seems quite appropriate to lay out the four
+ bullets that must be used to number this item exactly in this
+ form, as you can see in the label.
+
+ \item
+ If you have not lost the track, you will agree that this is
+ the fifth item of the list. A regular pentagon would probably
+ have been the optimal choice for displaying this value of the
+ counter, but for some reason the arrangement shown in the
+ label of this item has been preferred by the author of \tbull.
+
+ \item\label{Big-6}
+ Sixth item! Item~\#6! A regular hexagon is used here! Note,
+ this time, that the bullets have \emph{not} shrunk to a
+ smaller size, and that the resulting picture looks very
+ crowded---pretty awful, I~would say!
+
+ \item
+ In the opinion of the author, the shape used to display the
+ value~7 is even more pleasant than the regular hexagon used
+ for the value~6; indeed, this is a regular hexagon too, but
+ with the center marked by an additional bullet, which makes
+ the figure look more symmetric.
+
+ \item
+ If 7~was the perfect number of bullets, here we face the
+ disruption of this perfection. The solution adopted for
+ arranging 8~bullets, which you can see here, is, in the
+ author's opinion, the less inelegant among all possibilities.
+
+ \item\label{Big-9}
+ Item~\#9, the last value that the \verb|\bullcntr| command can
+ display. The bullets are just stacked in a $3\times3$ square
+ pattern---the obvious choice!
+\end{bullenum}
+
+A cross-reference to an item run into the main text may look really
+bad with bullets thus large: for instance, referencing the second item
+produces~\ref{Big-2} (quite acceptable), referencing the third one
+gives~\ref{Big-3} (just about acceptable), but a reference to the
+sixth item is typeset as~\ref{Big-6}, and the ninth one even
+yields~\ref{Big-9}! Note, however, that lines are not spaced out any
+further than usual.
+
+
+
+\subsubsection{Moderately large bullets (\command{largectrbull})}
+\label{SSS:Xmp-Large}
+
+Our next example illustrates the output produced by the style selected
+with a \verb|\largectrbull| declaration; this style continues to use,
+for the values over~5, the same bullet size adopted for the first five
+values. So, we say
+%
+\begin{verbatim}
+\begin{bullenum}
+ \largectrbull
+\end{verbatim}
+\begin{flushleft}
+ \texttt{\ \ \ \ }\meta{items}
+\end{flushleft}
+\begin{verbatim}
+\end{bullenum}
+\end{verbatim}
+%
+to produce the desired list.
+
+\begin{bullenum}
+ \largectrbull
+
+ \item
+ This is the first item of the list, that is, item~\#1. It is
+ therefore numbered with a single bullet. Poor bullet! How
+ lonely it must feel!
+
+ \item
+ This is the second item of the list, that is, item~\#2. It is
+ therefore numbered with two bullets, one on the left and one
+ on the right. If you are a romantic nature, you might even
+ think of them as Romeo and Juliet\ldots
+
+ \item\label{Large-3}
+ This is the third item of the list, that is---guess
+ what?---item~\#3. Not surprisingly, it is numbered with three
+ bullets neatly arranged in the shape of an equilateral
+ triangle.
+
+ \item
+ This is the fourth item, item~\#4. A square has exactly four
+ vertices, so it seems quite appropriate to lay out the four
+ bullets that must be used to number this item exactly in this
+ form, as you can see in the label.
+
+ \item
+ If you have not lost the track, you will agree that this is
+ the fifth item of the list. A regular pentagon would probably
+ have been the optimal choice for displaying this value of the
+ counter, but for some reason the arrangement shown in the
+ label of this item has been preferred by the author of \tbull.
+
+ \item\label{Large-6}
+ Sixth item! Item~\#6! A regular hexagon is used here! Note,
+ once again, that the bullets have \emph{not} shrunk to a
+ smaller size, so that the resulting picture looks pretty
+ crowded, although not intolerably bad-looking. Compare the
+ label of this item with a reference to the corresponding
+ item~\ref{Standard-6} under~\ref{SSS:Xmp-Standard}, and with a
+ reference to the corresponding item~\ref{Big-6}
+ under~\ref{SSS:Xmp-Big}.
+
+ \item
+ In the opinion of the author, the shape used to display the
+ value~7 is even more pleasant than the regular hexagon used
+ for the value~6; indeed, this is a regular hexagon too, but
+ with the center marked by an additional bullet, which makes
+ the figure look more symmetric.
+
+ \item
+ If 7~was the perfect number of bullets, here we face the
+ disruption of this perfection. The solution adopted for
+ arranging 8~bullets, which you can see here, is, in the
+ author's opinion, the less inelegant among all possibilities.
+
+ \item
+ Item~\#9, the last value that the \verb|\bullcntr| command can
+ display. The bullets are just stacked in a $3\times3$ square
+ pattern---the obvious choice!
+\end{bullenum}
+
+
+
+\subsubsection{Small bullets (\command{smallctrbull})}
+\label{SSS:Xmp-Small}
+
+The reciprocal example is to use small bullets throughout, from 1 to~9.
+Thus, we use the following source code:
+%
+\begin{verbatim}
+\begin{bullenum}
+ \smallctrbull
+\end{verbatim}
+\begin{flushleft}
+ \texttt{\ \ \ \ }\meta{items}
+\end{flushleft}
+\begin{verbatim}
+\end{bullenum}
+\end{verbatim}
+%
+And here is the output it yields.
+
+\begin{bullenum}
+ \smallctrbull
+
+ \item
+ This is the first item of the list, that is, item~\#1. It is
+ therefore numbered with a single bullet. Poor bullet! How
+ lonely it must feel!
+
+ \item
+ This is the second item of the list, that is, item~\#2. It is
+ therefore numbered with two bullets, one on the left and one
+ on the right. If you are a romantic nature, you might even
+ think of them as Romeo and Juliet\ldots
+
+ \item\label{Small-3}
+ This is the third item of the list, that is---guess
+ what?---item~\#3. Not surprisingly, it is numbered with three
+ bullets neatly arranged in the shape of an equilateral
+ triangle.
+
+ \item
+ This is the fourth item, item~\#4. A square has exactly four
+ vertices, so it seems quite appropriate to lay out the four
+ bullets that must be used to number this item exactly in this
+ form, as you can see in the label.
+
+ \item
+ If you have not lost the track, you will agree that this is
+ the fifth item of the list. A regular pentagon would probably
+ have been the optimal choice for displaying this value of the
+ counter, but for some reason the arrangement shown in the
+ label of this item has been preferred by the author of \tbull.
+
+ \item\label{Small-6}
+ Sixth item! Item~\#6! A regular hexagon is used here! Note,
+ once more, that the bullets have \emph{not} shrunk to a
+ smaller size, because they were \emph{already} small in the
+ items shown thus far.
+
+ \item
+ In the opinion of the author, the shape used to display the
+ value~7 is even more pleasant than the regular hexagon used
+ for the value~6; indeed, this is a regular hexagon too, but
+ with the center marked by an additional bullet, which makes
+ the figure look more symmetric.
+
+ \item
+ If 7~was the perfect number of bullets, here we face the
+ disruption of this perfection. The solution adopted for
+ arranging 8~bullets, which you can see here, is, in the
+ author's opinion, the less inelegant among all possibilities.
+
+ \item
+ Item~\#9, the last value that the \verb|\bullcntr| command can
+ display. The bullets are just stacked in a $3\times3$ square
+ pattern---the obvious choice!
+\end{bullenum}
+
+Again, compare the references to items \#3 and~\#6 from different
+examples: standard bullets (\ref{Standard-3} and~\ref{Standard-6}),
+big bullets (\ref{Big-3} and~\ref{Big-6}), moderately large bullets
+(\ref{Large-3} and~\ref{Large-6}), small bullets (\ref{Small-3}
+and~\ref{Small-6}).
+
+
+
+\subsubsection{Tiny bullets}
+\label{SSS:Xmp-Tiny}
+
+We come now to another extreme example: the use of
+\verb|\textperiodcentered|. In other words,
+%
+\begin{verbatim}
+\begin{bullenum}
+ \renewcommand*{\counterlargebullet}{\textperiodcentered}
+ \renewcommand*{\countersmallbullet}{\textperiodcentered}
+\end{verbatim}
+\begin{flushleft}
+ \texttt{\ \ \ \ }\meta{items}
+\end{flushleft}
+\begin{verbatim}
+\end{bullenum}
+\end{verbatim}
+%
+is asserted in order to produce the list.
+
+\begin{bullenum}
+ \renewcommand*{\counterlargebullet}{\textperiodcentered}
+ \renewcommand*{\countersmallbullet}{\textperiodcentered}
+
+ \item
+ This is the first item of the list, that is, item~\#1. It is
+ therefore numbered with a single bullet. Poor bullet! How
+ lonely it must feel!
+
+ \item
+ This is the second item of the list, that is, item~\#2. It is
+ therefore numbered with two bullets, one on the left and one
+ on the right. If you are a romantic nature, you might even
+ think of them as Romeo and Juliet\ldots
+
+ \item
+ This is the third item of the list, that is---guess
+ what?---item~\#3. Not surprisingly, it is numbered with three
+ bullets neatly arranged in the shape of an equilateral
+ triangle.
+
+ \item
+ This is the fourth item, item~\#4. A square has exactly four
+ vertices, so it seems quite appropriate to lay out the four
+ bullets that must be used to number this item exactly in this
+ form, as you can see in the label.
+
+ \item
+ If you have not lost the track, you will agree that this is
+ the fifth item of the list. A regular pentagon would probably
+ have been the optimal choice for displaying this value of the
+ counter, but for some reason the arrangement shown in the
+ label of this item has been preferred by the author of \tbull.
+
+ \item
+ Sixth item! Item~\#6! A regular hexagon is used here! Note
+ that it was really impossible, this time, for the bullets to
+ shrunk to a still smaller size than the one that has been
+ adopted in the above items!
+
+ \item
+ In the opinion of the author, the shape used to display the
+ value~7 is even more pleasant than the regular hexagon used
+ for the value~6; indeed, this is a regular hexagon too, but
+ with the center marked by an additional bullet, which makes
+ the figure look more symmetric.
+
+ \item
+ If 7~was the perfect number of bullets, here we face the
+ disruption of this perfection. The solution adopted for
+ arranging 8~bullets, which you can see here, is, in the
+ author's opinion, the less inelegant among all possibilities.
+
+ \item
+ Item~\#9, the last value that the \verb|\bullcntr| command can
+ display. The bullets are just stacked in a $3\times3$ square
+ pattern---the obvious choice!
+\end{bullenum}
+
+This bullet style might be employed in a \beenv\ environment nested
+inside another one.
+
+
+
+\subsubsection{St.\texorpdfstring{\,}{ }Valentine (\command{heartctrbull})}
+\label{SSS:Xmp-Hearts}
+
+To end this inventory of variations, let us illustrate the use of a
+fancier ``bullet'': a little heart. We obtain this by saying
+%
+\begin{verbatim}
+\begin{bullenum}
+ \heartctrbull
+\end{verbatim}
+\begin{flushleft}
+ \texttt{\ \ \ \ }\meta{items}
+\end{flushleft}
+\begin{verbatim}
+\end{bullenum}
+\end{verbatim}
+%
+% ( paren match
+This could be used in valentines to enumerate to your beloved the
+terms of your passion\ldots~:-)
+
+\begin{bullenum}
+ \heartctrbull
+
+ \item\label{Hearts-1}
+ This is the first item of the list, that is, item~\#1. It is
+ therefore numbered with a single heart. Poor heart! It is a
+ true lonely heart!
+
+ \item
+ This is the second item of the list, that is, item~\#2. It is
+ therefore numbered with two hearts, one on the left and one on
+ the right. Thinking of Romeo and Juliet is absolutely natural
+ in this context\ldots
+
+ \item\label{Hearts-3}
+ This is the third item of the list, that is---guess
+ what?---item~\#3. Not surprisingly, it is numbered with three
+ hearts neatly arranged in the shape of an equilateral
+ triangle.
+
+ \item\label{Hearts-4}
+ This is the fourth item, item~\#4. A square has exactly four
+ vertices, so it seems quite appropriate to lay out the four
+ hearts that must be used to number this item exactly in this
+ form, as you can see in the label.
+
+ \item\label{Hearts-5}
+ If you have not lost the track, you will agree that this is
+ the fifth item of the list. A regular pentagon would probably
+ have been the optimal choice for displaying this value of the
+ counter, but for some reason the arrangement shown in the
+ label of this item has been preferred by the author of \tbull.
+
+ \item
+ Sixth item! Item~\#6! A regular hexagon is used here,
+ adorned with hearts! Of course, the hearts do not shrink, as
+ doesn't yours, and as doesn't your ardent passion!
+
+ \item\label{Hearts-7}
+ In the opinion of the author, the shape used to display the
+ value~7 is even more pleasant than the regular hexagon used
+ for the value~6; indeed, this is a regular hexagon too, but
+ with the center marked by an additional heart, which makes the
+ figure look more symmetric.
+
+ \item\label{Hearts-8}
+ If 7~was the perfect number of hearts, here we face the
+ disruption of this perfection. The solution adopted for
+ arranging 8~hearts, which you can see here, is, in the
+ author's opinion, the less inelegant among all possibilities.
+
+ \item
+ Item~\#9, the last value that the \verb|\bullcntr| command can
+ display. The hearts are just stacked in a $3\times3$ square
+ pattern---the obvious choice!
+\end{bullenum}
+
+Cross-references are a bit funny with this style; they look like this:
+\ref{Hearts-1}, \ref{Hearts-3}, \ref{Hearts-4}, \ref{Hearts-5},
+\ref{Hearts-7}, and~\ref{Hearts-8}.
+
+
+
+\subsection{Nested enumerations}
+\label{SS:NestXmp}
+
+Try not to overdo this: carrying it to excess could lead to confused
+output.
+
+
+
+\subsubsection{Nesting one \beenv\ inside another}
+\label{SSS:NestBullBull}
+
+We use ``large'' bullets for the outer environment, and ``tiny''
+bullets for the inner one.
+
+\begin{bullenum}
+ \largectrbull
+
+ \item
+ First item: let this one alone, just to have a term of
+ comparison.
+
+ \item\label{NestBull-2}
+ Second item. Here we nest another \beenv\ environment:
+ \begin{bullenum}
+ \renewcommand*{\counterlargebullet}{\textperiodcentered}
+ \renewcommand*{\countersmallbullet}{\textperiodcentered}
+ \item\label{NestBull-2.1}
+ First sub-item.
+ \item\label{NestBull-2.2}
+ Second sub-item.
+ \item\label{NestBull-2.3}
+ Third sub-item.
+ \item\label{NestBull-2.4}
+ Fourth sub-item. OK, this should suffice.
+ \end{bullenum}
+ Don't forget, we are still inside item~\ref{NestBull-2} of
+ the outer enumeration.
+
+ \item\label{NestBull-3}
+ Third item (of the outer enumeration). Let us repeat exactly
+ the same nested enumeration as in item~\ref{NestBull-2}.
+ \begin{bullenum}
+ \renewcommand*{\counterlargebullet}{\textperiodcentered}
+ \renewcommand*{\countersmallbullet}{\textperiodcentered}
+ \item\label{NestBull-3.1}
+ First sub-item.
+ \item\label{NestBull-3.2}
+ Second sub-item.
+ \item\label{NestBull-3.3}
+ Third sub-item.
+ \item\label{NestBull-3.4}
+ Fourth sub-item. OK, this should suffice.
+ \end{bullenum}
+ Back to item~\ref{NestBull-3} of the outer enumeration.
+\end{bullenum}
+
+Now the bad news: you might want to refer to, say, item
+\ref{NestBull-3.4} under item~\ref{NestBull-3}. As you can see, the
+reference comes out wrong, since the label from the outer enumeration
+% ( paren match
+is typeset with the style of the inner one.~:-(\spacefactor=\sfcode`.
+\space This is a known bug: I~chose not to correct it, since doing so
+would require to introduce the concept of bullet styles distinguished
+by level, which I~deem intolerably burdensome. Be aware of this
+limitation when you nest \beenv\ environments inside one another (this
+does not apply, however, to \beenv's nested within \enenv's, as we'll
+see in the following examples).
+
+
+
+\subsubsection{Nesting \beenv\ inside \enenv}
+\label{SSS:NestBullEnum}
+
+Let us repeat \hyref{SSS:NestBullBull}{the same example shown above},
+but changing the outer environment to \enenv, and suppressing style
+variations.
+
+\begin{enumerate}
+ \item
+ First item: let this one alone, just to have a term of
+ comparison.
+
+ \item\label{NestBuEn-2}
+ Second item. Here we nest a \beenv\ environment:
+ \begin{bullenum}
+ \item\label{NestBuEn-2.1}
+ First sub-item.
+ \item\label{NestBuEn-2.2}
+ Second sub-item.
+ \item\label{NestBuEn-2.3}
+ Third sub-item.
+ \item\label{NestBuEn-2.4}
+ Fourth sub-item. OK, this should suffice.
+ \end{bullenum}
+ Don't forget, we are still inside item~\ref{NestBuEn-2} of
+ the outer enumeration.
+
+ \item\label{NestBuEn-3}
+ Third item (of the outer enumeration). Let us repeat exactly
+ the same nested enumeration as in item~\ref{NestBuEn-2}.
+ \begin{bullenum}
+ \item\label{NestBuEn-3.1}
+ First sub-item.
+ \item\label{NestBuEn-3.2}
+ Second sub-item.
+ \item\label{NestBuEn-3.3}
+ Third sub-item.
+ \item\label{NestBuEn-3.4}
+ Fourth sub-item. OK, this should suffice.
+ \end{bullenum}
+ Back to item~\ref{NestBuEn-3} of the outer enumeration.
+\end{enumerate}
+
+See Subsection~\ref{SS:CrossXmp} for examples of cross-references to
+the items of these lists.
+
+
+
+\subsubsection{Nesting \enenv\ inside \beenv}
+\label{SSS:NestEnumBull}
+
+As \hyref{SSS:NestBullEnum}{before}, but the other way around: \beenv\
+is now the outer environment, and \enenv\ the inner one.
+
+\begin{bullenum}
+ \item
+ First item: let this one alone, just to have a term of
+ comparison.
+
+ \item\label{NestEnBu-2}
+ Second item. Here we nest an \enenv\ environment:
+ \begin{enumerate}
+ \item\label{NestEnBu-2.1}
+ First sub-item.
+ \item\label{NestEnBu-2.2}
+ Second sub-item.
+ \item\label{NestEnBu-2.3}
+ Third sub-item.
+ \item\label{NestEnBu-2.4}
+ Fourth sub-item. OK, this should suffice.
+ \end{enumerate}
+ Don't forget, we are still inside item~\ref{NestEnBu-2} of
+ the outer enumeration.
+
+ \item\label{NestEnBu-3}
+ Third item (of the outer enumeration). Let us repeat exactly
+ the same nested enumeration as in item~\ref{NestEnBu-2}.
+ \begin{enumerate}
+ \item\label{NestEnBu-3.1}
+ First sub-item.
+ \item\label{NestEnBu-3.2}
+ Second sub-item.
+ \item\label{NestEnBu-3.3}
+ Third sub-item.
+ \item\label{NestEnBu-3.4}
+ Fourth sub-item. OK, this should suffice.
+ \end{enumerate}
+ Back to item~\ref{NestEnBu-3} of the outer enumeration.
+\end{bullenum}
+
+Again, see Subsection~\ref{SS:CrossXmp} for examples of
+cross-references to the items of the above lists.
+
+
+
+\subsubsection{Deep nesting}
+\label{SSS:DeepNest}
+
+Just to show what the output looks like, here is an example of \enenv\
+and \beenv\ environments nested down to the fourth level. We avoid,
+however, nesting \beenv\ environments one inside the other, because of
+the problem with cross-references outlined
+under~\ref{SSS:NestBullBull}.
+
+\begin{enumerate}
+ \item\label{Invertebrates}
+ Invertebrates are of many kinds.
+
+ \item\label{Vertebrates}
+ We detail the vertebrates.
+ \begin{enumerate}
+ \item\label{Fishes}
+ Fishes. They include, for instance:
+ \begin{bullenum}
+ \item\label{Barracuda} barracuda;
+ \item\label{Carp} carp;
+ \item\label{Swordfish} swordfish.
+ \end{bullenum}
+ \item\label{Amphibians}
+ Amphibians. They include, for instance:
+ \begin{bullenum}
+ \item\label{Frogs} frogs, among which are
+ \begin{enumerate}
+ \item\label{BarkingFrog} the barking frog,
+ \item\label{FlyingFrog} the flying frog,
+ \item\label{GreenFrog} the green frog,
+ \item\label{TreeFrog} the tree frog,
+ \end{enumerate}
+ and may others;
+ \item\label{Toads} toads, that comprise
+ \begin{enumerate}
+ \item\label{CaneToad} the cane toad,
+ \item\label{GiantToad} the giant toad,
+ \end{enumerate}
+ just to name a few;
+ \item\label{Salamanders} salamanders, \emph{e.g.},
+ \begin{enumerate}
+ \item\label{GreenSal} the green salamander,
+ \item\label{SlimySal} the slimy salamander,
+ \item\label{TigerSal} the tiger salamander.
+ \end{enumerate}
+ \end{bullenum}
+ \item\label{Reptiles}
+ Reptiles. Among these we find:
+ \begin{bullenum}
+ \item\label{Snakes} snakes, for instance
+ \begin{enumerate}
+ \item\label{Cobra} cobra,
+ \item\label{Python} python,
+ \item\label{Anaconda} anaconda,
+ \item\label{Viper} viper,
+ \item\label{Rattlesnake} rattlesnake;
+ \end{enumerate}
+ \item\label{Turtles} turtles, of which the following
+ \begin{enumerate}
+ \item\label{GreenTurtle} green turtle,
+ \item\label{PaintedTurtle} painted turtle,
+ \item\label{SnappingTurtle} snapping turtle
+ \end{enumerate}
+ are just a few examples.
+ \end{bullenum}
+ \item\label{Birds}
+ Birds. (I'm a bit bored, now.)
+ \item\label{Mammals}
+ Mammals.
+ \end{enumerate}
+\end{enumerate}
+
+
+
+\subsection{An example of use in the middle of text}
+
+\newcounter{mytest}
+\setcounter{mytest}{3}
+\newlength{\W}
+\setlength{\W}{\bigskipamount}
+
+We have just defined, in the source file of this document, a new
+counter named \cnt{mytest}, and we have set the value of the
+\cnt{mytest} counter to~\arabic{mytest}. With the default bullet
+sizes, this value is displayed by the command \verb|\bullcntr{mytest}|
+as~\bullcntr{mytest}. Other examples:
+
+\begin{tabbing}
+ \indent\verb|\footnotesize \bullcntr{mytest}|\hspace{2\tabbingsep}\=\kill
+ \> \verb|\Huge \bullcntr{mytest}|
+ \' {\Huge produces~\bullcntr{mytest}} \\[\W]
+ \> \verb|\huge \bullcntr{mytest}|
+ \' {\huge produces~\bullcntr{mytest}} \\[\W]
+ \> \verb|\LARGE \bullcntr{mytest}|
+ \' {\LARGE produces~\bullcntr{mytest}} \\[\W]
+ \> \verb|\Large \bullcntr{mytest}|
+ \' {\Large produces~\bullcntr{mytest}} \\[\W]
+ \> \verb|\large \bullcntr{mytest}|
+ \' {\large produces~\bullcntr{mytest}} \\[\W]
+ \> \verb|\normalsize \bullcntr{mytest}|
+ \' {\normalsize produces~\bullcntr{mytest}} \\[\W]
+ \> \verb|\small \bullcntr{mytest}|
+ \' {\small produces~\bullcntr{mytest}} \\[\W]
+ \> \verb|\footnotesize \bullcntr{mytest}|
+ \' {\footnotesize produces~\bullcntr{mytest}} \\[\W]
+ \> \verb|\scriptsize \bullcntr{mytest}|
+ \' {\scriptsize produces~\bullcntr{mytest}} \\[\W]
+ \> \verb|\tiny \bullcntr{mytest}|
+ \' {\tiny produces~\bullcntr{mytest}}
+\end{tabbing}
+
+\setcounter{mytest}{7}
+
+Let us repeat this example after assigning to the \cnt{mytest} counter
+the value~\arabic{mytest}, which \verb|\bullcntr{mytest}| displays
+as~\bullcntr{mytest}:
+
+\begin{tabbing}
+ \indent\verb|\footnotesize \bullcntr{mytest}|\hspace{2\tabbingsep}\=\kill
+ \> \verb|\Huge \bullcntr{mytest}|
+ \' {\Huge produces~\bullcntr{mytest}} \\[\W]
+ \> \verb|\huge \bullcntr{mytest}|
+ \' {\huge produces~\bullcntr{mytest}} \\[\W]
+ \> \verb|\LARGE \bullcntr{mytest}|
+ \' {\LARGE produces~\bullcntr{mytest}} \\[\W]
+ \> \verb|\Large \bullcntr{mytest}|
+ \' {\Large produces~\bullcntr{mytest}} \\[\W]
+ \> \verb|\large \bullcntr{mytest}|
+ \' {\large produces~\bullcntr{mytest}} \\[\W]
+ \> \verb|\normalsize \bullcntr{mytest}|
+ \' {\normalsize produces~\bullcntr{mytest}} \\[\W]
+ \> \verb|\small \bullcntr{mytest}|
+ \' {\small produces~\bullcntr{mytest}} \\[\W]
+ \> \verb|\footnotesize \bullcntr{mytest}|
+ \' {\footnotesize produces~\bullcntr{mytest}} \\[\W]
+ \> \verb|\scriptsize \bullcntr{mytest}|
+ \' {\scriptsize produces~\bullcntr{mytest}} \\[\W]
+ \> \verb|\tiny \bullcntr{mytest}|
+ \' {\tiny produces~\bullcntr{mytest} (Ugh!)}
+\end{tabbing}
+
+But look at the output of
+%
+\begin{verbatim}
+\begin{quote}
+ \renewcommand*{\countersmallbullet}{\textperiodcentered}
+ \tiny
+ The value is~\bullcntr{mytest}.
+\end{quote}
+\end{verbatim}
+%
+Here it is:
+%
+\begin{quote}
+ \renewcommand*{\countersmallbullet}{\textperiodcentered}
+ \tiny
+ The value is~\bullcntr{mytest}.
+\end{quote}
+%
+% ( paren match
+How cute it looks!~:-)
+
+
+
+\subsection{Examples of cross-references}
+\label{SS:CrossXmp}
+
+Cross-references are printed using the bullet style that was in
+effect when the \verb|\label| command was given. The following
+examples illustrate this.
+
+In~\ref{SSS:Xmp-Standard} we had references to~\ref{Standard-3} and
+to~\ref{Standard-6}. In~\ref{SSS:Xmp-Hearts}, on the other hand, the
+references were to~\ref{Hearts-1}, to~\ref{Hearts-3},
+to~\ref{Hearts-4}, to~\ref{Hearts-5}, to~\ref{Hearts-7}, and
+to~\ref{Hearts-8}.
+
+We turn now to nested lists. We let alone the example
+of~\ref{SSS:NestBullBull}, we already know that references come out
+wrong in this case. In~\ref{SSS:NestBullEnum} we had items
+\ref{NestBuEn-2.1}, \ref{NestBuEn-2.2}, \ref{NestBuEn-2.3}, and
+\ref{NestBuEn-2.4}, all listed under item~\ref{NestBuEn-2}, and
+similarly items \ref{NestBuEn-3.1}, \ref{NestBuEn-3.2},
+\ref{NestBuEn-3.3}, and \ref{NestBuEn-3.4}, as part of
+item~\ref{NestBuEn-3}. In~\ref{SSS:NestEnumBull}, on the other hand,
+we had items \ref{NestEnBu-2.1}, \ref{NestEnBu-2.2},
+\ref{NestEnBu-2.3}, and \ref{NestEnBu-2.4}, all listed under
+item~\ref{NestEnBu-2}: as you can see, the bullets now precede the
+reference to the item of \enenv; similarly, items \ref{NestEnBu-3.1},
+\ref{NestEnBu-3.2}, \ref{NestEnBu-3.3}, and \ref{NestEnBu-3.4} are now
+a part of the ``bulletted'' item~\ref{NestEnBu-3}.
+
+Coming to~\ref{SSS:DeepNest} (the animal kingdom), we see that, for
+instance, the green frog is \ref{GreenFrog}, an example of frog (under
+\ref{Frogs}), which, in turn, is an example of amphibian
+(see~\ref{Amphibians}). On the other hand, the tiger salamander is a
+kind of salamander (cf.~\ref{Salamanders}) listed under
+\ref{TigerSal}.
+
+And so on\ldots
+
+
+
+\setcounter{secnumdepth}{0}
+
+\begin{thebibliography}{9}
+ \providecommand*{\bysame}{\leavevmode\hbox to3em{\hrulefill}\thinspace}
+ \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}
+
+\end{document}
diff --git a/macros/latex/contrib/bullcntr/bullcntr-sam.tex b/macros/latex/contrib/bullcntr/bullcntr-sam.tex
new file mode 100644
index 0000000000..2ce5e15dd8
--- /dev/null
+++ b/macros/latex/contrib/bullcntr/bullcntr-sam.tex
@@ -0,0 +1,310 @@
+%
+% Copyright (C) 2007 by Gustavo MEZZETTI <gustavo.mezzetti@istruzione.it>.
+%
+% This file is part of a work named "bullcntr package".
+%
+% The 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
+% 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).
+%
+\documentclass[a4paper]{article}
+% Non-metric paper sizes have no right to exist! (;-)
+\usepackage{bullcntr}
+% Of course, there is no need to load the hyperref package, but we
+% like to use it:
+\usepackage[bookmarksnumbered]{hyperref}
+
+\title{Using \tbull:\\an example}
+\author{G.~Mezzetti}
+\date{October~10, 2008}
+
+% The following command definitions has nothing to do with the
+% bullcntr package: you may ignore them.
+
+\DeclareRobustCommand*{\command}[1]{%
+ {\texorpdfstring{\normalfont\ttfamily \char\escapechar}{\pdfbslash}#1}%
+}
+\DeclareRobustCommand*{\packlass}[1]{%
+ {\texorpdfstring{\normalfont \sffamily}{}#1}%
+}
+\DeclareRobustCommand*{\meta}[1]{%
+ \texorpdfstring
+ {\mbox{\normalfont \(\langle\textit{#1}\rangle\)}}%
+ {<#1>}%
+}
+\DeclareRobustCommand*{\filedir}[1]{{\normalfont\ttfamily #1}}
+\DeclareRobustCommand*{\cnt}[1]{\texttt{#1}}
+\newcommand*{\Bullcntr}{bullcntr}
+\newcommand*{\bull}{\packlass{\Bullcntr}}
+\newcommand*{\tbull}{the \bull\ package}
+\newcommand*{\Bullenum}{bullenum}
+\newcommand*{\benu}{\packlass{\Bullenum}}
+\newcommand*{\tbenu}{the \benu\ package}
+
+\newcommand*{\pdfbslash}{}
+{\catcode`\|=0 |catcode`|\=12 |gdef|pdfbslash{\\}}
+
+% End of command definitions.
+
+% The following is just a neurotic symptom of the author:
+\hfuzz = 0pt
+\vfuzz = 0pt
+
+
+
+\begin{document}
+
+\maketitle
+
+\begin{abstract}
+ This document illustrates, by means of practical examples, the use
+ of \tbull. You should read the \LaTeX\ source of this document
+ and compare it with the output it produces; you may also find it
+ useful as a starting base for your own coding.
+\end{abstract}
+
+\tableofcontents
+
+
+
+\setcounter{secnumdepth}{0}
+
+\section{Introduction}
+
+If you are reading this document, you will probably know what \tbull\
+is and what purpose it fulfills. In the sequel, we shall assume no
+other knowledge about \tbull\ besides this; in particular, we assume
+that you did not bother reading the documentation, and prefer to learn
+how to use this package by looking at some sample code. We also take
+for granted that you are reading the \LaTeX\ source of this document,
+and comparing it with the output it produces.
+
+Actually, you might quite well avoid reading this document too: the
+typical user of \tbull\ just wishes to produce enumeration lists whose
+items are numbered with bullets, and in order to learn quickly how to
+do this, it suffices to look at the examples contained
+in~\cite{enum-sam}.
+
+
+
+\setcounter{secnumdepth}{3}
+
+\section{Basic usage}
+
+\newcounter{mycntr}
+
+If you are reading the \LaTeX\ source, you will see that we have just
+defined a new counter named \cnt{mycntr}. We use this counter for
+the examples below.
+
+
+
+\subsection{Using the \command{\Bullcntr} command directly}
+
+Since it has just been defined, the \cnt{mycntr} counter has presently
+the value~\arabic{mycntr}, which \tbull\footnote{More precisely,
+version 0.04\ (2007/04/02), or later, of \tbull: version 0.03
+incorrectly displayed a spurious bullet in this case.} displays
+as~``\bullcntr{mycntr}'', that is, as nothing at all.
+\refstepcounter{mycntr}\label{mycntr-1}After a \verb|\refstepcounter|,
+the value has become~\arabic{mycntr}, which, in ``bulletted'' form, is
+shown as~``\bullcntr{mycntr}''. We may also refer to the
+value~\ref{mycntr-1} on page~\pageref{mycntr-1}: since we have not
+changed the definition of \verb|\themycntr|, the reference is printed
+as shown.
+
+Bear in mind that the \verb|\bullcntr| command works only if the value
+of the counter you want to display lies between 0 and~9 (inclusive);
+otherwise, an error is generated.
+
+
+
+\subsection{Redefining the \command{the}\meta{ctr} command}
+
+\renewcommand*{\themycntr}{\bullcntr{mycntr}}
+
+After redefining \verb|\themycntr|, we may say that the value of the
+\cnt{mycntr} counter is~\themycntr.
+\refstepcounter{mycntr}\label{mycntr-2}As above, after a
+\verb|\refstepcounter|, the value has become~\themycntr, but this time
+a reference is typeset as~``\ref{mycntr-2}'' too (on
+page~\pageref{mycntr-2}, why not).
+
+
+
+\subsection{Changing the bullet style}
+
+\heartctrbull
+
+Now the value of the counter is displayed as~``\themycntr'', but the
+previous reference is still typeset as~``\ref{mycntr-2}''.
+\refstepcounter{mycntr}\label{mycntr-3}You need another
+\verb|\refstepcounter|, issued after changing the style, to get a
+reference to the value~\ref{mycntr-3} on page~\pageref{mycntr-3}.
+This is in no way a bug, but really a feature! (Could it ever be the
+other way around?)
+
+\smartctrbull
+
+We have now reverted to the default style: indeed, the value of the
+counter is displayed as~``\themycntr'', but, of course, the reference
+is still to~\ref{mycntr-3}.
+
+\renewcommand*{\counterlargebullet}{$\scriptstyle \star$}
+
+You are not limited to the provided predefined bullet styles (there
+are four of them): you may pick any character you want---for example,
+a star---and use it in place of the default bullet, as
+in~``\themycntr''; but for this, you should better read the
+documentation\ldots
+
+
+
+\section{Simple enumerations}
+
+It is possible to employ \tbull\ alone to produce lists whose items
+are numbered with bullets, in simple situations, although there is
+little point in doing this, since it is easier to use \tbenu\
+(see~\cite{enum-sam}), which also works in more complex contexts. In
+any case, here are some examples.
+
+% Restore the default bullet style:
+\smartctrbull
+
+
+
+\subsection{The default style}
+
+If you don't alter the bullet style, you will get an enumeration like
+the following:
+
+\begin{enumerate}
+ \renewcommand*{\theenumi}{\bullcntr{enumi}}
+ \renewcommand*{\labelenumi}{\theenumi}
+
+ \item\label{enum-1} One bullet.
+ \item\label{enum-2} Two bullets.
+ \item\label{enum-3} Three bullets.
+ \item\label{enum-4} Four bullets.
+ \item\label{enum-5} Five bullets.
+ \item\label{enum-6} Six bullets. From six bullets onward,
+ the default settings provide that smaller bullets be used to
+ make up the arrangement.
+ \item\label{enum-7} Seven bullets.
+ \item\label{enum-8} And so on\ldots
+\end{enumerate}
+
+The references are to items \ref{enum-1}, \ref{enum-2}, \ref{enum-3},
+\ref{enum-4}, \ref{enum-5}, \ref{enum-6}, \ref{enum-7},
+and~\ref{enum-8}.
+
+
+
+\subsection{Larger bullets}
+
+You might prefer that the bullet size don't shrink when the value~6
+is reached, as in the following example.
+
+\begin{enumerate}
+ \renewcommand*{\theenumi}{\bullcntr{enumi}}
+ \renewcommand*{\labelenumi}{\theenumi}
+ \largectrbull
+
+ \item One bullet.
+ \item Two bullets.
+ \item Three bullets.
+ \item Four bullets.
+ \item Five bullets.
+ \item Six bullets. As you can see, the bullets have not shrunk.
+ \item Seven bullets.
+ \item And so on\ldots
+\end{enumerate}
+
+
+
+\subsection{Smaller bullets}
+
+Another possibility is to use small bullets since the beginning, as in
+the following example.
+
+\begin{enumerate}
+ \renewcommand*{\theenumi}{\bullcntr{enumi}}
+ \renewcommand*{\labelenumi}{\theenumi}
+ \smallctrbull
+
+ \item One bullet. As you can see, the bullet is already small.
+ \item Two bullets.
+ \item Three bullets.
+ \item Four bullets.
+ \item Five bullets.
+ \item Six bullets.
+ \item Seven bullets.
+ \item And so on\ldots
+\end{enumerate}
+
+
+
+\subsection{Hearts}
+
+What the title states.
+
+\begin{enumerate}
+ \renewcommand*{\theenumi}{\bullcntr{enumi}}
+ \renewcommand*{\labelenumi}{\theenumi}
+ \heartctrbull
+
+ \item One heart. The size of the hearts does not change.
+ \item Two hearts.
+ \item Three hearts.
+ \item Four hearts.
+ \item Five hearts.
+ \item Six hearts.
+ \item Seven hearts.
+ \item And so on\ldots
+\end{enumerate}
+
+
+
+\setcounter{secnumdepth}{0}
+\providecommand*\bysame{\leavevmode\hbox to3em{\hrulefill}\thinspace}
+
+\begin{thebibliography}{9}
+ \providecommand*{\bysame}{\leavevmode\hbox to3em{\hrulefill}\thinspace}
+ \addcontentsline{toc}{section}{\refname}
+
+ \bibitem{dtx}
+ G.~Mezzetti, \emph{The \bull\ package}, documented \TeX\
+ source (dtx), included in every distribution of \tbull\ (in
+ the file \filedir{\Bullcntr.dtx}).
+
+ \bibitem{overview}
+ \bysame, \emph{Overview of \tbull}, included in every
+ distribution of \tbull, surely as \LaTeX\ source (in the file
+ \filedir{\Bullcntr-man.tex}) and perhaps in precompiled PDF
+ format too (in the file \filedir{\Bullcntr-man.pdf}).
+
+ \bibitem{enum-sam}
+ \bysame, \emph{Using \tbenu: an example}, \LaTeX\ source,
+ included in every distribution of \tbull\ (in the file
+ \filedir{\Bullenum-sam.tex}).
+\end{thebibliography}
+
+
+\end{document}
diff --git a/macros/latex/contrib/bullcntr/bullcntr.dtx b/macros/latex/contrib/bullcntr/bullcntr.dtx
new file mode 100644
index 0000000000..781b0b0e55
--- /dev/null
+++ b/macros/latex/contrib/bullcntr/bullcntr.dtx
@@ -0,0 +1,1662 @@
+% \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 {2008/10/10}
+% \def\doclongdate{October~10, 2008}
+%
+% \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 be 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--35131\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.
+%
+% Don't forget that the versions of the \packlass{\bullcntr}
+% package prior to~0.04 (this version) contain some coarse---and
+% very embarassing!~:-(~---^^A ) paren match
+% bugs.
+%
+% \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
+%
diff --git a/macros/latex/contrib/bullcntr/bullcntr.ins b/macros/latex/contrib/bullcntr/bullcntr.ins
new file mode 100644
index 0000000000..e67b89165a
--- /dev/null
+++ b/macros/latex/contrib/bullcntr/bullcntr.ins
@@ -0,0 +1,106 @@
+%
+% This is file `bullcntr.ins'.
+%
+% This file is part of a work named "bullcntr package".
+%
+% Copyright (C) 2007 by Gustavo MEZZETTI <gustavo.mezzetti@istruzione.it>.
+%
+% The 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
+% 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).
+%
+% October 10, 2008 (vers. 0.04)
+%
+\input docstrip
+
+\def\filename{bullcntr.dtx}
+\def\fileversion{0.04}
+\def\filedate{2007/04/02}
+
+\Msg{----------------------------------------------------------------}
+\Msg{}
+\Msg{Unpacking the bullcntr package -- vers. \fileversion\space (\filedate).}
+\Msg{}
+\Msg{Since this package isn't standard LaTeX, no attempt will be made}
+\Msg{to place the generated files into any directory belonging to the}
+\Msg{texmf tree of your site, using the \string\usedir\space facility of DocStrip;}
+\Msg{rather, they will be saved to the current directory. \space This means}
+\Msg{that, in order to complete the installation, you'll have to move}
+\Msg{these files into a suitable directory where LaTeX can find them;}
+\Msg{these directories vary from site to site. \space In order to learn how}
+\Msg{to locate them, look at the documentation of your particular TeX}
+\Msg{implementation.}
+\Msg{}
+\Msg{The complete listing of all the files that you need to move will}
+\Msg{be displayed below at the end of this run.}
+\Msg{}
+\Msg{----------------------------------------------------------------}
+\Msg{}
+\Ask{\answer}{Press \space <return> \space to continue
+ (your \string\answer\space will be ignored).}
+
+\preamble
+
+This is a generated file.
+It is part of a work named "bullcntr package".
+
+Copyright (C) 2007 by Gustavo MEZZETTI <gustavo.mezzetti@istruzione.it>.
+
+The 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
+ 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).
+
+\endpreamble
+
+\askonceonly
+
+\generate{
+ \file{bullcntr.sty}{\from{\filename}{bullcntr}}
+ \file{bullenum.sty}{\from{\filename}{bullenum}}
+}
+
+\Msg{}
+\Msg{To finish the installation, please move the 2 files listed below}
+\Msg{into a directory where LaTeX looks for inputs files:}
+\Msg{}
+\Msg{\space\space\space\space bullcntr.sty}
+\Msg{\space\space\space\space bullenum.sty}
+\Msg{}
+\Msg{Happy TeXing!}
+
+\endbatchfile
diff --git a/macros/latex/contrib/bullcntr/bullenum-sam.tex b/macros/latex/contrib/bullcntr/bullenum-sam.tex
new file mode 100644
index 0000000000..e60fce346c
--- /dev/null
+++ b/macros/latex/contrib/bullcntr/bullenum-sam.tex
@@ -0,0 +1,688 @@
+%
+% Copyright (C) 2007 by Gustavo MEZZETTI <gustavo.mezzetti@istruzione.it>.
+%
+% This file is part of a work named "bullcntr package".
+%
+% The 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
+% 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).
+%
+\documentclass[a4paper]{article}
+% Non-metric paper sizes have no right to exist! (;-)
+\usepackage{bullenum}
+% Of course, there is no need to load the hyperref package, but we
+% like to use it:
+\usepackage[bookmarksnumbered]{hyperref}
+
+\title{Using \tbenu:\\an example}
+\author{G.~Mezzetti}
+\date{October~10, 2008}
+
+% The following command definitions has nothing to do with the
+% bullcntr package: you may ignore them.
+
+\DeclareRobustCommand*{\command}[1]{%
+ {\texorpdfstring{\normalfont\ttfamily \char\escapechar}{\pdfbslash}#1}%
+}
+\DeclareRobustCommand*{\packlass}[1]{%
+ {\texorpdfstring{\normalfont \sffamily}{}#1}%
+}
+\DeclareRobustCommand*{\meta}[1]{%
+ \texorpdfstring
+ {\mbox{\normalfont \(\langle\textit{#1}\rangle\)}}%
+ {<#1>}%
+}
+\DeclareRobustCommand*{\filedir}[1]{{\normalfont\ttfamily #1}}
+\DeclareRobustCommand*{\cnt}[1]{\texttt{#1}}
+\DeclareRobustCommand*{\env}[1]{\texttt{#1}}
+\newcommand*{\Bullcntr}{bullcntr}
+\newcommand*{\bull}{\packlass{\Bullcntr}}
+\newcommand*{\tbull}{the \bull\ package}
+\newcommand*{\Bullenum}{bullenum}
+\newcommand*{\benu}{\packlass{\Bullenum}}
+\newcommand*{\tbenu}{the \benu\ package}
+\newcommand*{\Enumerat}{enumerate}
+\newcommand*{\beenv}{\env{\Bullenum}}
+\newcommand*{\enenv}{\env{\Enumerat}}
+
+\newcommand*{\pdfbslash}{}
+{\catcode`\|=0 |catcode`|\=12 |gdef|pdfbslash{\\}}
+
+% End of command definitions.
+
+% The following is just a neurotic symptom of the author:
+\hfuzz = 0pt
+\vfuzz = 0pt
+
+
+
+\begin{document}
+
+\maketitle
+
+\begin{abstract}
+ This document illustrates, by means of practical examples, the use
+ of \tbenu. You should read the \LaTeX\ source of this document
+ and compare it with the output it produces; you may also find it
+ useful as a starting base for your own coding.
+\end{abstract}
+
+\tableofcontents
+
+
+
+\setcounter{secnumdepth}{0}
+
+\section{Introduction}
+
+If you are reading this document, you will probably know what \tbenu\
+is and what purpose it fulfills. In the sequel, we shall assume no
+other knowledge about \tbenu\ besides this; in particular, we assume
+that you did not bother reading the documentation, and prefer to learn
+how to use this package by looking at some sample code. We also take
+for granted that you are reading the \LaTeX\ source of this document,
+and comparing it with the output it produces.
+
+You might find it useful to read also~\cite{bull-sam}, which contains
+sample code that theaches you how to use \tbull.
+
+
+
+\setcounter{secnumdepth}{3}
+
+\section{Basic usage}
+
+Here we illustrate the use of the \beenv\ environment to produce lists
+whose items are numbered with the \verb|\bullcntr| command. Different
+``bullet styles'' are obtained by means of some declarations that
+affects the size (or even the shape) of the bullets employed.
+
+
+
+\subsection{The standard sizes (\command{smartctrbull})}
+\label{SS:Xmp-Standard}
+
+In our first example, actually, we do not alter the default bullet
+style, that is, the output \tbenu\ will produce by itself, if you
+invoke it without options and do not declare any style by your own; in
+any case, it corresponds to the style selected by a
+\verb|\smartctrbull| declaration.
+
+\begin{bullenum}
+ \item
+ This is the first item of the list, that is, item~\#1. It is
+ therefore numbered with a single bullet. Poor bullet! How
+ lonely it must feel!
+
+ \item
+ This is the second item of the list, that is, item~\#2. It is
+ therefore numbered with two bullets, one on the left and one
+ on the right. If you are a romantic nature, you might even
+ think of them as Romeo and Juliet\ldots
+
+ \item\label{Standard-3}
+ This is the third item of the list, that is---guess
+ what?---item~\#3. Not surprisingly, it is numbered with three
+ bullets neatly arranged in the shape of an equilateral
+ triangle.
+
+ \item
+ This is the fourth item, item~\#4. A square has exactly four
+ vertices, so it seems quite appropriate to lay out the four
+ bullets that must be used to number this item exactly in this
+ form, as you can see in the label.
+
+ \item
+ If you have not lost the track, you will agree that this is
+ the fifth item of the list. A regular pentagon would probably
+ have been the optimal choice for displaying this value of the
+ counter, but for some reason the arrangement shown in the
+ label of this item has been preferred by the author of \tbull.
+
+ \item\label{Standard-6}
+ Sixth item! Item~\#6! A regular hexagon is used here! Note,
+ however, that the bullets have shrunk to a smaller size,
+ because the size used so far would have made the bullet
+ cluster look a bit too crowded.
+
+ \item
+ In the opinion of the author, the shape used to display the
+ value~7 is even more pleasant than the regular hexagon used
+ for the value~6; indeed, this is a regular hexagon too, but
+ with the center marked by an additional bullet, which makes
+ the figure look more symmetric.
+
+ \item
+ If 7~was the perfect number of bullets, here we face the
+ disruption of this perfection. The solution adopted for
+ arranging 8~bullets, which you can see here, is, in the
+ author's opinion, the less inelegant among all possibilities.
+
+ \item
+ Item~\#9, the last value that the \verb|\bullcntr| command can
+ display. The bullets are just stacked in a $3\times3$ square
+ pattern---the obvious choice!
+\end{bullenum}
+
+
+
+\subsection{Moderately large bullets (\command{largectrbull})}
+
+Our next example illustrates the output produced by the style selected
+with a \verb|\largectrbull| declaration; this style continues to use,
+for the values over~5, the same bullet size adopted for the first five
+values. So, we say
+
+\begin{bullenum}
+ \largectrbull
+
+ \item
+ This is the first item of the list, that is, item~\#1. It is
+ therefore numbered with a single bullet. Poor bullet! How
+ lonely it must feel!
+
+ \item
+ This is the second item of the list, that is, item~\#2. It is
+ therefore numbered with two bullets, one on the left and one
+ on the right. If you are a romantic nature, you might even
+ think of them as Romeo and Juliet\ldots
+
+ \item\label{Large-3}
+ This is the third item of the list, that is---guess
+ what?---item~\#3. Not surprisingly, it is numbered with three
+ bullets neatly arranged in the shape of an equilateral
+ triangle.
+
+ \item
+ This is the fourth item, item~\#4. A square has exactly four
+ vertices, so it seems quite appropriate to lay out the four
+ bullets that must be used to number this item exactly in this
+ form, as you can see in the label.
+
+ \item
+ If you have not lost the track, you will agree that this is
+ the fifth item of the list. A regular pentagon would probably
+ have been the optimal choice for displaying this value of the
+ counter, but for some reason the arrangement shown in the
+ label of this item has been preferred by the author of \tbull.
+
+ \item\label{Large-6}
+ Sixth item! Item~\#6! A regular hexagon is used here! Note,
+ once again, that the bullets have \emph{not} shrunk to a
+ smaller size, so that the resulting picture looks pretty
+ crowded, although not intolerably bad-looking. Compare the
+ label of this item with a reference to the corresponding
+ item~\ref{Standard-6} under~\ref{SS:Xmp-Standard}.
+
+ \item
+ In the opinion of the author, the shape used to display the
+ value~7 is even more pleasant than the regular hexagon used
+ for the value~6; indeed, this is a regular hexagon too, but
+ with the center marked by an additional bullet, which makes
+ the figure look more symmetric.
+
+ \item
+ If 7~was the perfect number of bullets, here we face the
+ disruption of this perfection. The solution adopted for
+ arranging 8~bullets, which you can see here, is, in the
+ author's opinion, the less inelegant among all possibilities.
+
+ \item
+ Item~\#9, the last value that the \verb|\bullcntr| command can
+ display. The bullets are just stacked in a $3\times3$ square
+ pattern---the obvious choice!
+\end{bullenum}
+
+
+
+\subsection{Small bullets (\command{smallctrbull})}
+
+The reciprocal example is to use small bullets throughout, from 1 to~9.
+Thus, we use the following source code:
+
+\begin{bullenum}
+ \smallctrbull
+
+ \item
+ This is the first item of the list, that is, item~\#1. It is
+ therefore numbered with a single bullet. Poor bullet! How
+ lonely it must feel!
+
+ \item
+ This is the second item of the list, that is, item~\#2. It is
+ therefore numbered with two bullets, one on the left and one
+ on the right. If you are a romantic nature, you might even
+ think of them as Romeo and Juliet\ldots
+
+ \item\label{Small-3}
+ This is the third item of the list, that is---guess
+ what?---item~\#3. Not surprisingly, it is numbered with three
+ bullets neatly arranged in the shape of an equilateral
+ triangle.
+
+ \item
+ This is the fourth item, item~\#4. A square has exactly four
+ vertices, so it seems quite appropriate to lay out the four
+ bullets that must be used to number this item exactly in this
+ form, as you can see in the label.
+
+ \item
+ If you have not lost the track, you will agree that this is
+ the fifth item of the list. A regular pentagon would probably
+ have been the optimal choice for displaying this value of the
+ counter, but for some reason the arrangement shown in the
+ label of this item has been preferred by the author of \tbull.
+
+ \item\label{Small-6}
+ Sixth item! Item~\#6! A regular hexagon is used here! Note,
+ once more, that the bullets have \emph{not} shrunk to a
+ smaller size, because they were \emph{already} small in the
+ items shown thus far.
+
+ \item
+ In the opinion of the author, the shape used to display the
+ value~7 is even more pleasant than the regular hexagon used
+ for the value~6; indeed, this is a regular hexagon too, but
+ with the center marked by an additional bullet, which makes
+ the figure look more symmetric.
+
+ \item
+ If 7~was the perfect number of bullets, here we face the
+ disruption of this perfection. The solution adopted for
+ arranging 8~bullets, which you can see here, is, in the
+ author's opinion, the less inelegant among all possibilities.
+
+ \item
+ Item~\#9, the last value that the \verb|\bullcntr| command can
+ display. The bullets are just stacked in a $3\times3$ square
+ pattern---the obvious choice!
+\end{bullenum}
+
+Again, compare the references to items \#3 and~\#6 from different
+examples: standard bullets (\ref{Standard-3} and~\ref{Standard-6}),
+moderately large bullets (\ref{Large-3} and~\ref{Large-6}), small
+bullets (\ref{Small-3} and~\ref{Small-6}).
+
+
+
+\subsection{Tiny bullets}
+
+We come now to a sort of extreme example: the use of
+\verb|\textperiodcentered|. Since there is no predefined declaration
+for this style, it is necessary to manually redefine the two
+``hooks'', \verb|\counterlargebullet| and \verb|\countersmallbullet|,
+that \tbull\ (and therefore, indirectly, also \tbenu) call when they
+want to typeset a bullet.
+
+\begin{bullenum}
+ \renewcommand*{\counterlargebullet}{\textperiodcentered}
+ \renewcommand*{\countersmallbullet}{\textperiodcentered}
+
+ \item
+ This is the first item of the list, that is, item~\#1. It is
+ therefore numbered with a single bullet. Poor bullet! How
+ lonely it must feel!
+
+ \item
+ This is the second item of the list, that is, item~\#2. It is
+ therefore numbered with two bullets, one on the left and one
+ on the right. If you are a romantic nature, you might even
+ think of them as Romeo and Juliet\ldots
+
+ \item
+ This is the third item of the list, that is---guess
+ what?---item~\#3. Not surprisingly, it is numbered with three
+ bullets neatly arranged in the shape of an equilateral
+ triangle.
+
+ \item
+ This is the fourth item, item~\#4. A square has exactly four
+ vertices, so it seems quite appropriate to lay out the four
+ bullets that must be used to number this item exactly in this
+ form, as you can see in the label.
+
+ \item
+ If you have not lost the track, you will agree that this is
+ the fifth item of the list. A regular pentagon would probably
+ have been the optimal choice for displaying this value of the
+ counter, but for some reason the arrangement shown in the
+ label of this item has been preferred by the author of \tbull.
+
+ \item
+ Sixth item! Item~\#6! A regular hexagon is used here! Note
+ that it was really impossible, this time, for the bullets to
+ shrunk to a still smaller size than the one that has been
+ adopted in the above items!
+
+ \item
+ In the opinion of the author, the shape used to display the
+ value~7 is even more pleasant than the regular hexagon used
+ for the value~6; indeed, this is a regular hexagon too, but
+ with the center marked by an additional bullet, which makes
+ the figure look more symmetric.
+
+ \item
+ If 7~was the perfect number of bullets, here we face the
+ disruption of this perfection. The solution adopted for
+ arranging 8~bullets, which you can see here, is, in the
+ author's opinion, the less inelegant among all possibilities.
+
+ \item
+ Item~\#9, the last value that the \verb|\bullcntr| command can
+ display. The bullets are just stacked in a $3\times3$ square
+ pattern---the obvious choice!
+\end{bullenum}
+
+This bullet style might be employed in a \beenv\ environment nested
+inside another one.
+
+
+
+\subsection{St.\texorpdfstring{\,}{ }Valentine (\command{heartctrbull})}
+\label{SS:Xmp-Hearts}
+
+To end this inventory of variations, let us illustrate the use of a
+fancier ``bullet'': a little heart. We obtain this with a
+\verb|\heartctrbull| declaration.
+
+\begin{bullenum}
+ \heartctrbull
+
+ \item\label{Hearts-1}
+ This is the first item of the list, that is, item~\#1. It is
+ therefore numbered with a single heart. Poor heart! It is a
+ true lonely heart!
+
+ \item
+ This is the second item of the list, that is, item~\#2. It is
+ therefore numbered with two hearts, one on the left and one on
+ the right. Thinking of Romeo and Juliet is absolutely natural
+ in this context\ldots
+
+ \item\label{Hearts-3}
+ This is the third item of the list, that is---guess
+ what?---item~\#3. Not surprisingly, it is numbered with three
+ hearts neatly arranged in the shape of an equilateral
+ triangle.
+
+ \item\label{Hearts-4}
+ This is the fourth item, item~\#4. A square has exactly four
+ vertices, so it seems quite appropriate to lay out the four
+ hearts that must be used to number this item exactly in this
+ form, as you can see in the label.
+
+ \item\label{Hearts-5}
+ If you have not lost the track, you will agree that this is
+ the fifth item of the list. A regular pentagon would probably
+ have been the optimal choice for displaying this value of the
+ counter, but for some reason the arrangement shown in the
+ label of this item has been preferred by the author of \tbull.
+
+ \item
+ Sixth item! Item~\#6! A regular hexagon is used here,
+ adorned with hearts! Of course, the hearts do not shrink, as
+ doesn't yours, and as doesn't your ardent passion!
+
+ \item\label{Hearts-7}
+ In the opinion of the author, the shape used to display the
+ value~7 is even more pleasant than the regular hexagon used
+ for the value~6; indeed, this is a regular hexagon too, but
+ with the center marked by an additional heart, which makes the
+ figure look more symmetric.
+
+ \item\label{Hearts-8}
+ If 7~was the perfect number of hearts, here we face the
+ disruption of this perfection. The solution adopted for
+ arranging 8~hearts, which you can see here, is, in the
+ author's opinion, the less inelegant among all possibilities.
+
+ \item
+ Item~\#9, the last value that the \verb|\bullcntr| command can
+ display. The hearts are just stacked in a $3\times3$ square
+ pattern---the obvious choice!
+\end{bullenum}
+
+% ( paren match
+This could be used in valentines to enumerate to your beloved the
+terms of your passion\ldots~:-)
+
+Cross-references are a bit funny with this style; they look like this:
+\ref{Hearts-1}, \ref{Hearts-3}, \ref{Hearts-4}, \ref{Hearts-5},
+\ref{Hearts-7}, and~\ref{Hearts-8}.
+
+
+
+\section{Nested enumerations}
+
+Try not to overdo this: carrying it to excess could lead to confused
+output.
+
+
+
+\subsection{Nesting one \beenv\ inside another}
+\label{SS:NestBullBull}
+
+We use ``large'' bullets for the outer environment, and ``tiny''
+bullets for the inner one.
+
+\begin{bullenum}
+ \largectrbull
+
+ \item
+ First item: let this one alone, just to have a term of
+ comparison.
+
+ \item\label{NestBull-2}
+ Second item. Here we nest another \beenv\ environment:
+ \begin{bullenum}
+ \renewcommand*{\counterlargebullet}{\textperiodcentered}
+ \renewcommand*{\countersmallbullet}{\textperiodcentered}
+ \item\label{NestBull-2.1}
+ First sub-item.
+ \item\label{NestBull-2.2}
+ Second sub-item.
+ \item\label{NestBull-2.3}
+ Third sub-item.
+ \item\label{NestBull-2.4}
+ Fourth sub-item. OK, this should suffice.
+ \end{bullenum}
+ Don't forget, we are still inside item~\ref{NestBull-2} of
+ the outer enumeration.
+
+ \item\label{NestBull-3}
+ Third item (of the outer enumeration). Let us repeat exactly
+ the same nested enumeration as in item~\ref{NestBull-2}.
+ \begin{bullenum}
+ \renewcommand*{\counterlargebullet}{\textperiodcentered}
+ \renewcommand*{\countersmallbullet}{\textperiodcentered}
+ \item\label{NestBull-3.1}
+ First sub-item.
+ \item\label{NestBull-3.2}
+ Second sub-item.
+ \item\label{NestBull-3.3}
+ Third sub-item.
+ \item\label{NestBull-3.4}
+ Fourth sub-item. OK, this should suffice.
+ \end{bullenum}
+ Back to item~\ref{NestBull-3} of the outer enumeration.
+\end{bullenum}
+
+Now the bad news: you might want to refer to, say, item
+\ref{NestBull-3.4} under item~\ref{NestBull-3}. As you can see, the
+reference comes out wrong, since the label from the outer enumeration
+% ( paren match
+is typeset with the style of the inner one.~:-(\spacefactor=\sfcode`.
+\space This is a known bug: I\@ decided not to correct it, since doing
+so would require to introduce the concept of bullet styles
+distinguished by level, which I\@ deem intolerably burdensome. Be
+aware of this limitation when you nest \beenv\ environments inside one
+another (this does not apply, however, to \beenv's nested within
+\enenv's, as we'll see in the following examples).
+
+
+
+\subsection{Nesting \beenv\ inside \enenv}
+\label{SS:NestBullEnum}
+
+Let us repeat the same example shown above, but changing the outer
+environment to \enenv, and suppressing style variations.
+
+\begin{enumerate}
+ \item
+ First item: let this one alone, just to have a term of
+ comparison.
+
+ \item\label{NestBuEn-2}
+ Second item. Here we nest a \beenv\ environment:
+ \begin{bullenum}
+ \item\label{NestBuEn-2.1}
+ First sub-item.
+ \item\label{NestBuEn-2.2}
+ Second sub-item.
+ \item\label{NestBuEn-2.3}
+ Third sub-item.
+ \item\label{NestBuEn-2.4}
+ Fourth sub-item. OK, this should suffice.
+ \end{bullenum}
+ Don't forget, we are still inside item~\ref{NestBuEn-2} of
+ the outer enumeration.
+
+ \item\label{NestBuEn-3}
+ Third item (of the outer enumeration). Let us repeat exactly
+ the same nested enumeration as in item~\ref{NestBuEn-2}.
+ \begin{bullenum}
+ \item\label{NestBuEn-3.1}
+ First sub-item.
+ \item\label{NestBuEn-3.2}
+ Second sub-item.
+ \item\label{NestBuEn-3.3}
+ Third sub-item.
+ \item\label{NestBuEn-3.4}
+ Fourth sub-item. OK, this should suffice.
+ \end{bullenum}
+ Back to item~\ref{NestBuEn-3} of the outer enumeration.
+\end{enumerate}
+
+See Subsection~\ref{S:CrossXmp} for examples of cross-references to
+the items of these lists.
+
+
+
+\subsection{Nesting \enenv\ inside \beenv}
+\label{SS:NestEnumBull}
+
+As before, but the other way around: \beenv\ is now the outer
+environment, and \enenv\ the inner one.
+
+\begin{bullenum}
+ \item
+ First item: let this one alone, just to have a term of
+ comparison.
+
+ \item\label{NestEnBu-2}
+ Second item. Here we nest an \enenv\ environment:
+ \begin{enumerate}
+ \item\label{NestEnBu-2.1}
+ First sub-item.
+ \item\label{NestEnBu-2.2}
+ Second sub-item.
+ \item\label{NestEnBu-2.3}
+ Third sub-item.
+ \item\label{NestEnBu-2.4}
+ Fourth sub-item. OK, this should suffice.
+ \end{enumerate}
+ Don't forget, we are still inside item~\ref{NestEnBu-2} of
+ the outer enumeration.
+
+ \item\label{NestEnBu-3}
+ Third item (of the outer enumeration). Let us repeat exactly
+ the same nested enumeration as in item~\ref{NestEnBu-2}.
+ \begin{enumerate}
+ \item\label{NestEnBu-3.1}
+ First sub-item.
+ \item\label{NestEnBu-3.2}
+ Second sub-item.
+ \item\label{NestEnBu-3.3}
+ Third sub-item.
+ \item\label{NestEnBu-3.4}
+ Fourth sub-item. OK, this should suffice.
+ \end{enumerate}
+ Back to item~\ref{NestEnBu-3} of the outer enumeration.
+\end{bullenum}
+
+Again, see Subsection~\ref{S:CrossXmp} for examples of
+cross-references to the items of the above lists.
+
+
+
+\section{Examples of cross-references}
+\label{S:CrossXmp}
+
+Cross-references are printed using the bullet style that was in effect
+when the \verb|\label| command was given. The following examples
+illustrate this.
+
+In~\ref{SS:Xmp-Standard} we had references to~\ref{Standard-3} and
+to~\ref{Standard-6}. In~\ref{SS:Xmp-Hearts}, on the other hand, the
+references were to~\ref{Hearts-1}, to~\ref{Hearts-3},
+to~\ref{Hearts-4}, to~\ref{Hearts-5}, to~\ref{Hearts-7}, and
+to~\ref{Hearts-8}.
+
+We turn now to nested lists. We let alone the example
+of~\ref{SS:NestBullBull}, we already know that references come out
+wrong in this case. In~\ref{SS:NestBullEnum} we had items
+\ref{NestBuEn-2.1}, \ref{NestBuEn-2.2}, \ref{NestBuEn-2.3}, and
+\ref{NestBuEn-2.4}, all listed under item~\ref{NestBuEn-2}, and
+similarly items \ref{NestBuEn-3.1}, \ref{NestBuEn-3.2},
+\ref{NestBuEn-3.3}, and \ref{NestBuEn-3.4}, as part of
+item~\ref{NestBuEn-3}. In~\ref{SS:NestEnumBull}, on the other hand,
+we had items \ref{NestEnBu-2.1}, \ref{NestEnBu-2.2},
+\ref{NestEnBu-2.3}, and \ref{NestEnBu-2.4}, all listed under
+item~\ref{NestEnBu-2}: as you can see, the bullets now precede the
+reference to the item of \enenv; similarly, items \ref{NestEnBu-3.1},
+\ref{NestEnBu-3.2}, \ref{NestEnBu-3.3}, and \ref{NestEnBu-3.4} are now
+a part of the ``bulletted'' item~\ref{NestEnBu-3}.
+
+
+
+\setcounter{secnumdepth}{0}
+
+\begin{thebibliography}{9}
+ \providecommand*{\bysame}{\leavevmode\hbox to3em{\hrulefill}\thinspace}
+ \addcontentsline{toc}{section}{\refname}
+
+ \bibitem{dtx}
+ G.~Mezzetti, \emph{The \bull\ package}, documented \TeX\
+ source (dtx), included in every distribution of \tbull\ (in
+ the file \filedir{\Bullcntr.dtx}).
+
+ \bibitem{overview}
+ \bysame, \emph{Overview of \tbull}, included in every
+ distribution of \tbull, surely as \LaTeX\ source (in the file
+ \filedir{\Bullcntr-man.tex}) and perhaps in precompiled PDF
+ format too (in the file \filedir{\Bullcntr-man.pdf}).
+
+ \bibitem{bull-sam}
+ \bysame, \emph{Using \tbull: an example}, \LaTeX\ source,
+ included in every distribution of \tbull\ (in the file
+ \filedir{\Bullcntr-sam.tex}).
+\end{thebibliography}
+
+\end{document}
diff --git a/macros/latex/contrib/bullcntr/manifest.txt b/macros/latex/contrib/bullcntr/manifest.txt
new file mode 100644
index 0000000000..9866253bbd
--- /dev/null
+++ b/macros/latex/contrib/bullcntr/manifest.txt
@@ -0,0 +1,101 @@
+
+This is file `manifest.txt'.
+
+This file is part of a work named "bullcntr package".
+
+Copyright (C) 2007 by Gustavo MEZZETTI <gustavo.mezzetti@istruzione.it>.
+
+The 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
+ 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".
+
+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.
+
+October 10, 2008 (vers. 0.04)
+
+
+
+MEANING OF THE TERM "Work"
+==========================
+
+In the case of the bullcntr package, the "Work" is the collection of the
+following 7 files:
+
+00readme.txt -- start by reading this file
+manifest.txt -- the file you are reading now
+bullcntr.dtx -- main source file
+bullcntr.ins -- installation script
+bullcntr-man.tex -- LaTeX source of package overview/manual
+bullcntr-sam.tex -- sample code that uses the bullcntr package
+bullenum-sam.tex -- sample code that uses the bullenum package
+
+If you have received the 7 files listed above, you possess an integral copy
+of the bullcntr package.
+
+
+
+MEANING OF THE TERM "Compiled Work"
+===================================
+
+In the case of the bullcntr package, a "Compiled Work" is the collection of:
+
+a) the following 5 files that are also part of the "Work" (see above):
+
+00readme.txt
+manifest.txt
+bullcntr-man.tex
+bullcntr-sam.tex
+bullenum-sam.tex
+
+AND
+b) the following 3 files:
+
+bullcntr.sty -- the bullcntr "executable" package
+bullenum.sty -- the bullenum "executable" package
+bullcntr.dvi -- documentation in DVI format
+
+You may, at your option, substitute (or supplement) the file `bullcntr.dvi'
+with the following one:
+
+bullcntr.pdf -- documentation in PDF format
+
+but at least one among the files `bullcntr.dvi' and `bullcntr.pdf' must be
+included in a "Compiled Work" that you wish to distribute. The file
+`bullcntr.pdf' is obtained by submitting to the program pdflatex the file
+`bullcntr.dtx', following the same steps as those explained in
+`00readme.txt' under the title "How to generate the documentation".
+
+
+
+ANCILLARY FILES
+===============
+
+The package of files distributed through the Comprehensive TeX Archive
+Network (CTAN) includes also the following 2 files:
+
+README -- guide to directory contents
+bullcntr-man.pdf -- package overview/manual in PDF format
+
+These two files are included only for the convenience of the CTAN visitors
+and are _not_ a required part of the bullcntr package (of course you may,
+if you wish, include them in your distribution too).
+
+
+
+COMMENT
+=======
+
+Please remember that, in order to distribute a LPPL-compliant copy of the
+bullcntr package, it suffices to distribute only the 7 files that
+constitute the "Work".
+