diff options
author | Karl Berry <karl@freefriends.org> | 2007-04-03 00:14:46 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2007-04-03 00:14:46 +0000 |
commit | db7c29b795e61406c9a9fc1b6353694c3268774a (patch) | |
tree | 143dc81d4d1f8a90793d158d5d77bbf99bc95605 /Master/texmf-dist/doc/latex/bullcntr/bullenum-sam.tex | |
parent | ca1b85bdf009dbd78fbbd650d4313d056e2e6761 (diff) |
new latex package bullcntr (11feb07)
git-svn-id: svn://tug.org/texlive/trunk@4104 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/bullcntr/bullenum-sam.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/bullcntr/bullenum-sam.tex | 688 |
1 files changed, 688 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/bullcntr/bullenum-sam.tex b/Master/texmf-dist/doc/latex/bullcntr/bullenum-sam.tex new file mode 100644 index 00000000000..72409e75dd9 --- /dev/null +++ b/Master/texmf-dist/doc/latex/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{April~2, 2007} + +% 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 introducing 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} |