References notes and floats/Bibliography and citations

• Support for bibliographies is integrated in MkIV’s and LMTX’s core (for the curious, the files are named bibl-tra . Two other important sources of information are:
  • Bibliographies manual
  • From BibTEX to ConTEXt mkiv , a 2014 presentation about BibTeX and the state of Bibliography in MkIV.
  For older ConTeXt MkII, support for bibliographies was added by Taco. The Bibliography mkii page explains a few basic facts and points you to the manual of the module.
• TeX offers excellent ways to handle bibliographic references. BibTeX allows you to use a database to manage your references and to insert citations and a list of references into your document. If you’re completely new to this subject, you should probably begin to read some basic hints about BibTeX databases. You will find a good selection of resources (most of them are free and available on-line) at the section “Bibliographies and Citations” of the [ TeX faq ]. A good place for beginners is Nicolas Markey’s [ Tame the Beast ]. If you have TeXLive installed, it may already be on your hard disk.

Quickstart

From the manual:

\usebtxdataset[mkiv-publications.bib]
\starttext

\startbodymatter
a citation: \cite[article,book]
\stopbodymatter

\startbackmatter
    \startchapter[title=Bibliography]
        \placelistofpublications
    \stopchapter
\stopbackmatter

\stoptext

Before using any database: the buffer method

Before using a bibliographic database built with tools such as JabRef or Zotero (among others), it is possible to use the BibTeX format for bibliographic data by buffering it. With ConTexT MKIV, a relatively simple document of a few pages can be composed with simple commands such as \startbuffer .... \stopbuffer, between which you copy all the bibliographic references to be used in the text like this :

\startbuffer[biblio]

@Book{cicero-tuscu2011,
 author     = {Cicero, Marcus Tullius},
 editor     = {Fohlen, G.},
 publisher  = {Les Belles Lettres},
 title      = {Tusculanes},
 year       = {2011},
 address    = {Paris},
 edition    = {7e tirage},
 isbn       = {9782251010830},
 series     = {œuvres philosophiques},
 volume     = {1},
 ppn_gvk    = {1823774121},
 translator = {Jules Humbert},
}

@Book{Aristote2008,
 Title                    = {Les Politiques},
 Author                   = {Aristote},
 Editor                   = {Pellegrin, Pierre},
 Publisher                = {Garnier-Flammarion},
 Year                     = {2008},
 Address                  = {Paris, France},
 Series                   = {Le monde de la philosophie},
 Date                     = {2008},
 ISBN                     = {978-2-08-121816-1},
 Location                 = {Paris, France},
 Pagetotal                = {xxiii+518},
 Translator               = {Pierre Pellegrin}
}
\stopbuffer

• Next, we will write text between the starttext and stoptext tags, before defining how the references will be printed after the body of the text, in the area defined for the table of contents (and possibly the various indexes, index rerum and index nominum). For the simplest texts, the bibliographic references after the \stopbuffer command can, for example, be defined (with our example) as follows:

\usebtxdataset[ancient philosophy][biblio.buffer]

\usebtxdefinitions[apa]

\definebtxrendering[ancient philosophy][apa][dataset=ancient philosophy]

\setupbtxrendering[continue=yes]

• As you can see, the memory buffer named 'biblio' will be associated with a database named 'ancient philosophy'; the format will follow the American Psychological Association (APA) model. We are writing a short text on Aristotle and Cicero with two bibliographical references in footnotes (one for each philosopher).

• Then, we have to give place to what is called 'backmatter', say the the space where the bibliographic references given in the text will be printed, either in the body of the text or, as in our example, as footnotes. In this way, at the end of the document, all the references used from the buffer are summarised. Personally, I find the buffer method simple and easy, but much less powerful and convenient than the method of feeding a bibliographic file, constructed in the form *.bib, using software such as JabRef. ConTeXt will fetch the references from this file as and when they are called up using the \cite command, instead of having to copy each reference into the buffer.

Below is a complete sample using a buffer method:

\startbuffer[biblio]

@Book{cicero-tuscu2011,
 author     = {Cicéron, Marcus Tullius},
 editor     = {Fohlen, G.},
 publisher  = {Les Belles Lettres},
 title      = {Tusculanes},
 year       = {2011},
 address    = {Paris},
 edition    = {7e tirage},
 isbn       = {9782251010830},
 series     = {œuvres philosophiques},
 volume     = {1},
 ppn_gvk    = {1823774121},
 translator = {Jules Humbert},
}

@Book{Aristote2008,
 Title                    = {Les Politiques},
 Author                   = {Aristote},
 Editor                   = {Pellegrin, Pierre},
 Publisher                = {Garnier-Flammarion},
 Year                     = {2008},
 Address                  = {Paris, France},
 Series                   = {Le monde de la philosophie},
 Date                     = {2008},
 ISBN                     = {978-2-08-121816-1},
 Location                 = {Paris, France},
 Pagetotal                = {xxiii+518},
 Translator               = {Pierre Pellegrin}
}
\stopbuffer

\usebtxdataset[ancient philosophy][biblio.buffer]

\usebtxdefinitions[apa]

\definebtxrendering[ancient philosophy][apa][dataset=ancient philosophy]

\setupbtxrendering[continue=yes]

\starttext

\startchapter[title={An Introduction To Philosophy}]

In the notes that follow, we will focus on philosophical thought as political philosophy. Aristotle, the Greek philosopher who published and commented on the Constitutions of the ancient Greek cities, begins his work {Politics} with the thesis that {man is a political animal}\footnote{\cite[alternative=entry][ancient philosophy::Aristote2008]}.


Cicero, the great politician and scholarly writer, had the well-known phrase, \quotation{Socrates brought philosophy down from heaven to earth.}\footnote{\cite[alternative=entry][ancient philosophy::cicero-tuscu2011]}, which refers to the fundamental question of philosophy's interest in {\it human things}.


\stopchapter

\starttext

\startbackmatter

\startchapter[title={Bibliographie}]

\startsection[title={Ancient Philosophy}]


\placelistofpublications[ancient philosophy][method=local]

\stopsection

\stopchapter

\stopbackmatter

\stoptext

Here is another, more minimal example that additionally sets a default dataset and enables some tracing:

\startbuffer[testdata]
@Book{sometag,
	author = {Some Person},
	title = {An awesome title},
	year = {1900},
	publisher = {Foo},
}
@Article{someother,
	author = {Some Otherperson},
	title = {Another title},
	year = {1900},
}
\stopbuffer

% enable tracing
\enabletrackers[publications, publications.crossref, publications.details, publications.cite, publications.strings]

\usebtxdataset[main][testdata.buffer]
\usebtxdefinitions[aps]
\setupbtx[dataset=main]
\definebtxrendering[bibrendering][aps][dataset=main]

\starttext

Some person said something \cite[sometag].

\placelistofpublications[bibrendering]

\stoptext

Database Formats

ConTeXt can read several different formats of bibliographic databases:

BibTeX .bib format

ConTeXt is independent from the BibTeX program, but can read .bib databases, if they’re not too polluted with non-standardized (LaTeX) commands. This format is the oldest, but supported by most bibliography management programs. The other supported formats use the same structure of records, just ported to different “languages”.

A BibTeX database is a text file, consisting of entries like:

@Article {Hagen2010,
 author = "One or more authors",
 title = "Some interesting title",
 journal = "Publisher’s Weekly",
 volume = "27",
 number = "2",
 pages = "21--30",
 month = may,
 year = "2020",
 ISSN = "1234-5678"
}

@Article is an example for a common category, like @Book, @unpublished etc. Letter case doesn’t matter. The first argument reference must not contain spaces and is ended with a comma. Spacing within an entry doesn’t matter. If values consist of only one word, you don’t need quotes, otherwise you can also use brackets.

ConTeXt understands UTF-8 encoded bib files as well as old fashioned TeX accent combinations.

Fields

Some known fields of @Article are (see manual p.19 ):

• Title (also Title:en, Title:de etc.), Subtitle
• Author (see manual for possible formats)
• Journal, Type, Number, Volume, Pages, Review
• Year, Month, Day
• Warning, Comment, Note
• XCrossref
• Doi
• Keywords
• Language
• Url
• author, editor: fields are parsed as "Firstname(s) Lastname", multiple entries separated by 'and' (see manual p.6/14)
• keywords: separated by semicolons

There’s a (complete?) overview of categories and their fields in the manual on page 18 (Table 3.2).

Commands in entries

you can define unknown commands like this:

\definebtxcommand\TUB {TUGboat}
\definebtxcommand\sltt{\tt}
\definebtxcommand\<#1>{\type{#1}}

btx commands use a separate namespace.

MkII .bbl format

This intermediate format is still supported, but obsolete. Just an example to let you know what it means:

\startpublication[k=Hagen:Second,t=article,a={Hans Hagen},y=2013,s=HH01] 
    \artauthor[]{Hans}[H.]{}{Hagen}
    \arttitle{Who knows more?}
    \journal{MyJournal}
    \pubyear{2013}
    \month{8}
    \volume{1}
    \issue{3}
    \issn{1234-5678}
    \pages{123--126}
\stoppublication

Lua tables

Since internally everything anyway are Lua tables, you can use them directly as a database format:

   return { ["Hagen:First"] = {
       author = "Hans Hagen",
       category = "article",
       issn = "1234-5678",
       issue = "3",
       journal = "MyJournal",
       month = "8",
       pages = "123--126",
       tag = "Hagen:First",
       title = "Who knows nothing?",
       volume = "1",
       year = "2013", },
   }

XML

    <?xml version="2.0" standalone="yes" ?>
    <bibtex>
        <entry tag="Hagen:First" category="article">
            <field name="author">Hans Hagen</field>
            <field name="category">article</field>
            <field name="issn">1234-5678</field>
            <field name="issue">3</field>
            <field name="journal">MyJournal</field>
            <field name="month">8</field>
            <field name="pages">123--126</field>
            <field name="tag">Hagen:First</field>
            <field name="title">Who knows nothing?</field>
            <field name="volume">1</field>
            <field name="year">2013</field>
        </entry>
    </bibtex>

Setup

\usebtxdataset[default][mybooks.bib]
\setupbtx[dataset=default]
\usebtxdefinitions[apa] % see p.15
\placelistofpublications

• The mentioned database file formats are recognized by their extension: .bib, .bbl., .lua and .xml
• default is the name for this database. If you load several files into the same name space, they get merged.
• \definebtxrendering , \setupbtxrendering

\definebtxrendering[example][apa][%  setup "example" inherits from "apa"
  specification=apa,
  sorttype=authoryear,
  numbering=no
]

sorttypes

• default, none, cite, list: don’t sort, use original order
• dataset, index: sort after dataset index
• reference: sort by reference tag
• key: sort by key (traditionally used in BibTeX as sortkey)
• short: sort by short
• authoryear: sort by author(s) and publication year

bib list rendering

See manual, p.24ff.

\setupbtxlist[apa][
  alternative=paragraph,
  width=fit,
  distance=.5em,
  margin=3em % hanging list
]

Predefined renderings include:

• apa (by American Psychological Assoc.)
• mla
• chicago
• harvard
• ieee,
• aps (used in physical sciences)
• vancouver (used in biological sciences)
• sbl (used in theology), external project

Note: Only apa, aps, and chicago styles are currently provided as a showcase.

The vertical distance between entries can be modified using the before argument; for instance,

\setupbtxlist[apa][
    before=\vskip-1ex,
]

gives a tighter bibliography.

Language

Bibliography lists and citations are rendered in the language of the document (\mainlanguage). If an entry includes a language field, this can be used, depending on the rendering specification.

You can force the main language on all entries with \setupdelimitedtext[language=global].

You can define and use translated titles with language modifiers, e.g. title:de or booktitle:fr.

Complex example

To see how the concepts play together, here a relatively complete example:

\definebtxdataset[main] % choose a name for a dataset to use
\usebtxdataset[main][testbib.bib] % fill the dataset with bib entries
\setupbtx[dataset=main] % make \cite use our dataset by default
\setupbtx[default:cite][alternative=authoryear] % make \cite[ref] work like \cite[authoryear][ref]
\usebtxdefinitions[apa] % activate apa style for \cite rendering (also *load* apa style for bib entry rendering)
\setupbtx[apa:cite][otherstext={ et al.}] % modify the apa \cite rendering style (remove comma after sole author name)
\definebtxrendering[mainlist][apa][dataset=main] % define a bib entry rendering to use with \placebtxrendering

% in the document:
\placebtxrendering[mainlist][method=global]

Citations

See p.31ff. of the manual. E.g.

\cite[num][reference] % [77]
\cite[authoryear][reference] % (Hagen 1977)
\cite[short][reference] % [HHH+77b]
and even
\cite[num][ref1,ref2,ref3] % [2,15,77] see p.35f.

The first argument defaults to the default citation rendering, as defined by \setupbtx[default:cite][alternative=num].

Custom bibliographical styles

Users who wish to develop their own custom styles could start with the files in the distribution, copy them to different names and then modify them (e.g., the files publ-imp-apa.lua and publ-imp-apa.mkvi). However, these files contain a number of advanced code to deal with the numerous exceptions and rules. Hence, in some cases, it may be easier to write your own custom style. Here, I will provide you with an example what a minimal setup will be to get you started. Once you have a style in place and understand what's needed, it is easy to experiment further.

Files

For every style, you will need two files: one with the TeX setups and one with the Lua definitions. They have to follow the naming conventions that the bibliographic subsystem expects so they can be found. If your style is called mycustom, these two files should be publ-imp-mycustom.mkiv and publ-imp-mycustom.lua.

The Lua code

A minimal Lua file can be very brief. It has to contain a little bit of boiler plate with the required tables and the "categories" (i.e. publication types) that your bibliography will process. A minimal example will look like this:

local specification = {
  name      = "mycustom",
  categories = { },
}

local categories = specification.categories

categories.book = {
  required = { "title" },
  optional = {"author", "editor",
  "year", "editor",
  "edition", "series", "volume", "number",
  "address", "publisher",
  },
}
return specification

For every type publicationtype you want processed, you need an entry categories.publicationtype. This entry needs to have a list of fields that will be processed, divided into "required" fields (that every entry needs to have) and "optional" fields (that they may or may not have). Every book needs to have a title, but not necessarily an author. Remember: only types that have a category will be processed. Only fields that are listed in the category will be processed.

The TeX code

The TeX file is where the formatting is done. Again, you need to start with a few lines that make the publ-imp-mycustom.mkiv file work:

\startbtxrenderingdefinitions[mycustom]

\definebtx
  [mycustom]
  [default=default,
   specification=mycustom]

\definebtxrendering
  [mycustom]
  [specification=mycustom,
   numbering=yes]

\stopbtxrenderingdefinitions

This will make ConTeXt use your definitions. Further on, you include formatting directives for every type of publication you have included in your Lua file. If you want to modify the way the cite command will be displayed, these directives will be in the form \startsetups btx:mycustom:cite. For formatting the bibliographic list, they will be in the form \startsetups btx:mycustom:list:categroy. In our example, the only category is "book," so that's what our minimal definition will look like:

\startsetups btx:mycustom:list:book
  \btxdoif {author} {
      \color[blue]{\btxflush{author}}
  \btxcomma
  }
   \btxdoifelse {title} {
       \color[red]{\btxflush{title}}
   } {
       No Title
   }
  \removeunwantedspaces
\stopsetups

The most important command here is the btxflush: it will typeset the corresponding field of your bibliographic entry. You include it within formatting directives. As you can see, in our example, the author name will be typeset in blue; the title will be typeset in red. In the first section, btxdoif {author} checks whether there is a field "author"; if it exists, it will be typeset; if it doesn't exist, nothing happens. In the second example, the btxdoifelse {title} checks whether the field "title" exists. If it exists, the code within the first pair of braces will be executed, i.e., the title will be typeset in red. If it doesn't exist, the second pair of braces will be executed, and ConTeXt will typeset "No Title" in your document.

This should get you started with your custom style and let you experiment to your heart's content. The fields will be typeset in the order in which you include them in the setups. If you want to know more about these fields and about the commands that are available, check Chapter 6 of mkiv-publications.pdf.

Simple manual bibliography

If you don’t need bibliographical databases, but just references within one document, this approach might be enough for you:

% LMTX: 
\tolerant\def\startbibitem[#1]#*[#2]% LMTX!
	{\doifsomethingelse{#2}%
    {\startBibItem[reference={#1},title={#2}]}%
    {\startBibItem[reference={#1},title={#1}]}%
}
\def\stopbibitem{\stopBibItem}

% MkIV:
%\def\dostartbibitem[#1][#2]%
%	{\doifsomethingelse{#2}%
%    {\startBibItem[reference={#1},title={#2}]}%
%    {\startBibItem[reference={#1},title={#1}]}%
%}
%\def\startbibitem{\dodoubleempty\dostartbibitem}
%\def\stopbibitem{\stopBibItem}

\definedescription[BibItem][
	width=broad,
	margin=4em,
	indenting={no},
	indentnext=no,
	alternative=hanging,
	hang=1,
	headcommand=\gobbleoneargument,
	align=flushleft
]

\def\bibitemrule{\noindentation\vrule height0.5pt width4em depth0pt\thinspace}

\definereferenceformat [cite]  [type=title,left={},right={}]
\definereferenceformat [bibpage]   [type=page]

\starttext

\section{Content}

While we wait for the perfect book about ConTeXt\footnote{Maybe \cite[Hagen 2050]}, we can at least read a nice novel (\cite[Hagen 2014]).

\section{Bibliography}

\startbibitem[Hagen 2014]
Hagen, Hans: \emph{The Cow in the Ridderstraat.} Hasselt 2014.
\stopbibitem

\startbibitem[Hagen 2050]
\bibitemrule \emph{ConTeXt complete compendium.} Hasselt 2050.
\stopbibitem

\startbibitem[Hagen 2060][The Wizard 1899] % First parameter is reference, second gets displayed
\bibitemrule \emph{Optional differing reference title.} Hasselt 2060
\stopbibitem

\stoptext

See also : Simple bibliography

Here’s a similar approach using \defineitemgroup.

Miscelaneous tips

Colored links in bibliography entries

By default, bibliography entries link to the first point where they are cited. A side-effect is that if interactions are set to colored links (e.g. with \setupinteraction[state=start,color=blue]), the whole entries get colored, and external links they contain may not stand out. One possible workaround is to add \setupinteraction[color=] just before \placelistofpublications.