Changes

<br/>

A bibTEX file looks like this:

</pre>

<br/>

<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.

</pre>

<br/>

<br/>

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

</pre>

<br/>

and

and

</pre>

<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:

</pre>

<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">

<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>

</pre>

<br/>

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:

</pre>

<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:

</pre>

<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:

</pre>

<br/>

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:

</pre>

<br/>

<br/>

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

</pre>

<br/>

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

</pre>

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:

</pre>

<br/>

<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.

</pre>

<br/>

There are three test macros:

</pre>

<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:

</pre>

<br/>

<br/>

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

</pre>

<br/>

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

</pre>

<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:

</pre>

<br/>

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

</pre>

(Hans Ha­gen and Ton Ot­ten, Luigi Scarso)

<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:

</pre>

<br/>

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.

</pre>

<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

</pre>

<br/>

<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:

<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.

</pre>

<br/>

The dataset has to be con­verted to xml:

</pre>

<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:

</pre>

<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:

</pre>

|}

</pre>

{|

<br/>

Here is an­other ex­am­ple:

</pre>

{|

<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.

</pre>

{|

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):

</pre>

<br/>

<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:

</pre>

<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:

</pre>

<br/>

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.

</pre>

<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>