hhmuf — Manual

Herman Haverkort

                      hermanh@cistron.nl

May 1995 – Addresses corrected March 1999

1 Introduction

The hhmuf package contains the multinote system, which provides an alternative to the usual dull footnote system. It is not meant to be used by conservatives! hhmuf’s multinotes can be used in forbidden modes and can be repeated easily. When repeating multinotes, the hhmuf macros make sure the same marker is used throughout, while preventing repeated notes from being typeset twice on the same page. hhmuf’s multinotes do not use counters, numbers or alphabetic characters to represent them: they use sets of symbols without a well-defined order.

To be able to use hhmuf one should have the files hhmuf.sty, hhqueue.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 The Principal Macros

hhmuf does not set footnotes directly. First they should be defined, then they can be typeset once or several times, and finally they should be fired.

\mufhire label:{text} defines a footnote label to have contents text. A footnote marker is reserved for the exclusive use by this footnote. Neither the marker nor the text will be typeset yet. Note that labels should not contain commas, periods or colons!

\muf label:{} typesets the previously defined footnote label. If one tries to typeset the same footnote several times on the same page, hhmuf tries to ensure that the actual note at the foot of the page is typeset only once. If the in-text footnote marker is followed by a comma or period, then the comma or period is automatically typeset under the marker, which generally looks better than after the marker.

\muffire label: frees the footnote’s label and marker, to enable their use for footnotes which will be defined later on.

To ease the typesetting of incidental footnotes, the following abbreviations are provided. \muf:{text} acts as an abbreviation for hiring, typesetting and firing a note using a temporary label. \muf label:{text} acts as an abbreviation for hiring and typesetting a footnote.

3 Use of Footnotes in Forbidden Environments

One is said to be in a forbidden environment when TEX is constructing some box. Attempts to insert a footnote when in a forbidden environment fail: the in-text marker is set all right, but the actual note is not inserted at the foot of the page. hhmuf solves this problem for its multinotes by saving all footnotes called from a forbidden environment and typesetting them after the environment is left. This is implemented at several levels of automation: the interface of the highest ones will be presented here.

Suppose we have a short sentence containing a hhmuf style footnote, and want to \fbox it, like this:

\fbox{%
  Short sentence with footnote\muf:{Just an example.}.%
}

The result will be like Short sentence with footnote.^{♠} : there is no note at the foot of the page. The solution is to use the following TEX code instead of the listing above:

\fbox{\mufoff
  Short sentence with footnote\muf:{Another example.}.%
}\muffin

The result will be like Short sentence with footnote.^{△} : now the footnote appears at the foot of the page indeed. The macro couple \mufoff – \muffin did the job. Note that \mufoff is called inside the forbidden environment, while \muffin is called outside the forbidden environment.

△ Another example.

If the forbidden environment used arises from the expansion of a L^{A}TEX environment, then there is an easier way to get the footnotes right. Suppose we defined a L^{A}TEX environment for \fboxing short sentences:

\newenvironment{fboxed}{\sbox0\bgroup}{\egroup\fbox{\box0}}

Then the following:

\begin{fboxed}%
  Short sentence with footnote\muf:{Third example.}.%
\end{fboxed}

will yield Short sentence with footnote.^{⊖} : there is no note at the foot of the page. The solution is to protect the forbidden environment by \mufoff [fboxed]. From now on all hhmuf style footnotes appearing in fboxed environments will be handled correctly automatically. So when \mufoff [fboxed] has been processed,

\begin{fboxed}%
  Short sentence with footnote\muf:{Last example.}.%
\end{fboxed}

will yield the proper result Short sentence with footnote.^{♣} , with a note at the foot of the page, as expected.

Both ways of calling footnotes from forbidden environments allow nesting of forbidden environments, automatic protections and \mufoff – \muffin couples.

4 Local Footnote Hiring

\mufend{group} muffires all footnotes which had been defined since the corresponding call to \mufbegin{group}. Thus \mufbegin and \mufend establish some kind of footnote definition environment, called a mufgroup. Mufgroups can be nested, but if you do nest them, nest them properly. So this is not permitted:

♣ Last example.

\mufbegin{A}%
  \mufbegin{B}%
\mufend{A}%
  \mufend{B}%

while this is OK:

\mufbegin{A}%
  \mufbegin{B}%
  \mufend{B}%
\mufend{A}%

Whenever you enter a new group all footnotes which had already been defined are frozen. You cannot fire them until the new group is closed with \mufend. So the following is OK:

\mufhire F:{Foo}%
\mufbegin{B}%
\mufend{B}%
\muffire F:%

while this is not:

\mufhire F:{Foo}%
\mufbegin{B}%
  \muffire F:%
\mufend{B}%

Whenever you are in a group, you cannot redefine footnotes which have been defined already in some outer group, because in that case you would have to muffire the footnote, which is not allowed. You cannot even define a new footnote which is local to the group but gets the same label as some footnote which has been defined in some outer group (e.g. a global footnote). The hhmuf macros are not that smart. So the following is not allowed:

\mufhire F:{Foo}%
\mufbegin{A}%
  \mufhire F:{bar}%

If you have closed all the groups you had opened (or if you never opened any), then you are in the outermost, nameless group. You can close that group with \mufend{}. It will muffire all footnotes you had defined, and automatically reopen a outermost nameless group. So it is a kind of: \muffire all.

5 Customizing hhmuf

5.1 References to Footnotes

\mufword defines the word which is used in references to multinotes. By default it is ‘footnote’; redefine it if you like, preferably by defining an appropriate language option.

5.2 In-text Markers

\@makemufword defines how to format a footnote’s marker (in the text, not in the insertion at the foot of the page). Its default definition is:

\def\@makemufmark#1{\hbox{$^{#1}$}}

Redefine it if you like.

5.3 Handling of Following Punctuation Marks

All in-text markers are typeset using the macro \@covermufpunct, which gets the marker setting macro as its first and only argument. By default \@covermufpunct will pull periods and commas following a footnote’s marker under that marker. With some definitions of \@makemufmark this will not be desirable: \@covermufpunct should be redefined then, for example by:

\def\@covermufpunct{}

5.4 Footnote formatting

\@makemuftext defines how to format a footnote. It takes two arguments: #1 is the footnote’s marker; #2 is the footnote text. Redefine it if you like.

5.5 Set of Markers to be Used

To make it easier to choose out of the numerous possibilities for footnote markers I defined some sets of markers which can be selected by using the appropriate option, for example:

\usepackage{hhmuf}[circlox]

The recognized options are the following:

option id. size description  packages needed
black  8 black symbols  amssymb
circlox  12 circle and box symbols  amssymb
fuss  10 miscellaneous symbols  amssymb
geometry 10 geometrical symbols  amssymb
misc  19 miscellaneous symbols (default set) none
music  3 music symbols  none
strokes  8 symbols made of thin strokes  amssymb

Take care that you do not select a set which is too small for your purposes.

You can also define your own set of markers to be used. The following provides an example:

\h@initqueue{mufsyms@avail}{%
  \\{\blacklozenge}%
  \\{\square}%
  \\{\blacktriangledown}%
  \\{\vartriangle}%
  \\{\blacksquare}%
  \\{\triangleleft}%
  \\{\blacktriangle}%
  \\{\lozenge}%
  \\{\blacktriangleleft}%
  \\{\triangledown}}

The symbols are specified as arguments of \\. Please note that it makes no sense to use symbols with a well-defined order: the muf macros will not respect it.

6 Failures and Possible Causes

Failure:

! Package hhmuf Warning: Refusing to redefine multinote `LABEL'.
(hhmuf)                  Muffire it first.

Cause: If you defined a footnote labelled LABEL, using \muf or \mufhire, you should call \muffire LABEL: before defining another footnote having the same label.

Failure:

! Package hhmuf Warning: Out of multinote symbols.
(hhmuf)                  Using `?' instead.

Cause: A marker is assigned to each footnote which has been defined. Because the number of markers is limited, you will run out of markers if too many footnotes have been defined at the same time. To prevent this from happening, use \muffire to undefine footnotes as soon as you do not need them anymore. Keep in mind that each call to \muf:{TEXT} in a forbidden environment (even without a explicit label) reserves a marker, which will not be released until the forbidden environment is left.

Failures:

! Package hhmuf Warning: Reference to undefined multinote `LABEL'.
! Package hhmuf Warning: Cannot type-set multinote `LABEL':
(hhmuf)                  it is not defined.
! Package hhmuf Warning: Cannot muffire multinote `LABEL':
(hhmuf)                  it is not defined.

Cause: Should be evident. If it is not, please check if you did not close the group in which the multinote was defined already (using \mufend). One other mistake you could have made, is calling \muffire LABEL: somewhere between \muf LABEL:{optional text} in a protected forbidden environment and the closure of that environment. Note that if the multinote LABEL is undefined, calling for example \muf LABEL:{} results in two warnings: one for the intext multinote reference marker (‘Reference to undefined...’), and another for the type-setting of the footnote itself (‘Cannot type-set...’).

Failure:

! Package hhmuf Warning: Reference to undefined multinote `tmp_'.

Cause: You used \muf:{}, which does not make any sense.

Failure:

! Package hhmuf Warning: Multinote `LABEL' was defined at level 1,
(hhmuf)                  so cannot muffire it at level 3.

(and similar messages) Cause: Since you defined the multinote LABEL, you opened another group which is still open. It is not possible to undefine the multinote then. Muffire it before opening the current group, or after closing it.

Failure:

! Package hhmuf Warning: Refusing to end multinote group `GROUPA' by
(hhmuf)                  \mufend{GROUPB}.

(and similar messages) Cause: This warning should be caused by mismatched \mufbegins and \mufends. Remember mufgroups should be properly nested.

Failure: The footnote’s marker appears all right, but the text is missing.

Cause: You used \muf or \muffin in some ‘forbidden’ environment. The constraints are the same as for ordinary L^{A}TEX footnotes, unless the environment is protected by \mufoff[environment name].

Failure: A footnote text is set although it should not be there.

Cause: You probably forgot some \muffin some time ago, so that the footnote texts, which should have been set by that \muffin, are set by a following

\muffin.

Failure: A footnote text appears twice on the same page.

Cause: L^{A}TEX could have floated a identical footnote from the previous page to this one which cannot be detected by the multinote macros. Another possible cause is probably the multinote macros getting the the page number of the in-text marker wrong. This problem is very much like the inability to start the footnote numbering every page (which — by the way — is no problem if you use multinotes, because they use a shift-system for their numbering). This problem can be solved, and probably will be solved as soon as I encounter it in practice. In both cases correct the error ‘manually’ by using \mufsymonly once instead of \muf.