HH Count Packages — Manual

Herman Haverkort

                      hermanh@cistron.nl

March 1999

Contents

1 Introduction 1 2 Simple Number Formatting 2 3 How to Define Composite Counters 3

3.1 A First Format . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.2 A First Result . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.3 Adding Verbosity . . . . . . . . . . . . . . . . . . . . . . . . . 7

4 Adding Partial Formats 8 5 Multiple Use of Subcounters 9 6 hhccidx and makeindex 10 7 Bugs and Deficiencies 11 8 Gamesters Page Numbers 12

1 Introduction

This manual describes how to use the hhcount macro packages for L^{A}TEX2e. I wrote the packages in 1995 and 1996, and used them in my L^{A}TEXsetup since. They may not have been tested in combination with the latest versions of common class files and macro packages, so actually I would not be surprised if you experience some trouble with these packages. Please let me know.

hhcount is actually a set of four package files: hhscount (simple counters), hhccount (complex counters), hhicount (standard initialisation) and hhccidx (complex counters in the index). A previous version of hhcount was provided as a single file hhcount.sty.

The hhscount package 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, hhccount provides macros which combine several macros to format the values of composite counters. hhicount provides a macro \initfancycounters which sets up a standard numbering system using hhccount; this may serve as an example (if you do not want to use it as is).

hhccidx offers the possibility to have composite counters of arbitrary structure appear in the index.

To be able to use hhcount you need the files hhscount.sty, hhccount.sty,

hhicount.sty, hhccidx.sty and hhutils0.sty available. These files can

be obtained from my website at http://come.to/hh (follow the directions to the library) or from ctan.

2 Simple Number Formatting

Let us start by summarizing the simple number formatting macros which are provided by hhscount: 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}]
[figure: \fcbigrounddice{2}]
[figure: \fcsmallrounddice{2}]

\fcbigscore{2}
\fcsmallscore{2}

\fcfnsymbol{2}  †

The next step in complexity are number formatting macros that give contextdependent 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(s) of subcounters may be shown (for example: “3”);

\if@fclocal if true, only the lowest level(s) of subcounters may be shown in a reference, if the higher levels are the same for the place that is refered from and the place that is refered to.

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; we will discuss how to define formatting macros depending

on \if@fcverbose, \if@fcfull and \if@fclocal 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}]
         [figure: \fcrounddice{14}]

         \fcscore{14}

By default \fcinheading is active; \fcintext is active when using \ref or \pageref (those two macros are redefined by hhscount); \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

Composite counters can be constructed using hhccount. 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 macro name for our composite counter, e.g. \rulesseries.

Second we select a series identifier for our composite counter. Series identifiers are natural numbers which are assigned to composite counters. Each composite counter must 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.

Next we determine in which order the subcounters are to be combined. Of course this is:

  1. ruleschapter
  2. rulessection
  3. rulesparagraph
  4. rulessubpar

3.1 A First Format

Finally we combine all this with a specification of how the counter is to be formatted:

\defcombicounter\rulesseries{9}{%
  ruleschapter-rulessection-|-rulesparagraph-|-rulessubpar%
}{%
  % capitals for chapter numbers (first level):
  \<1:[\fcalpha]>
  % digits for section numbers (second level):
  \<2:[\fcdigit]>
  % digits for paragraph numbers (third level),

  % and a dot to separate them from section numbers
  \<3:_._[\fcdigit]>
  % parenthesized lower case for subparagraph numbers:
  \<4:([\fcloweralpha])>
  }

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 \defcombicounter or \setcounterformat;

instead select a new series identifier for the back matter, and repeat the steps shown above.

Let me explain the above listing. The third argument of \defcombicounter contains a list of parameter numbers, separated by hyphens. Because the composite counter at issue here consists of four subcounters, four parameter numbers are given. Sometimes -|- is used instead of just a hyphen. The -|- indicates where higher level counters may be cut off if the counter is used in a local reference; that is a reference for which the higher level counters have the same value for both the place that is refered to and the place that is refered from.

The fourth argument of \defcombicounter specifies how to format the composite counter. For each subcounter \< is used with the following syntax: \<level:_infix_prefix[style]postfix_infix_>. The infixes are optional; the prefix and the postfix may be empty.

The level indicates which subcounter is to be typeset: 1 stands for the highest level subcounter, while higher numbers stand for lower level subcounters. Only non-zero numbers will be typeset: if the specified subcounter happens to be zero, it is ignored.

The first infix is used to connect the formatted subcounter to preceding subcounters; the infix is ignored when the subcounter at issue is the first one to be actually typeset. If no infix is desired, the infix and the surrounding underscores can be omitted.

The prefix is typeset just before the counter. It can be omitted.

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 subcounter 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: \(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 \(...) construct may also be used in the infixes, prefix and postfix.

The postfix is typeset just after the counter. It can be omitted. If the postfix is longer than one token, it can be necessary to enclose it in braces.

The last infix is used to connect the formatted subcounter to following subcounters; the infix is ignored when the subcounter at issue is the last one to be actually typeset. If no infix is desired, the infix and the surrounding underscores can be omitted.

Note: if you would like to use characters that are part of the syntax that is described above, you should enclose them in braces in most cases. This goes for the underscore _, brackets [, ] and > in general, and for the slash / and closing parenthesis ) inside a \(...) construct.

3.2 A First Result

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

hhccount provides two additional macros to be used in the fourth argument

of \defcombicounter: \( and \pre.

\(verbose/non-verbose) was already mentioned above; it expands to verbose when the context switch \if@fcverbose is true; otherwise it expands to non-verbose.

\pre level:_short prefix_long prefix\fix takes care of typesetting long prefix if and only if the subcounter of level level is non-zero. The short prefix is used to connect the long prefix to preceding formatted subcounters, if there are any. If \pre is used multiple times in succession, withouth putting a \<...> construct in between, then only the last \pre that got a non-zero value for subcounter level, will be effective. The short prefix may be omitted together with the underscores.

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

\defcombicounter\rulesseries{9}{%
  ruleschapter-rulessection-|-rulesparagraph-|-rulessubpar%
}{%
  \pre1:\(chapter~/)\fix
  \pre2:\(section~/\S)\fix
  \<1:[\fcalpha]>
  \<2:[\fcdigit]>
  \(\pre3:__par.~\fix/)
  \(\pre4:__par.~\fix/)
  \<3:_\(/.)_[\fcdigit]>
  \<4:([\fcloweralpha])>
  }

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:

\defcombicounter\rulesseries{9}{%
ruleschapter-rulessection-|-rulesparagraph-|-rulessubpar%
}{%
\<4:\(par.~/)([\fcloweralpha])>
\orelse
\<3:\(par.~/)[\fcdigit]>
\orelse
\pre1:\(chapter~/)\fix
\pre2:\(section~/\S)\fix
\<1:[\fcalpha]>
\<2:[\fcdigit]>
\(\pre3:__par.~\fix/)
\(\pre4:__par.~\fix/)
\<3:_\(/.)_[\fcdigit]>
\<4:([\fcloweralpha])>
}

As can be seen in the above listing, the partial formats are separated by \orelse. The last format is 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. \fcinlist sets \if@fcfull true, so that the full format is always used. \fcintext also sets \if@fcfull true, but it sets \if@fclocal true as well, so that the number may be shortened if it is a local reference (it is omitted if you are referring one level up from the current label; I think it would be a waste of time to correct this).

 \fcinheading  \fcinlist  \fcintext while in §A2.4

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

5 Multiple Use of Subcounters

Sometimes it may be convenient to use a single subcounter 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:

\defcombicounter\fcchapterseries{3}{%
  chapter-section-subsection-subsubsection-paragraph-subparagraph%
}{%
     \<1:[\fcdigit]_-_>
  \<2:_._[\fcdigit]_-_>
  \<3:_._[\fcdigit]_-_>
  \<4:_._[\fcdigit]_-_>
  \<5:_._[\fcdigit]_-_>
  \<6:_._[\fcdigit]>}

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, for example:

  \defcombicounter\fcequationseries{5}{chapter-|-equation}{%

    \<1:[\fcdigit]_._>\<2:[\fcdigit]>\orelse
    (\<1:[\fcdigit]_._>\<2:[\fcdigit]>)}

However, this would have the unwanted side-effect of redefining \thechapter. This can be prevented by typing a star just before the counter name, as in:

  \defcombicounter\fcequationseries{5}{*chapter-|-equation}{%
    \<1:[\fcdigit]_._>\<2:[\fcdigit]>\orelse
    (\<1:[\fcdigit]_._>\<2:[\fcdigit]>)}

So when reusing subcounters which actually belong to another composite counter, put stars in front of them.

6 hhccidx 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. hhccidx provides a way to get around these problems.

All composite numbers defined by hhccount 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 subcounters.

hhccidx provides macros \indextolabels and \indextopages. Both redefine the section and page numbering system to use hhccount’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 hhccount 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 hhccount’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 hhccidx: load the former packages before hhccidx instead.

• Do not call the macro \makeindex: hhccidx 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 hhccount 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 hhccount 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 hhccount 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 hhccount. Class files are too different in that respect. If hhccount 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 hhccount 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):

\defcombicounter\fcpageseries{12}{page}{\<1:[\fcdice]>}

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