Smile for the Camera: a new cybercrime short story ebook.

Gallery: Summary of Frequently Used Terms

Image of summary of most frequently used terms

One of the major differences between bib2gls and makeindex/xindy is that instead of creating a file containing the commands to typeset the glossary bib2gls creates a file containing the entry definitions structured in a way that allows \printunsrtglossary to display the glossary by simply iterating over the list of entries defined for the given glossary.

Some glossary styles use a tabular-like environment, which often causes complications in an iterative context. In order to avoid these problems, \printunsrtglossary iterates over all entries outside of the style and constructs an internal control sequence that contains all the glossary typesetting commands. At the end of the process, the control sequence effectively contains the main bulk of the commands that makeindex/xindy would typically write to the file that's input by \printglossary.

At each iteration of the loop used by \printunsrtglossary there's a hook that can be used to skip the current entry. This makes it easier to filter the list so that only a subset of entries are displayed. This example does this to create a summary at the start of the document that only contains the most frequently used terms. The glossary at the end of the document contains the complete list.

The example uses the sample file example-glossaries-symbolnames.bib which should be installed on your system if you have a reasonably up-to-date version of glossaries-extra.

Remember that the record package option is required if you want to use bib2gls. Here I've used record=nameref as it works better particularly where, as in this case, the location counter is set to equation in one place. I've also used the long style and adjusted the width of the description column:

\usepackage[record=nameref,stylemods=long,style=long]{glossaries-extra}
\setlength{\glsdescwidth}{.75\textwidth}

Although the entries represent symbols they are defined using @entry rather than @symbol. For example:

@entry{sym.alpha,
  name = {\ensuremath{\alpha}},
  description = {Quisque ullamcorper placerat ipsum.}
}

Since the sort field hasn't been set, this means that the sort value will be obtained from the name field. (If @symbol was used instead the default fallback would be the ID.) So the sym.alpha entry will have the sort value 𝛼 (U+1D6FC) etc.

The summary at the start of the document should only include the most frequently used terms. With bib2gls, the simplest way of finding out how many times an entry has been used is to save the record count for each entry. This requires the --record-count (or -c) switch. The total number of records for each entry will then be saved in the special recordcount internal field. I've decided to only include entries where the total record count is greater than 3:

\newcommand{\filterhook}[1]{%
  \GlsXtrIfFieldCmpNum*{recordcount}{#1}{>}{3}%
  {}%
  {\printunsrtglossaryskipentry}%
}

The summary can now be created using the starred form where I can locally set this filter in the mandatory argument:

\printunsrtglossary*[target=false,title={Summary of Most Frequently Used Terms}]
{\let\printunsrtglossaryentryprocesshook\filterhook}

Note that I have to switch off the default hypertarget creation with target=false to prevent duplicate hypertargets. (The links formed by \gls will all go to the relevant entry in the main glossary at the end of the document.)

The complete document is:

% arara: pdflatex
% arara: bib2gls: { recordcount: on }
% arara: pdflatex
\documentclass{report}

\usepackage[T1]{fontenc}
\usepackage[a4paper]{geometry}
\usepackage[colorlinks]{hyperref}
\usepackage[record=nameref,stylemods=long,style=long]{glossaries-extra}

\setlength{\glsdescwidth}{.75\textwidth}

\GlsXtrLoadResources[src=example-glossaries-symbolnames]

\newcommand{\filterhook}[1]{%
  \GlsXtrIfFieldCmpNum*{recordcount}{#1}{>}{3}%
  {}%
  {\printunsrtglossaryskipentry}%
}

\begin{document}
\printunsrtglossary*[target=false,title={Summary of Most Frequently Used Terms}]
{\let\printunsrtglossaryentryprocesshook\filterhook}

\chapter{Example}
\gls{sym.gamma}, \gls{sym.gamma}, \gls{sym.gamma}.
\gls{sym.alpha}, \gls[format=hyperbf]{sym.alpha}, \gls{sym.alpha}, \gls{sym.alpha}.
\gls{sym.delta}, \gls{sym.delta}, \gls{sym.delta}.
\gls{sym.eta}.
\gls{sym.kappa}.
\gls{sym.epsilon}, \gls{sym.epsilon}, \gls{sym.epsilon},
\gls{sym.epsilon}, \gls{sym.epsilon}, \gls{sym.epsilon}.
\gls{sym.theta}, \gls{sym.theta}, \gls{sym.theta}, \gls{sym.theta},
\gls{sym.theta}.

\gls{sym.lambda}, \gls{sym.lambda}, \gls{sym.lambda}.
\begin{equation}
\gls[counter=equation]{sym.lambda}
\end{equation}

\chapter{Another Example}
\gls{sym.epsilon}, \gls[noindex]{sym.gamma}, \gls[format=glsignore]{sym.delta}.

\printunsrtglossary
\end{document}

The initial comment lines are arara directives. You can remove them if you don't use arara, in which case the document build is:

pdflatex sample-bib2gls-frequentsummary
bib2gls --record-count sample-bib2gls-frequentsummary
pdflatex sample-bib2gls-frequentsummary

(Note that I haven't used --group as letter groups aren't appropriate for this document.)

Download PDF (56.08K) and source code (1.30K).

The summary on the first page lists the following:

(If you find that the summary is empty while trying out this example, check that you remembered to call bib2gls with --record-count.)

Notes:

  1. Delta (𝛿) has been used 4 times in total: three times on page 2 and once on page 3. Only page 2 is listed in the glossary because the reference on page 3 has format=glsignore. This means that the page 3 location is omitted from the location list but the location still counts towards the total number of records for that entry. Therefore delta is included in the summary.
  2. Gamma (𝛾) has also been used 4 times in total: three times on page 2 and once on page 3. Only page 2 is listed in the main glossary because the reference on page 3 has noindex. This means that no record of that reference was added to the .aux file and so bib2gls has no knowledge of that instance of \gls. Therefore that fourth reference of gamma doesn't count towards the total number of records for that entry. Therefore gamma isn't included in the summary since its total record count is 3.
  3. The summary has the same relative ordering as the main glossary (albeit with entries missing).

In this example there are no child entries. If you want to apply this filtering approach to a hierarchical glossary then extra care is required to ensure that parent entries aren't omitted where child entries are retained as this will create a strange disjointed effect. The slightly modified definition of the custom \filterhook command below will additionally skip any entries that have a parent:

\newcommand{\filterhook}[1]{%
  \GlsXtrIfFieldCmpNum*{recordcount}{#1}{>}{4}%
  {\ifglshasparent{#1}{\printunsrtglossaryskipentry}{}}%
  {\printunsrtglossaryskipentry}%
}

If you want to test if an entry has any children then you will need to use the save-child-count resource option.

If the summary needs to have a different order, then you'll need to create a secondary glossary. For example, to have the summary sorted by order of use:

\newglossary*{frequent}{Summary of Most Frequently Used Terms}
\GlsXtrLoadResources[src=example-glossaries-symbolnames,secondary=use:frequent]

Remember the type is now required:

\printunsrtglossary*[target=false,type=frequent]
{\let\printunsrtglossaryentryprocesshook\filterhook}