Changes

==The data­base==

<br/>

A bibTEX file looks like this:

author = "An Author and Another One",

title = "A hopefully meaningful title",

<br/>

In the old MkII setup we have two kinds of en­tries: the ones that come from the bibTEX run and user sup­plied ones. We no longer rely on bibTEX out­put but we do still sup­port the user sup­plied de­f­i­n­i­tions. These were in fact pre­pared in a way that suits the pro­cess­ing of bibTEX gen­er­ated en­tries. The next vari­ant re­flects the ConTEXt re­cod­ing of the old bibTEX out­put.

\artauthor[]{Hans}[H.]{}{Hagen}

\arttitle{Who knows more?}

<br/>

In the new setup we sup­port these vari­ants as well:

\author{Hans Hagen}

\title{Who knows who?}

<br/>

and

\author{Hans Hagen}

\title{Who knows who?}

<br/>

and

\tag{Hagen:Third}

\category{article}

<br/>

Be­cause in­ter­nally the en­tries are Lua ta­bles, we also sup­port load­ing of Lua based de­f­i­n­i­tions:

["Hagen:First"] = {

author = "Hans Hagen",

<br/>

Files set up like this can be loaded too. The fol­low­ing xml in­put is rather close to this, and is also ac­cepted as in­put.

<bibtex>

<entry tag="Hagen:First" category="article">

You can load more data than you ac­tu­ally need. Only en­tries that are re­ferred to ex­plic­itly through the <tt>\cite</tt> and <tt>\nocite</tt> com­mands will be shown in lists. We will cover these de­tails later.

==Com­mands in en­tries==

One un­for­tu­nate as­pect com­monly found in bibTEX files is that they of­ten con­tain TEX com­mands. Even worse is that there is no stan­dard on what these com­mands can be and what they mean, at least not for­mally, as bibTEX is a pro­gram in­tended to be used with many vari­ants of TEX style: plain, LATEX, and oth­ers. This means that we need to de­fine our use of these type­set­ting com­mands. How­ever, in most cases, they are just ab­bre­vi­a­tions or font switches and these are of­ten known. There­fore, ConTEXt will try to re­solve them be­fore re­port­ing an is­sue. In the log file there is a list of com­mands that has been seen in the loaded data­bases. For in­stance, load­ing <tt>tugboat.bib</tt> gives a long list of com­mands of which we show a small set here:

publications > standard CONTEXT 1 known

publications > standard ConTeXt 4 known

<br/>

You can de­fine un­known com­mands, or over­load ex­ist­ing de­f­i­n­i­tions in the fol­low­ing way:

\definebtxcommand\sltt{\tt}

\definebtxcommand\<#1>{\type{#1}}

<br/>

Un­known com­mands do not stall pro­cess­ing, but their names are then type­set in a mono- spaced font so they prob­a­bly stand out for proof­read­ing. You can ac­cess the com­mands with <tt>\btxcommand{...}</tt>, as in:

<br/>

As this is an un­de­fined com­mand we get: “com­mands like MySpe­cial­Com­mand are han­dled in an in­di­rect way”.

Nor­mally in a doc­u­ment you will use only one bib­li­o­graphic data­base, whether or not dis­trib­uted over mul­ti­ple files. Nev­er­the­less we sup­port mul­ti­ple data­bases as well which is why we talk of datasets in­stead. A dataset is loaded with the <tt>\usebtxdataset</tt> com­mand. Al­though cur­rently it is not nec­es­sary to de­fine a (de­fault) dataset you can best do this be­cause in the fu­ture we might pro­vide more op­tions. Here are some ex­am­ples:

\usebtxdataset[standard][tugboat.bib]

\usebtxdataset[standard][mtx-bibtex-output.xml]

<br/>

In this doc­u­ment we use some ex­am­ple data­bases, so let’s load one of them now:

\usebtxdataset[example][mkiv-publications.bib]

<br/>

You can ask for an overview of en­tries in a dataset with:

<br/>

this gives:

<br/>

You can set the cur­rent ac­tive dataset with

</pre>

<br/>

<br/>

If you want to see what pub­li­ca­tions are in the data­base, the eas­i­est way is to ask for a com­plete list:

[example]

[dataset=example,

[example]

[criterium=all]

<br/>

This gives:1 Ha­gen, H. and Ot­ten, T. (1996). Type­set­ting ed­u­ca­tion doc­u­ments2 Scarso, L. (2021). De­sign­ing high speed trains3 au­thor (year). ti­tle pages p.

<br/>

There are a cou­ple of ac­ces­sors and helpers to get the job done. When you want to fetch a field from the cur­rent en­try you use <tt>\btxfield</tt>. In most cases you want to make sure this field has a value, for in­stance be­cause you don’t want fences or punc­tu­a­tion that be­longs to a field.

\bold{\btxfield{title}},

}

<br/>

There are three test macros:

\btxdoif {fieldname}{action when found}

\btxdoifnot {fieldname} {action when not found}

<br/>

An ex­tra con­di­tional is avail­able for test­ing in­ter­ac­tiv­ity:

</pre>

<br/>

<br/>

You can im­prove read­abil­ity by us­ing se­tups, for in­stance:

\btxsetup{btx:apa:author:yes}

} {

<br/>

So, the pre­vi­ous ex­am­ple setup can be rewrit­ten as:

\bold{\btxfield{title}}

\btxcomma

<br/>

There is a spe­cial com­mand for ren­der­ing a (com­bi­na­tion) of au­thors:

\btxflushauthor{editor}

\btxflushauthor[inverted]{editor}

<br/>

In­stead of the last one you can also use:

</pre>

<br/>

Ci­ta­tions are ref­er­ences to bib­li­o­graphic en­tries that nor­mally show up in lists some­place in the doc­u­ment: at the end of a chap­ter, in an ap­pen­dix, at the end of an ar­ti­cle, etc. We dis­cussed the ren­der­ing of these lists in the pre­vi­ous chap­ter. A ci­ta­tion is nor­mally pretty short as its main pur­pose is to re­fer uniquely to a more de­tailed de­scrip­tion. But, there are sev­eral ways to re­fer, which is why the ci­ta­tion sub­sys­tem is con­fig­urable and ex­ten­si­ble. Just look at the fol­low­ing com­mands:

\cite[authoryear][example::demo-003]

\cite[authoryears][example::demo-003]

\cite[authoryear][example::demo-004,demo-003]

\cite[authoryears][example::demo-004,demo-003]

(Hans Ha­gen and Ton Ot­ten)

<br/>

You can tune the way a ci­ta­tion shows up:

\setupbtxcitevariant[authoryear] [sorttype=author,color=darkyellow]

\setupbtxcitevariant[authoryears][sorttype=author,color=darkyellow]

\cite[author][example::demo-004,demo-003]

\cite[authoryear][example::demo-004,demo-003]

<br/>

The <tt>\citation</tt> com­mand is syn­ony­mous but is more flex­i­ble with re­spect to spac­ing of its ar­gu­ments:

\citation[authoryear] [example::demo-004,demo-003]

\citation[authoryears][example::demo-004,demo-003]

A ci­ta­tion vari­ant is de­fined in sev­eral steps and if you re­ally want to know the dirty de­tails, you should look into the <tt>publ-imp-*.mkiv</tt> files. Here we stick to the con­cept.

\btxcitevariant{author}

\stopsetups

<br/>

You can over­load such se­tups if needed, but that only makes sense when you can­not con­fig­ure the ren­der­ing with pa­ra­me­ters. The <tt>\btxcitevariant</tt> com­mand is one of the build in ac­ces­sors and it calls out to Lua where more com­plex ma­nip­u­la­tion takes place if needed. If no ma­nip­u­la­tion is known, the field with the same name (if found) will be flushed. A com­mand like <tt>\btxcitevariant</tt> as­sumes that a dataset and spe­cific tag has been set. This is nor­mally done in the wrap­per macros, like <tt>\cite</tt>. For spe­cial pur­poses you can use these com­mands

\setbtxentry[hh2013]

</pre>

<br/>

Un­less you use <tt>criterium=all</tt> only pub­li­ca­tions that are cited will end up in the lists. You can force a ci­ta­tion into a list us­ing <tt>\usecitation</tt>, for ex­am­ple:

</pre>

<br/>

<br/>

The en­tries are col­lected in datasets and each set has a unique name. In this doc­u­ment we have the set named <tt>example</tt>. A dataset ta­ble has sev­eral fields, and prob­a­bly the one of most in­ter­est is the <tt>luadata</tt> field. Each en­try in this ta­ble de­scribes a pub­li­ca­tion:

["author"]="Hans Hagen",

["category"]="book",

</pre>

This is <tt>publications.datasets.example.luadata["demo-001"]</tt>. There can be a com­pan­ion en­try in the par­al­lel <tt>details</tt> ta­ble.

["author"]={

{

<br/>

You can loop over the en­tries us­ing reg­u­lar Lua code com­bined with MkIV helpers:

context.starttabulate { "|l|l|l|" }

for tag, entry in table.sortedhash(dataset.luadata) do

<br/>

Once a dataset is ac­ces­si­ble as xml tree, you can use the reg­u­lar <tt>\xml...</tt> com­mands. We start with load­ing a dataset, in this case from just one file.

<br/>

The dataset has to be con­verted to xml:

<br/>

The tree is now ac­ces­si­ble by its root ref­er­ence <tt>btx:tugboat</tt>. If we want sim­ple field ac­cess we can use a few se­tups:

\xmlsetsetup{#1}{bibtex|entry|field}{btx:*}

\xmlmain{#1}

\stopxmlsetups

\startxmlsetups btx:field

\xmlflushcontext{#1}

<br/>

The two se­tups are pre­de­fined in the core al­ready, but you might want to change them. They are ap­plied in for in­stance:

\NC \type {tag} \NC \xmlfirst {btx:tugboat}

{/bibtex/entry[string.find(@tag,'Hagen')]/attribute('tag')}

\NC \NR

\stoptabulate

{|

|}

\xmlcommand

{#1}

{/bibtex/entry[string.find(@tag,'Hagen')][1]}{btx:table}

\stopxmlsetups

\startxmlsetups btx:table

\starttabulate[|||]

<br/>

Here is an­other ex­am­ple:

\NC \xmlatt{#1}{tag}

\NC \xmlfirst{#1}{/field[@name='title']}

\NC \NR

\stopxmlsetups

\startxmlsetups btx:demo

\xmlfilter {#1} {

<br/>

A more ex­ten­sive ex­am­ple is the fol­low­ing. Of course this as­sumes that you know what xml sup­port mech­a­nisms and macros are avail­able.

\xmladdsortentry{btx}{#1}{\xmlfilter{#1}{/field[@name='author']/text()}}

\xmladdsortentry{btx}{#1}{\xmlfilter{#1}{/field[@name='year' ]/text()}}

\xmladdsortentry{btx}{#1}{\xmlatt{#1}{tag}}

\stopxmlsetups

\startxmlsetups btx:sorter

\xmlresetsorter{btx}

In the orig­i­nal bib­li­og­ra­phy sup­port mod­ule us­age was as fol­lows (ex­am­ple taken from the con­textgar­den wiki):

\usemodule[bib]

\usemodule[bibltx]

<br/>

In the new ap­proach we no longer use bibTEXso we don’t need to setup bibTEX. In­stead we de­fine dataset(s). We also no longer set up pub­li­ca­tions with one com­mand, but have split that up in ren­der­ing-, list-, and cite-vari­ants. The ba­sic <tt>\cite</tt> com­mand re­mains. The above ex­am­ple be­comes:

[document]

\usebtxdataset

<br/>

So, we have a few more com­mands to set up things. If you in­tend to use just a sin­gle dataset and ren­der­ing, the above pre­am­ble can be sim­pli­fied to:

[mybibfile.bib]

\setupbtxrendering

As TEX and Lua are both open and ac­ces­si­ble in ConTEXt it is pos­si­ble to ex­tend the func­tion­al­ity of the bib­li­og­ra­phy re­lated code. For in­stance, you can add ex­tra load­ers.

local t = { }

-- Load data from 'filename' and convert it to a Lua table 't' with

<br/>

This then per­mits load­ing a data­base (into a dataset) with the com­mand:

</pre>

<br/>

The <tt>myformat</tt> suf­fix is rec­og­nized au­to­mat­i­cally. If you want to use an­other suf­fix, you can do this:

</pre>