GNU TeXmacs: How to Create a Bibliography and Add Citations

Introduction

While writing last month's article, I realized that certain tasks in TeXmacs might be a bit intimidating for users who are unfamiliar with the (La)TeX ecosystem. Although TeXmacs does not use (La)TeX directly, its method of creating bibliographies and handling citations / references follows “the LaTeX way”.

If you decided to explore TeXmacs but have little or no prior LaTeX experience, and are wondering how to create a bibliography and add citations to your document, I will attempt to demystify the process. It is not complicated once you acquire some basic knowledge of two programs: BibTeX and JabRef.

BibTeX

The GNU TeXmacs editor uses BibTeX to compile bibliographies. BibTeX is a software program that is used in conjunction with LaTeX to help organize your bibliographic references and create a bibliography. BibTeX automates most of the work in managing references. The program formats your citations and reference list consistently, in a style of your choosing.

BibTeX references are stored in a plain-text database with a simple format (with a file extension of .bib). Every reference in this bibliography file is formatted according to a certain structure and is given a “key” (also known as a “citation key”) which uniquely identifies that item. The “key” is the first item in a BibTeX entry.

The citation key is something that you create yourself. You may use any naming convention that you wish; a common pattern is “AuthorsurnameYearofpublication”, e.g., Knuth84, Lamport94, etc. An author with multiple publications in the same year could have a letter appended to the key, e.g., Dijkstra69, Dijkstra69a, Dijkstra69b.

Below is an example of a BibTeX entry for Donald E. Knuth's famous book, The Art of Computer Programming. It illustrates the general structure of the file format:

BibTeX was developed by computer scientist Oren Patashnik in the 1980s, while he was a graduate student at Stanford University (working under the supervision of Donald Knuth and Leslie Lamport). The program's first public release was in March 1985, so it has been in existence for almost forty years. BibTeX is tried and true; it has proven itself to be an invaluable tool.

As you might imagine, with such a long history, there is a large corpus of literature published on BibTeX. If you have specific questions about how to accomplish something in BibTeX, a quick web search will lead you to answers.

Andrew Roberts, the author of some popular LaTeX tutorials, provides a good introduction to BibTeX with a helpful cheat sheet (in PDF format) that summarizes all the BibTeX entry types and fields.

If you would like to delve more deeply into BibTeX, Dr. Nelson Beebe (Dept. of Mathematics, University of Utah) wrote an excellent tutorial.

A few other points to consider about BibTeX:

• The order of the BibTeX fields is unimportant

• Your .bib file can contain references that you do not cite. At the end of your document, BibTeX and TeXmacs will only print the references that you have cited (using the “\cite|your-citation-key” command)

• BibTeX is persnickety about the capitalization of proper nouns and acronyms, as well as the formatting of names (or words) with non-ASCII characters (such as foreign-language diacritics). Some basic guidelines are available here. A table demonstrating how to type common foreign-language diacritics can be found on Wikibooks

JabRef

Although you can create and edit BibTeX files in any text editor — such as Kate, Emacs, Geany, etc. — using a reference manager app is a more comfortable experience. I recommend that you consider JabRef as your primary citation management software because it uses BibTeX (.bib) as its native file format.

JabRef is a reference manager that acts as an interface to BibTeX. JabRef is FOSS, cross-platform (Linux, macOS, Windows) and is freely downloadable. The GUI allows the user to easily import, edit, search, and group citations in the BibTeX format. It also offers automatic citation key generation. JabRef does not offer any citation styles of its own; instead, the citation is generated from the BibTeX style setting.

A complete JabRef tutorial is outside the scope of this article. However, the video tutorials below can help you quickly become familiar with JabRef's features:

• The presentation by Dr. James Azam, “JabRef for Beginners (Part 1): JabRef Interface and Creating a Library” [3 Apr. 2021 (13 min., 55 sec.)], is an excellent starting point. It provides a clear overview and is well paced

• The tutorial by JoshTheEngineer, “Introduction to JabRef” [31 Jan. 2021 (22 min., 25 sec.)], is more detailed but at times the presenter overly focuses on his personal configurations / preferences

How to Install JabRef

Although JabRef is not currently in the PCLinuxOS repositories, it can be installed easily as a Flatpak (ver. 5.15).

• First, install the Flatpak utility via Synaptic from the official PCLinuxOS repository. The current version (at the time this article was written) is flatpak 1.15.6.

• As root user, you need to add the Flathub repository and initialize it before installing the JabRef Flatpak on your system. Open a Terminal and type the following (this is all one line):
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

• Note: Restart/reboot your computer. After that, you can proceed with actually installing the JabRef app.

• Open a web browser and go to the Flathub page for JabRef:
https://flathub.org/apps/org.jabref.jabref

• Copy the “Manual Install” CLI command from the Flathub.org webpage, and paste it into a Terminal. (You must have root privileges): flatpak install flathub org.jabref.jabref

(In case you are curious, here is a partial gloss of the command's syntax:

flatpak install flathub org.jabref.jabref

• The third element (“flathub”) is the remote repository, i.e., flathub[.org].

• The final element is the ID of the application.
Identifiers have a three-part structure, e.g., com.company.App
In this instance, we have “org” since it is a non-commercial entity.
The “jabref” is the name of the developer.
“jabref” is the object's name, i.e., application name.)

Methods of Creating a BibTeX File

There are several methods of creating a BibTeX (.bib) file:

• You may convert your existing references from text format using the online tool text2bib. You can copy and paste your bibliography from LibreOffice Writer (or another word processor) into text2bib, which will convert your references into a BibTeX file.

• The text2bib website is maintained by Martin Osborne, a retired economics professor from the University of Toronto. Dr. Osborne prepared a brief video which explains how the utility works.

• Makino Takaki provides an (experimental) online converter here.

• If you already use a reference management program such as Zotero, it can export your references as a .bib file. This library guide explains how to export Zotero references in BibTeX format.

• You can export references from Google Scholar in BibTeX format. However, please be aware that the accuracy of these references is often not very high.

Google Scholar is a web search engine that indexes the full text or metadata of publications from a variety of scholarly disciplines. After conducting your search, identify the source(s) that you wish to cite. Then, it is a simple three-step process to export the BibTeX reference: click on the “Cite” hyperlink; then click on the “BibTeX [format]” hyperlink; copy and paste the displayed BibTeX entry into JabRef or your favorite text editor.

Below is the citation, in BibTeX format, for the book Linux for Small Business Owners (as downloaded from Google Scholar):

@book{both2022linux,
title={Linux for Small Business Owners},
author={Both, David and Bulka, Cyndi},
year={2022},
publisher={Springer}
}

The sample item above, although it is bare-bones, contains mistakes. It omits the book's subtitle; it omits the edition statement and lists the publisher incorrectly (it should be “Apress” [which is an imprint of parent company Springer Verlag]. The book's ISBN was not included in the Google Scholar metadata.

I edited the entry to include additional bibliographic data. My modifications are in blue boldface type:

@book{Both22,
isbn = {978-1484282632},
year = {2022},
title = {Linux for Small Business Owners: Using Free and Open-Source Software to Power Your Dreams},
edition = {First},
publisher = {Apress},
author = {David Both and Cyndi Bulka}
}

• A topic on the TeX StackExchange lists good websites to find citations in BibTeX format. In particular, DBLP is mentioned as an excellent source if you are interested in computer science and/or math topics.

• As a retired librarian, I must put in a plug: don't forget your local public library. It probably offers free access to online databases (on an array of subjects) which you can search. Most of these databases allow exporting citations in various formats.

The screenshot below shows a small sample of the databases available at my local library (via the Texas State Library).

• A more labor-intensive option is to type your BibTeX database from scratch — either directly as a plain text file, or by using a BibTeX reference management program such as JabRef.

Referencing In Action: TeXmacs

We have covered background information on BibTeX and the role it plays in compiling bibliographies. Now let's walk through the process of citing reference sources within GNU TeXmacs and actually compiling a bibliography.

• To begin, you should have already created a (separate) bibliography file, in BibTeX format (.bib).

• Make sure that your TeXmacs file (.tm) and your bibliography file (.bib) are saved / stored in the same directory.

• To include the bibliography file and make it known to your current TeXmacs file, from the Insert menu > choose Automatic > then Bibliography.

(As an alternative, you can insert the bibliography file via the menu on the second-tier toolbar. Look for the last icon in the left group [“Insert automatically generated content”] > then choose the Bibliography option.)

Navigate to the folder with your .bib file, select it and click on the Open button.

Notice that an unnumbered section called “Bibliography” will be added at the bottom of your document.

At this point, you may begin entering your relevant citations. For example, to add a citation after the phrase:

“In the book by Mittelbach et al.”: After “et al.” press the Spacebar then Tab:

• A faint blue hyphen will appear (as shown above).

You must type the Spacebar + Tab key sequence to ensure that the automatic hyperlinking of the citation works properly. (If you fail to do this, hyperlinking will not be active, and you will receive an error message if you click on the citation.)

• Next, type “\cite”, i.e., Backslash symbol followed by the word “cite” (without quotation marks):

(The purple-colored angle brackets appear automatically in the TeXmacs editor while you are typing out this command.)

• Next, press the Enter/Return key.

A pipe symbol (“ | ”) will automatically appear:

• Type in (or paste) your BibTeX citation key for this book. In this example, I used the citation key “Mittelbach04”:

• Press the Enter/Return key.

Notice that the argument you were typing as part of the “cite” command disappears, and changes to a red question mark:

The question mark appears because TeXmacs is unaware — for now — of this newly added citation. In order for TeXmacs to “look up” this new information, you must first update / refresh your TeXmacs file.

• To refresh your file, click on the Hammer icon two or three times.

• Afterwards, all changes should be reflected, and the citation will become active / hyperlinked.

• You will see the “[?]” change to an Arabic numeral (“3” in this example):

• An entry for the Mittelbach book will be generated in the “Bibliography” list:

The reference list shown in the screenshot above is one of the seven standard BibTeX bibliography styles; it is called “plain”. (TeXmacs refers to it as “tm-plain”). A brief overview of BibTeX styles is available in the library guide at https://www.reed.edu/it/help/LaTeX/bibtexstyles.html

• You may optionally change the style by going to the Focus bar (the smaller, third-tier toolbar). Look for the property labeled “Style” and use its menu to change the style to “tm-alpha”:

• After applying the change, results will look like this in the text body and reference list:

Video Demos

I hope this article has clarified how BibTeX and TeXmacs interact, and perhaps saved you some frustration. You might find it helpful to watch two real-time video demonstrations of the bibliography / citation procedure:

• Useful Knowledge. “How to Easily Type Your (Scientific) Notes with TeXmacs.” 1 Apr. 2022.
The bibliography segment runs from minute 17:08 to minute 20:42.

• TeXmacs Videos. “Typing Your First Article with GNU TeXmacs.” 25 Apr. 2019. The bibliography demonstration runs from minute 4:54 to minute 6:19.