Latest news 2024-10-15: New blog post: Tales for Our Times Book Launch.

bib2gls application FAQ

An indexing application (written in Java) designed for use with the glossaries-extra package. Related resources: gallery, home page and GitHub repository. Example documents can be found in the gallery.

See also the glossaries package and the glossaries-extra package.

General Queries

What version of Java is required? 🔗

At least Java 8. Earlier versions don’t have the required sort method for lists.

2020-06-29 12:41:39

Top

What file encoding does bib2gls use? 🔗

Input Encoding:
The encoding of the .bib file should be set using the encoding comment within the .bib file. For example: 
% Encoding: UTF-8

This is best placed at the start of the file where it can easily be found. You can also use the charset resource option but it makes more sense to have the encoding identified within the .bib file. (charset takes precedence.)

If the .bib file doesn’t contain an encoding comment and charset isn’t used then the default file encoding for the Java Runtime Environment is assumed (see below).

Output Encoding:
The encoding of the .glstex file (which is input by \GlsXtrLoadResources) may be identified in the .aux file by \glsxtr@texencoding{encoding}. The glossaries-extra package writes this information when it encounters the first instance of \GlsXtrLoadResources. It obtains encoding from \inputencodingname if it has been defined. If that command hasn’t been set but fontspec has been loaded then it will assume that the encoding is utf8. If neither \inputencodingname has been defined nor fontspec has been loaded then the information is omitted from the .aux file.

bib2gls has a set of mappings from the encoding labels used in \glsxtr@texencoding (such as utf8) and Java’s recognised encoding names (such as UTF-8). However there are some inputenc labels that aren’t recognised.

If the encoding information is missing from the .aux file or if the encoding label is unrecognised then bib2gls will use the default file encoding for the Java Runtime Environment (see below). If this is incorrect, then you can use the --tex-encoding command line switch to specify the encoding. Alternatively, you may want to consider changing Java’s default file encoding.

The Java default file encoding is determined by the file.encoding property. This usually matches the operating system’s default file encoding, but it can be changed with the Java option -Dfile.encoding=Encoding. (The syntax is -Dproperty-name=property-value.) This may be set in the JAVA_TOOLS_OPTIONS environment variable if you want this default for all your installed Java applications. The value of this environment variable is a space-separated list of Java options (switches that can be used when invoking the java command line application).

How you set or modify environment variables depends on your operating system. (See How do I set or change the PATH system variable? and substitute PATH for JAVA_TOOLS_OPTIONS.) For example, with Bash: 

JAVA_TOOLS_OPTIONS=$JAVA_TOOLS_OPTIONS -Dfile.encoding=UTF-8
export JAVA_TOOLS_OPTIONS

Alternatively: 

declare -x JAVA_TOOLS_OPTIONS=$JAVA_TOOLS_OPTIONS -Dfile.encoding=UTF-8

Note that the bib2gls Bash script invokes the application as follows: 

if [ -z "$JAVA_TOOL_OPTIONS" ]; then
  exec java -Djava.locale.providers=CLDR,JRE,SPI -jar "$jarpath" "$@"
else
  exec java -jar "$jarpath" "$@"
fi

This means that with Unix-like systems, if you define JAVA_TOOLS_OPTIONS you may also need to add the java.locale.providers property for Java 8 to ensure the CLDR is listed first (otherwise with Java 8 the JRE provider will take precedence). Windows users with Java 8 may want to set this property in JAVA_TOOLS_OPTIONS regardless of whether or not they need to change the default file encoding.

If you have a problem with any non-ASCII characters not appearing correctly in your document:

2020-07-02 11:15:56

Top

Sorting

How do I sort by group? 🔗

You don’t (usually). The group field is an internal field that’s designed to be set by bib2gls. When you invoke bib2gls with the --group switch, most of the sort methods will assign the group field as a by-product of sorting.

It is possible to assign a custom value to the group field, but if you do this you must ensure that the entries are ordered in such a way that the groups aren’t broken up. This is typically done by separating the glossary into logical blocks through the use of multiple instances of \GlsXtrLoadResources with the group option set.

Technically it is possible to change the field used for sorting to group but the value of the group field must always be a label. The corresponding title is set in the document where it’s not visible to bib2gls. This means that at most you can only sort by the label not by the title.

If you find yourself wanting to order by group then that’s a strong indication that you have a hierarchical glossary and you should be using the parent field instead. You just need to find an appropriate glossary style.

Compare, for example, sample-textsymbols.tex and sample-textsymbols2.tex, both of which use miscsymbols.bib. The first case sorts by the group label and sets the sort suffix to the description field. The second case uses a hierarchical approach that sorts the topic (top-level @index and @indexplural entries) by name and sorts the symbols by their description. The second method is the simpler and better approach that will work with non-English languages.

See also Logical Glossary Divisions (type vs group vs parent).

2020-06-29 12:31:39

Top

Why doesn’t symbol-sort-fallback work? 🔗

The symbol-sort-fallback option identifies the fallback field to use if the sort field is missing for entries defined with @symbol (or related symbol types, such as @number). If the sort field is set then the fallback value isn’t needed. Similarly, if the sort field is never needed (for example, the field used for sorting is changed with sort-field) then the fallback value for the sort field will never be needed.

So if the symbol-sort-fallback option doesn’t seem to be working check that you haven’t set the sort field in the .bib file and check that you haven’t switched to a different field for sorting and check the entry type is @symbol (or @number etc).

Remember also that custom-sort-fallbacks can override symbol-sort-fallback, so check if that has been set.

For example, if the entry is defined as: 

@symbol{fx,
  name={\ensuremath{f(x)}},
  description={a function of $x$},
  sort={fx}
}

In this case the sort field isn’t missing, so symbol-sort-fallback won’t apply to this entry. The explicit use of the sort field in the .bib file forces the sort field to fx regardless of the symbol-sort-fallback setting. (Remember that this can also happen if you alias or copy a field to sort.)

Suppose now the entry is defined as: 

@symbol{fx,
  name={\ensuremath{f(x)}},
  description={a function of $x$}
}

And the document has: 

\GlsXtrLoadResources[src={entries},
 sort-field=description,
 symbol-sort-fallback=name
]

Here the symbol-sort-fallback is redundant as the sort field isn’t queried (because the description field is now being used for the sort value).

Suppose now the entry is defined as: 

@entry{fx,
  name={\ensuremath{f(x)}},
  description={a function of $x$}
}

And the document has: 

\GlsXtrLoadResources[src={entries},
 symbol-sort-fallback=description
]

The symbol-sort-fallback setting won’t be applied to the fx entry because it’s been defined with @entry not @symbol (so it’s governed by the entry-sort-fallback setting).

In general, it’s best not to use the sort field in the .bib and it’s more flexible to keep the default sort-field setting. See Gallery (bib2gls): Sorting.

2020-07-01 16:56:39

Top

Is it possible to apply different sort methods hierarchically? 🔗

No, it’s not possible to apply a different sort method to different hierarchical levels in the same glossary within the same resource set. Although it’s possible to sort blocks differently through the use of multiple resource commands (as demonstrated in Custom Group Blocks) it’s not possible to divide the hierarchy across multiple resource sets as that would separate the child entries from their parents.

However it is possible to create the effect of a hierarchical glossary with differently sorted levels through the use of inner nested glossaries. See the Inner or Nested Glossaries page in the gallery or the sample-nested.tex sample document described in the “Examples” chapter of the bib2gls user manual (PDF).

2020-03-26 15:52:53

Top

Automated Adjustments

Is it possible to automatically move a lonely entry up a hierarchical level? 🔗

Yes, it is. You can use the flatten-lonely option. For example, suppose you have a file called entries.bib that contains: 

@index{animal}
@index{mineral}
@index{vegetable}

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

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

@entry{abelsonite,
  name={abelsonite},
  description={a nickel porphyrin mineral},
  parent={mineral}
}

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

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

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

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

The document below only references some of these entries and as a result there are some sub-entries with no siblings: 

\documentclass{report}

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

\GlsXtrLoadResources[src={entries}]

\begin{document}
Test: \gls{abelsonite}, \gls{cabbage}, \gls{cauliflower}, \gls{animal}
and \gls{duck}.

\printunsrtglossary
\end{document}

The glossary has the following structure:

There are two sub-entries with no siblings: “duck” (where its parent has also been indexed) and “abelsonite” (where its parent hasn’t been indexed). If the resource option flatten-lonely=presort is used, the “abelsonite” entry will be moved up a hierarchical level and its parent will be removed. The “duck” entry won’t be modified as its parent has been indexed. The result now has the hierarchy:

Compare this with flatten-lonely=postsort where the resulting hierarchy is:

If you want the “duck” entry to also be adjusted, then it’s necessary to change the flatten-lonely-rule option but note that the parent entry can’t be removed as it’s been indexed in the document. For example, with: 

\GlsXtrLoadResources[src={entries},
 flatten-lonely=presort,
 flatten-lonely-rule={discard unrecorded}
]

Then the resulting hierarchy is:

2020-06-29 12:27:31

Top

Warnings and Errors

What does the warning “Found internal non bib-field” mean? 🔗

The full warning is:

Warning: Found internal non bib-field 'field' in '.bib' file for entry 'label'. Unexpected results may occur.

There are some keys, such as group and location, that are defined by the glossaries-extra package for use when manually creating your glossaries (with \printunsrtglossaries and without any external tool). However, bib2gls considers these fields as internal fields where the values are assigned according to the resource options or command line switches. If you set them manually, you will override bib2gls's normal behaviour, which can cause unexpected results. Since this takes some users by surprise, as from version 1.9, bib2gls warns if these fields are found in the .bib file.

If you get this warning, check the field in the tables in section 4.3 ("Fields") of the bib2gls manual. If you are absolutely sure you know what you are doing then you can disable this warning.

If you’re trying to use the group field, see Logical Divisions (type vs group vs parent).

2020-06-29 12:38:10

Top

Error: ConcurrentModificationException 🔗

If a ConcurrentModificationException error is reported, it probably means that you have a recursive reference, such as an alias field that references its own entry label.

A check for self-referencing aliases will be added to bib2gls v3.6.

2023-09-02 13:05:24

Top

Indexing (Recording)

indexonlyfirst attribute doesn’t work 🔗

Consider the following example: 

\documentclass{report}
\usepackage[record]{glossaries-extra}
\GlsXtrLoadResources[src=example-glossaries-acronym,category=abbreviation]
\glssetcategoryattribute{abbreviation}{indexonlyfirst}{true}
\begin{document}
\chapter{Sample}
\gls{lid}
\chapter{Another Sample}
\gls{lid}
\printunsrtglossary
\end{document}
The usual document build sequence LaTeX+bib2gls+LaTeX results in two locations in the location list for the “lid” dummy entry. The indexonlyfirst attribute should only index (record) the first use.

The problem here is that the entry isn’t defined on the first LaTeX run. This means that \gls is unable to determine the category for the entry (since it doesn’t exist yet, from LaTeX’s point of view). So \gls is unable to pick up the attribute. This means that an extra bib2gls call is needed.

Here’s the sequence starting from a clean directory (no aux or glstex files) where the document is saved in the file myDoc.tex:

  1. pdflatex myDoc
    The aux file is created containing two records for “lid”.
  2. bib2gls myDoc
    The glstex file is created with the location list for “lid” containing two locations.
  3. pdflatex myDoc
    The aux file is created containing one record for “lid” but the location list contains two locations (obtained from the glstex file created in the previous step).
  4. bib2gls myDoc
    The glstex file is created with the location list for “lid” containing one location.
  5. pdflatex myDoc
    The aux file is created containing one record for “lid” and the location list contains one location (obtained from the glstex file created in the previous step).
Unless you delete all temporary files at the start (or end) of each build, this problem will only occur when you first build your document or reference a new entry or change the category of an existing entry.

2023-01-31 21:48:15

Top