enotez-cum-appendices-and-starred-chapters

enotez is a LaTeX package that produces endnotes, and works well, and can group said endnotes by chapters—except if the chapters are either starred (i.e. numberless), or appendices. This is how I solve workaround that problem.    #latex #enotez #split #chapters #title #starred #appendix

enotez is a LaTeX package used to create endnotes, i.e., instead of notes that are shown at the bottom of the page (so-called footnotes), these are shown, for example, at the end of the document (usually just before references). It works well, but out-of-the-box, it will just dump and group all of the notes into a single section or chapter (depending on the document type), named by default “Notes.” This happens to be annoying to me, when the documents in question have chapters: I would much rather have the notes grouped by chapter.

Now enotez does provide a feature to solve this, but the notes for, say the first chapter, are grouped under the heading “Chapter 1”, and so on—which is more than a bit lame. I wanted said heading to display the chapter’s title (in addition to its number). The internet came to the rescue, and I found a solution that got me what I wanted—except it introduced a new problem: it didn’t work if the document had any starred chapters (\chapter*{title}). I duly solved that problem too, only to—you’ve guessed it—stumble on another issue: due to the internal mechanics of enotez, if the document had any appendices, then the title shown for appendix A would that of chapter 1, for appendix B that of chapter 2, and so on. As you can probably guess from the fact that I am writing this, I fixed this too—which means that by now I have a rather large story to tell.

But there are problems. To begin with, the appendices: for my solution for grouping endnotes by chapter to display notes in the appendices properly, requires that the notes are printed after the appendices. More seriously though, when there are starred chapters, the logic required to define enotez’s tags (see below), assumes that all said chapters have at least one endnote each—in fact, depending on the scenario, it is possible to have errors if, say, all the starred chapters have footnotes, but the last numbered chapter does not. All of which forced me to change my strategy.

The original reason that led me to adopt endnotes (instead of the customary footnotes), is that my notes, although not usually very long, are often long enough to—if they are footnotes—end up split across more than one page. This is not a big problem on paper, but when reading on a screen, it becomes quite the nuisance. Moreover, also when reading on paper, it’s best to have all notes in one place (usually at the ending, before the references): this way, when you find an endnote number, you can move directly to the end of the book to read its contents, and then get back to reading the “main content”. As I explained above, this is the behaviour that I wanted to replicate. However, given the all the constraints that exist, I ended up doing the following:

Getting enotez to group all notes at the end of each chapter, is actually quite easy. And it fixes the problem I had with footnotes: even if they go over to the next page, endnotes will still be much easier to read on a screen, than a footnote that crossed over to the (bottom of the) next page… It is also easy to deal with chapters without endnotes—in fact, you don’t need to worry about whether any chapter has any endnotes, or not. Also, if you want to apply the longer solution to group notes at the end of the document, this strategy allows you to wait, until you have a version of the document that is mature enough for you to know how many starred chapters you will have, and which (if any) of them will contain endnotes.

So to group endnotes at each chapter’s end, do the following:

\usepackage{enotez}
\setenotez{
  backref=true,
  reset=true,
  list-heading=\section*{#1},
  counter-format=arabic,
}

Then, at the end of each chapter—starred or not, no matter—in which there are endnotes, issue the \printendnotes command:

\chapter{Introduction}
\label{cha:intro}
Some text.\endnote{And an endnote for the introduction.}

\printendnotes

This will print a section at the end of the chapter (named by default, “Notes”), containing the endnotes for the Introduction chapter. Observe that in this scenario, this section is kept out of the table of contents—unlike in the below scenario of endnotes only at the end of the document. And we are done.

Added bonus: reconverting to footnotes only. Easy, just add the following to the preamble:

\let\endnote\footnote
\let\printendnotes

What this does is make the \endnote command actually call \footnote, and make the \printendnotes command do nothing. And presto, you have a footnote-only document!2

*   *   *

Group endnotes at the end of the document, (sub-)grouped by chapters. First, recall that here, we assume that the endnotes are printed after the appendices. Moreover, we only call \printendnotes once, at the end of the main document, like so:

\clearpage
\printendnotes

The \clearpage is needed because in this scenario, I place an entry in the table of contents for the Notes chapter—cf. totoc=chapter in the next snippet—and without the \clearpage command, that entry will link to the wrong page.

Now, to make enotez group all notes by chapter, set it up like so:

\usepackage{enotez}
\setenotez{
  backref=true,
  totoc=chapter,
  counter-format=arabic,
  reset=true,
  split=chapter,
}

As mentioned above, this will group the endnotes for first chapter under the heading “Chapter 1,” and so on. To change this, add an extra line to \setenotez:

\setenotez{
  backref=true,
  totoc=chapter,
  counter-format=arabic,
  reset=true,
  split=chapter,
  split-title={<ref>. <title>}
}

As you may already be able to surmise, this will group the notes for the first chapter under the heading 1. <Chapter 1's title>, and so on. <ref> is a tag that is provided by enotez, and that—when there are no starred chapters—contains the number of the current chapter (and after the \appendix command has been issued, contains A, B, etc.). title is a tag that we will construct to carry the title of the chapter whose number is in <ref>—and to construct it, we need to attach a unique label to each chapter.

And here’s the problem: in LaTeX, starred chapters do not cause the chapter counter to be incremented—which means that <ref> will end up with the wrong value. For example, if before Chapter 1, there is, say, a \chapter*{Foreword} that contains endnotes, then those notes will show up in the Notes chapter under a heading with the number 0… The way to deal with this, is to setup counters to keep track of the starred chapters, and implement the logic to deal with the places they show up. How this is to be done, is the theme of the rest of this section. I’ll assume a document with two starred chapters before chapter 1, two starred chapters after chapter 3 and two appendices, A and B:

First, we shall need the number of numbered chapters, and I find it easier to use a macro for that (in the case of our example document, we have 3 numbered chapters):

\newcommand\numNumberedChapters{3}

Next, we set the counters:

\newcounter{unnamedrref}
\newcounter{unnamedtitle}

What is “rref,” I hear you ask? It stands for “retractable <ref>.” <ref> always has a value, but for starred chapters, I want the corresponding heading in the Notes chapter to not have a number. Hence, this line will not do:

split-title={<ref>. <title>}

because it always displays a number. So we define a new tag, <rref>, which will display <ref> for numbered chapters/appendices, and display nothing for starred chapters. This new tag will be used by modifying the line above as follows:

split-title={<rref><title>}

Here is the definition of the <rref> tag:

\NewSplitTitleTag{rref}{%
  \ifnum10=1<ref>\relax% <ref>=0
  \else%
    \ifnum0<0<ref>\relax% <ref> is a positive number
      \ifnum<ref>=\numNumberedChapters%
        \ifnum\value{unnamedrref}=0% chapter 3
          \stepcounter{unnamedrref}%
          <ref>.\ %
        \else% epilogue or post scriptum
        \fi%
      \else% chapters 1--2
        <ref>.\ %
      \fi%
    \else% <ref> is neither 0 nor a positive number, so...
      <ref>.\ % ... appendices
    \fi
  \fi}

It helps to think of this code—as well as that of the <title> tag, below—as a loop, that runs once for each chapter where there are endnotes. The comments should help you glean the logic, which is as follows: if <ref> is 0, that means we are dealing with one of the first two starred chapters. So return no output, as the chapters have no number. When <ref> becomes a positive number, that means we are dealing with a numbered chapter. In which case we must keep track of the number of the current chapter (i.e., the current value of <ref>). Why? To know when are in the last numbered chapter (3 in our case), because after that, there are two more unnumbered chapters. So if <ref> is a positive number, but it is not equal to the number of numbered chapters, then this means that this we are dealing with a numbered chapter other than chapter 3—hence just return <ref>.\␣, i.e., the chapter’s number.3 If <ref> equals 3, then we check the value of the unnamedrref counter (which starts at 0): if it is 0, that means we are actually on chapter 3, so we increase the counter, and return <ref>.\␣; if the counter is not zero, that means we are in one of the chapters Epilogue or Post Scriptum, so we return nothing. And we keep returning nothing, until <ref> stops being a number—which means we are now in the appendices. So we again return <ref>.\␣, which in this case will be A.\␣ and B.\␣, for the first and second appendices, respectively. And that is it, as far as the <ref>/<rref> tags are concerned.

Before moving on to the <title> tag, a TeXnical explanation is in order, about the way one must do integer tests in this environment. Take a look at the line:

\ifnum0<0<ref>\relax%

This if condition returns true if <ref> is a positive number (more specifically, an integer). How does it work? If <ref> is, say, 1, then we get the comparison 0<01, which is true. The same holds if <ref> is 2, 3, etc. But if <ref> is A, then one obtains 0<0A, and this is processed by ignoring the A, yielding 0<0, which is false. This means that to test equality with 0, one cannot do 0=0<ref>—because this will yield true when <ref> is A. Hence, we use the following hack: 10=1<ref>, which yields a true condition (10=10) when, and only when, <ref> is 0.

OK, with that out of the way, let us now check the code for the <title> tag. The logic follows the same broad strokes, except that now, when dealing with the starred chapters, either before or after the numbered ones, one has to keep track of exactly which starred chapter one is in—so as to be able to grab the appropriate title. Which, as you may have guessed, is done using counters. Furthermore, I had to use a different new counter—unnamedtitle—because if I attempted to re-use counter unnamedrref, it kept changing value unexpectedly (i.e., the code for the two tags seemed to interact, somehow). (This might also be a good time to point out that in this programming environment, there is no else-if construct.) Here is the code:

\NewSplitTitleTag{title}{%
  \ifnum10=1<ref>\relax% <ref>=0
    \ifnum\value{unnamedtitle}=0% first starred chapter
      \stepcounter{unnamedtitle}%
      \nameref*{cha:acks}%
    \else%
      \ifnum\value{unnamedtitle}=1% second starred chapter
        \nameref*{cha:foreword}%
        \setcounter{unnamedtitle}{0}% to be able to use the ...
        % ... same counter, for starred chapters after the numbered ones.
      \fi%
    \fi%
  \else%
    \ifnum0<0<ref>\relax% <ref> is positive number
      \ifnum<ref>=\numNumberedChapters%
        \ifnum\value{unnamedtitle}=0% last numbered chapter
          \stepcounter{unnamedtitle}%
          \nameref*{cha:conclusion}%
        \else%
          \ifnum\value{unnamedtitle}=1% first (ending) starred chapter
            \stepcounter{unnamedtitle}%
            \nameref*{cha:epilogue}%
          \else%
            \ifnum\value{unnamedtitle}=2% second (ending) starred chapter
              \setcounter{unnamedtitle}{0}%
              \nameref*{cha:postscriptum}%
            \fi%
          \fi%
        \fi%
      \else%
        \nameref*{ch:<ref>}% chapters 1--2
      \fi%
    \else
      \nameref*{appdx:<ref>}% appendices
    \fi%
  \fi}

Now, we deal with the appendices. The value of the <ref> comes from the counter \thechapter, which is the number of the current chapter. The problem is that after the \appendix command is issued, the chapter counter is reset, but it is displayed as a letter, rather than as an Arabic number. Which means that both Chapter 1 and Appendix A will end up being assigned the same label… and thus, will be shown with the same title in the Notes chapter. A problem we fix in two steps. First, we modify the \appendix command:

\newif\ifinappendix% Default is \inappendixfalse
\let\oldappendix\appendix% Store original \appendix
\renewcommand{\appendix}{% Update \appendix
  \oldappendix% Call original \appendix command.
  \inappendixtrue% Set switch to true.
}

In this manner, after the \appendix command has been run, \ifinappendix will evaluate to true. We use this to modify the \chapter command, to add different labels, depending on whether or not we are in an appendix:

\usepackage{letltxmacro}
\LetLtxMacro\origchapter\chapter
\RenewDocumentCommand\chapter{som}{%
  \IfBooleanTF{#1}
    {% starred chapter, no label then
      \origchapter*{#3}%
    }
    {% else add a label
      \IfNoValueTF{#2}
        {\origchapter{#3}}
        {\origchapter[#2]{#3}}%
        \ifinappendix% if in appendix, label starts with appdx
          \expanded{\noexpand\label{appdx:\thechapter}}%
        \else% if in regular chapter, label starts with ch
          \expanded{\noexpand\label{ch:\thechapter}}%
        \fi%
    }%
}

And that’s basically it.

If you want appendices after the endnotes. As I pointed out at the start, the above strategy is only good if you print the endnotes after the appendices. As I am not a fan of doing this, when modifying the \appendix command, I also modify the \endnote command to produce a footnote instead:

\newif\ifinappendix% Default is \inappendixfalse
\let\oldappendix\appendix% Store original \appendix
\renewcommand{\appendix}{% Update \appendix
  \oldappendix% Call original \appendix command.
  \inappendixtrue% Set switch to true.
  \let\endnote\footnote% In appendices, we use footnotes.
}

If you prefer this approach, then you do not need to worry about appendices when defining the rref and title tags (cf. their respective code above).

Switching between endnotes at the end of chapters, and endnotes at the end of document. If you have a document with a \printendnotes command at the end of each chapter, and want to change it to have endnotes only at the end of the document, you would have to manually delete/comment all the \printendnotes commands at the end of chapters… and going in the opposite direction requires you to insert one \printendnotes command for each chapter with endnotes… too much hassle. The solution is to define an alias command for \printendnotes, to be used only at the end of chapters!

\let\ppen\printendnotes% ppen: partial print endnotes

To switch from endnotes at chapters’ end, to endnotes at document’s end, add the \printendnotes command at the end of the document (cf. above), and then just clear the above alias, i.e., substitute the above line with:

\let\ppen

To go the other direction, delete/comment the \printendnotes command at the end of the document, and redefine alias again.

Recall that for this to work, this alias must be used only with endnotes after chapters; the command for endnotes at the end of document only continues to be \printendnotes, as shown above.

Example code. In the this tar.gz archive you can find the code corresponding to the example given above—two starred chapters, followed by three numbered chapters, followed by two more starred chapters, and two appendices, and only then the \printendnotes declaration—with the notes at the end, grouped by chapter. The code is based on the report class of my LaTeX templates.

November 2022. Got feedback? See the contact page.

*   *   *

Update, June 18, 2023. Migrated the content from PDF to HTML, and added an alternative to place endnotes at the end of each chapter. Also added an easy way to convert the document, should the need arise, to using only footnotes. Retained the original solution of grouping notes at the end of document, and (sub-)grouping by chapter.