About 🛈
Shop 🛒Shop 🛒
LaTeX 🖹
Software 💾
Books 📚
Gallery 🖺
News 📢
Contact 📧
Blog 🖋
The site has just moved to a new web hosting provider. There may be some temporary disruption.

Gallery (bib2gls): Logical Glossary Divisions (type vs group vs parent)

If you have a document with many terms that need listing, it's likely that you may want to divide the terms into separate blocks or units for easier reading. There are three fields that are used for this.

type
The highest division is the glossary to which the entry belongs. The glossary must first be defined with an associated label used to identify it. The title is assigned to the glossary when it is defined or it can be overridden with the title key. The glossary is displayed using \printunsrtglossary and the title is placed in a sectioning command by default. The ordering of the lists corresponds to the ordering of the corresponding \printunsrtglossary commands.
group
The entries within a glossary can form groups (such as letter groups) as a by-product of the sorting method. This must be enabled with the --group switch and isn't available for the sort methods that don't use a comparator. The group label is stored in the group field. This is an internal field that typically shouldn't be set in the .bib file. If you want to use custom groups, the best way is to split them up using separate instances of \GlsXtrLoadResources with the group option set. In this case, the ordering of the groups matches the order of the corresponding \GlsXtrLoadResources commands. If you try setting the group field in the .bib file and select that field for sorting, the most you can do is order by the group label (not title). Given the limitations on labels (such as no extended or non-Latin characters with inputenc) this can lead to unsuitable results.
parent
An entry may have one or more sub-entries. Most of the sort methods will produce a hierarchical ordering that ensures that the sub-entries are listed immediately after their parent entry. The parent entry is identified by the parent field which should contain the parent's label.

So, if the logical divisions require sectioning commands for the titles with different styles for the way the content is displayed and shouldn't be sorted according to the heading, then you need to divide your entries into type and define the corresponding glossaries.

If the logical divisions don't have titles or have titles but need to be in a specific non-alphabetical order, then use the group option in \GlsXtrLoadResources.

If the logical divisions have titles and they need to be ordered according to those titles using the same comparator as their sub-entries, then use a hierarchical style with the parent field set and the define the corresponding parent entries.

The original idea behind bib2gls was to provide a convenient way of storing all terms, abbreviations and symbols that can be accessed across multiple documents. With this in mind it's best to adopt a flexible approach so that you're not locked into a particular way of dividing up your entries. This is where the field aliasing is useful. The idea here is to have a custom field (called identifier or topic in this example) that contains a label as the value. This field is unknown so bib2gls will ignore it, but it can be aliased to another label field, such as type, group, parent or category.

A variation is to make use of the basename of the .bib file. This means separating all your entries into different .bib files where each file's basename (without the .bib extension) can be supplied as the value. If you have hundreds (or thousands!) of entries, this is much more efficient than storing them all in a single file in terms of housekeeping as well as reducing run time and memory usage (for both bib2gls and your bib management application).

You can also have a mixture of both methods, as demonstrated in the examples below.

Example .bib Files

The file topics.bib contains terms that represent general topics. Some entries have a custom field called topicdescription, which is ignored by default but could be aliased to description. The file contents follow:

% Encoding: UTF-8

@indexplural{animal,
 topicdescription={living organism that has specialised sense 
 organs and nervous system}
}

@indexplural{vegetable,
 topicdescription={plant or part of a plant used as food}
}

@indexplural{mineral,
 topicdescription={solid, inorganic, naturally-occurring substance}
}

@indexplural{abbreviation}
@indexplural{symbol}
@indexplural{markuplanguage,text={markup language}}
@indexplural{agency,plural={agencies}}

The file symboltopics.bib contains terms the represent symbol topics. Three of the topics have a custom field called topic that will be ignored by default, but it could be aliased, for example, to parent to make those entries sub-topics. The file contents follow:

% Encoding: UTF-8

@indexplural{latinsymbol,text={Latin symbol},topic={symbol}}
@indexplural{mathgreek,text={Greek symbol},topic={symbol}}
@indexplural{pictograph,topic={symbol}}


The vegetables.bib file is distributed with bib2gls in the examples directory. These entries have a custom field called identifier which will be ignored by default, but may be aliased to a label field.

% Encoding: UTF-8

@entry{cabbage,
  name={cabbage},
  description={vegetable with thick green or purple leaves},
  identifier={vegetable}
}

@entry{brussels-sprout,
  name={Brussels sprout},
  description={small leafy green vegetable buds},
  identifier={vegetable}
}

@entry{artichoke,
  name={artichoke},
  description={a variety of thistle cultivated as food},
  identifier={vegetable}
}

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

@entry{spinach,
  name={spinach},
  description={green, leafy vegetable},
  identifier={vegetable}
}

@entry{marrow,
  name={marrow},
  description={long white-fleshed gourd with green skin},
  identifier={vegetable}
}

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

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

The minerals.bib file is distributed with bib2gls in the examples directory. These entries have a custom field called identifier which will be ignored by default, but may be aliased to a label field.

% Encoding: UTF-8

@entry{quartz,
  name={quartz},
  description={hard mineral consisting of silica},
  identifier={mineral}
}

@entry{corundum,
  name={corundum},
  description={crystalline form of aluminium oxide},
  identifier={mineral}
}

@entry{beryl,
  name={beryl},
  description={composed of beryllium aluminium cyclosilicate},
  identifier={mineral}
}

@entry{amethyst,
  name={amethyst},
  description={purple variety of \gls{quartz}},
  identifier={mineral}
}

@entry{chalcedony,
  name={chalcedony},
  description={cryptocrystalline variety of \gls{quartz}},
  identifier={mineral}
}

@entry{citrine,
  name={citrine},
  description={yellow variety of \gls{quartz}},
  identifier={mineral}
}

@entry{aquamarine,
  name={aquamarine},
  description={light blue variety of \gls{beryl}},
  identifier={mineral}
}

@entry{aragonite,
  name={aragonite},
  description={a crystal form of calcium carbonate},
  identifier={mineral}
}

@entry{calcite,
  name={calcite},
  description={a crystal form of calcium carbonate},
  identifier={mineral}
}

@entry{vaterite,
  name={vaterite},
  description={a crystal form of calcium carbonate},
  identifier={mineral}
}

@entry{bakerite,
  name={bakerite},
  description={a borosilicate mineral},
  identifier={mineral}
}

@entry{bilinite,
  name={bílinite},
  description={an iron sulfate mineral},
  identifier={mineral}
}

@entry{biotite,
  name={biotite},
  description={a common phyllosilicate mineral},
  identifier={mineral}
}

@entry{cobaltite,
  name={cobaltite},
  description={a sulfide mineral composed of cobalt, arsenic and 
  sulfur},
  identifier={mineral}
}

@entry{cyanotrichite,
  name={cyanotrichite},
  description={a hydrous copper aluminium sulfate mineral},
  identifier={mineral}
}

@index{lettsomite,
  alias={cyanotrichite},
  identifier={mineral}
}

@entry{diamond,
  name={diamond},
  description={a metastable allotrope of carbon},
  identifier={mineral}
}

@entry{dolomite,
  name={dolomite},
  description={an anhydrous carbonate mineral},
  identifier={mineral}
}

@entry{quetzalcoatlite,
  name={quetzalcoatlite},
  description={a rare tellurium oxysalt mineral},
  identifier={mineral}
}

@entry{vulcanite,
  name={vulcanite},
  description={a rare copper telluride mineral},
  identifier={mineral}
}


The animals.bib file is distributed with bib2gls in the examples directory. These entries have a custom field called identifier which will be ignored by default, but may be aliased to a label field.

% Encoding: UTF-8

@entry{duck,
  name={duck},
  description={a waterbird with webbed feet},
  identifier={animal}
}

@entry{parrot,
  name={parrot},
  description={mainly tropical bird with bright plumage},
  identifier={animal}
}

@entry{goose,
  name={goose},
  plural={geese},
  description={a large waterbird with a long neck, short legs,
   webbed feet and a short broad bill},
  identifier={animal}
}

@entry{swan,
  name={swan},
  description={a large waterbird with a long flexible neck, 
   short legs, webbed feet and a broad bill},
  identifier={animal}
}

@entry{chicken,
  name={chicken},
  description={a domestic fowl},
  identifier={animal}
}

@entry{aardvark,
  name={aardvark},
  description={nocturnal African burrowing mammal},
  identifier={animal}
}

@entry{zebra,
  name={zebra},
  description={wild African horse with black-and-white stripes},
  identifier={animal}
}

@entry{armadillo,
  name={armadillo},
  description={nocturnal insectivore with large claws},
  identifier={animal}
}

@entry{zander,
  name={zander},
  description={large freshwater perch},
  identifier={animal}
}

@entry{hedgehog,
  name={hedgehog},
  description={small nocturnal mammal with a spiny coat and 
   short legs},
  identifier={animal}
}

@entry{seal,
  name={seal},
  description={sea-dwelling fish-eating mammal with flippers},
  identifier={animal}
}

@entry{sealion,
  name={sea lion},
  description={a large type of \gls{seal}},
  identifier={animal}
}


The mathgreek.bib file is distributed with bib2gls in the examples directory. These entries have a custom field called identifier which will be ignored by default, but may be aliased to a label field. (\omicron is provided by glossaries-extra-bib2gls.sty, which should automatically be loaded by the record package option. If you get an undefined control sequence error, check you have the latest version of glossaries-extra.) Remember that with the default settings, if the sort field is missing then entries defined with @symbol will fallback on the symbol label.

Note that the command \varkappa requires the amssymb package.

% Encoding: UTF-8

@symbol{alpha,
  name={\ensuremath{\alpha}},
  description={alpha},
  identifier={mathgreek}
}

@symbol{beta,
  name={\ensuremath{\beta}},
  description={beta},
  identifier={mathgreek}
}

@symbol{gamma,
  name={\ensuremath{\gamma}},
  description={gamma},
  identifier={mathgreek}
}

@symbol{delta,
  name={\ensuremath{\delta}},
  description={delta},
  identifier={mathgreek}
}

@symbol{varepsilon,
  name={\ensuremath{\varepsilon}},
  description={epsilon (variant)},
  identifier={mathgreek}
}

@symbol{zeta,
  name={\ensuremath{\zeta}},
  description={zeta},
  identifier={mathgreek}
}

@symbol{eta,
  name={\ensuremath{\eta}},
  description={eta},
  identifier={mathgreek}
}

@symbol{theta,
  name={\ensuremath{\theta}},
  description={theta},
  identifier={mathgreek}
}


@symbol{iota,
  name={\ensuremath{\iota}},
  description={iota},
  identifier={mathgreek}
}

@symbol{kappa,
  name={\ensuremath{\kappa}},
  description={kappa},
  identifier={mathgreek}
}

@symbol{lambda,
  name={\ensuremath{\lambda}},
  description={lambda},
  identifier={mathgreek}
}

@symbol{mu,
  name={\ensuremath{\mu}},
  description={mu},
  identifier={mathgreek}
}

@symbol{nu,
  name={\ensuremath{\nu}},
  description={nu},
  identifier={mathgreek}
}

@symbol{xi,
  name={\ensuremath{\xi}},
  description={xi},
  identifier={mathgreek}
}

@symbol{omicron,
  name={\ensuremath{\omicron}},
  description={omicron},
  identifier={mathgreek}
}

@symbol{pi,
  name={\ensuremath{\pi}},
  description={pi},
  identifier={mathgreek}
}

@symbol{rho,
  name={\ensuremath{\rho}},
  description={rho},
  identifier={mathgreek}
}

@symbol{varsigma,
  name={\ensuremath{\varsigma}},
  description={sigma (variant)},
  identifier={mathgreek}
}

@symbol{sigma,
  name={\ensuremath{\sigma}},
  description={sigma},
  identifier={mathgreek}
}

@symbol{tau,
  name={\ensuremath{\tau}},
  description={tau},
  identifier={mathgreek}
}

@symbol{upsilon,
  name={\ensuremath{\upsilon}},
  description={upsilon},
  identifier={mathgreek}
}

@symbol{varphi,
  name={\ensuremath{\varphi}},
  description={phi (variant)},
  identifier={mathgreek}
}

@symbol{chi,
  name={\ensuremath{\chi}},
  description={chi},
  identifier={mathgreek}
}

@symbol{psi,
  name={\ensuremath{\psi}},
  description={psi},
  identifier={mathgreek}
}

@symbol{omega,
  name={\ensuremath{\omega}},
  description={omega},
  identifier={mathgreek}
}

@symbol{epsilon,
  name={\ensuremath{\epsilon}},
  description={epsilon},
  identifier={mathgreek}
}

@symbol{vartheta,
  name={\ensuremath{\vartheta}},
  description={theta (variant)},
  identifier={mathgreek}
}

@symbol{varkappa,
  name={\ensuremath{\varkappa}},
  description={kappa (variant)},
  identifier={mathgreek}
}

@symbol{phi,
  name={\ensuremath{\phi}},
  description={phi},
  identifier={mathgreek}
}

@symbol{varrho,
  name={\ensuremath{\varrho}},
  description={rho (variant)},
  identifier={mathgreek}
}

@symbol{varpi,
  name={\ensuremath{\varpi}},
  description={pi (variant)},
  identifier={mathgreek}
}


The latinsymbols.bib file contains Latin mathematical symbols. Again there's a custom field identifier which will be ignored by default, but may be aliased to a label field.

% Encoding: UTF-8

@symbol{y,
 name={\ensuremath{y}},
 description={second unknown variable or vertical co-ordinate},
 identifier={latinsymbol}
}

@symbol{x,
 name={\ensuremath{x}},
 description={first unknown variable or horizontal co-ordinate},
 identifier={latinsymbol}
}

@symbol{z,
 name={\ensuremath{z}},
 description={third unknown variable or co-ordinate},
 identifier={latinsymbol}
}

@symbol{t,
 name={\ensuremath{t}},
 description={time variable or parameter},
 identifier={latinsymbol}
}

@symbol{L,
 name={\ensuremath{L}},
 description={Lagrangian function},
 identifier={latinsymbol}
}

@symbol{f,
 name={\ensuremath{f}},
 description={function},
 identifier={latinsymbol}
}


The pictographs.bib file contains pictographs (icons). Again there's a custom field identifier which will be ignored by default, but may be aliased to a label field.

% Encoding: UTF-8

@symbol{heartsuit,
 name={\ensuremath{\heartsuit}},
 description={heart},
 identifier={pictograph}
}

@symbol{spadesuit,
 name={\ensuremath{\spadesuit}},
 description={spade},
 identifier={pictograph}
}

@symbol{diamondsuit,
 name={\ensuremath{\diamondsuit}},
 description={diamond},
 identifier={pictograph}
}

@symbol{clubsuit,
 name={\ensuremath{\clubsuit}},
 description={club},
 identifier={pictograph}
}


The abbreviations.bib file contains abbreviations. There's a mixture of @abbreviation and @acronym. Again there's a custom field identifier which will be ignored by default, but may be aliased to a label field. Remember that with the default settings, if the sort field is missing then entries defined with @abbreviation or acronym will fallback on the short field.

% Encoding: UTF-8

@preamble{"\providecommand{\abbrvtag}[1]{#1}"}
@string{markuplang="\abbrvtag{m}arkup \abbrvtag{l}anguage"}

@abbreviation{xml,
  short={XML},
  long={e\abbrvtag{x}tensible }#markuplang,
  description={a markup language that defines a set of rules for
    encoding documents},
  identifier={markuplanguage}
}

@abbreviation{html,
  short={HTML},
  long={\abbrvtag{h}yper\abbrvtag{t}ext }#markuplang,
  description={the standard markup language for creating web pages},
  identifier={markuplanguage}
}

@abbreviation{mathml,
  short={MathML},
  long={\abbrvtag{m\NoCaseChange{ath}}ematical }#markuplang,
  description={markup language for describing mathematical notation},
  identifier={markuplanguage}
}

@abbreviation{xhtml,
  short={XHTML},
  long={e\abbrvtag{x}tensible \abbrvtag{h}yper\abbrvtag{t}ext }
    # markuplang,
  description={{}\glsxtrshort{xml} version of \glsxtrshort{html}},
  identifier={markuplanguage}
}

@abbreviation{svg,
  short={SVG},
  long={\abbrvtag{s}calable \abbrvtag{v}ector \abbrvtag{g}raphics},
  description={{}\glsxtrshort{xml}-based vector image format},
  identifier={markuplanguage}
}

@acronym{nasa,
  short={NASA},
  long = {National Aeronautics and Space Administration},
  identifier={agency}
}

@acronym{ofcom,
  short={Ofcom},
  long = {Office of Communications},
  identifier={agency}
}

@acronym{ofsted,
  short={Ofsted},
  long = {Office for Standards in Education},
  identifier={agency}
}


The Sort Value

Remember that by default, provided the sort field hasn't been set, terms defined with @entry, @index or @indexplural will have the sort value taken from the name field, terms defined with @symbol will have the sort value taken from the label, and terms defined with @abbreviation or @acronym will have the sort value taken from the short field.

If @index doesn't have the name field set, then the value is obtained from the label.

If @indexplural doesn't have the name field set, then the value is obtained from the plural field. If the plural field isn't set, the value is obtained from the text field with the letter ‘s’ appended. If the text field is missing then it's assumed to be the same as the label.

Spacing

The vertical space before and after a topic title depends on various settings. By default the glossary title is displayed using \chapter*, if it's defined, or \section*, so the spacing will be governed by these commands (which is usually determined by the document class, but may also be adjusted by packages). There may also be additional spacing after the title that's introduced by the glossary style. (For example, if the style uses a list environment.)

The spacing before and after a group title and between hierarchical entries is determined by the glossary style. There are many predefined styles and they provide means to adjust various settings. There's greater flexibility if you use the glossaries-extra-stylemods package. This can easily be done with the stylemods package option.

This page is primarily concerned with the various ways of dividing your list of terms into logical blocks rather than fine-tuning the document style parameters.

Example Document: No Divisions

This first example simply selects all entries and sorts them into a single block and displays them with the index style. (The comment lines below are arara directives. You can remove them if you don't use arara.)

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

\usepackage{amssymb}
\usepackage[record,stylemods={tree}]{glossaries-extra}

\setabbreviationstyle{short-long-desc}
\setabbreviationstyle[acronym]{short-long}

\GlsXtrLoadResources[
  src={topics,symboltopics,vegetables,minerals,animals,
       mathgreek,latinsymbols,pictographs,
       abbreviations},
  selection={all},
  save-locations=false,
  sort={en}
]

\begin{document}
\printunsrtglossary[style=index]
\end{document}

If you don't use arara, the document build is:

pdflatex logicaldivisions-none
bib2gls logicaldivisions-none
pdflatex logicaldivisions-none

Note that the --group switch isn't used.

Image of example document

There are no divisions in this list. The symbols are positioned according to their labels.

Download document source.

Example Document: Letter Groups

Two simple modifications to the above example will split the list into letter groups:

  1. Change the style to one that supports groups, for example the indexgroup style.
  2. Run bib2gls with the --group switch.
% arara: pdflatex
% arara: bib2gls: {group: on}
% arara: pdflatex
\documentclass{article}

\usepackage{amssymb}
\usepackage[record,stylemods={tree}]{glossaries-extra}

\setabbreviationstyle{short-long-desc}
\setabbreviationstyle[acronym]{short-long}

\GlsXtrLoadResources[
  src={topics,symboltopics,vegetables,minerals,animals,
       mathgreek,latinsymbols,pictographs,
       abbreviations},
  selection={all},
  save-locations=false,
  sort={en}
]

\begin{document}
\printunsrtglossary[style=indexgroup]
\end{document}

If you don't use arara, the document build is:

pdflatex logicaldivisions-letter
bib2gls --group logicaldivisions-letter
pdflatex logicaldivisions-letter

The list has now been split up into alphabetical groups.

Image of example document

Download document source.

Example Document: Multiple Glossaries

This example uses the nomain package option to prevent the default main glossary from being created. The custom glossaries are then defined with \newglossary* in the desired order. The index style is set as a package option, so all glossaries can simply be displayed with \printunsrtglossaries. In this case, however, I've decided to use \printunsrtglossary for each glossary so that I can use different styles.

The resource option type={same as base} is used to assign the type field to the base name of the .bib file. For example, entries defined in mathgreek.bib will have the type field set to mathgreek.

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

\usepackage{amssymb}
\usepackage[record,nomain,stylemods={tree,mcols},style=index]{glossaries-extra}

\newglossary*{pictographs}{Pictographs}
\newglossary*{latinsymbols}{Latin Symbols}
\newglossary*{mathgreek}{Greek Symbols}
\newglossary*{abbreviations}{Abbreviations}

\setabbreviationstyle{short-long-desc}
\setabbreviationstyle[acronym]{short-long}

\GlsXtrLoadResources[
  src={mathgreek,latinsymbols,pictographs,
       abbreviations},
  type={same as base},
  selection={all},
  save-locations=false,
  sort={en}
]

\begin{document}
\printunsrtglossary[type=pictographs]
\printunsrtglossary[type=latinsymbols]
\printunsrtglossary[type=mathgreek,style=mcolindex]
\printunsrtglossary[type=abbreviations]
\end{document}

If you don't use arara, the document build is:

pdflatex logicaldivisions-types
bib2gls --group logicaldivisions-types
pdflatex logicaldivisions-types

The list has now been split up into separate glossaries. Note that the glossaries aren't ordered by the glossary title.

Image of example document

Download document source.

Example Document: Custom Group Blocks

This example is a modification of the previous one that has a single glossary that's split up into custom groups through the use of multiple resource commands. Note that the nomain option has been removed and the style has been set to indexgroup. (As from bib2gls version 1.9, the --group switch isn't required when overriding the default group=auto setting.)

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

\usepackage{amssymb}
\usepackage[record,stylemods={tree},style=indexgroup]{glossaries-extra}

\glsxtrsetgrouptitle{pictographs}{Pictographs}
\glsxtrsetgrouptitle{latinsymbols}{Latin Symbols}
\glsxtrsetgrouptitle{mathgreek}{Greek Symbols}
\glsxtrsetgrouptitle{abbreviations}{Abbreviations}

\setabbreviationstyle{short-long-desc}
\setabbreviationstyle[acronym]{short-long}

\GlsXtrLoadResources[
  src={pictographs},
  group={pictographs},
  selection={all},
  save-locations=false,
  sort={en}
]

\GlsXtrLoadResources[
  src={latinsymbols},
  group={latinsymbols},
  selection={all},
  save-locations=false,
  sort={en}
]

\GlsXtrLoadResources[
  src={mathgreek},
  group={mathgreek},
  selection={all},
  save-locations=false,
  sort={en}
]

\GlsXtrLoadResources[
  src={abbreviations},
  group={abbreviations},
  selection={all},
  save-locations=false,
  sort={en}
]

\begin{document}
\printunsrtglossary
\end{document}

Note that the groups are in the same order as the corresponding resource commands.

Image of example document

Download document source.

An alternative is to alias the identifier fields to group. These have different labels, so the labels used in the \glsxtrsetgrouptitle need adjusting. Note also that the abbreviations.bib file needs to have the markuplanguage entries separated from the agency entries.

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

\usepackage{amssymb}
\usepackage[record,stylemods={tree},style=indexgroup]{glossaries-extra}

\glsxtrsetgrouptitle{pictograph}{Pictographs}
\glsxtrsetgrouptitle{latinsymbol}{Latin Symbols}
\glsxtrsetgrouptitle{mathgreek}{Greek Symbols}
\glsxtrsetgrouptitle{markuplanguage}{Markup Languages}
\glsxtrsetgrouptitle{agency}{Agencies}

\setabbreviationstyle{short-long-desc}
\setabbreviationstyle[acronym]{short-long}

\GlsXtrLoadResources[
  src={pictographs},
  field-aliases={identifier=group},
  selection={all},
  save-locations=false,
  sort={en}
]

\GlsXtrLoadResources[
  src={latinsymbols},
  field-aliases={identifier=group},
  selection={all},
  save-locations=false,
  sort={en}
]

\GlsXtrLoadResources[
  src={mathgreek},
  field-aliases={identifier=group},
  selection={all},
  save-locations=false,
  sort={en}
]

\GlsXtrLoadResources[
  src={abbreviations},
  field-aliases={identifier=group},
  selection={all},
  match={group=markuplanguage},
  save-locations=false,
  sort={en}
]

\GlsXtrLoadResources[
  src={abbreviations},
  field-aliases={identifier=group},
  selection={all},
  match={group=agency},
  save-locations=false,
  sort={en}
]

\begin{document}
\printunsrtglossary
\end{document}

The first page is the same as above. The second page, which contains the abbreviations, is different.

Image of example document

You might be wondering if you can modify the above document so that it only uses one resource command. For example:

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

\usepackage{amssymb}
\usepackage[record,stylemods={tree},style=indexgroup]{glossaries-extra}

\glsxtrsetgrouptitle{pictograph}{Pictographs}
\glsxtrsetgrouptitle{latinsymbol}{Latin Symbols}
\glsxtrsetgrouptitle{mathgreek}{Greek Symbols}
\glsxtrsetgrouptitle{markuplanguage}{Markup Languages}
\glsxtrsetgrouptitle{agency}{Agencies}

\setabbreviationstyle{short-long-desc}
\setabbreviationstyle[acronym]{short-long}

\GlsXtrLoadResources[
  src={pictographs,latinsymbols,mathgreek,abbreviations},
  field-aliases={identifier=group},
  selection={all},
  save-locations=false,
  sort={en}
]

\begin{document}
\printunsrtglossary
\end{document}

This doesn't work because the sort method doesn't order by group. It's designed to assign the groups as a by-product (if --group is used). But this action is overridden if the group field is already set (or the action is prevented if --group isn't used). This results in fragmented groups:

Image of example document

If you try modifying the above document so that it sorts by the group field, you will have unexpected results. Firstly, you now have multiple entries with the same sort value (all entries with the same group label), so you would need to set an identical sort fallback value (which performs a simple character code comparison of the identified field) or set a sort suffix. Secondly, if you sort by the group field, then you are sorting by the label not by the group title (which is supplied in the document).

For example, consider the following document:

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

\usepackage{amssymb}
\usepackage[record,stylemods={tree},style=indexgroup]{glossaries-extra}

\glsxtrsetgrouptitle{pictograph}{Pictographs}
\glsxtrsetgrouptitle{latinsymbol}{Latin Symbols}
\glsxtrsetgrouptitle{mathgreek}{Greek Symbols}
\glsxtrsetgrouptitle{markuplanguage}{Markup Languages}
\glsxtrsetgrouptitle{agency}{Agencies}

\setabbreviationstyle{short-long-desc}
\setabbreviationstyle[acronym]{short-long}

\GlsXtrLoadResources[
  src={pictographs,latinsymbols,mathgreek,abbreviations},
  field-aliases={identifier=group},
  selection={all},
  save-locations=false,
  sort={en},
  sort-field=group,
  sort-suffix=name
]

\begin{document}
\printunsrtglossary
\end{document}

This produces:

Image of example document

There are two major problems with this:

So you don't actually get alphabetical ordering of the group titles and you don't have the flexibility of choosing different sort fields for different types of entries. This can be quite problematic for symbols that can't be interpreted or that are interpreted into Unicode characters that are discarded by the collation rule or by the break-at setting.

If you find yourself wanting to sort by the title of each block, then you most likely have a hierarchical glossary, in which you need to use the parent field not the group field, as in the next example.

Example Document: Hierarchical

This example has a single hierarchical glossary where the top-level entries represent topics. It has a single glossary that uses the topic style. The custom identifier field is aliased to parent.

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

\usepackage{amssymb}
\usepackage[record,stylemods={topic},style=topic]{glossaries-extra}

\setabbreviationstyle{short-long-desc}
\setabbreviationstyle[acronym]{short-long}

\GlsXtrLoadResources[
  src={topics,symboltopics,pictographs,latinsymbols,mathgreek,
       abbreviations,animals,minerals,vegetables},
  field-aliases={identifier=parent},
  selection={all},
  save-locations=false,
  sort={en}
]

\begin{document}
\printunsrtglossary
\end{document}

Note that the topic titles are now in alphabetical order. The symbols are sorted according to the label not the name value.

Image of example document

Download document source.

There are two top-level entries without children: abbreviations and symbols. If the selection=all option is removed then only entries that have been referenced in the document (and their ancestors and dependencies) will be included.

A minor modification can be made to the above document that also aliases the custom topicdescription and topic fields:

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

\usepackage{amssymb}
\usepackage[record,stylemods={topic},style=topic]{glossaries-extra}

\setabbreviationstyle{short-long-desc}
\setabbreviationstyle[acronym]{short-long}

\GlsXtrLoadResources[
  src={topics,symboltopics,pictographs,latinsymbols,mathgreek,
       abbreviations,animals,minerals,vegetables},
  field-aliases={identifier=parent,
   topic=parent,
   topicdescription=description},
  selection={all},
  save-locations=false,
  sort={en}
]

\begin{document}
\printunsrtglossary
\end{document}

This changes the ordering of the ‘Greek symbols’, ‘Latin symbols’ and ‘Pictographs’, which are now all sub-entries of the ‘Symbols’ topic.

Image of example document

The glossary is quite untidy. Some of the topics would look better with the descriptions aligned, but changing the style to implement this would end up with a very narrow space for the description to accommodate the wide names for the markup language abbreviations (which include the long form in the name). In this circumstance it's much better to use multiple glossaries.

Example Document: Mixture

This example uses a mixture of type, group and parent. In this case the document indexes entries (with \gls), so only those entries and their dependencies will be selected from the .bib files. The location numbers are present, but for this trivial document the location lists mostly contain just page~1 (although there are some entries indexed in the glossary within the description of other entries so they have additional locations).

I've used different styles and locally modified \glstreenamefmt for just the first glossary for demonstration purposes. A real document would most likely need additional adjustments appropriate to the content.

I've also used the hyperref package and redefined \glstopicMarker to make the topicmcols style create a PDF bookmark for each top-level entry (topic).

The section package option makes the glossary titles use \section (rather than \chapter). The starred form is the default, but the toc package option (which glossaries-extra automatically sets) ensures that the title is added to the table of contents. This means that the glossary titles appear in the PDF bookmarks at bookmark level~1, so level~2 is used in the bookmark command.

If you have at least version 1.41 of glossaries-extra-stylemods, it's also possible to insert a bookmark for each group heading for the tree-group styles (such as alttreegroup) by redefining \glstreePreHeader.

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

\usepackage{amssymb}
\usepackage[colorlinks]{hyperref}
\usepackage[record,section,symbols,nostyles,stylemods={list,tree,topic}]{glossaries-extra}

\renewcommand{\glstopicMarker}[1]{%
 \pdfbookmark[2]{\glsentryname{#1}}{\currentglossary.#1}%
}

\renewcommand{\glstreePreHeader}[2]{%
 \pdfbookmark[2]{#2}{\currentglossary.#1}%
}

\newglossary*{agency}{Agencies}
\newglossary*{markuplanguage}{Markup Languages}

\setabbreviationstyle{short-long-desc}
\setabbreviationstyle[acronym]{short-long}

\GlsXtrLoadResources[
  src={abbreviations},
  field-aliases={identifier=type}
]

\GlsXtrLoadResources[
  src={symboltopics,pictographs,latinsymbols,mathgreek},
  type=symbols,
  field-aliases={identifier=parent},
  set-widest
]

\glsxtrsetgrouptitle{minerals}{Minerals}
\glsxtrsetgrouptitle{animals}{Animals}
\glsxtrsetgrouptitle{vegetables}{Vegetables}

\GlsXtrLoadResources[
  src={animals},
  type=main,
  group=animals,
  set-widest
]

\GlsXtrLoadResources[
  src={vegetables},
  type=main,
  group=vegetables,
  set-widest
]

\GlsXtrLoadResources[
  src={minerals},
  type=main,
  group=minerals,
  set-widest
]


\begin{document}
\chapter{Sample}

\gls{ofcom}, \gls{nasa}, \gls{ofsted}.

\gls{hedgehog}, \gls{parrot}, \gls{goose}, \gls{sealion},
\gls{zander}, \gls{zebra}, \gls{armadillo}, \gls{duck},
\gls{seal}, \gls{chicken}, \gls{aardvark}, \gls{swan}.

\gls{gamma}, \gls{varepsilon}, \gls{iota}, \gls{eta},
\gls{omicron}, \gls{varphi}, \gls{rho}, \gls{varsigma},
\gls{mu}, \gls{nu}, \gls{omega}, \gls{delta}, \gls{phi},
\gls{varpi}, \gls{alpha}, \gls{beta}, \gls{chi}, \gls{epsilon},
\gls{pi}, \gls{kappa}, \gls{zeta}, \gls{rho}, \gls{sigma}, \gls{tau}, 
\gls{theta}, \gls{upsilon}, \gls{varkappa},
\gls{psi}, \gls{vartheta}, \gls{xi}, \gls{lambda}.

\gls{t}, \gls{z}, \gls{L}, \gls{x}, \gls{f}, \gls{y}.

\gls{svg}, \gls{xml}, \gls{mathml}, \gls{html}, \gls{xhtml}.

\gls{diamondsuit}, \gls{clubsuit}, \gls{spadesuit}, \gls{heartsuit}.

\gls{quartz}, \gls{bilinite}, \gls{aquamarine}, \gls{calcite},
\gls{amethyst}, \gls{cobaltite}, \gls{aragonite}, \gls{bakerite},
\gls{vaterite}, \gls{cyanotrichite}, \gls{beryl}, \gls{dolomite},
\gls{lettsomite}, \gls{biotite}, \gls{quetzalcoatlite},
\gls{chalcedony}, \gls{corundum}, \gls{vulcanite}, 
\gls{citrine}, \gls{diamond}.

\gls{brussels-sprout}, \gls{cauliflower}, \gls{spinach},
\gls{artichoke}, \gls{courgette}, \gls{marrow}, \gls{zucchini},
\gls{cabbage}.

\chapter{Terminology}

\printunsrtglossary*[style=alttreegroup,title={Systema Natur\ae}]
{%
  \renewcommand*{\glstreenamefmt}[1]{\emph{#1}}%
}

\printunsrtglossary[type=agency,style=tree]
\printunsrtglossary[type=symbols,style=topicmcols]
\printunsrtglossary[type=markuplanguage,style=altlist]

\end{document}

The document build has an extra LaTeX call in the build process to ensure that the bookmarks are up-to-date:

pdflatex logicaldivisions-mixture
bib2gls logicaldivisions-mixture
pdflatex logicaldivisions-mixture
pdflatex logicaldivisions-mixture

The PDF bookmarks are shown on the left in the image below. Note that the main glossary was divided into groups through the use of three resource commands. The entries within each group are alphabetically ordered but the group titles aren't.

Image of example document

Download document source.

If you want to use the --group switch to automatically form letter groups for a particular glossary then use a group style for that glossary with nogroupskip off and a non-group style with nogroupskip on for the other styles. In the example below, only the main glossary has letter groups so, rather than using nogroupskip in the optional argument of each of the other glossaries, I've set it as a package option and overrode it for just the main glossary.

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

\usepackage{amssymb}
\usepackage[colorlinks]{hyperref}
\usepackage[record,section,symbols,nogroupskip,nostyles,stylemods={list,tree,topic}]{glossaries-extra}

\renewcommand{\glstopicMarker}[1]{%
 \pdfbookmark[2]{\glsentryname{#1}}{\currentglossary.#1}%
}

\renewcommand{\glstreePreHeader}[2]{%
 \pdfbookmark[2]{#2}{\currentglossary.#1}%
}

\newglossary*{agency}{Agencies}
\newglossary*{markuplanguage}{Markup Languages}

\setabbreviationstyle{short-long-desc}
\setabbreviationstyle[acronym]{short-long}

\GlsXtrLoadResources[
  src={abbreviations},
  field-aliases={identifier=type}
]

\GlsXtrLoadResources[
  src={symboltopics,pictographs,latinsymbols,mathgreek},
  type=symbols,
  field-aliases={identifier=parent},
  set-widest
]

\GlsXtrLoadResources[
  src={animals,minerals,vegetables},
  type=main,
  set-widest
]

\begin{document}
\chapter{Sample}

\gls{ofcom}, \gls{nasa}, \gls{ofsted}.

\gls{hedgehog}, \gls{parrot}, \gls{goose}, \gls{sealion},
\gls{zander}, \gls{zebra}, \gls{armadillo}, \gls{duck},
\gls{seal}, \gls{chicken}, \gls{aardvark}, \gls{swan}.

\gls{gamma}, \gls{varepsilon}, \gls{iota}, \gls{eta},
\gls{omicron}, \gls{varphi}, \gls{rho}, \gls{varsigma},
\gls{mu}, \gls{nu}, \gls{omega}, \gls{delta}, \gls{phi},
\gls{varpi}, \gls{alpha}, \gls{beta}, \gls{chi}, \gls{epsilon},
\gls{pi}, \gls{kappa}, \gls{zeta}, \gls{rho}, \gls{sigma}, \gls{tau}, 
\gls{theta}, \gls{upsilon}, \gls{varkappa},
\gls{psi}, \gls{vartheta}, \gls{xi}, \gls{lambda}.

\gls{t}, \gls{z}, \gls{L}, \gls{x}, \gls{f}, \gls{y}.

\gls{svg}, \gls{xml}, \gls{mathml}, \gls{html}, \gls{xhtml}.

\gls{diamondsuit}, \gls{clubsuit}, \gls{spadesuit}, \gls{heartsuit}.

\gls{quartz}, \gls{bilinite}, \gls{aquamarine}, \gls{calcite},
\gls{amethyst}, \gls{cobaltite}, \gls{aragonite}, \gls{bakerite},
\gls{vaterite}, \gls{cyanotrichite}, \gls{beryl}, \gls{dolomite},
\gls{lettsomite}, \gls{biotite}, \gls{quetzalcoatlite},
\gls{chalcedony}, \gls{corundum}, \gls{vulcanite}, 
\gls{citrine}, \gls{diamond}.

\gls{brussels-sprout}, \gls{cauliflower}, \gls{spinach},
\gls{artichoke}, \gls{courgette}, \gls{marrow}, \gls{zucchini},
\gls{cabbage}.

\chapter{Terminology}

\printunsrtglossary*[style=alttreegroup,title={Systema Natur\ae},
 nogroupskip=false]
{%
  \renewcommand*{\glstreenamefmt}[1]{\emph{#1}}%
}

\printunsrtglossary[type=agency,style=tree]
\printunsrtglossary[type=symbols,style=topicmcols]
\printunsrtglossary[type=markuplanguage,style=altlist]

\end{document}

The document build is now:

pdflatex logicaldivisions-mixture2
bib2gls --group logicaldivisions-mixture2
pdflatex logicaldivisions-mixture2
pdflatex logicaldivisions-mixture2

Image of example document

Download document source.

© 2019 Dickimaw Books. "Dickimaw", "Dickimaw Books" and the Dickimaw parrot logo are trademarks. The Dickimaw parrot was painted by Magdalene Pritchett.

Terms of Use Privacy Policy Cookies Site Map FAQs