Bibliography and indexes: synthesis and challenges

Summary

This lesson closes the sixth unit of the course, devoted to the bibliography and the indexes. It rebuilds the chain of principles and mechanisms that runs from the bibliographic entry to the glossary, pointing out at each link which principle is used and in which lesson it is established; it places what has been achieved within the plan of the course and specifies which questions, merely anticipated, are left for the following unit; it repeats in its exit assessment the skills of the entry assessment; and it ends with six challenges, harder than the problems of the lessons, which require combining several of them to move a paper from one citation style to another, to diagnose a list of references that compiles without warning with four defects, to predict the notes of an essay on Plato, to compose an index of names that agrees with the bibliography, to reconstruct the compilation cycle of a thesis and to prepare a database that serves both bibtex and biber.

Learning objectives

Rebuild the order of the mechanisms of the unit, identifying the principle on which each one rests.
Explain why the defects of a bibliographic database, of a citation or of an index almost always compile without warning, and where to look for their trace: in the output, in biber's messages, in makeindex's report or in the log.
Distinguish what the unit established from what it only anticipated and the following unit will develop.
Predict what a database, a style and a sequence of citations, index entries and acronyms print, and correct the source so that it prints what was intended.
Order the programs that take part in compiling a document with a bibliography, an index and a glossary, and know which of them run by themselves.

What the unit achieved

The unit set out to have the sources of a piece of work cited from a database, so that the citations and the list are typeset by themselves in the style of each discipline, and to give the document the indexes and glossaries that make it possible to consult it. The purpose has been fulfilled by relying on what the introduction declared known from the previous units: the runs, in which the engine writes in one compilation what it reads in the next; logical markup, which says what each thing is and leaves its form to a decision taken elsewhere; and the notes and quotation marks of the second unit. With that, the path travelled can be read as a single chain in four stretches.

The bibliographic database

The lesson on the bibliographic database separated the data of a work from the style in which it is cited, and applied to references the principle of logical markup: the .bib file says what each work is, and the style decides how it is written. It described the entries, their types, their keys, which must be unique and deducible, and their fields; it showed that biber understands both the biblatex field names and the classic ones, while bibtex understands only the classic ones; it established the mechanical rules by which biber divides names, and between people, the comma between surname and given name, the lower-case particle and the double braces of institutions, whose errors are seen only in the output; it protected with braces the capitals that a classic style would change; it explained why bibtex sorts accented letters after z and biber according to the language; it presented exporting from Zotero; and it taught to look for the errors of the database in biber's messages, not in the log of the document.

Citing with biblatex

The lesson on citing with biblatex loaded the package with backend=biber, the database with \addbibresource and its extension, and csquotes, which biblatex asks for alongside babel. It specified the cycle: the engine records the keys in the .bcf, biber looks them up and writes the .bbl, and the next run typesets it; without biber, the citations remain as keys in bold, and Texmaker's bibliography button runs bibtex by default. It chose the citation command by its function in the sentence, \textcite for the narrative citation, \parencite for the parenthetical one and \autocite for the one the style decides, with prenotes and postnotes; it compared the author–year, numeric, compressed numeric and alphabetic styles, in which the numbers follow the order of the list and not that of the citations unless sorting=none is given; and it composed the list with its title, its heading and its filters.

Citing in the humanities

The lesson on citing in the humanities automated the rule of economy of citation by notes: the first citation is complete, the following ones short, and the Latin abbreviations, ibid., op. cit. and loc. cit., are computed by the style, so that they do not become false when a citation is moved. It went through the verbose family; it showed that \autocite already puts the note number after the punctuation, as English requires, and that \DeclareAutoCiteCommand puts it before, as Spanish or French require; it cited the classics by their canonical reference in the postnote, which biblatex prints without “p.” when it is not a number, and with \nopp when it looks like one; it introduced the abbreviations of shorthand and their list; it recorded translations and their original through a related entry, because the standard styles do not print origdate; and it separated the sources from the secondary literature with keywords.

Indexes and glossaries

The lesson on indexes and glossaries carried the same cycle over to another program: the engine writes the entries to the .idx, makeindex sorts them into the .ind, and imakeidx runs it by itself except with nonewpage or noautomatic. It taught subentries with !, the sort key with @, cross-references and formats with |, and ranges; it showed that makeindex compares bytes and sends to the end the words that begin with a letter with a diacritic, and that upmendex sorts according to the language; it kept several named indexes; and it composed with glossaries the terms and the acronyms, which are spelled out at their first mention, with makeglossaries between the runs.

The following figure gathers the four stretches into a single chain. Each node of the column is a mechanism or a rule, numbered according to the order in which they rest on one another and joined by an arc to the earlier links it uses; around them float the supports, that is, the principles to which the chain turns again and again, each joined by a solid line to the links that rest on it and by a dotted one to the link where it is established, except those established in earlier units, which are drawn as rings. Clicking on a support highlights all the links that use it, and each link points to the lesson in which it is studied.

Supports of the chain

ARuns. The engine records in the auxiliary files what it computes in one run, and uses it in the next. Established in the first unit and refined in the third. Admitted without proof in this unit.
BWhat it is, not how it looks. Logical markup says what each element is and leaves its form to a decision taken elsewhere. Established in the second unit. Admitted without proof in this unit.
CDeciding once. What is decided in a single place (a style, a preamble option, a command of one’s own, an entry) changes throughout the document when it is changed there; what is copied by hand stops agreeing. Established in the previous units. Admitted without proof in this unit.
DWhat babel supplies. The babel language fixes the words the document writes by itself: titles, conjunctions, abbreviations and labels. Established in the second unit. Admitted without proof in this unit.
EWhat is valid gives no warning. The engine and its programs only warn about what they cannot process; a valid source that does not say what the author meant compiles without warning, and the defect is seen only in the output. Established in the previous unit. Admitted without proof in this unit.
FSorting bytes or letters. bibtex and makeindex compare character codes and send accented letters after z; biber and upmendex sort according to the rules of the language. Established in: 3. Fields, braces and accents.
GMark, sort, typeset. The author marks in the text what is cited or indexed; an external program sorts it between two runs of the engine; the next run typesets it. Established in: 6. The cycle with biber.

Segment 1 The bibliographic database
- Write correct entries, with their type, their key and their fields.
- Write names so that they are divided as they should be.
- Prepare a database for biber or for bibtex.
- Diagnose a database from biber's messages.
1. Data and style. Each work is described once in a .bib entry, with its type, a unique key that is never printed and its fields; the style decides the form, and the list contains exactly the works cited.
  Rests on: B (What it is, not how it looks), C (Deciding once). Proved in: The bibliographic database.
2. Names. and separates people and the comma separates the surname from the given name; without a comma, the surname is the last word; initial lower-case words are a particle; double braces prevent the name of an institution from being divided. No error gives a warning.
  Uses: 1. Data and style. Rests on: E (What is valid gives no warning). Proved in: The bibliographic database.
3. Fields, braces and accents. biber understands journal, address and year as well as their new names; bibtex only the classic ones, and with the new ones it loses the journal and the year; braces protect capitals; bibtex sorts accented letters after z, and biber according to the language.
  Uses: 1. Data and style. Rests on: F (Sorting bytes or letters). Proved in: The bibliographic database.
4. Diagnosing the database. A missing comma stops biber and empties the whole list; a repeated key is ignored with a warning; an unescaped & gives a LuaLaTeX error on the line of the document that typesets the list.
  Uses: 2. Names, 3. Fields, braces and accents. Rests on: E (What is valid gives no warning). Proved in: The bibliographic database.
Segment 2 Citing with biblatex
- Load biblatex with biber and csquotes.
- Compile the cycle with biber, by hand, with latexmk or with Texmaker.
- Choose the citation command according to the sentence.
- Predict what each style prints and compose the list with its filters.
1. Loading biblatex. backend=biber and style in the options; \addbibresource with the extension of the file; csquotes after babel, which biblatex recommends with a warning.
  Uses: 1. Data and style. Rests on: D (What babel supplies). Proved in: Citing with BibLaTeX.
2. The cycle with biber. The engine writes the keys to the .bcf, biber writes the .bbl and the engine typesets it; before that, the citations are keys in bold; latexmk runs biber by itself, and Texmaker’s button runs bibtex unless it is changed.
  Uses: 5. Loading biblatex. Rests on: A (Runs), G (Mark, sort, typeset). Proved in: Citing with BibLaTeX.
3. The citation according to the sentence. \textcite for the author who is part of the sentence, \parencite for the parenthesis, \autocite for the citation the style decides; a numeric postnote receives “p.” by itself, and \citeauthor does not point to the list.
  Uses: 6. The cycle with biber. Rests on: D (What babel supplies), C (Deciding once). Proved in: Citing with BibLaTeX.
4. The style decides. authoryear, numeric, numeric-comp and alphabetic change all the citations and the list with one option; the numbers follow the order of the list, alphabetical by default, and sorting=none puts them in the order of the citations.
  Uses: 7. The citation according to the sentence, 2. Names. Rests on: B (What it is, not how it looks), C (Deciding once). Proved in: Citing with BibLaTeX.
5. The list and its filters. \printbibliography sets the title and the heading; keyword and notkeyword divide the list without losing works; \nocite adds works that are not cited; a list without works is not printed, with the warning “Empty bibliography”.
  Uses: 8. The style decides. Rests on: E (What is valid gives no warning). Proved in: Citing with BibLaTeX.
Segment 3 Citing in the humanities
- Choose a note style and predict its abbreviations.
- Place the note number after or before the punctuation, as the language requires.
- Cite the classics by their canonical reference.
- Record translations and separate sources from studies.
1. Complete, then short. The verbose family gives the full reference in the first citation and the short one afterwards; verbose-ibid writes “Ibid.” if it repeats the previous note on the same page; the traditional schemes add op. cit. and loc. cit.
  Uses: 8. The style decides. Rests on: C (Deciding once). Proved in: Citing in the humanities.
2. The note number and the punctuation. In note mode, \autocite moves the punctuation mark before the note number, as English requires; \DeclareAutoCiteCommand with [r] leaves it after, as Spanish or French require, and a space before \autocite serves both systems.
  Uses: 10. Complete, then short, 7. The citation according to the sentence. Rests on: D (What babel supplies). Proved in: Citing in the humanities.
3. Canonical references. A postnote that is not a number, such as 514a or 980a21, is printed without “p.”; one that looks like a number needs \nopp; shorthand gives an abbreviation, which prevails over ibid., and \printbiblist{shorthand} prints its list.
  Uses: 7. The citation according to the sentence, 10. Complete, then short. Rests on: E (What is valid gives no warning). Proved in: Citing in the humanities.
4. Translations and sources. translator and origlanguage name the translator and the language; the standard styles do not print origdate, and the original is declared as a related entry; keywords separates the sources from the secondary literature.
  Uses: 12. Canonical references, 9. The list and its filters. Rests on: E (What is valid gives no warning). Proved in: Citing in the humanities.
Segment 4 Indexes and glossaries
- Mark entries and compile the index with makeindex.
- Sort words with diacritics correctly and write cross-references and ranges.
- Keep a single form for each entry, and several indexes.
- Define terms and acronyms and foresee each mention.
1. The index with imakeidx. \index writes to the .idx, makeindex sorts into the .ind and \printindex typesets it; imakeidx runs makeindex by itself, except with nonewpage or noautomatic.
  Uses: 6. The cycle with biber. Rests on: A (Runs), G (Mark, sort, typeset). Proved in: Indexes and glossaries.
2. Subentries, keys and cross-references. ! separates levels, @ separates the sort key from the printed form, |see refers without a page and |( opens a range; without a key, words with a diacritic on their first letter go to the end.
  Uses: 14. The index with imakeidx. Rests on: F (Sorting bytes or letters), E (What is valid gives no warning). Proved in: Indexes and glossaries.
3. One form, several indexes. makeindex compares character by character, and two spellings of a term are two entries; a convention applied through a command of one’s own prevents it; name opens separate indexes, and a misspelled name loses the entry.
  Uses: 15. Subentries, keys and cross-references, 2. Names. Rests on: C (Deciding once). Proved in: Indexes and glossaries.
4. Glossaries and acronyms. glossaries defines each term once and \gls spells out an acronym at its first mention; makeglossaries sorts between the runs; a term with a diacritic on its first letter needs sort, or the engine stops.
  Uses: 15. Subentries, keys and cross-references. Rests on: G (Mark, sort, typeset), F (Sorting bytes or letters). Proved in: Indexes and glossaries.

Towards other documents. The chain stops where the academic work is complete: text, structure, formulas, tables, figures, sources and indexes, each computed from its declaration. The following unit carries the same database and the same mechanisms to presentations, posters and shared work.