path: root/macros/latex/contrib/bullcntr/bullcntr-sam.tex

%
% 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}