Gallery: Cross-References (bib2gls)

Image of glossary including cross-references

This example uses a mixture of cross-referencing techniques:

One entry (courgette) cross-references another (marrow) by using \gls in the description:

@entry{courgette,
  name={courgette},
  description={immature fruit of a vegetable \gls{marrow}}
}

One entry (cauliflower) uses the seealso key to indicate a related term:

@entry{cauliflower,
  name={cauliflower},
  description={type of cabbage with edible white flower head},
  seealso={cabbage}
}

One entry (eggplant) uses the see key to indicate that it’s a synonym:

@entry{eggplant,
  name={eggplant},
  description={another name for aubergine},
  see={aubergine}
}

Another synonym entry (zucchini) uses the alias key instead:

@index{zucchini,
  name={zucchini},
  alias={courgette}
}

Only some entries are actually used in the main document text:

Examples: \gls{courgette} (or \gls{zucchini}), \gls{aubergine} and
\gls{cabbage}.

The default behaviour of bib2gls is to select all entries that have been recorded (courgette, zucchini, aubergine and cabbage) and their dependencies. Since bib2gls has access to all the entry data, it’s able to detect \gls{marrow} in the description of courgette and so it identifies marrow as a dependency. (The courgette entry depends on the marrow entry being present in the glossary otherwise there will be a broken link.)

The complete document is:

\documentclass{report}

\usepackage[colorlinks]{hyperref}
\usepackage[record]{glossaries-extra}

\GlsXtrLoadResources[
  src={vegetables2}
]

\begin{document}

Examples: \gls{courgette} (or \gls{zucchini}), \gls{aubergine} and
\gls{cabbage}.

\printunsrtglossaries
\end{document}

If this file is called sample-bib2gls-crossrefs.tex and we do just:

pdflatex sample-bib2gls-crossrefs.tex
bib2gls sample-bib2gls-crossrefs.tex
pdflatex sample-bib2gls-crossrefs.tex

Then the resulting glossary (on page 2) will contain:

aubergine: purple egg-shaped vegetable 1
cabbage: vegetable with thick green or purple leaves 1
courgette: immature fruit of a vegetable marrow 1
marrow: long white-fleshed gourd with green skin
zucchini: see courgette

This uses the default selection={recorded and deps} setting so marrow is selected since courgette depends on it, but note that there’s no location since \gls{marrow} hasn’t been used in the document text so there’s no associated record in the aux file. However, if I rerun bib2gls and pdflatex:

bib2gls sample-bib2gls-crossrefs.tex
pdflatex sample-bib2gls-crossrefs.tex

then marrow will have a location (page 2) because now the \gls{marrow} in the description of courgette has created a record.

aubergine: purple egg-shaped vegetable 1
cabbage: vegetable with thick green or purple leaves 1
courgette: immature fruit of a vegetable marrow 1
marrow: long white-fleshed gourd with green skin 2
zucchini: see courgette

(The red text highlights the hyperlinks in the document.)

The only reason that zucchini appears in the glossary is because it has been used in the document. It doesn’t have an associated page number because it uses the alias key. This identifies it as an alias to bib2gls and the default action is to move the locations from zucchini to courgette. This means that zucchini has no locations and courgette has page 1 twice but the duplicate is dropped. This action can be changed with the alias-loc resource option.

Note that if you click on “zucchini” in the main document text, it will take you to the courgette entry. This is a feature of glossaries-extra rather than bib2gls.

The eggplant entry, which is a synonym for aubergine, hasn’t been selected because it doesn’t have any records and no selected entries depend on it (eggplant depends on aubergine but aubergine doesn’t depend on eggplant). Similarly, the cauliflower entry is dependent on the cabbage entry, but the cabbage entry isn’t dependent on the cauliflower entry.

The selection=all setting will select all entries in the bib file, but there are some entries that aren’t relevant to this particular document (even though they are all vegetables).

In order to ensure that the eggplant entry is included even though it hasn’t been used (but only if aubergine is included), the selection criteria can be modified to include entries that depend on selected entries:

\GlsXtrLoadResources[
  selection={recorded and deps and see}, 
  src={vegetables2}
]

This instructs bib2gls to include all recorded entries and their dependent entries (deps) and the entries dependent on them (see).

aubergine: purple egg-shaped vegetable 1
cabbage: vegetable with thick green or purple leaves 1
cauliflower: type of cabbage with edible white flower head see also cabbage
courgette: immature fruit of a vegetable marrow 1
eggplant: another name for aubergine see aubergine
marrow: long white-fleshed gourd with green skin 2
zucchini: see courgette

This now includes eggplant, which provides a useful redirect for the reader, but also includes cauliflower (which is related to the cabbage entry, but might not be relevant to the document content).

There’s a similar setting that doesn’t include entries with the seealso key when selecting entries that are dependent on required entries:

\GlsXtrLoadResources[ 
  selection={recorded and deps and see not also}, 
  src={vegetables2}
]

This now includes eggplant but not cauliflower:

aubergine: purple egg-shaped vegetable 1
cabbage: vegetable with thick green or purple leaves 1
courgette: immature fruit of a vegetable marrow 1
eggplant: another name for aubergine see aubergine
marrow: long white-fleshed gourd with green skin 2
zucchini: see courgette

Finally, you might not want locations for entries that are only used in the description of other entries (such as marrow). This can be achieved by switching off the automatic indexing (performed by commands like \gls) before the start of the glossary:

\GlsXtrSetDefaultGlsOpts{noindex}
\printunsrtglossaries

The complete document is now:

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

\usepackage[colorlinks]{hyperref}
\usepackage[record]{glossaries-extra}

\GlsXtrLoadResources[
  %selection={recorded and deps}, % default
  %selection={recorded and deps and see}, 
  selection={recorded and deps and see not also}, 
  src={vegetables2}
]

\begin{document}

Examples: \gls{courgette} (or \gls{zucchini}), \gls{aubergine} and
\gls{cabbage}.

\GlsXtrSetDefaultGlsOpts{noindex}
\printunsrtglossaries
\end{document}

The initial comment lines are arara directives. You can remove them if you don’t use arara. If you don’t use arara, you need to run the following commands:

pdflatex sample-bib2gls-crossrefs
bib2gls sample-bib2gls-crossrefs
pdflatex sample-bib2gls-crossrefs

(See Incorporating makeglossaries or makeglossaries-lite or bib2gls into the document build.)

Download: PDF (48.72K), source code (505B), vegetables2.bib (787B).