summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/bullcntr/bullcntr-sam.tex
blob: 2ce5e15dd8592309d1a544fcb62f4483a3fbb649 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
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}