__TOC__<h1>The database</h1>
<h1>The database</h1> The <span tag="MKIV" style="font-style:sans;">bibTEX</span> format format is rather popular popular in the <span tag="MKIV" style="font-style:sans;">TEX</span> community community and even with its shortcomings shortcomings it will stay around for a while. Many publication websites publication websites can export export and many tools are available available to work with this database formatdatabase format. It is rather simple simple and looks a bit like <span tag="MKIV" style="font-style:sans;">Lua</span> tablestables. Unfortunately Unfortunately the content content can be polluted polluted with non-standardized standardized <span tag="MKIV" style="font-style:sans;">TEX</span> commands commands which complicates complicates pre- or postprocessing outside postprocessing outside <span tag="MKIV" style="font-style:sans;">TEX</span>. In that sense a <span tag="MKIV" style="font-style:sans;">bibTEX</span> database database is often often not coded neutrallyneutrally. Some limitationslimitations, like the use of commands commands to encode accented characters encode accented characters root in the <span tag="MKIV" style="font-style:sans;">ascii</span> world and can be bypassed bypassed by using using <span tag="MKIV" style="font-style:sans;">utf</span> instead instead (as handled somewhat handled somewhat in <span tag="MKIV" style="font-style:sans;">LATEX</span> through extensions extensions such as <tt style="color:rgb(0,102,102);font-size:100%;" >bibtex8</tt>).
<p></p>
The normal normal way to deal with a bibliography bibliography is to refer refer to entries using entries using a unique tag or key. When a list of entries entries is typesettypeset, this reference reference can be used for linking purposeslinking purposes. The typeset typeset list can be processed and sorted using using the <tt style="color:rgb(0,102,102);font-size:100%;" >bibtex</tt> program program that converts converts the database database into something something more <span tag="MKIV" style="font-style:sans;">TEX</span> friendly (a <tt style="color:rgb(0,102,102);font-size:100%;" >.bbl</tt> file). I never used the program myself program myself (nor bibliographiesbibliographies) so I will not go into too much detail detail here, if only because because all I say can be wrong.
<p></p>
In <span tag="MKIV" style="font-style:sans;">ConTEXt</span> we no longer use the <tt style="color:rgb(0,102,102);font-size:100%;" >bibtex</tt> programprogram: we just use database database files and deal with the necessary manipulations directly necessary manipulations directly in <span tag="MKIV" style="font-style:sans;">ConTEXt</span>. One or more such databases databases can be used and combined combined with additional entries defined additional entries defined within the documentdocument. We can have several several such datasets active active at the same time.
<p></p>
A <span tag="MKIV" style="font-style:sans;">bibTEX</span> file looks like this:
</pre>
<p></p>
Normally Normally a value is given between between quotes (or curly bracketsbrackets) but single single words are also OK (there is no real benefit benefit in not using using quotes, so we advise advise to always always use them). There can be many more fields and instead instead of strings one can use predefined shortcutspredefined shortcuts. The title title for example example quite often contains often contains <span tag="MKIV" style="font-style:sans;">TEX</span> macros. Some fields, like <tt style="color:rgb(0,102,102);font-size:100%;" >pages</tt> have funny characters characters such as the endash endash (typically typically as <tt style="color:rgb(0,102,102);font-size:100%;" >--</tt>) so we have a mixture mixture of data and typesetting directivestypesetting directives. If you are covering covering non--english referencesenglish references, you often often need characters characters that are not in the <span tag="MKIV" style="font-style:sans;">ascii</span> subset subset but <span tag="MKIV" style="font-style:sans;">ConTEXt</span> is quite happy with <span tag="MKIV" style="font-style:sans;">utf</span>. If your database database file uses old-fashioned fashioned <span tag="MKIV" style="font-style:sans;">TEX</span> accent commands accent commands then these will be internally converted automatically internally converted automatically to <span tag="MKIV" style="font-style:sans;">utf</span>. Commands Commands (macros) are converted converted to an indirect indirect call, which is quite robustrobust.
<p></p>
The <span tag="MKIV" style="font-style:sans;">bibTEX</span> files are loaded in memory memory as <span tag="MKIV" style="font-style:sans;">Lua</span> table table but can be converted converted to <span tag="MKIV" style="font-style:sans;">xml</span> so that we can access access them in a more flexible flexible way, but that is a subject subject for specialistsspecialists.
<p></p>
In the old <span tag="MKIV" style="font-style:sans;">MkII</span> setup we have two kinds of entriesentries: the ones that come from the <span tag="MKIV" style="font-style:sans;">bibTEX</span> run and user supplied supplied ones. We no longer rely on <span tag="MKIV" style="font-style:sans;">bibTEX</span> output output but we do still support support the user supplied definitionssupplied definitions. These were in fact prepared prepared in a way that suits the processing processing of <span tag="MKIV" style="font-style:sans;">bibTEX</span> generated entriesgenerated entries. The next variant reflects variant reflects the <span tag="MKIV" style="font-style:sans;">ConTEXt</span> recoding recoding of the old <span tag="MKIV" style="font-style:sans;">bibTEX</span> outputoutput.
<pre style="color:rgb(102,0,102);font-size:100%">\startpublication[k=Hagen:Second,t=article,a={Hans Hagen},y=2013,s=HH01]
</pre>
<p></p>
The split <tt style="color:rgb(0,102,102);font-size:100%;" >\artauthor</tt> fields are collapsed collapsed into a single single <tt style="color:rgb(0,102,102);font-size:100%;" >author</tt> field as we deal with the splitting splitting later when it gets parsed in <span tag="MKIV" style="font-style:sans;">Lua</span>. The <tt style="color:rgb(0,102,102);font-size:100%;" >\artauthor</tt> syntax syntax is only kept around for backward compatibility backward compatibility with the previous previous use of <span tag="MKIV" style="font-style:sans;">bibTEX</span>.
<p></p>
In the new setup we support support these variants variants as well:
<pre style="color:rgb(102,0,102);font-size:100%">\startpublication[k=Hagen:Third,t=article]
</pre>
<p></p>
Because internally Because internally the entries entries are <span tag="MKIV" style="font-style:sans;">Lua</span> tablestables, we also support loading support loading of <span tag="MKIV" style="font-style:sans;">Lua</span> based definitionsdefinitions:
<pre style="color:rgb(102,0,102);font-size:100%">return {
</pre>
<p></p>
Files set up like this can be loaded too. The following following <span tag="MKIV" style="font-style:sans;">xml</span> input input is rather close to this, and is also accepted accepted as inputinput.
<pre style="color:rgb(102,0,102);font-size:100%"><?xml version="2.0" standalone="yes" ?>
</pre>
<p></p>
Todo: Add some remarks remarks about loading EndNote loading EndNote and RIS formatsformats, but first we need to complete complete the tag mapping mapping (on Alan’s plate).
<p></p>
So the user has a rather wide choice of formatting formatting style for bibliography database bibliography database files.
You can load more data than you actually actually need. Only entries entries that are referred referred to explicitly explicitly through the <tt style="color:rgb(0,102,102);font-size:100%;" >\cite</tt> and <tt style="color:rgb(0,102,102);font-size:100%;" >\nocite</tt> commands commands will be shown in lists. We will cover these details details later.
<h1>Commands Commands in entriesentries</h1>
One unfortunate aspect commonly unfortunate aspect commonly found in <span tag="MKIV" style="font-style:sans;">bibTEX</span> files is that they often contain often contain <span tag="MKIV" style="font-style:sans;">TEX</span> commandscommands. Even worse is that there is no standard standard on what these commands commands can be and what they mean, at least not formallyformally, as <span tag="MKIV" style="font-style:sans;">bibTEX</span> is a program intended program intended to be used with many variants variants of <span tag="MKIV" style="font-style:sans;">TEX</span> style: plain, <span tag="MKIV" style="font-style:sans;">LATEX</span>, and othersothers. This means that we need to define define our use of these typesetting commandstypesetting commands. HoweverHowever, in most cases, they are just abbreviations abbreviations or font switches and these are often often known. ThereforeTherefore, <span tag="MKIV" style="font-style:sans;">ConTEXt</span> will try to resolve resolve them before reporting before reporting an issueissue. In the log file there is a list of commands commands that has been seen in the loaded databasesdatabases. For instanceinstance, loading loading <tt style="color:rgb(0,102,102);font-size:100%;" >tugboat.bib</tt> gives a long list of commands commands of which we show a small set here:
<pre style="color:rgb(102,0,102);font-size:100%">publications > start used btx commands
</pre>
<p></p>
You can define unknown commandsdefine unknown commands, or overload existing definitions overload existing definitions in the following following way:
<pre style="color:rgb(102,0,102);font-size:100%">\definebtxcommand\TUB {TUGboat}
</pre>
<p></p>
Unknown commands Unknown commands do not stall processingprocessing, but their names are then typeset typeset in a mono- spaced font so they probably probably stand out for proofreadingproofreading. You can access access the commands commands with <tt style="color:rgb(0,102,102);font-size:100%;" >\btxcommand{...}</tt>, as in:
<pre style="color:rgb(102,0,102);font-size:100%">commands like \btxcommand{MySpecialCommand} are handled in an indirect way
</pre>
<p></p>
As this is an undefined command undefined command we get: “commands “commands like MySpecialCommand MySpecialCommand are handled handled in an indirect indirect way”.
<p></p>
??
<h1>Datasets</h1>
Normally Normally in a document document you will use only one bibliographic databasebibliographic database, whether or not distributed distributed over multiple multiple files. Nevertheless Nevertheless we support multiple databases support multiple databases as well which is why we talk of datasets insteadinstead. A dataset is loaded with the <tt style="color:rgb(0,102,102);font-size:100%;" >\usebtxdataset</tt> commandcommand. Although currently Although currently it is not necessary necessary to define define a (defaultdefault) dataset you can best do this because because in the future future we might provide provide more optionsoptions. Here are some examplesexamples:
<pre style="color:rgb(102,0,102);font-size:100%">\definebtxdataset[standard]
</pre>
<p></p>
These three suffixes suffixes are understood understood by the loader. Here the dataset has the name <tt style="color:rgb(0,102,102);font-size:100%;" >standard</tt> and the three database database files are merged, where later entries having entries having the same tag overload previous overload previous ones. Definitions Definitions in the document document source (coded in <span tag="MKIV" style="font-style:sans;">TEX</span> speak) are also added, and they are saved for successive successive runs. This means that if you load and define entriesdefine entries, they will be known at a next run beforehandbeforehand, so that references references to them are independent independent of when loading loading and definitions definitions take place.
<div style="border:thin solid black;" >
<span style="font-style:oblique;" > setup definition setupbtxdataset </span >
</div>
<p></p>
In this document document we use some example databasesexample databases, so let’s load one of them now:
<pre style="color:rgb(102,0,102);font-size:100%">\definebtxdataset[example]
</pre>
<p></p>
You can ask for an overview of entries entries in a dataset with:
<pre style="color:rgb(102,0,102);font-size:100%">\showbtxdatasetfields[example]
</pre>
<p></p>this gives:
<table>
<tr><td>tag</td><td>categorycategory</td><td>fields</td></tr><tr><td>demo-001</td><td>book</td><td>author index title author index title year</td></tr><tr><td>demo-002</td><td>book</td><td>crossref index crossref index year</td></tr><tr><td>demo-003</td><td>book</td><td>author comment index title author comment index title year</td></tr><tr><td>demo-004</td><td>book</td><td>author comment index title author comment index title year</td></tr><tr><td>demo-005</td><td>book</td><td>author author doi index index pages serial title serial title url year</td></tr>
</table>
<p></p>
You can set the current active current active dataset with
<pre style="color:rgb(102,0,102);font-size:100%">\setbtxdataset[standard]
</pre>
<p></p>
but most publicationpublication-related commands accept optional arguments related commands accept optional arguments that denote denote the dataset and references references to entries entries can be prefixed prefixed with a dataset identifieridentifier.. More about that later.<p></p>Sometimes you want to check a database. One way of doing that is the following: <pre style="color:rgb(102,0,102);font-size:100%">\definebtxdataset[check]\usebtxdataset[check][mkiv-publications-check.bib]\showbtxdatasetcompleteness[check]</pre><p></p>The database like like this:<p></p>The completeness check shows (with green field names) the required fields and when one is missing this is indicated in red. In blue we show what gets inherited.
<h1>RenderingsRenderings</h1>
A list of publications publications can be rendered rendered at any place in the documentdocument. A database database can be much larger than needed for a documentdocument. The same is true for the fields that make up an entryentry. Here is the list of fields that are currently handledcurrently handled, but of course there can be additional additional ones:
<p></p>
<tt style="color:rgb(0,102,102);font-size:100%;" >abstract</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >address</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >annotate</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >assignee</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >author</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >bibnumber</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >booktitle</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >chapter</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >comment</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >country</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >day</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >dayfiled</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >doi</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >edition</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >editor</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >eprint</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >howpublished</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >institution</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >isbn</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >issn</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >journal</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >key</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >keyword</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >keywords</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >language</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >lastchecked</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >month</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >monthfiled</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >names</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >nationality</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >note</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >notes</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >number</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >organization</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >pages</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >publisher</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >revision</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >school</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >series</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >size</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >title</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >type</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >url</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >volume</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >year</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >yearfiled</tt>
<p></p>
If you want to see what publications publications are in the databasedatabase, the easiest easiest way is to ask for a complete complete list:
<pre style="color:rgb(102,0,102);font-size:100%">\definebtxrendering
</pre>
<p></p>
This gives:1 HagenHagen, H. and OttenOtten, T. (1996). Typesetting education documentsTypesetting education documents.2 Scarso, L. (2021). Designing Designing high speed trains.3 author author (year). titletitle. pages p.
<p></p>
The rendering itself rendering itself is somewhat complex somewhat complex to set up because because we have not only many different standards different standards but also many fields that can be set up. This means that there are several commands involvedseveral commands involved. Often Often there is a prescribed prescribed style to render bibliographic descriptionsrender bibliographic descriptions, for example example <tt style="color:rgb(0,102,102);font-size:100%;" >apa</tt>. A rendering rendering is setup and defined defined with:
<div style="border:thin solid black;" >
<span style="font-style:oblique;" > setup definition setupbtxrendering </span >
</div>
<p></p>
And a list of such descriptions descriptions is generated generated with:
<div style="border:thin solid black;" >
<span style="font-style:oblique;" > setup definition placebtxrendering </span >
</div>
<p></p>
A dataset can have all kind of entriesentries:
<p></p>
<tt style="color:rgb(0,102,102);font-size:100%;" >article</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >book</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >booklet</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >conference</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >inbook</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >incollection</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >inproceedings</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >manual</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >mastersthesis</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >misc</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >phdthesis</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >proceedings</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >techreport</tt>, <tt style="color:rgb(0,102,102);font-size:100%;" >unpublished</tt><p></p>Each has its own rendering variantrendering variant. To keep things simple simple we have their settings separatedsettings separated. HoweverHowever, these settings settings are shared for all rendering alternativesrendering alternatives. In practice practice this is seldom seldom a problem problem in a publication publication as only one rendering alternative rendering alternative will be activeactive. If this be not sufficientsufficient, you can always always group local settings local settings in a setup and hook that into the specific renderingspecific rendering.
<div style="border:thin solid black;" >
<span style="font-style:oblique;" > setup definition setupbtxlistvariant </span >
</div>
<p></p>
Examples Examples of list variants variants are:
<p></p>
<tt style="color:rgb(102,0,102);font-size:100%;" >setupbtxlistvariant : artauthor</tt>
</table>
<p></p>
<tt style="color:rgb(102,0,102);font-size:100%;" >setupbtxlistvariant : editor</tt>
<p></p>
The exact rendering exact rendering of list entries entries is determined determined by the <tt style="color:rgb(0,102,102);font-size:100%;" >alternative</tt> key and defaults defaults to <tt style="color:rgb(0,102,102);font-size:100%;" >apa</tt> which uses definitions definitions from <tt style="color:rgb(0,102,102);font-size:100%;" >publ-imp-apa.mkiv</tt>. If you look at that file you will see that each category category has its own setup. You may also notice notice that additional additional tests are needed to make sure that empty fields don’t trigger separators trigger separators and such.
<p></p>
There are a couple couple of accessors accessors and helpers to get the job done. When you want to fetch a field from the current entry current entry you use <tt style="color:rgb(0,102,102);font-size:100%;" >\btxfield</tt>. In most cases you want to make sure this field has a value, for instance because instance because you don’t want fences or punctuation punctuation that belongs belongs to a field.
<pre style="color:rgb(102,0,102);font-size:100%">\btxdoif {title} {
</pre>
<p></p>
An extra conditional extra conditional is available available for testing interactivitytesting interactivity:
<pre style="color:rgb(102,0,102);font-size:100%">\btxdoifelseinteraction{action when true}{action when false}
</pre>
<p></p>
In addition addition there is also a conditional conditional <tt style="color:rgb(0,102,102);font-size:100%;" >\btxinteractive</tt> which is more efficientefficient, although although in practice efficiency practice efficiency is not so important important here.
<p></p>
There are three commands commands to flush data:
<table>
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >\btxfield</tt></td><td>fetch a explicit explicit field (e.g. <tt style="color:rgb(0,102,102);font-size:100%;" >year</tt>)</td></tr><tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >\btxdetail</tt></td><td>fetch a derived derived field (e.g. <tt style="color:rgb(0,102,102);font-size:100%;" >short</tt>)</td></tr><tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >\btxflush</tt></td><td>fetch a derived derived or explicit explicit field</td></tr>
</table>
<p></p>
Normally Normally you can use <tt style="color:rgb(0,102,102);font-size:100%;" >\btxfield</tt> or <tt style="color:rgb(0,102,102);font-size:100%;" >\btxflush</tt> as derived derived fields just like analyzed author analyzed author fields are flushed in a special special way.
<p></p>
You can improve readability improve readability by using setupsusing setups, for instanceinstance:
<pre style="color:rgb(102,0,102);font-size:100%">\btxdoifelse {author} {
</pre>
<p></p>
Keep in mind that normally normally you don’t need to mess with definitions definitions like this because standard rendering because standard rendering styles are providedprovided. These styles use a few helpers that inject symbols inject symbols but also take care of leading leading and trailing trailing spaces:
<table>
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >\btxspace</tt></td><td>before afterbefore after</td></tr><tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >\btxperiod</tt></td><td>beforebefore. afterafter</td></tr><tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >\btxcomma</tt></td><td>beforebefore, afterafter</td></tr><tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >\btxlparent</tt></td><td>before before (afterafter</td></tr><tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >\btxrparent</tt></td><td>beforebefore) afterafter</td></tr><tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >\btxlbracket</tt></td><td>before before [afterafter</td></tr><tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >\btxrbracket</tt></td><td>beforebefore] afterafter</td></tr>
</table>
<p></p>
So, the previous example previous example setup can be rewritten rewritten as:
<pre style="color:rgb(102,0,102);font-size:100%">\btxdoif {title} {
</pre>
<p></p>
There is a special command special command for rendering rendering a (combinationcombination) of authorsauthors:
<pre style="color:rgb(102,0,102);font-size:100%">\btxflushauthor{author}
</pre>
<p></p>
Instead Instead of the last one you can also use:
<pre style="color:rgb(102,0,102);font-size:100%">\btxflushauthorinverted{editor}
</pre>
<p></p>
You can use a (configurableconfigurable) default default or pass directivesdirectives: Valid directives directives are
<table>
<tr><td>conversionconversion</td><td>renderingrendering</td></tr><tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >inverted</tt></td><td>the Frog jr, KermitKermit</td></tr>
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >invertedshort</tt></td><td>the Frog jr, K</td></tr>
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >normal</tt></td><td>KermitKermit, the Frog, jr</td></tr>
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >normalshort</tt></td><td>K, the Frog, jr</td></tr>
</table>
<h1>CitationsCitations</h1>
Citations Citations are references references to bibliographic entries bibliographic entries that normally normally show up in lists someplace someplace in the documentdocument: at the end of a chapterchapter, in an appendixappendix, at the end of an articlearticle, etc. We discussed discussed the rendering rendering of these lists in the previous chapterprevious chapter. A citation citation is normally normally pretty short as its main purpose purpose is to refer refer uniquely to a more detailed descriptiondetailed description. But, there are several several ways to referrefer, which is why the citation subsystem citation subsystem is configurable configurable and extensibleextensible. Just look at the following commandsfollowing commands:
<pre style="color:rgb(102,0,102);font-size:100%">\cite[author][example::demo-003]
</pre>
<divli>:<ul>(Hans Hagen Hagen and Ton OttenOtten)</ul>:<ul>(Hans Hagen Hagen and Ton Otten Otten (1996))</ul>:<ul>(Hans Hagen Hagen and Ton OttenOtten, 1996)</ul>:<ul>(Hans Hagen Hagen and Ton OttenOtten, Luigi Scarso)</ul>:<ul>(Hans Hagen Hagen and Ton Otten Otten (1996), Luigi Scarso (2021))</ul>:<ul>(Hans Hagen Hagen and Ton OttenOtten, 1996, Luigi Scarso, 2021)</ul>:<ul>(Luigi Scarso, Hans Hagen Hagen and Ton OttenOtten)</ul>:<ul>(Luigi Scarso (2021), Hans Hagen Hagen and Ton Otten Otten (1996))</ul>:<ul>(Luigi Scarso, 2021, Hans Hagen Hagen and Ton OttenOtten, 1996)</ul></divli>
<p></p>
The first argument argument is optionaloptional.
<div style="border:thin solid black;" >
<span style="font-style:oblique;" > setup definition cite </span >
</div>
<p></p>
You can tune the way a citation citation shows up:
<pre style="color:rgb(102,0,102);font-size:100%">\setupbtxcitevariant[author] [sorttype=author,color=darkyellow]
</pre>
<p></p>
Here we sort the authors authors and color the citationcitation:
<divli>:<ul>(Hans Hagen Hagen and Ton OttenOtten, Luigi Scarso)</ul>:<ul>(Hans Hagen Hagen and Ton Otten Otten (1996), Luigi Scarso (2021))</ul>:<ul>(Hans Hagen Hagen and Ton OttenOtten, 1996, Luigi Scarso, 2021)</ul></divli>
<p></p>
For reasons reasons of backward compatibility backward compatibility the <tt style="color:rgb(0,102,102);font-size:100%;" >\cite</tt> command command is a bit picky about spaces between between the two argumentsarguments, of which the first is optionaloptional. This is a consequence consequence of allowing allowing its use with the key specified between specified between curly brackets brackets as is the traditional practicetraditional practice. (We do encourage encourage users to adopt the more coherent coherent <span tag="MKIV" style="font-style:sans;">ConTEXt</span> syntax syntax by using using square brackets brackets for keywords keywords and reserving reserving curly brackets brackets to regroup regroup text to be typesettypeset.)
<p></p>
The <tt style="color:rgb(0,102,102);font-size:100%;" >\citation</tt> command command is synonymous synonymous but is more flexible flexible with respect respect to spacing spacing of its argumentsarguments:
<pre style="color:rgb(102,0,102);font-size:100%">\citation[author] [example::demo-004,demo-003]
</pre>
<p></p>
There is a whole bunch of cite options options and more can be easily definedeasily defined.
<table>
<tr><td>key</td><td>renderingrendering</td></tr><tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >author</tt></td><td>(authorauthor)</td></tr><tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >authornum</tt></td><td>[author author [btx error error 1]]</td></tr><tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >authoryear</tt></td><td>(author author (year))</td></tr><tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >authoryears</tt></td><td>(authorauthor, year)</td></tr>
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >doi</tt></td><td>[todo: doi]</td></tr>
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >key</tt></td><td>[demo-005]</td></tr>
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >none</tt></td><td></td></tr>
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >num</tt></td><td>[[btx error error 1]]</td></tr>
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >page</tt></td><td>pages</td></tr>
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >serial</tt></td><td>[5]</td></tr>
<p></p>
Because Because we are dealing dealing with database input database input and because because we generally generally need to manipulate entriesmanipulate entries, much of the work is delegated delegated to <span tag="MKIV" style="font-style:sans;">Lua</span>. This makes it easier easier to maintain maintain and extend extend the code. Of course <span tag="MKIV" style="font-style:sans;">TEX</span> still does the renderingrendering. The typographic details typographic details are controlled controlled by parameters parameters but not all are used in all variantsvariants. As with most <span tag="MKIV" style="font-style:sans;">ConTEXt</span> commandscommands, it starts out with a general general setup commandcommand:
<div style="border:thin solid black;" >
<span style="font-style:oblique;" > setup definition setupbtxcitevariant </span >
</div>
<p></p>
On top of that we can define instances define instances that inherit either inherit either from a given parent parent or from the topmost topmost setup.
<div style="border:thin solid black;" >
<span style="font-style:oblique;" > setup definition definebtxcitevariant </span >
</div>
<p></p>
But, specific variants specific variants can have them overloadedoverloaded:
<p></p>
<tt style="color:rgb(102,0,102);font-size:100%;" >setupbtxcitevariant : author</tt>
</table>
A citation variant citation variant is defined defined in several several steps and if you really really want to know the dirty detailsdetails, you should look into the <tt style="color:rgb(0,102,102);font-size:100%;" >publ-imp-*.mkiv</tt> files. Here we stick to the conceptconcept.
<pre style="color:rgb(102,0,102);font-size:100%">\startsetups btx:cite:author
</pre>
<p></p>
You can overload overload such setups setups if needed, but that only makes sense when you cannot configure cannot configure the rendering rendering with parametersparameters. The <tt style="color:rgb(0,102,102);font-size:100%;" >\btxcitevariant</tt> command command is one of the build in accessors accessors and it calls out to <span tag="MKIV" style="font-style:sans;">Lua</span> where more complex manipulation complex manipulation takes place if needed. If no manipulation manipulation is known, the field with the same name (if found) will be flushed. A command command like <tt style="color:rgb(0,102,102);font-size:100%;" >\btxcitevariant</tt> assumes assumes that a dataset and specific specific tag has been set. This is normally normally done in the wrapper wrapper macros, like <tt style="color:rgb(0,102,102);font-size:100%;" >\cite</tt>. For special purposes special purposes you can use these commands commands
<pre style="color:rgb(102,0,102);font-size:100%">\setbtxdataset[example]
</pre>
<p></p>
But don’t expect expect too much support support for such low level rendering controlrendering control.
<p></p>
Unless Unless you use <tt style="color:rgb(0,102,102);font-size:100%;" >criterium=all</tt> only publications publications that are cited will end up in the lists. You can force a citation citation into a list using using <tt style="color:rgb(0,102,102);font-size:100%;" >\usecitation</tt>, for exampleexample:
<pre style="color:rgb(102,0,102);font-size:100%">\usecitation[example::demo-004,demo-003]
</pre>
<p></p>
This command command has two synonymssynonyms: <tt style="color:rgb(0,102,102);font-size:100%;" >\nocite</tt> and <tt style="color:rgb(0,102,102);font-size:100%;" >\nocitation</tt> so you can choose whatever whatever fits you best.
<div style="border:thin solid black;" >
<span style="font-style:oblique;" > setup definition nocite </span >
<h1>The LUA view</h1>
Because Because we manage manage data at the <span tag="MKIV" style="font-style:sans;">Lua</span> end it is tempting tempting to access access it there for other purposespurposes. This is fine as long as you keep in mind that aspects aspects of the implementation implementation may change over time, although although this is unlikely unlikely once the modules become stablemodules become stable.
<p></p>
The entries entries are collected collected in datasets and each set has a unique name. In this document document we have the set named <tt style="color:rgb(0,102,102);font-size:100%;" >example</tt>. A dataset table table has several several fields, and probably probably the one of most interest interest is the <tt style="color:rgb(0,102,102);font-size:100%;" >luadata</tt> field. Each entry entry in this table describes table describes a publicationpublication:
<pre style="color:rgb(102,0,102);font-size:100%">t={
}
</pre>
This is <tt style="color:rgb(0,102,102);font-size:100%;" >publications.datasets.example.luadata["demo-001"]</tt>. There can be a companion entry companion entry in the parallel parallel <tt style="color:rgb(0,102,102);font-size:100%;" >details</tt> tabletable.
<pre style="color:rgb(102,0,102);font-size:100%">t={
}
</pre>
These details details are accessed accessed as <tt style="color:rgb(0,102,102);font-size:100%;" >publications.datasets.example.details["demo-001"]</tt> and by using using a separate table separate table we can overload overload fields in the original entry without losing original entry without losing the originaloriginal.
<p></p>
You can loop over the entries using regular entries using regular <span tag="MKIV" style="font-style:sans;">Lua</span> code combined combined with <span tag="MKIV" style="font-style:sans;">MkIV</span> helpers:
<pre style="color:rgb(102,0,102);font-size:100%">local dataset = publications.datasets.example
</pre>
<p></p>
This results results in:
<table>
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >demo-001</tt></td><td>Hag13</td><td><span tag="MKIV" style="font-style:sans;">bibTEX</span>, the <span tag="MKIV" style="font-style:sans;">ConTEXt</span> way</td></tr>
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >demo-002</tt></td><td>Hag14</td><td><span tag="MKIV" style="font-style:sans;">bibTEX</span>, the <span tag="MKIV" style="font-style:sans;">ConTEXt</span> way</td></tr>
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >demo-003</tt></td><td>HO96</td><td>Typesetting education documentsTypesetting education documents</td></tr><tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >demo-004</tt></td><td>Sca21</td><td>Designing Designing high speed trains</td></tr><tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >demo-005</tt></td><td>aut00</td><td>titletitle</td></tr>
</table>
<p></p>
You can manipulate manipulate a dataset after loadingafter loading. Of course this assumes assumes that you know what kind of content content you have and what you need for renderingrendering. As example example we load a small dataset.
<pre style="color:rgb(102,0,102);font-size:100%">\definebtxdataset[drumming]
</pre>
<p></p>
Because Because we’re going going to do some <span tag="MKIV" style="font-style:sans;">Lua</span>, we could also have loaded the dataset with:
<pre style="color:rgb(102,0,102);font-size:100%">publications.load("drumming","mkiv-publications.lua","lua")
</pre>
<p></p>
The dataset has three entriesentries:
<p></p>
As you can see, we can have a subtitlesubtitle. We will combine combine the title title and subtitle subtitle into one:
<pre style="color:rgb(102,0,102);font-size:100%">\startluacode
</pre>
<p></p>
We can now typeset typeset the entries entries with:
<pre style="color:rgb(102,0,102);font-size:100%">\definebtxrendering[drumming][dataset=drumming,method=dataset]
</pre>
<p></p>
Because Because we just want to show the entriesentries, and have no citations citations that force them to be shown, we have to the <tt style="color:rgb(0,102,102);font-size:100%;" >method</tt> to <tt style="color:rgb(0,102,102);font-size:100%;" >dataset</tt>.1
<h1>The XML view</h1>
The <tt style="color:rgb(0,102,102);font-size:100%;" >luadata</tt> table table can be converted converted into an <span tag="MKIV" style="font-style:sans;">xml</span> representationrepresentation. This is a follow follow up on earlier experiments earlier experiments with an <span tag="MKIV" style="font-style:sans;">xml</span>-only approachapproach. I decided decided in the end to stick to a <span tag="MKIV" style="font-style:sans;">Lua</span> approach approach and provide provide some simple simple <span tag="MKIV" style="font-style:sans;">xml</span> support support in additionaddition.
<p></p>
Once a dataset is accessible accessible as <span tag="MKIV" style="font-style:sans;">xml</span> tree, you can use the regular regular <tt style="color:rgb(0,102,102);font-size:100%;" >\xml...</tt> commandscommands. We start with loading loading a dataset, in this case from just one file.
<pre style="color:rgb(102,0,102);font-size:100%">\usebtxdataset[tugboat][tugboat.bib]
</pre>
<p></p>
The dataset has to be converted converted to <span tag="MKIV" style="font-style:sans;">xml</span>:
<pre style="color:rgb(102,0,102);font-size:100%">\convertbtxdatasettoxml[tugboat]
</pre>
<p></p>
The tree is now accessible accessible by its root reference reference <tt style="color:rgb(0,102,102);font-size:100%;" >btx:tugboat</tt>. If we want simple simple field access access we can use a few setupssetups:
<pre style="color:rgb(102,0,102);font-size:100%">\startxmlsetups btx:initialize
</pre>
<p></p>
The two setups setups are predefined predefined in the core alreadyalready, but you might want to change them. They are applied applied in for instanceinstance:
<pre style="color:rgb(102,0,102);font-size:100%">\starttabulate[|||]
<table>
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >tag</tt></td><td>HagenHagen:TB17-1-54</td></tr><tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >title</tt></td><td>PPCHTEX: typesetting chemical formulas typesetting chemical formulas in TEX</td></tr>
</table>
<table>
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >tag</tt></td><td>HagenHagen:TB17-1-54</td></tr><tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >title</tt></td><td>PPCHTEX: typesetting chemical formulas typesetting chemical formulas in TEX</td></tr>
</table>
<p></p>
Here is another exampleanother example:
<pre style="color:rgb(102,0,102);font-size:100%">\startxmlsetups btx:row
<table>
<tr><td>Knuth:TB10-1-31</td><td>Typesetting Concrete MathematicsTypesetting Concrete Mathematics</td></tr><tr><td>Knuth:TB10-1-8</td><td>TEX would find it difficult difficult …</td></tr><tr><td>Knuth:TB10-3-325</td><td>The new versions versions of TEX and MF</td></tr><tr><td>Knuth:TB10-4-529</td><td>The errors errors of TEX</td></tr><tr><td>Knuth:TB11-1-13</td><td>Virtual Virtual Fonts: More Fun for Grand WizardsWizards</td></tr><tr><td>Knuth:TB11-2-165</td><td>Exercises Exercises for TEX: The ProgramProgram</td></tr><tr><td>Knuth:TB11-4-489</td><td>The future future of TEX and MF</td></tr>
<tr><td>Knuth:TB11-4-497</td><td>Arthur Lee Samuel, 1901--1990</td></tr>
<tr><td>Knuth:TB11-4-499</td><td>Answers Answers to Exercises Exercises for TEX: The ProgramProgram</td></tr><tr><td>Knuth:TB12-2-313</td><td>Fixed-point glue settingsetting: ErrataErrata</td></tr>
<tr><td>Knuth:TB14-4-387</td><td>Icons for TEX and MF</td></tr>
<tr><td>Knuth:TB17-1-29</td><td>Important message regarding Important message regarding CM fonts</td></tr><tr><td>Knuth:TB2-3-5</td><td>The current current state of things</td></tr><tr><td>Knuth:TB3-1-10</td><td>Fixed-point glue settingDash an example settingDashan example of WEB</td></tr><tr><td>Knuth:TB31-2-121</td><td>An Earthshaking AnnouncementEarthshaking Announcement</td></tr><tr><td>Knuth:TB4-2-64</td><td>A note on hyphenationhyphenation</td></tr><tr><td>Knuth:TB5-1-4</td><td>TEX incunabulaincunabula</td></tr><tr><td>Knuth:TB5-1-67</td><td>Comments Comments on quality quality in publishingpublishing</td></tr><tr><td>Knuth:TB5-2-105</td><td>A course on MF programmingprogramming</td></tr><tr><td>Knuth:TB6-1-36</td><td>Recipes and fractionsfractions</td></tr><tr><td>Knuth:TB7-2-101</td><td>The TEX logo in various various fonts</td></tr><tr><td>Knuth:TB7-2-95</td><td>Remarks Remarks to celebrate celebrate the publication publication of Computers Computers & TypesettingTypesetting</td></tr><tr><td>Knuth:TB8-1-14</td><td>Mixing Mixing right-to-left texts with left-to-right texts</td></tr><tr><td>Knuth:TB8-1-6</td><td>It happenedhappened: announcement announcement of TEX 2.1</td></tr><tr><td>Knuth:TB8-1-73</td><td>Problem Problem for a Saturday afternoonSaturday afternoon</td></tr><tr><td>Knuth:TB8-2-135</td><td>Fonts for digital digital halftones</td></tr><tr><td>Knuth:TB8-2-210</td><td>Saturday morning problemDash solutionSaturday morning problemDashsolution</td></tr><tr><td>Knuth:TB8-2-217</td><td>ReplyReply: Printing Printing out selected selected pages</td></tr>
<tr><td>Knuth:TB8-3-309</td><td>Macros for Jill</td></tr>
<tr><td>Knuth:TB9-2-152</td><td>A Punk Meta-Font</td></tr>
<p></p>
A more extensive example extensive example is the followingfollowing. Of course this assumes assumes that you know what <span tag="MKIV" style="font-style:sans;">xml</span> support mechanisms support mechanisms and macros are availableavailable.
<pre style="color:rgb(102,0,102);font-size:100%">\startxmlsetups btx:getkeys
<table>
<tr><td>1984</td><td>Knuth:TB5-1-67</td><td>Don Knuth</td></tr>
<tr><td>1984</td><td>Knuth:TB5-1-4</td><td>Donald Donald E. Knuth</td></tr><tr><td>1984</td><td>Knuth:TB5-2-105</td><td>Donald Donald E. Knuth</td></tr><tr><td>1985</td><td>Knuth:TB6-1-36</td><td>Donald Donald E. Knuth</td></tr><tr><td>1986</td><td>Knuth:TB7-2-101</td><td>Donald Donald E. Knuth</td></tr><tr><td>1987</td><td>Knuth:TB8-2-135</td><td>Donald Donald E. Knuth</td></tr><tr><td>1987</td><td>Knuth:TB8-3-309</td><td>Donald Donald E. Knuth</td></tr><tr><td>1988</td><td>Knuth:TB9-2-152</td><td>Donald Donald E. Knuth</td></tr><tr><td>1989</td><td>Knuth:TB10-3-325</td><td>Donald Donald E. Knuth</td></tr><tr><td>1989</td><td>Knuth:TB10-4-529</td><td>Donald Donald E. Knuth</td></tr><tr><td>1990</td><td>Knuth:TB11-4-489</td><td>Donald Donald E. Knuth</td></tr><tr><td>1993</td><td>Knuth:TB14-4-387</td><td>Donald Donald E. Knuth</td></tr><tr><td>1996</td><td>Knuth:TB17-1-29</td><td>Donald Donald E. Knuth</td></tr><tr><td>1987</td><td>Knuth:TB8-1-14</td><td>Donald Donald Knuth and Pierre MacKay</td></tr><tr><td>1981</td><td>Knuth:TB2-3-5</td><td>Donald Donald Knuth</td></tr><tr><td>1982</td><td>Knuth:TB3-1-10</td><td>Donald Donald Knuth</td></tr><tr><td>1983</td><td>Knuth:TB4-2-64</td><td>Donald Donald Knuth</td></tr><tr><td>1986</td><td>Knuth:TB7-2-95</td><td>Donald Donald Knuth</td></tr><tr><td>1987</td><td>Knuth:TB8-1-6</td><td>Donald Donald Knuth</td></tr><tr><td>1987</td><td>Knuth:TB8-1-73</td><td>Donald Donald Knuth</td></tr><tr><td>1987</td><td>Knuth:TB8-2-210</td><td>Donald Donald Knuth</td></tr><tr><td>1987</td><td>Knuth:TB8-2-217</td><td>Donald Donald Knuth</td></tr><tr><td>1989</td><td>Knuth:TB10-1-8</td><td>Donald Donald Knuth</td></tr><tr><td>1989</td><td>Knuth:TB10-1-31</td><td>Donald Donald Knuth</td></tr><tr><td>1990</td><td>Knuth:TB11-1-13</td><td>Donald Donald Knuth</td></tr><tr><td>1990</td><td>Knuth:TB11-2-165</td><td>Donald Donald Knuth</td></tr><tr><td>1990</td><td>Knuth:TB11-4-497</td><td>Donald Donald Knuth</td></tr><tr><td>1990</td><td>Knuth:TB11-4-499</td><td>Donald Donald Knuth</td></tr><tr><td>1991</td><td>Knuth:TB12-2-313</td><td>Donald Donald Knuth</td></tr><tr><td>2010</td><td>Knuth:TB31-2-121</td><td>Donald Donald Knuth</td></tr>
</table>
<p></p>
The original original data is stored in a <span tag="MKIV" style="font-style:sans;">Lua</span> tabletable, hashed by tag. Starting Starting with <span tag="MKIV" style="font-style:sans;">Lua</span> 5.2 each run of <span tag="MKIV" style="font-style:sans;">Lua</span> gets a different ordering different ordering of such a hash. In older versionsversions, when you looped over a hash, the order order was undefinedundefined, but the same as long as you used the same binarybinary. This had the advantage advantage that successive successive runs, something something we often often have in document processing document processing gave consistent resultsconsistent results. In today’s today’s <span tag="MKIV" style="font-style:sans;">Lua</span> we need to do much more sorting sorting of hashes before before we loop, especially especially when we save multi--pass data. It is for this reason reason that the <span tag="MKIV" style="font-style:sans;">xml</span> tree is sorted by hash key by defaultdefault. That way lookups (especially especially the first of a set) give consistent outcomesconsistent outcomes.
<h1>StandardsStandards</h1>
The rendering rendering of bibliographic entries bibliographic entries is often standardized often standardized and prescribed prescribed by the publisherpublisher. If you submit submit an article article to a journaljournal, normally normally it will be reformatted reformatted (or even re- keyed) and the rendering rendering will happen happen at the publishers publishers end. In that case it may not matter matter how entries entries were rendered rendered when writing writing the publicationpublication, because because the publisher publisher will do it his or her way. This means that most users probably probably will stick to the standard standard <span tag="MKIV" style="font-style:sans;">apa</span> rules and for them we provide provide some configurationconfiguration. Because Because we use setups setups it is easy to overload overload specifics. If you really really want to tweak, best look in the files that deal with it.
<p></p>
Many standards exist standards exist and support support for other renderings renderings may be added to the core. Interested Interested users are invited invited to develop develop and to test alternate standard renderings according alternate standard renderings according to their needs.
<p></p>
Todo: maybe a list of categories categories and fields.
<h1>Cleaning Cleaning up</h1>
Although Although the <span tag="MKIV" style="font-style:sans;">bibTEX</span> format format is reasonably reasonably well defineddefined, in practice practice there are many ways to organize organize the data. For instanceinstance, one can use predefined predefined string constants constants that get used (either either or not combined combined with other strings) later on. A string can be enclosed enclosed in curly braces or double double quotes. The strings can contain contain <span tag="MKIV" style="font-style:sans;">TEX</span> commands commands but these are not standardizedstandardized. The databases often databases often have somewhat complex somewhat complex ways to deal with special characters special characters and the use of braces in their definition definition is also not normalizednormalized.
<p></p>
The most complex complex to deal with are the fields that contain contain names of peoplepeople. At some point it might be needed to split a combination combination of names into individual individual ones that then get split into titletitle, first name, optional inbetweensoptional inbetweens, surnamesurname(s) and additionaladditional: <tt style="color:rgb(0,102,102);font-size:100%;" >Prof. Dr. Alfred B. C. von Kwik Kwak Jr. II and P. Q. Olet</tt> is just one example example of this. The convention convention seems to be not to use commas commas but <tt style="color:rgb(0,102,102);font-size:100%;" >and</tt> to separate separate names (often often each name will be specified specified as lastnamelastname, firstnamefirstname).
<p></p>
We don’t see it as challenge challenge nor as a duty to support support all kinds of messy definitionsdefinitions. Of course we try to be somewhat tolerantsomewhat tolerant, but you will be sure to get better results better results if you use nicely setup, consistent databasesconsistent databases.
<p></p>
Todo: maybe some examples examples of bad.
<h1>TransitionTransition</h1>
In the original bibliography support module usage original bibliography support module usage was as follows follows (example example taken from the contextgarden contextgarden wiki):
<pre style="color:rgb(102,0,102);font-size:100%">% engine=pdftex
</pre>
<p></p>
For <span tag="MKIV" style="font-style:sans;">MkIV</span> the modules modules were partly rewritten rewritten and ended up in the core so the two commands commands were no longer needed. The overhead associated overhead associated with the automatic loading automatic loading of the bibliography bibliography macros can be neglected neglected these days, so standardized modules standardized modules such as <tt style="color:rgb(0,102,102);font-size:100%;" >bib</tt> are all being being moved to the core and do not need to be explicitly explicitly loaded.
<p></p>
The first <tt style="color:rgb(0,102,102);font-size:100%;" >\setupbibtex</tt> command command in this example example is needed to bootstrap bootstrap the process: it tells what database database has to be processed by <span tag="MKIV" style="font-style:sans;">bibTEX</span> between between runs. The second second <tt style="color:rgb(0,102,102);font-size:100%;" >\setuppublications</tt> command command is optionaloptional. Each citation citation (tagged with <tt style="color:rgb(0,102,102);font-size:100%;" >\cite</tt>) ends up in the list of publicationspublications.
<p></p>
In the new approach approach we no longer use <span tag="MKIV" style="font-style:sans;">bibTEX</span>so we don’t need to setup <span tag="MKIV" style="font-style:sans;">bibTEX</span>. Instead Instead we define define dataset(s). We also no longer set up publications publications with one commandcommand, but have split that up in renderingrendering-, list-, and cite-variantsvariants. The basic basic <tt style="color:rgb(0,102,102);font-size:100%;" >\cite</tt> command remainscommand remains. The above example becomesexample becomes:
<pre style="color:rgb(102,0,102);font-size:100%">\definebtxdataset
</pre>
<p></p>
So, we have a few more commands commands to set up things. If you intend intend to use just a single single dataset and renderingrendering, the above preamble preamble can be simplified simplified to:
<pre style="color:rgb(102,0,102);font-size:100%">\usebtxdataset
</pre>
<p></p>
But keep in mind that compared compared to the old <span tag="MKIV" style="font-style:sans;">MkII</span> derived derived method we have moved some of the options options to the renderingrendering, list and cite setup variantsvariants.
<p></p>
Another difference Another difference is now the use of lists. When you define define a renderingrendering, you also define define a list. HoweverHowever, all entries entries are collected collected in a common common list tagged <tt style="color:rgb(0,102,102);font-size:100%;" >btx</tt>. Although Although you will normally configure normally configure a rendering rendering you can still set some properties properties of lists, but in that case you need to prefix prefix the list identifieridentifier. In the case of the above example example this is <tt style="color:rgb(0,102,102);font-size:100%;" >btx:document</tt>.
<h1>MLBIBTEXMLBIBTEX</h1>
Todo: how to plug in <span tag="MKIV" style="font-style:sans;">MLbibTEXMLbibTEX</span> for sorting sorting and other advanced operationsadvanced operations.
<h1>ExtensionsExtensions</h1>
As <span tag="MKIV" style="font-style:sans;">TEX</span> and <span tag="MKIV" style="font-style:sans;">Lua</span> are both open and accessible accessible in <span tag="MKIV" style="font-style:sans;">ConTEXt</span> it is possible possible to extend extend the functionality functionality of the bibliography related bibliography related code. For instanceinstance, you can add extra loadersextra loaders.
<pre style="color:rgb(102,0,102);font-size:100%">function publications.loaders.myformat(dataset,filename)
</pre>
<p></p>
This then permits loading permits loading a database database (into a dataset) with the commandcommand:
<pre style="color:rgb(102,0,102);font-size:100%">\usebtxdataset[standard][myfile.myformat]
</pre>
<p></p>
The <tt style="color:rgb(0,102,102);font-size:100%;" >myformat</tt> suffix suffix is recognized automaticallyrecognized automatically. If you want to use another suffixanother suffix, you can do this:
<pre style="color:rgb(102,0,102);font-size:100%">\usebtxdataset[standard][myformat::myfile.txt]
</pre>
<h1>Notes</h1>
The move from external <span tag="MKIV" style="font-style:sans;">bibTEX</span> processing to internal processing has the advantage that we stay within the same run. In the traditional approach we had roughly the following steps:
<div >
<div >
<span>• </span>
<span>the first run information is collected and written to file</span>
</div>
<div >
<span>• </span>
<span>after that run the <span tag="MKIV" style="font-style:sans;">bibTEX</span> program converts that file to another one</span>
</div>
<div >
<span>• </span>
<span>successive runs use that data for references and producing lists</span>
</div>
</div>
<p></p>
In the <span tag="MKIV" style="font-style:sans;">MkIV</span> approach the bibliographic database is loaded in memory each run and processing also happens each run. On paper this looks less efficient but as <span tag="MKIV" style="font-style:sans;">Lua</span> is quite fast, in practice performance is much better.
<p></p>
Probably most demanding is the treatment of authors as we have to analyze names, split multiple authors and reassemble firstnames, vons, surnames and juniors. When we sort by author sorting vectors have to be made which also has a penalty. However, in practice the user will not notice a performance degradation. We did some tests with a list of 500.000 authors, sorted them and typeset them as list (producing some 5400 dense pages in a small font and with small margins). This is typical one of these cases where using <span tag="MKIV" style="font-style:sans;">LuajitTEX</span> saves quite time. On my machine it took just over 100 seconds to get this done. Unfortunately not all operating systems performed equally well: 32 bit versions worked fine, but 64 bit <span tag="MKIV" style="font-style:sans;">linux</span> either crashed (stalled) the machine or ran out of memory rather fast, while <span tag="MKIV" style="font-style:sans;">MacOSX</span> and <span tag="MKIV" style="font-style:sans;">Windows</span> performed fine. In practice you will never run into this, unless you produce massive amounts of bibliographic entries. <span tag="MKIV" style="font-style:sans;">LuaJIT</span> has some benefits but also some drawbacks.