References notes and floats/Simple bibliography

From Wiki
Jump to navigation Jump to search


Bibliography and citations in ConTeXt  ·  Overview  ·  How-to guides  ·  Manual bibliography with simplebib  · 

🚧 Under construction — This page is currently being revised. Contributions are welcome: feel free to edit and improve it.

Choose the modern bibliography system for complete projects

The simplebib module is intended for short, manually constructed bibliographies whose entries require unusual, freely written, or locally controlled descriptions.

For books, theses, article collections, multilingual editions, or other long-term projects, prefer the modern ConTeXt bibliography system based on reusable .bib files, BTX datasets, citation styles, sorting, selection, and bibliography renderings.

Before choosing this manual method, consult the Bibliography and citations overview and the bibliography tutorial. The complete set of links to the modern workflow is collected in Section 16.1.

Contents

1. Purpose

A conventional bibliographic database works best when each publication can be described through a stable and predictable collection of fields.

Some bibliographic material is less regular. For example:

  • the available information may not fit naturally into a conventional BibTeX entry type;
  • a notice may require explanatory prose;
  • an editor may need to reproduce an unusual historical description;
  • a bibliography may combine references with comments or documentary information;
  • a short document may require only a small number of manually controlled entries;
  • several independently written bibliography blocks may be needed inside the same document.

The simplebib module provides a manually constructed bibliography based on individual \bibitem commands.

Scope of this page

This page preserves documentation for a specialized manual workflow. It is not the entry point for the current dataset-based bibliography system used in most complete ConTeXt projects.

Central principle

With simplebib, bibliographic entries are written directly in the ConTeXt source. No separate .bib database is required.

2. When to use simplebib

Use simplebib when:

  • the bibliography is short and local to one document;
  • individual entries require unusual manual descriptions;
  • the data cannot be represented conveniently in the available bibliographic schema;
  • explanatory text must be inserted among the bibliographic entries;
  • exact local control matters more than database reuse;
  • the bibliography is not intended to be maintained as a large structured dataset.

Do not choose simplebib merely because a structured bibliography initially appears more complicated.

For a substantial project, a .bib database usually provides better:

  • reuse;
  • consistency;
  • sorting;
  • validation;
  • style management;
  • collaboration;
  • maintenance across several documents or language versions.

A suitable use case

A critical edition may contain a short list of archival documents whose descriptions include shelf marks, physical details, editorial remarks, and explanatory prose that do not fit an ordinary publication record. A manually constructed simplebib list may be appropriate for that local documentary bibliography.

3. Basic workflow

The basic workflow has four stages:

  1. load the module;
  2. cite one or more internal references in the running text;
  3. create a bibliography environment;
  4. define the corresponding entries with \bibitem.

3.1. Load the module

\usemodule[simplebib]

3.2. Cite an item in the running text

\bibref[brk]

A citation may include a detail such as a page number: 

\bibref[detail={p. 38}][brk]

3.3. Start and stop the bibliography

\startbibliography

  % Bibliographic entries

\stopbibliography

3.4. Add an item

\bibitem
  [reference=brk,
   label={Brk-01},
   author={Brinker, Klaus},
   year={2001},
   title={Linguistische Textanalyse:
          Eine Einführung in Grundbegriffe und Methoden},
   publisher={Schmidt Verlag},
   place={Berlin}]

The value assigned to reference connects the citation in the running text with the corresponding bibliography entry.

4. Minimal working example

  • \usemodule[simplebib]

\setuppapersize[A6]

\starttext

The method is discussed by Brinker\bibref[brk].

\startsubject[title={Bibliography}]

\startbibliography

\bibitem
  [reference=brk,
   label={Brk-01},
   author={Brinker, Klaus},
   year={2001},
   title={Linguistische Textanalyse:
          Eine Einführung in Grundbegriffe und Methoden},
   series={Grundlagen der Germanistik},
   volume={29},
   revedition={5},
   publisher={Schmidt Verlag},
   place={Berlin},
   isbn={3-503-04995-9}]

\stopbibliography

\stopsubject

\stoptext

Result

The citation in the running text points to the manually defined entry in the bibliography block.

5. Create bibliography blocks

A bibliography may be placed in one block or distributed across several blocks in the document.

For example, separate lists may appear at the end of individual chapters: 

\startchapter[title={First chapter}]

  % Chapter text and citations

  \startsubject[title={Bibliography}]
    \startbibliography

      % Entries used in the first chapter

    \stopbibliography
  \stopsubject

\stopchapter

\startchapter[title={Second chapter}]

  % Chapter text and citations

  \startsubject[title={Bibliography}]
    \startbibliography

      % Entries used in the second chapter

    \stopbibliography
  \stopsubject

\stopchapter

One document may contain several bibliography environments

The commands \startbibliography and \stopbibliography may be used more than once. Each environment defines a separate bibliography block at the point where it occurs.

6. Define bibliographic items

Bibliographic entries are defined inside a bibliography environment with \bibitem.

The general form is: 

\bibitem
  [reference=,
   label=,
   author=,
   editor=,
   year=,
   title=,
   in=,
   number=,
   series=,
   volume=,
   magazine=,
   edition=,
   revedition=,
   datedition=,
   publisher=,
   place=,
   isbn=,
   url=,
   pages=,
   access=]

Not every entry uses every field. Include only the information required for the item.

6.1. Available fields

Field Purpose
reference Stable internal identifier used by \bibref or \crossref.
label Label printed for the entry. If omitted, the module can generate labels automatically.
author Author or authors of the item.
editor Editor or editors of the publication.
year Year of publication.
title Title of the work or contribution.
in Structured description of a containing publication.
number Number within a sequence, journal, or series.
series Name of a publication series.
volume Volume number.
magazine Journal, magazine, or periodical designation used by the module.
edition Edition statement.
revedition Revised-edition statement.
datedition Date-specific edition statement.
publisher Publisher.
place Place of publication.
isbn ISBN identifier.
url Web address.
pages Page or page range.
access Date on which an online resource was last consulted.

Field names reflect the module's own model

The fields used by simplebib do not necessarily correspond exactly to modern BTX field names or to every conventional BibTeX entry type. Treat them as parameters of this particular module.

6.2. Distinguish the reference from the printed label

The reference value is the stable internal identifier: 

reference=brk

The label value is printed in the bibliography: 

label={Brk-01}

These values serve different purposes.

Use stable semantic references

The internal reference should remain stable even if the printed label changes. Avoid using a temporary position such as item17 when a descriptive reference such as brinker2001 is available.

6.3. Generate labels automatically

To let the module number or label entries automatically, omit the label field: 

\bibitem
  [reference=brk,
   author={Brinker, Klaus},
   year={2001},
   title={Linguistische Textanalyse:
          Eine Einführung in Grundbegriffe und Methoden},
   publisher={Schmidt Verlag},
   place={Berlin}]

Use explicit labels when a publication requires a particular shorthand or siglum.

Use automatic labels when the exact printed identifier is not editorially significant.

7. Describe an article inside a containing publication

The in field describes a journal, collection, compendium, or other publication containing the cited contribution.

The fields outside in describe the article or contribution itself.

The nested fields inside in=Template:... describe the containing publication.

7.1. Example: an article in a journal

\bibitem
  [reference=bpf,
   label={BüPrFr-98},
   author={Büchel, Christian;
           Price, Cathy J.;
           Friston, Karl},
   year={1998},
   title={A multimodal language region
          in the ventral visual pathway},
   in={{title={Nature},
        volume={394},
        pages={274-277}}}]

The outer fields identify the article:

  • authors;
  • year;
  • article title.

The nested in value identifies the containing journal:

  • journal title;
  • volume;
  • page range.

Read the entry from the outside inward

The outer item is the work being cited. The in structure supplies information about the larger publication in which that work appears.

7.2. Keep the nested syntax balanced

The nested value uses two pairs of braces: 

in={{title={Nature},
     volume={394},
     pages={274-277}}}

Common syntax error

An omitted closing brace in the in field may cause the rest of the entry—or even the following document source—to be parsed incorrectly.

8. Refer to bibliographic items

The simplebib module uses the cross-reference mechanism for citations.

8.1. Use bibref

The concise citation command is: 

\bibref[reference]

Example: 

\bibref[brk]

8.2. Add a detail

Use the detail parameter for a page number, section, volume, or other local indication: 

\bibref
  [detail={p. 38}]
  [brk]

Another example: 

\bibref
  [detail={pp. 274-275}]
  [bpf]

8.3. Use the underlying cross-reference command

The following pairs express the same operations: 

\bibref[ref1]

\crossref
  [type=external]
  [ref1]

and: 

\bibref
  [detail={p. 38}]
  [ref1]

\crossref
  [type=external,
   detail={p. 38}]
  [ref1]

Use bibref for ordinary citations

The command \bibref is the convenient bibliographic interface. Use the underlying \crossref form only when direct access to the cross-reference configuration is required.

9. Adjust printed labels

9.1. Reserve space for labels

The labelSpace parameter controls the space reserved for bibliography labels.

The default value reported by the original module documentation is 12.

For example: 

\usemodule[crossref]
  [labelSpace=18]

\usemodule[simplebib]

Increase this value when labels are longer than the default space allows.

Module-version caution

The label width is provided through the cross-reference mechanism used by simplebib. Check the module version installed with your ConTeXt distribution if the parameter is not recognized or does not affect the output.

9.2. Add text around labels

Text placed before and after bibliography labels is configured with labelLeft and labelRight.

For square brackets: 

\setupsimplebibtext[labelLeft={[}]
\setupsimplebibtext[labelRight={]}]

This produces labels such as: 

[Brk-01]
[BüPrFr-98]

Braces and brackets must remain distinct

The square bracket to be printed is itself the value of the parameter. Check the balance of the square brackets and braces carefully.

10. Customize language-dependent terms

The module uses configurable words and abbreviations when constructing entries.

Use: 

\setupsimplebibtext
  [language]
  [key={text}]

10.1. English terms

\setupsimplebibtext[en][editor={ed.}]
\setupsimplebibtext[en][number={number}]
\setupsimplebibtext[en][fromSeries={from series}]
\setupsimplebibtext[en][volume={volume}]
\setupsimplebibtext[en][magazine={magazine}]
\setupsimplebibtext[en][edition={edition}]
\setupsimplebibtext[en][revedition={revised edition}]
\setupsimplebibtext[en][datedition={edition from}]
\setupsimplebibtext[en][isbn={ISBN}]
\setupsimplebibtext[en][pages={p.}]
\setupsimplebibtext[en][access={last accessed}]
\setupsimplebibtext[en][in={in}]

10.2. German terms

\setupsimplebibtext[de][editor={Hrsg.}]
\setupsimplebibtext[de][number={Nummer}]
\setupsimplebibtext[de][fromSeries={aus der Reihe}]
\setupsimplebibtext[de][volume={Band}]
\setupsimplebibtext[de][magazine={Heft}]
\setupsimplebibtext[de][edition={Auflage}]
\setupsimplebibtext[de][revedition={überarbeitete Auflage}]
\setupsimplebibtext[de][datedition={Auflage vom}]
\setupsimplebibtext[de][isbn={ISBN}]
\setupsimplebibtext[de][pages={S.}]
\setupsimplebibtext[de][access={letzter Zugriff}]
\setupsimplebibtext[de][in={in}]

Language-dependent terms affect presentation, not bibliographic identity

Changing editor, volume, pages, or related labels adapts the printed language of the bibliography. It does not change the internal reference of any item.

10.3. Adapt terms to the publication

The supplied terms are not mandatory editorial choices.

A publication may prefer, for example: 

\setupsimplebibtext[en][editor={edited by}]
\setupsimplebibtext[en][pages={pp.}]
\setupsimplebibtext[en][access={accessed}]

Choose abbreviations and formulations according to the language and style of the publication.

11. Insert free text in a bibliography

One reason to use a manually constructed bibliography is the possibility of inserting explanatory material directly into the bibliography environment.

For example: 

\startbibliography

\bibitem
  [reference=primary-source,
   label={A},
   author={Author},
   year={1785},
   title={Primary source title}]

\blank[small]

The following items are later editions and translations
derived from the primary source.

\blank[small]

\bibitem
  [reference=translation,
   label={A-FR},
   author={Author},
   year={2026},
   title={French translation of the primary source}]

\stopbibliography

Use free text sparingly

Explanatory prose may be useful in a documentary or annotated bibliography, but excessive free text can obscure the structure of the entries. When annotations follow a repeated pattern, consider defining a more systematic command or using structured BTX data instead.

12. Complete example

The following example combines:

  • two citations;
  • one citation with a page detail;
  • two manually constructed entries;
  • an article described through the in field;
  • explicit labels;
  • square brackets around labels;
  • a bibliography heading.
  • \usemodule[crossref]
  [labelSpace=18]

\usemodule[simplebib]

\setupsimplebibtext[labelLeft={[}]
\setupsimplebibtext[labelRight={]}]

\setuppapersize[A5]

\setupbodyfont
  [libertinus,10pt]

\starttext

Brinker provides a general methodological framework
\bibref[brk].

The neurological example is discussed on a specific page
\bibref[detail={p. 275}][bpf].

\startsubject[title={Bibliography}]

\startbibliography

\bibitem
  [reference=brk,
   label={Brk-01},
   author={Brinker, Klaus},
   year={2001},
   title={Linguistische Textanalyse:
          Eine Einführung in Grundbegriffe und Methoden},
   series={Grundlagen der Germanistik},
   volume={29},
   revedition={5},
   publisher={Schmidt Verlag},
   place={Berlin},
   isbn={3-503-04995-9}]

\bibitem
  [reference=bpf,
   label={BüPrFr-98},
   author={Büchel, Christian;
           Price, Cathy J.;
           Friston, Karl},
   year={1998},
   title={A multimodal language region
          in the ventral visual pathway},
   in={{title={Nature},
        volume={394},
        pages={274-277}}}]

\stopbibliography

\stopsubject

\stoptext

Compile the example and check that:

  1. both references in the running text resolve;
  2. the second reference includes the page detail;
  3. each internal reference points to the correct item;
  4. the two labels are printed inside square brackets;
  5. the journal title, volume, and pages are taken from the nested in data;
  6. only one \starttext and one \stoptext occur in the document;
  7. the bibliography environment is closed with \stopbibliography.

13. Common mistakes

13.1. Misspelling stopbibliography

Incorrect: 

\stopbibiography

Correct: 

\stopbibliography

13.2. Starting the document twice

Incorrect: 

\starttext

% Citations

\starttext

% Bibliography

A complete document must contain only one top-level \starttext and one corresponding \stoptext.

13.3. Using bibtex instead of bibref

The citation command used in the examples is: 

\bibref[reference]

Do not confuse the command name with BibTeX, the external bibliographic data format and processing tradition.

13.4. Using different internal references

These values do not match: 

\bibref[brinker]

\bibitem
  [reference=brk,
   ...]

Use exactly the same spelling and capitalization.

13.5. Confusing the reference and label

This citation uses the internal reference: 

\bibref[brk]

It does not cite the printed label: 

label={Brk-01}

13.6. Omitting braces in the in field

Incorrectly balanced nested data may prevent the item from being parsed correctly.

Keep the complete structure visible: 

in={{
  title={Nature},
  volume={394},
  pages={274-277}
}}

13.7. Using simplebib for a large reusable database

A large bibliography maintained across chapters, books, editions, or languages is usually better handled with the modern BTX workflow and one or more external .bib files.

Most important design mistake

Do not choose a manual bibliography merely to avoid learning the structured bibliography system. Choose it because the material genuinely requires local, irregular, or freely written description.

14. Diagnostic checklist

When the bibliography does not appear or a reference does not resolve, check:

  1. whether \usemodule[simplebib] is present;
  2. whether the item occurs inside \startbibliography and \stopbibliography;
  3. whether the citation and item use the same reference;
  4. whether all brackets and braces are balanced;
  5. whether the nested in data is correctly enclosed;
  6. whether the bibliography block occurs where it is intended to appear;
  7. whether a long printed label exceeds the configured labelSpace;
  8. whether the language-dependent texts have been configured for the active language;
  9. whether the document contains only one top-level \starttext;
  10. whether the installed module version supports the parameters being used;
  11. whether the project would be better served by the modern BTX bibliography system.

15. What this page has established

The simplebib module provides a direct method for constructing bibliographies manually in a ConTeXt source file.

The essential workflow is: 

load simplebib
      |
      v
cite an internal reference with \bibref
      |
      v
start a bibliography block
      |
      v
define the matching item with \bibitem
      |
      v
stop the bibliography block

This method supports:

  • manually specified bibliographic fields;
  • explicit or automatic labels;
  • nested descriptions through in;
  • several bibliography blocks;
  • citation details;
  • language-dependent terms;
  • free explanatory text inside a bibliography.

Its principal advantage is local flexibility.

Its principal limitation is that manually entered data is less reusable and less systematically managed than a modern dataset-based bibliography.

16. Related pages

16.1. Modern bibliography workflow

16.2. Related mechanisms

16.3. External module information

Bibliography and citations in ConTeXt  ·  Overview  ·  Tutorial  ·  How-to guides  ·  Manual bibliography with simplebib  ·  Reference  ·  Explanation

Retrieved from "https://wiki.contextgarden.net/index.php?title=References_notes_and_floats/Simple_bibliography&oldid=43612"