Organising bibliographies in complex editorial projects

From Wiki
Jump to navigation Jump to search


🚧 This page is under construction. Feel free to correct, expand, and improve it; its structure and examples may still change.

Bibliography guides — Guide 4 of 4

← Previous: Guide 3 — Creating local and multiple bibliographies  ·  Current: Guide 4 — Organising bibliographies in complex editorial projects  ·  End of the bibliography guides

Contents

1. Organising bibliographies in a multifile project

The first three guides introduced:

  • bibliographic records and citation keys;
  • sources and datasets;
  • specifications and renderings;
  • bibliography scope with method and criterium;
  • repeated rendering with repeat;
  • chapter bibliographies and final bibliographies;
  • several renderings and several datasets.

This guide applies those mechanisms to a structured publication containing several files.

A long monograph, critical edition, translation, or collected volume may contain:

  • shared page and font settings;
  • several chapters or components;
  • primary and secondary bibliographic collections;
  • chapter bibliographies;
  • final bibliography lists;
  • commands that must remain stable throughout the project;
  • data files maintained independently from the document prose.

At that scale, bibliography management becomes an architectural problem.

The main principle

Keep four responsibilities separate:

  • bibliographic data;
  • shared bibliography configuration;
  • citations in the textual components;
  • placement of chapter and final bibliography lists.

Each responsibility should have a clearly identified location in the project.

2. Separate the project responsibilities

A multifile publication is easier to maintain when each kind of file has one main responsibility.

Responsibility Recommended location
General layout, fonts, language, and headings A shared environment
Dataset loading, specifications, renderings, and bibliography commands A bibliography environment
Bibliographic records One or more .bib files
Chapter prose and citations Chapter components
Chapter bibliography placement The relevant chapter component
Final bibliography placement A backmatter component
Complete publication assembly A product file

This separation prevents the same setup from being copied into several chapters.

It also makes it easier to determine where a correction belongs.

Diagnose by responsibility

  • incorrect publication data → inspect the .bib file;
  • wrong punctuation or sorting → inspect the bibliography environment;
  • unresolved citation → inspect the dataset, path, and key;
  • misplaced or incorrectly scoped chapter bibliography → inspect the chapter component;
  • missing final bibliography → inspect the backmatter component and product.

3. A recommended directory structure

The following structure uses one product, several components, shared environments, and two bibliographic data files: 

book/
├── product.tex
├── env/
│   ├── general.mkxl
│   └── bibliography.mkxl
├── bib/
│   ├── primary.bib
│   └── secondary.bib
├── frontmatter/
│   └── introduction.tex
├── bodymatter/
│   ├── chapter-01.tex
│   └── chapter-02.tex
└── backmatter/
    └── bibliography.tex

The directory names describe the function of the files.

The extensions used here are project conventions:

  • .mkxl identifies shared LMTX environment files;
  • .tex identifies the product and textual components;
  • .bib identifies bibliographic data.

ConTeXt can recognise other file extensions, but a consistent local convention makes the project easier to read.

Location Main responsibility
product.tex Assemble the publication.
env/general.mkxl Define general document settings.
env/bibliography.mkxl Load datasets and define renderings and citation commands.
bib/*.bib Store bibliographic records.
frontmatter/*.tex Preliminary components.
bodymatter/*.tex Chapters, citations, and chapter bibliography placement.
backmatter/bibliography.tex Place the final bibliography lists.

4. Environment, product, and components

This guide uses a product-centred structure:

  • environments define reusable settings;
  • the product assembles the publication;
  • components contain the actual document units.

A larger publication may additionally use a ConTeXt project containing several products, but that extra level is not required for the example below.

4.1. The general environment

The file env/general.mkxl may contain: 

\startenvironment general

\mainlanguage
  [en]

\setuppapersize
  [A5]

\setuplayout
  [backspace=18mm,
   topspace=15mm,
   width=middle,
   height=middle,
   header=0pt,
   footer=8mm]

\setupbodyfont
  [libertinus,10pt]

\stopenvironment

This file contains settings shared by all components.

4.2. The product file

The file product.tex loads the environments and lists the components in publication order: 

\environment env/general.mkxl
\environment env/bibliography.mkxl

\startproduct book

\component frontmatter/introduction

\component bodymatter/chapter-01
\component bodymatter/chapter-02

\component backmatter/bibliography

\stopproduct

The product expresses the structure of the publication.

It should not repeat the detailed bibliography configuration.

4.3. Chapter components

A chapter component contains prose, citations, and—when required—the bibliography associated with that chapter.

For example: 

\startcomponent chapter-01

\chapter{The pantheism controversy}

Jacobi's intervention changed the terms of the debate
\PrimaryCite{jacobi1785}.

Beiser reconstructs the wider historical conflict
\SecondaryCite{beiser1987}.

\subject{Secondary literature used in this chapter}

\placebtxrendering
  [secondary-chapter]
  [method=global,
   criterium=chapter,
   repeat=yes]

\stopcomponent

Here the rendering is defined centrally, while the chapter component determines where it is placed and which structural scope is requested.

4.4. The bibliography component

The backmatter component decides where the final lists appear: 

\startcomponent bibliography

\chapter{Bibliography}

\subject{Primary sources}

\placebtxrendering
  [primary-global]
  [method=global,
   repeat=yes]

\subject{Secondary bibliography}

\placebtxrendering
  [secondary-global]
  [method=global,
   repeat=yes]

\stopcomponent

The distinction is therefore:

Element Main role
Environment Defines reusable settings and commands.
Product Assembles the publication.
Component Contains one editorial or structural unit and determines where structurally dependent material is placed.

5. Centralising bibliography settings

The file env/bibliography.mkxl should contain the shared bibliography configuration.

5.1. Loading the datasets

For example: 

\startenvironment bibliography

\usebtxdataset
  [primary]
  [bib/primary.bib]

\usebtxdataset
  [secondary]
  [bib/secondary.bib]

\usebtxdefinitions
  [apa]

The paths are written relative to the compilation context used for the product.

For a production project, verify the paths both when compiling the complete product and when testing individual components.

5.2. Defining the renderings

The same environment may define: 

\definebtxrendering
  [primary-global]
  [apa]
  [dataset=primary,
   sorttype=authoryear]

\definebtxrendering
  [secondary-chapter]
  [apa]
  [dataset=secondary,
   sorttype=authoryear]

\definebtxrendering
  [secondary-global]
  [apa]
  [dataset=secondary,
   sorttype=authoryear]

The names combine:

  • the collection;
  • the intended scope or editorial role.

Prefer: 

primary-global
secondary-chapter
secondary-global

to temporary names such as: 

list1
testlist
final2

The environment defines reusable bibliography configurations.

Structural options such as criterium=chapter remain at the placement point because they depend on the current document context.

In other words: 

environment  -> what bibliography configurations exist
component    -> where and in which structural scope they are rendered

5.3. Ending the environment

The file ends with: 

\stopenvironment

The complete environment therefore follows this pattern: 

\startenvironment bibliography

\usebtxdataset
  [primary]
  [bib/primary.bib]

\usebtxdataset
  [secondary]
  [bib/secondary.bib]

\usebtxdefinitions
  [apa]

\definebtxrendering
  [primary-global]
  [apa]
  [dataset=primary,
   sorttype=authoryear]

\definebtxrendering
  [secondary-chapter]
  [apa]
  [dataset=secondary,
   sorttype=authoryear]

\definebtxrendering
  [secondary-global]
  [apa]
  [dataset=secondary,
   sorttype=authoryear]

\stopenvironment

6. One dataset or several datasets?

Several files may contribute to one logical dataset: 

\usebtxdataset
  [secondary]
  [bib/books.bib]

\usebtxdataset
  [secondary]
  [bib/articles.bib]

This is useful when files are separated for maintenance but the records form one collection.

Separate datasets are useful when a stable editorial distinction must remain visible: 

\usebtxdataset
  [primary]
  [bib/primary.bib]

\usebtxdataset
  [secondary]
  [bib/secondary.bib]

The distinction can then be expressed directly in citations: 

primary::jacobi1785
secondary::beiser1987

Avoid accidental duplication

Do not copy the same record into several datasets merely because it must appear in several bibliography lists.

One record can be rendered by several bibliography configurations.

Duplicate records create a risk that later corrections will be applied to only one copy.

7. Defining project-level citation commands

A project may define semantic wrapper commands so that chapter authors do not have to repeat dataset names and low-level options.

For example, add to env/bibliography.mkxl: 

\define[1]\PrimaryCite
  {\cite
     [authoryear]
     [primary::#1]}

\define[1]\SecondaryCite
  {\cite
     [authoryear]
     [secondary::#1]}

A chapter can then use: 

\PrimaryCite{jacobi1785}

and: 

\SecondaryCite{beiser1987}

These commands:

  • reduce repeated typing;
  • prevent dataset-name errors;
  • make the editorial role of the citation visible;
  • allow later project-wide changes.

These are minimal examples

A production citation interface may also need to accept:

  • locators;
  • prefixes and suffixes;
  • several record keys;
  • narrative citation forms;
  • different citation alternatives.

Do not hide necessary editorial information behind an interface that is too restrictive.

8. Chapter and final bibliography placement

The bibliography environment defines the lists.

The components decide where those lists are placed and, when necessary, which structural scope applies.

8.1. Chapter placement

At the end of a chapter component: 

\subject{Secondary literature used in this chapter}

\placebtxrendering
  [secondary-chapter]
  [method=global,
   criterium=chapter,
   repeat=yes]

The option criterium=chapter restricts this rendering to the current chapter scope.

The physical placement of the list and its structural scope remain distinct aspects of the setup.

The three options answer different questions: 

method=global       -> use globally registered bibliography references
criterium=chapter   -> restrict the rendering to the current chapter
repeat=yes          -> allow already rendered records to appear again

8.2. Final placement in the backmatter

In backmatter/bibliography.tex: 

\subject{Primary sources}

\placebtxrendering
  [primary-global]
  [method=global,
   repeat=yes]

\subject{Secondary bibliography}

\placebtxrendering
  [secondary-global]
  [method=global,
   repeat=yes]

The data and rendering definitions remain in the shared environment.

The placement remains in the appropriate textual component.

8.3. Repeated placement

A record already displayed in a chapter bibliography may need to appear again in the final bibliography.

In the chapter-plus-final pattern used here: 

repeat=yes

allows records already rendered in chapter bibliographies to appear again in the final bibliography.

Other rendering sequences may require different choices.

9. A complete multifile project example

The following files form one small but genuine multifile project.

9.1. Directory tree

book/
├── product.tex
├── env/
│   ├── general.mkxl
│   └── bibliography.mkxl
├── bib/
│   ├── primary.bib       — primary texts and historical sources
│   └── secondary.bib     — secondary scholarship
├── frontmatter/
│   └── introduction.tex
├── bodymatter/
│   ├── chapter-01.tex
│   └── chapter-02.tex
└── backmatter/
    └── bibliography.tex

9.2. File: bib/primary.bib

@Book{jacobi1785,
  author    = {Jacobi, Friedrich Heinrich},
  title     = {Über die Lehre des Spinoza
               in Briefen an Herrn Moses Mendelssohn},
  publisher = {Gottlieb Löwe},
  address   = {Breslau},
  year      = {1785},
}

@Book{hegel1820,
  author    = {Hegel, Georg Wilhelm Friedrich},
  title     = {Grundlinien der Philosophie des Rechts},
  publisher = {Nicolai},
  address   = {Berlin},
  year      = {1820},
}

9.3. File: bib/secondary.bib

@Book{beiser1987,
  author    = {Beiser, Frederick C.},
  title     = {The Fate of Reason},
  subtitle  = {German Philosophy from Kant to Fichte},
  publisher = {Harvard University Press},
  address   = {Cambridge, Massachusetts},
  year      = {1987},
}

@Article{ameriks1981,
  author  = {Ameriks, Karl},
  title   = {Kant's Deduction of the Categories},
  journal = {The Monist},
  year    = {1981},
  volume  = {64},
  number  = {4},
  pages   = {451--470},
}

9.4. File: env/general.mkxl

\startenvironment general

\mainlanguage
  [en]

\setuppapersize
  [A5]

\setuplayout
  [backspace=18mm,
   topspace=15mm,
   width=middle,
   height=middle,
   header=0pt,
   footer=8mm]

\setupbodyfont
  [libertinus,10pt]

\stopenvironment

9.5. File: env/bibliography.mkxl

\startenvironment bibliography

\usebtxdataset
  [primary]
  [bib/primary.bib]

\usebtxdataset
  [secondary]
  [bib/secondary.bib]

\usebtxdefinitions
  [apa]

\definebtxrendering
  [primary-global]
  [apa]
  [dataset=primary,
   sorttype=authoryear]

\definebtxrendering
  [secondary-chapter]
  [apa]
  [dataset=secondary,
   sorttype=authoryear]

\definebtxrendering
  [secondary-global]
  [apa]
  [dataset=secondary,
   sorttype=authoryear]

\define[1]\PrimaryCite
  {\cite
     [authoryear]
     [primary::#1]}

\define[1]\SecondaryCite
  {\cite
     [authoryear]
     [secondary::#1]}

\stopenvironment

9.6. File: frontmatter/introduction.tex

\startcomponent introduction

\chapter{Introduction}

This small project demonstrates the separation of data, shared bibliography
configuration, chapter content, and final-list placement.

\stopcomponent

9.7. File: bodymatter/chapter-01.tex

\startcomponent chapter-01

\chapter{The pantheism controversy}

Jacobi's intervention transformed the reception of Spinoza
\PrimaryCite{jacobi1785}.

Beiser reconstructs the wider philosophical conflict
\SecondaryCite{beiser1987}.

\subject{Secondary literature used in this chapter}

\placebtxrendering
  [secondary-chapter]
  [method=global,
   criterium=chapter,
   repeat=yes]

\stopcomponent

9.8. File: bodymatter/chapter-02.tex

\startcomponent chapter-02

\chapter{Law and the categories}

Hegel develops the institutional form of freedom
\PrimaryCite{hegel1820}.

Ameriks analyses the structure of Kant's deduction
\SecondaryCite{ameriks1981}.

\subject{Secondary literature used in this chapter}

\placebtxrendering
  [secondary-chapter]
  [method=global,
   criterium=chapter,
   repeat=yes]

\stopcomponent

9.9. File: backmatter/bibliography.tex

\startcomponent bibliography

\chapter{Bibliography}

\subject{Primary sources}

\placebtxrendering
  [primary-global]
  [method=global,
   repeat=yes]

\subject{Secondary bibliography}

\placebtxrendering
  [secondary-global]
  [method=global,
   repeat=yes]

\stopcomponent

9.10. File: product.tex

\environment env/general.mkxl
\environment env/bibliography.mkxl

\startproduct book

\component frontmatter/introduction

\component bodymatter/chapter-01
\component bodymatter/chapter-02

\component backmatter/bibliography

\stopproduct

9.11. Compile the product

From the book/ directory, run: 

context product.tex

The intended result is:

  • Chapter 1 contains a chapter-scoped secondary bibliography with Beiser;
  • Chapter 2 contains a chapter-scoped secondary bibliography with Ameriks;
  • the final primary bibliography contains Jacobi and Hegel;
  • the final secondary bibliography contains Beiser and Ameriks.

This project demonstrates two independent editorial dimensions: 

dataset
    primary / secondary

structural scope
    chapter / whole document

Bibliographic classification and structural scope are therefore independent choices.

What this project demonstrates

File or directory Responsibility
bib/ Bibliographic records
env/bibliography.mkxl Dataset loading, renderings, and citation commands
bodymatter/ Chapter prose, citations, and chapter-scoped bibliography placement
backmatter/bibliography.tex Final-list placement
product.tex Publication assembly

10. Naming and path conventions

Use names that express stable editorial roles.

10.1. Dataset names

Prefer: 

primary
secondary
translations
archives

10.2. Rendering names

Include the collection and intended scope or editorial role: 

primary-global
secondary-chapter
secondary-global
translations-global

Avoid names whose meaning depends on an implementation detail or an ambiguous use of terms such as local.

10.3. Citation command names

Use commands that express editorial function: 

\PrimaryCite
\SecondaryCite
\TranslationCite

10.4. Paths

Keep path conventions consistent.

For example: 

\usebtxdataset
  [secondary]
  [bib/secondary.bib]

Test the project from the directory and compilation workflow that will be used in production.

Direct component compilation may require additional environment or path arrangements and should be tested separately.

11. Common project-level problems

11.1. The same setup appears in several chapters

Move shared definitions to an environment.

11.2. A citation resolves in one component but not another

Check:

  • whether the bibliography environment is loaded;
  • whether the dataset has been loaded;
  • whether the path to the .bib file is correct;
  • whether the key is explicitly qualified;
  • whether the component is being compiled inside the expected product setup.

11.3. A record appears in the wrong bibliography

Check the dataset attached to the rendering.

The visible bibliography heading does not determine the dataset.

11.4. A chapter bibliography contains records from another chapter

Check:

  • whether criterium=chapter is used;
  • the active structural scope;
  • component boundaries;
  • placement of the chapter rendering;
  • whether the citations belong to the intended dataset;
  • whether the document has been reprocessed after structural changes.

Do not attempt to repair chapter scope merely by replacing method=global with method=local.

11.5. A final bibliography omits a record displayed in a chapter bibliography

Check:

  • the dataset associated with the final rendering;
  • whether method=global is used;
  • whether repeat=yes permits the record to appear again;
  • whether the record was cited or otherwise registered;
  • whether the complete product has been processed again.

11.6. A record appears in one chapter bibliography but not another

If the same record is cited in more than one chapter, check:

  • whether each placement uses the intended criterium=chapter;
  • whether repeat=yes permits repeated rendering;
  • whether the citation occurs within the expected chapter scope.

11.7. Several files contain the same key

Duplicate keys in one dataset may produce conflicts or unexpected results.

Use a bibliography manager or a text search to locate duplicate records.

11.8. A style change requires editing every chapter

The bibliography configuration has not been sufficiently centralised.

Move the specification and rendering settings to the bibliography environment.

12. A practical diagnostic table

Symptom Inspect first
A key is unresolved Data file, dataset loading, path, key spelling, or qualification
A citation works only in the complete product Component environment and path setup
The correct record appears in the wrong list Rendering-to-dataset association
A chapter bibliography contains records from another chapter criterium=chapter, component boundaries, and placement context
A chapter bibliography is empty Rendering dataset, qualified citation key, chapter scope, and criterium
A record appears in the first chapter bibliography but not when cited again later repeat
A chapter record is absent from the final bibliography Final rendering scope and repeat=yes
A style correction must be repeated in several files Missing central environment
Two records disagree about one publication Duplicate bibliographic data
The final bibliography does not appear Backmatter component and product assembly

13. Checklist before publication

Before producing the final PDF, verify:

  • shared bibliography settings are centralised in an environment;
  • bibliographic records are stored outside the textual components;
  • every dataset has a stable editorial purpose;
  • every rendering is associated with the correct dataset;
  • dataset and rendering names are consistent;
  • citation keys are unique;
  • citations are explicitly qualified where several datasets are used;
  • chapter bibliographies use the intended criterium and contain only records from the intended structural scope;
  • repeat=yes is used where chapter and final renderings must reuse the same records;
  • final bibliographies contain all intended records;
  • paths work in the production compilation workflow;
  • the product includes the bibliography component;
  • the complete project compiles cleanly after structural changes.

14. What you have learned

This guide has shown how to organise bibliography management in a structured multifile publication.

The main workflow is: 

bib/*.bib
        |
        v
datasets and renderings in env/bibliography.mkxl
        |
        +--------------------> citations in bodymatter/*.tex
        |
        +--------------------> chapter-scoped lists in bodymatter/*.tex
        |
        +--------------------> final lists in backmatter/bibliography.tex
        |
        v
complete assembly in product.tex

The central principles are:

  • data, configuration, content, and placement should remain separate;
  • shared bibliography settings belong in an environment;
  • the product expresses publication structure;
  • components contain chapter or backmatter content;
  • datasets express bibliographic collections;
  • renderings express bibliography lists;
  • method controls the rendering/reference state used;
  • criterium expresses structural scope at bibliography placement;
  • repeat permits intentional reuse across chapter and final lists;
  • stable names and paths make the project maintainable;
  • a genuine multifile test is necessary before adopting the architecture in a large production project.

A useful summary is: 

dataset    -> which bibliographic collection?
rendering  -> which bibliography list?
method     -> which rendering/reference state?
criterium  -> which structural scope?
repeat     -> may an already rendered record appear again?
component  -> where is the list placed?
product    -> how is the publication assembled?

15. End of the bibliography guides

The four guides form a progression:

  1. Creating a bibliography and citing sources
  2. Understanding bibliography datasets, styles, renderings, selection, and sorting
  3. Creating local and multiple bibliographies
  4. Organising bibliographies in complex editorial projects

Together they move from a first working citation to the organisation of a structured scholarly publication.

Advanced subjects require separate treatment, including:

  • developed bibliographic references in notes;
  • Chicago notes-and-bibliography and SBL workflows;
  • custom bibliographic specifications;
  • complex parent–child records and crossref;
  • PDF interaction between citations and bibliography entries;
  • multilingual and multiscript bibliographies;
  • philological references, critical editions, translations, and scholarly series.

16. Related pages and commands

Bibliography guides — Guide 4 of 4

← Previous: Guide 3 — Creating local and multiple bibliographies  ·  Current: Guide 4 — Organising bibliographies in complex editorial projects  ·  End of the bibliography guides

Retrieved from "https://wiki.contextgarden.net/index.php?title=Organising_bibliographies_in_complex_editorial_projects&oldid=43699"