hhcount — Manual

Herman Haverkort

                      hermanh@cistron.nl

May 1995 – Addresses corrected March 1999

1 Introduction

hhcount provides some macros to display numbers in various ways. For example: numbers could be formatted as roman numbers, dice or scores. Some of the display macros act context dependent: in headings they yield other results than in the midst of a paragraph or in an index. On top of these ‘simple’ formatting macros, hhcount provides macros which combine several ‘simple’ formatting macros to format the values of composite counters. Besides hhcount offers the possibility to have composite counters of arbitrary structure appear in the index.

The hhcount package is not stable yet: it is too young. The simple counter formatting macros will probably not change much anymore, although their output may be smoothed a little. However, the more complex macros may still be reorganized a lot, although I hope it will not be necessary anymore.

To be able to use hhcount one should have the files hhcount.sty and hhutils0.sty available. Both files can be obtained from the library of my website at http://come.to/hh and from ctan.

2 Simple Number Formatting

Let us start by summarizing the simple number formatting macros which are provided by hhcount: example input corresp. output other example output

\fctabdigit{2}  2  29
\fcolddigit{2}  2  29
\fcloweralpha{2}  b  cc
\fcbigalpha{2}  B  CC
\fcsmallalpha{2}  b  cc
\fclowerroman{2}  ii  xxix
\fcbigroman{2}  II  XXIX
\fcsmallroman{2}  ii  xxix
\fcbigromanlined{2}       II  XXIX
\fcsmallromanlined{2}     ii  xxix
[figure: \fcbigdice{2}]
[figure: \fcsmalldice{2}]

\fcbigscore{2}
\fcsmallscore{2}

\fcfnsymbol{2}  †

The next step in complexity are number formatting macros which give context-dependent output. This is implemented by using the following context switches:

\if@fcoldstyle selects old style numerals (as opposed to tabular style);

\if@fcsmall selects lower case size output (as opposed to upper case size);

\if@fcverbose determines whether or not verbose output should be given, for example: “Chapter 2” or just “2”;

\if@fcfull if true, then composite counters are shown completely (for example: “§1.2.3”), else only the lowest level subcounters may be shown (for example: “3”);

The context switches are set by context switching macros like \fcinheading, \fcintext and \fcinlist. We say that a context switching macro is active if it was the last one to affect the context switches. The formatting macros in the following table are affected only by the switches \if@fcoldstyle or \if@fcsmall; how to define formatting macros depending on the switches \if@fcverbose and \if@fcfull will be discussed later. example input output when

                             \fcinheading

is active

output when \fcintext is active

         \fcdigit{14}  14  14
         \fcalpha{14}  N  n
         \fcroman{14}  XIV  xiv
         \fcromanlined{14}       XIV  xiv
         [figure: \fcdice{14}]

         \fcscore{14}

By default \fcinheading is active; \fcintext is active when using \ref or \pageref (those two macros are redefined by hhcount); \fcinlist is active when typesetting the index. With respect to the formatting macros in the above table \fcinlist is the same as \fcinheading: both macros set the context switches \if@fcoldstyle and \if@fcsmall to the same values.

3 How to Define Composite Counters

Suppose we want to set up a four-level section numbering system for some sub-document in another document, for example the rules of a club embedded in some booklet about that club. The section numbers should be composed from the values of four (sub-)counters: ruleschapter, rulessection, rulesparagraph and rulessubpar. Chapter numbers should be represented by capital alphabetic characters; elementary section and paragraph numbers by arabic digits; subparagraph numbers by parenthesized lower case characters. What should be done?

First we select a series identifier for our composite counter. Series identifiers are natural numbers which are assigned to composite counters. Each composite counter should be assigned a unique identifier. The following identifiers are reserved for common purposes:

id. purpose
1 part numbering
2 front matter section numbering
3 main matter section numbering
4 (back matter) appendix numbering
5 equation numbering
6 table numbering
7 figure numbering
8 footnote numbering
12 page numbering

Since our sub-document section numbering is a non-common purpose, we select another identifier for our rules section numbers, say 9.

Then we define a macro which expands to the series identifier:

\def\rulesseries{9}

Next we specify how the four sub-counters are to be combined:

\combinecounters\rulesseries{%
\\{ruleschapter}%
\\{rulessection}%
\\{rulesparagraph}%
\\{rulessubpar}}

3.1 A First Format

Finally we define how the counter is to be formatted:

\setcounterformat\rulesseries{#1-#2-#3-#4}{%
\fcorfinally
% capitals for chapter numbers:
\fcformat{#1}{\fcalpha}%
% digits for section numbers:
\fcformat{#2}{\fcdigit}%
% a period to separate section and paragraph
% numbers:
\fcformat{#3}[.]%

  % digits for paragraph numbers:
               {\fcdigit}%
  % parenthesized lower case for subpar. nrs.:
  \fcformat{#4}{\fcsurround{(}{\fcloweralpha}{)}}%
  \fcordespair}

The format specification should not change throughout the document! You may be tempted to do so if you want to change the formatting of section numbers when entering the back matter of a document. However, do not change the format using just \setcounterformat; instead select a new series identifier for the back matter, and repeat the three steps shown above.

Let me explain the above listing. \setcounterformat’s second argument contains a list of parameter numbers, separated by hyphens. Because the composite counter at issue here consists of four sub-counters, four parameter numbers are given.

The third argument of \setcounterformat specifies how to format the composite counter. The function of \fcorfinally and \fcordespair will be explained later. The calls to \fcformat serve to format the various subcounters. In general \fcformat gets four arguments, of which the second and fourth are optional and must be bracketed when applied: \fcformat {number to be set}[prefix]{style}[postfix].

The number to be set is typically denoted by a parameter identifier: #1 stands for the highest level sub-counter, while higher numbers stand for lower level sub-counters. \fcformat only sets non-zero numbers: if the specified sub-counter happens to be zero it is ignored.

The prefix is used to connect the formatted sub-counter to preceding subcounters; the prefix is ignored when the sub-counter at issue is the first one to be actually typeset.

The style should be a macro with all arguments specified except for the last one. The last, unspecified parameter of the macro will be used to pass on the value of the sub-counter at issue as a natural number. The macro should format the natural number somehow. The following expressions can be used as styles:

• all simple number formatting macros listed in section 2;

• expressions of the form: \fcsurround{prefix}{style}{postfix}, where prefix and postfix are arbitrary expressions and style is a valid style.

The result of such expressions is that the sub-counter will be formatted according to style, surrounded by prefix and postfix;

• expressions of the form: \fcverbose{verbose style}{non-verbose style}, where verbose style and non-verbose style are valid styles and the style used is selected according to the value of the \if@fcverbose context switch.

The postfix is used to connect the formatted sub-counter to following subcounters; the postfix is ignored when the sub-counter at issue is the last one to be actually typeset.

3.2 A First Result

Now the composite counter can be accessed by the macros \theruleschapter,

\therulessection, \therulesparagraph and \therulessubpar, which give

results like: “A”, “A2”, “A2.3” and “A2.3(d)”. To step the counters, you use

the macros \stepcounter{ruleschapter}, \stepcounter{rulessection},
\stepcounter{rulesparagraph} and \stepcounter{rulessubpar}.

When \fcinheading is active, rules paragraph numbers will be set like “A2.3(d)”, but when \fcintext is active, the same number will be set like “a2.3(d)”.

3.3 Adding Verbosity

hhcount provides two additional macros to be used in the third argument of

\setcounterformat: \fcverbose and \fcprefix.

\fcverbose{verbose}{non-verbose} expands to verbose when the context switch \if@fcverbose is true; otherwise it expands to non-verbose.

\fcprefix{number to be set}[short prefix]{long prefix} takes care of typesetting long prefix if and only if the number to be set is non-zero. The optional short prefix is used to connect the long prefix to preceding formatted sub-counters, if there are any. If \fcprefix is used multiple times in succession, withouth putting a \fcformat in between, then only the last one which got a non-zero number to be set will be effective.

Using these two macros we define a new format for our rules paragraph numbers:

\setcounterformat\rulesseries{#1-#2-#3-#4}{%
 \fcorfinally
 \fcverbose{%
   \fcprefix{#1}{chapter~}%
   \fcprefix{#2}{section~}%
 }{%
   \fcprefix{#2}{\S}%
 }%
 \fcformat{#1}{\fcalpha}%
 \fcformat{#2}{\fcdigit}%
 \fcverbose{%
   \fcprefix{#3}[ ]{par.~}%
   \fcprefix{#4}[ ]{par.~}%
 }{}%
 \fcformat{#3}[\fcverbose{}{.}]{\fcdigit}%
 \fcformat{#4}{\fcsurround{(}{\fcloweralpha}{)}}%
 \fcordespair}

Now compare the results when different context switching macros are active.

Note that \fcintext sets \if@fcverbose true.

\fcinheading  \fcintext

A  chapter a
§A2  section a2
§A2.3  section a2 par. 3
§A2.3(d)  section a2 par. 3(d)

To demonstrate the flexibility of counters formatted with hhcount, the following table shows what happens if the chapter counter is never stepped:

\fcinheading  \fcintext

§2  section 2
§2.3  section 2 par. 3
§2.3(d)  section 2 par. 3(d)

The folllowing table shows what happens if the section counter remains zero:

\fcinheading  \fcintext

A  chapter a
A.3  chapter a par. 3
A.3(d)  chapter a par. 3(d)

4 Adding Partial Formats

Because headings for paragraphs and sub-paragraphs are typically set as run-in headings, we do not want the full paragraph numbers, including the containing chapter and section numbers, to appear in the heading. We can accomplish this by defining partial formats for subparagraph and paragraph numbers, in that order:

\setcounterformat\rulesseries{#1-#2-#3-#4}{%
    \fcformat{#4}{\fcsurround
      {\fcverbose{par.~}{}(}{\fcloweralpha}{)}}%
  \fcor
    \fcformat{#3}{\fcsurround
      {\fcverbose{par.~}{}}{\fcdigit}{}}%
  \fcorfinally
    \fcverbose{%
      \fcprefix{#1}{chapter~}%
      \fcprefix{#2}{section~}%
    }{%
      \fcprefix{#2}{\S}%
    }%
    \fcformat{#1}{\fcalpha}%
    \fcformat{#2}{\fcdigit}%
    \fcverbose{%
      \fcprefix{#3}[ ]{par.~}%
      \fcprefix{#4}[ ]{par.~}%
    }{}%
    \fcformat{#3}[\fcverbose{}{.}]{\fcdigit}%
    \fcformat{#4}{\fcsurround{(}{\fcloweralpha}{)}}%
  \fcordespair}

As can be seen in the above listing, \fcor separates the partial formats. \fcorfinally introduces the full format, and finally \fcordespair concludes the full format.

The following table shows the new results when different context switching macros are active. Note that \fcinheading sets \if@fcfull false, so that partial formats are used when available. \fcintext and \fcinlist set \if@fcfull true, so that the full format is always used.

 \fcinheading  \fcinlist  \fcintext

A  A  chapter a
§A2  §A2  section a2
3  §A2.3  section a2 par. 3
(d)  §A2.3(d)  section a2 par. 3(d)

5 Multiple Use of Sub-Counters

Sometimes it may be convenient to use a single sub-counter as a component of multiple composite counters. As an example consider the chapter counter in a book. This counter is obviously part of the section numbering system. Therefore it can occur in a statement like:

\combinecounters\chapterseries{%
  \\{chapter}%
  \\{section}%
  \\{subsection}}

by which \thechapter will be defined.

The chapter counter could also be part of the equation numbering system, for example when equation numbers are composed of the chapter counter and an equation counter which should be reset every chapter. To set up the equation numbering system one would like to use:

\combinecounters\equationseries{%
  \\{chapter}%
  \\{equation}}

However, this would have the unwanted side-effect of redefining \thechapter. This can be prevented by using a star-form of \\, as in:

\combinecounters\equationseries{%
  \\*{chapter}%
  \\{equation}}

So when reusing sub-counters which actually belong to another composite counter, use the star-form of \\ in the \combinecounters statement.

6 hhcount and makeindex

The makeindex program cannot handle composite section numbers like “A2.3(d)”. Besides makeindex has problems with sorting alphabetic numbers since it cannot determine whether or not it are roman numbers. hhcount provides a way to get around these problems.

All composite numbers defined by hhcount constructs are internally represented by a sequence of natural numbers, separated by hyphens and embedded in a macro call. A typical example is \fancycounter9-1-2-3-4-!. The first number represents the series identifier (9 in the example), while the following numbers represent the values of the relevant sub-counters.

hhcount provides the macros \initfancycounters, \indextolabels and

\indextopages. The first redefines the section and page numbering systems to use hhcount’s composite counters. \indextolabels sort of redefines \index to use the redefined section numbers and strip the \fancycounter and the -! off the composite counter representation. \indextopages does the similar thing for page numbers. In both cases the result is a sequence of natural numbers, separated by hyphens, which can be handled perfectly well by makeindex. By embodying the appropriate definitions in your index style (.ist) file makeindex will undo the stripping after sorting the page or section numbers, so that your index entries will still be typeset as defined by means of hhcount macros. Thus section numbers like “A2.3(d)” can be used for references in the index. Inserting equation, table and figure numbers in the index is just as easy. It is even possible to have different kind of composite numbers in the same index, for example page as well as section numbers, because the series identifiers are not stripped off so that it remains possible to determine the proper series and formatting of each composite number.

So what should appear in your index style file and what should not? The following lines should be in it:

delim_r ",!--\\fancycounters "
encap_infix "{\\fancycounters "
encap_suffix ",!}"

Make sure that you do not redefine delim_n or page_compositor in your index style file.

Furthermore note the following restrictions if you want to use hhcount’s composite counters in the index:

• Never use \index without specifying an encapsulator. So do not use simply: \index{word}, but use, for example: \index{word|empty} instead. The empty encapsulator does no harm but forces the necessary encap_suffix to be used.

• Do not load the makeidx or index package after loading hhcount: load the former packages before hhcount instead.

• Do not call the macro \makeindex: hhcount will do it for you.

7 Bugs and Deficiencies

Class files tend to make the TEX compiler show on your terminal which chapter of your book or report is being processed. Error messages often contain the page number. When using hhcount there is a chance that the chapter and page numbers shown on your terminal look weird: you will be shown the internal representation of your counter (\fancycounter 9-1-0-0-0-! for example). This is caused by an incorrect timing of macro expansion: in this case \fancycounter is expanded too late, that is: not at all.

Late expansion with hhcount is typically a problem with error and other messages: I would be highly surprised if someone discovers something like \fancycounter 9-1-0-0-0-! outside verbatim environments in a typeset document. However, when compiling your document you might run into early expansion, which causes severe errors. With the latest version of hhcount this problem does not seem to emerge in ‘usual’ contexts; however I am not sure.

Front matter, appendix and back matter peculiarities (with respect to page and section numbering) are not automatically supported by hhcount. Class files are too different in that respect. If hhcount is to be used to handle the section and page numbering in documents containing front matter and appendices, it would probably be best to incorporate hhcount in the class file, instead of loading it as an additional package.

8 Gamesters Page Numbers

The following redefines the page counter so that page numbers will be set as dice (I designed this for a gamesters society):

\def\fcpageseries{12}
\combinecounters\fcpageseries{\\{page}}
\setcounterformat\fcpageseries{#1}{%
  \fcorfinally
  \fcformat{#1}\fcdice
  \fcordespair}

I could not help to give you this as an final example.