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