Difference between revisions of "User:Luigi.scarso"

From Wiki
Jump to navigation Jump to search
Line 1: Line 1:
 
__TOC__
 
__TOC__
  
= Modules::documentation=
 
  
Modules as name come from <code>modules</code> switch in <br/>
+
 
<code>
+
 
texexec --pdf --modules ''module name''
+
 
</code><br/>
+
   
or<br/>
+
<h1>The data­base</h1>
<code>
 
texmfstart texexec --pdf --modules ''module name''
 
</code><br/>
 
or<br/>
 
<code>
 
texmfstart texexec --luatex --modules ''module name''
 
</code><br/>
 
  
which is  
+
The <span tag="MKIV" style="font-style:sans;">bibTEX</span> for­mat is rather pop­u­lar in the <span tag="MKIV" style="font-style:sans;">TEX</span> com­mu­nity and even with its short­com­ings it will stay around for a while. Many pub­li­ca­tion web­sites can ex­port and many tools are avail­able to work with this data­base for­mat. It is rather sim­ple and looks a bit like <span tag="MKIV" style="font-style:sans;">Lua</span> ta­bles. Un­for­tu­nately the con­tent can be pol­luted with non-stan­dard­ized <span tag="MKIV" style="font-style:sans;">TEX</span> com­mands which com­pli­cates pre- or post­pro­cess­ing out­side <span tag="MKIV" style="font-style:sans;">TEX</span>. In that sense a <span tag="MKIV" style="font-style:sans;">bibTEX</span> data­base is of­ten not coded neu­trally. Some lim­i­ta­tions, like the use of com­mands to en­code ac­cented char­ac­ters root in the <span tag="MKIV" style="font-style:sans;">ascii</span> world and can be by­passed by us­ing <span tag="MKIV" style="font-style:sans;">utf</span> in­stead (as han­dled some­what in <span tag="MKIV" style="font-style:sans;">LATEX</span> through ex­ten­sions such as <tt style="color:rgb(0,102,102);font-size:100%;" >bibtex8</tt>).
a way to make pdf of documentation and code of ''module name'' .
+
<p></p>
 +
The nor­mal way to deal with a bib­li­og­ra­phy is to re­fer to en­tries us­ing a unique tag or key. When a list of en­tries is type­set, this ref­er­ence can be used for link­ing pur­poses. The type­set list can be processed and sorted us­ing the <tt style="color:rgb(0,102,102);font-size:100%;" >bibtex</tt> pro­gram that con­verts the data­base into some­thing 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 pro­gram my­self (nor bib­li­ogra­phies) so I will not go into too much de­tail here, if only be­cause 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> pro­gram: we just use data­base files and deal with the nec­es­sary ma­nip­u­la­tions di­rectly in <span tag="MKIV" style="font-style:sans;">ConTEXt</span>. One or more such data­bases can be used and com­bined with ad­di­tional en­tries de­fined within the doc­u­ment. We can have sev­eral such datasets ac­tive at the same time.
 +
<p></p>
 +
A <span tag="MKIV" style="font-style:sans;">bibTEX</span> file looks like this:
 +
   
 +
<pre style="color:rgb(102,0,102);font-size:100%">@Article{sometag,
 +
    author  = "An Author and Another One",
 +
    title  = "A hopefully meaningful title",
 +
    journal = maps,
 +
    volume  = "25",
 +
    number  = "2",
 +
    pages  = "5--9",
 +
    month  = mar,
 +
    year    = "2013",
 +
    ISSN    = "1234-5678",
 +
}
 +
</pre>
 +
<p></p>
 +
Nor­mally a value is given be­tween quotes (or curly brack­ets) but sin­gle words are also OK (there is no real ben­e­fit in not us­ing quotes, so we ad­vise to al­ways use them). There can be many more fields and in­stead of strings one can use pre­de­fined short­cuts. The ti­tle for ex­am­ple quite of­ten con­tains <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 char­ac­ters such as the en­dash (typ­i­cally as <tt style="color:rgb(0,102,102);font-size:100%;" >--</tt>) so we have a mix­ture of data and type­set­ting di­rec­tives. If you are cov­er­ing non--eng­lish ref­er­ences, you of­ten need char­ac­ters that are not in the <span tag="MKIV" style="font-style:sans;">ascii</span> sub­set 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 data­base file uses old-fash­ioned <span tag="MKIV" style="font-style:sans;">TEX</span> ac­cent com­mands then these will be in­ter­nally con­verted au­to­mat­i­cally to <span tag="MKIV" style="font-style:sans;">utf</span>. Com­mands (macros) are con­verted to an in­di­rect call, which is quite ro­bust.
 +
<p></p>
 +
The <span tag="MKIV" style="font-style:sans;">bibTEX</span> files are loaded in mem­ory as <span tag="MKIV" style="font-style:sans;">Lua</span> ta­ble but can be con­verted to <span tag="MKIV" style="font-style:sans;">xml</span> so that we can ac­cess them in a more flex­i­ble way, but that is a sub­ject for spe­cial­ists.
 +
<p></p>
 +
In the old <span tag="MKIV" style="font-style:sans;">MkII</span> setup we have two kinds of en­tries: the ones that come from the <span tag="MKIV" style="font-style:sans;">bibTEX</span> run and user sup­plied ones. We no longer rely on <span tag="MKIV" style="font-style:sans;">bibTEX</span> 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 <span tag="MKIV" style="font-style:sans;">bibTEX</span> gen­er­ated en­tries. The next vari­ant re­flects the <span tag="MKIV" style="font-style:sans;">ConTEXt</span> re­cod­ing of the old <span tag="MKIV" style="font-style:sans;">bibTEX</span> out­put.
 +
   
 +
<pre style="color:rgb(102,0,102);font-size:100%">\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
 +
</pre>
 +
<p></p>
 +
The split <tt style="color:rgb(0,102,102);font-size:100%;" >\artauthor</tt> fields are col­lapsed into a sin­gle <tt style="color:rgb(0,102,102);font-size:100%;" >author</tt> field as we deal with the split­ting 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> syn­tax is only kept around for back­ward com­pat­i­bil­ity with the pre­vi­ous use of <span tag="MKIV" style="font-style:sans;">bibTEX</span>.
 +
<p></p>
 +
In the new setup we sup­port these vari­ants as well:
 +
   
 +
<pre style="color:rgb(102,0,102);font-size:100%">\startpublication[k=Hagen:Third,t=article]
 +
    \author{Hans Hagen}
 +
    \title{Who knows who?}
 +
    ...
 +
\stoppublication
 +
</pre>
 +
<p></p>
 +
and  
 +
   
 +
<pre style="color:rgb(102,0,102);font-size:100%">\startpublication[tag=Hagen:Third,category=article]
 +
    \author{Hans Hagen}
 +
    \title{Who knows who?}
 +
    ...
 +
\stoppublication
 +
</pre>
 +
<p></p>
 +
and
 +
   
 +
<pre style="color:rgb(102,0,102);font-size:100%">\startpublication
 +
    \tag{Hagen:Third}
 +
    \category{article}
 +
    \author{Hans Hagen}
 +
    \title{Who knows who?}
 +
    ...
 +
\stoppublication
 +
</pre>
 +
<p></p>
 +
Be­cause in­ter­nally the en­tries are <span tag="MKIV" style="font-style:sans;">Lua</span> ta­bles, we also sup­port load­ing of <span tag="MKIV" style="font-style:sans;">Lua</span> based de­f­i­n­i­tions:
 +
   
 +
<pre style="color:rgb(102,0,102);font-size:100%">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",
 +
    },
 +
}
 +
</pre>
 +
<p></p>
 +
Files set up like this can be loaded too. The fol­low­ing <span tag="MKIV" style="font-style:sans;">xml</span> in­put is rather close to this, and is also ac­cepted as in­put.
 +
   
 +
<pre style="color:rgb(102,0,102);font-size:100%"><?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>
 +
</pre>
 +
<p></p>
 +
Todo: Add some re­marks about load­ing End­Note and RIS for­mats, but first we need to com­plete the tag map­ping (on Alan’s plate).
 +
<p></p>
 +
So the user has a rather wide choice of for­mat­ting style for bib­li­og­ra­phy data­base files.
 +
   
 +
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 style="color:rgb(0,102,102);font-size:100%;" >\cite</tt> and <tt style="color:rgb(0,102,102);font-size:100%;" >\nocite</tt> com­mands will be shown in lists. We will cover these de­tails later.
 +
 
 +
<h1>Com­mands in en­tries</h1>
  
For lua code, I've found convenient<br/>
+
One un­for­tu­nate as­pect com­monly found in <span tag="MKIV" style="font-style:sans;">bibTEX</span> files is that they of­ten con­tain <span tag="MKIV" style="font-style:sans;">TEX</span> 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 <span tag="MKIV" style="font-style:sans;">bibTEX</span> is a pro­gram in­tended to be used with many vari­ants of <span tag="MKIV" style="font-style:sans;">TEX</span> style: plain, <span tag="MKIV" style="font-style:sans;">LATEX</span>, 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, <span tag="MKIV" style="font-style:sans;">ConTEXt</span> 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 style="color:rgb(0,102,102);font-size:100%;" >tugboat.bib</tt> gives a long list of com­mands of which we show a small set here:
<code>
+
   
mtxrun --internal x-ldx ''module.lua'' <br/>
+
<pre style="color:rgb(102,0,102);font-size:100%">publications > start used btx commands
texmfstart texexec --use=x-ldx --forcexml ''module.ldx''
+
publications > standard CONTEXT 1 known
</code><br>
+
publications > standard ConTeXt 4 known
 +
publications > standard TeXLive 3 KNOWN
 +
publications > standard eTeX    1 known
 +
publications > standard hbox    6 known
 +
publications > standard sltt    1 unknown
 +
publications > stop used btxcommands
 +
</pre>
 +
<p></p>
 +
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 style="color:rgb(102,0,102);font-size:100%">\definebtxcommand\TUB {TUGboat}
 +
\definebtxcommand\sltt{\tt}
 +
\definebtxcommand\<#1>{\type{#1}}
 +
</pre>
 +
<p></p>
 +
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 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 un­de­fined com­mand we get: “com­mands like MySpe­cial­Com­mand are han­dled in an in­di­rect way”.
 +
<p></p>
 +
??
 +
   
 +
   
 +
<h1>Datasets</h1>
  
* first, see ''Inside_ConTeXt'' in [http://sandbox.contextgarden.net/Inside_ConTeXt];
+
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 style="color:rgb(0,102,102);font-size:100%;" >\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:
* also, see ''CONTEXT System Macros''  at [http://tex.aanhet.net/context/syst-gen-doc.pdf]
+
   
* [[User:Luigi.scarso/modules.pdf]] for a comprensive set of pdf
+
<pre style="color:rgb(102,0,102);font-size:100%">\definebtxdataset[standard]
 +
\usebtxdataset[standard][tugboat.bib]
 +
\usebtxdataset[standard][mtx-bibtex-output.xml]
 +
\usebtxdataset[standard][test-001-btx-standard.lua]
 +
</pre>
 +
<p></p>
 +
These three suf­fixes are un­der­stood by the loader. Here the dataset has the name <tt style="color:rgb(0,102,102);font-size:100%;" >standard</tt> and the three data­base files are merged, where later en­tries hav­ing the same tag over­load pre­vi­ous ones. De­f­i­n­i­tions in the doc­u­ment source (coded in <span tag="MKIV" style="font-style:sans;">TEX</span> speak) are also added, and they are saved for suc­ces­sive runs. This means that if you load and de­fine en­tries, they will be known at a next run be­fore­hand, so that ref­er­ences to them are in­de­pen­dent of when load­ing and de­f­i­n­i­tions take place.
 +
<div style="border:thin solid black;" >
 +
<span style="font-style:oblique;" > setup definition setupbtxdataset </span >
 +
</div>
 +
<div style="border:thin solid black;" >
 +
<span style="font-style:oblique;" > setup definition definebtxdataset </span >
 +
</div>
 +
<div style="border:thin solid black;" >
 +
<span style="font-style:oblique;" > setup definition usebtxdataset </span >
 +
</div>
 +
<p></p>
 +
In this doc­u­ment we use some ex­am­ple data­bases, so let’s load one of them now:
 +
   
 +
<pre style="color:rgb(102,0,102);font-size:100%">\definebtxdataset[example]
 +
\usebtxdataset[example][mkiv-publications.bib]
 +
</pre>
 +
<p></p>
 +
You can ask for an overview of en­tries in a dataset with:
 +
   
 +
<pre style="color:rgb(102,0,102);font-size:100%">\showbtxdatasetfields[example]
 +
</pre>
 +
this gives:
 +
   
 +
<table>
 +
<tr><td>tag</td><td>cat­e­gory</td><td>fields</td></tr>
 +
<tr><td>demo-001</td><td>book</td><td>au­thor in­dex ti­tle year</td></tr>
 +
<tr><td>demo-002</td><td>book</td><td>cross­ref in­dex year</td></tr>
 +
<tr><td>demo-003</td><td>book</td><td>au­thor com­ment in­dex ti­tle year</td></tr>
 +
<tr><td>demo-004</td><td>book</td><td>au­thor com­ment in­dex ti­tle year</td></tr>
 +
<tr><td>demo-005</td><td>book</td><td>au­thor doi in­dex pages se­r­ial ti­tle url year</td></tr>
 +
</table>
  
-- Maybe you are searching for [[Modules]], ie extensions to ConTeXt's core functions.--
+
<p></p>
 +
You can set the cur­rent ac­tive dataset with
 +
   
 +
<pre style="color:rgb(102,0,102);font-size:100%">\setbtxdataset[standard]
 +
</pre>
 +
<p></p>
 +
but most pub­li­ca­tion-re­lated com­mands ac­cept op­tional ar­gu­ments that de­note the dataset and ref­er­ences to en­tries can be pre­fixed with a dataset iden­ti­fier.. More about that later.
 +
   
 +
   
 +
<h1>Ren­der­ings</h1>
  
= Other stuffs=
+
A list of pub­li­ca­tions can be ren­dered at any place in the doc­u­ment. A data­base can be much larger than needed for a doc­u­ment. The same is true for the fields that make up an en­try. Here is the list of fields that are cur­rently han­dled, but of course there can be ad­di­tional 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 pub­li­ca­tions are in the data­base, the eas­i­est way is to ask for a com­plete list:
 +
   
 +
<pre style="color:rgb(102,0,102);font-size:100%">\definebtxrendering
 +
  [example]
 +
  [dataset=example,
 +
  method=local,
 +
  alternative=apa]
 +
\placelistofpublications % \placebtxrendering
 +
  [example]
 +
  [criterium=all]
 +
</pre>
 +
<p></p>
 +
This gives:1 Ha­gen, H. and Ot­ten, T. (1996). Type­set­ting ed­u­ca­tion doc­u­ments.2 Scarso, L. (2021). De­sign­ing high speed trains.3 au­thor (year). ti­tle. pages p.
 +
<p></p>
 +
The ren­der­ing it­self is some­what com­plex to set up be­cause we have not only many dif­fer­ent stan­dards but also many fields that can be set up. This means that there are sev­eral com­mands in­volved. Of­ten there is a pre­scribed style to ren­der bib­li­o­graphic de­scrip­tions, for ex­am­ple <tt style="color:rgb(0,102,102);font-size:100%;" >apa</tt>. A ren­der­ing is setup and de­fined with:
 +
<div style="border:thin solid black;" >
 +
<span style="font-style:oblique;" > setup definition setupbtxrendering </span >
 +
</div>
 +
<div style="border:thin solid black;" >
 +
<span style="font-style:oblique;" > setup definition definebtxrendering </span >
 +
</div>
 +
<p></p>
 +
And a list of such de­scrip­tions is gen­er­ated 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 en­tries:
 +
<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 ren­der­ing vari­ant. To keep things sim­ple we have their set­tings sep­a­rated. How­ever, these set­tings are shared for all ren­der­ing al­ter­na­tives. In prac­tice this is sel­dom a prob­lem in a pub­li­ca­tion as only one ren­der­ing al­ter­na­tive will be ac­tive. If this be not suf­fi­cient, you can al­ways group lo­cal set­tings in a setup and hook that into the spe­cific ren­der­ing.
 +
<div style="border:thin solid black;" >
 +
<span style="font-style:oblique;" > setup definition setupbtxlistvariant </span >
 +
</div>
 +
<div style="border:thin solid black;" >
 +
<span style="font-style:oblique;" > setup definition definebtxlistvariant </span >
 +
</div>
 +
<p></p>
 +
Ex­am­ples of list vari­ants are:
 +
<p></p>
 +
<tt style="color:rgb(102,0,102);font-size:100%;" >setupbtxlistvariant : artauthor</tt>
 +
   
 +
<table>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >no specific settings</tt></td><td></td></tr>
 +
</table>
  
*AutoSize: see supp-fun.tex. Some stuff here: http://wiki.contextgarden.net/User:Luigi.scarso/autosize
+
<p></p>
 +
<tt style="color:rgb(102,0,102);font-size:100%;" >setupbtxlistvariant : author</tt>
 +
   
 +
<table>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >no specific settings</tt></td><td></td></tr>
 +
</table>
  
* Two  SRA3 papers labels here http://wiki.contextgarden.net/Image:SRA3.jpg <!--[[Image:SRA3.jpg]] -->
+
<p></p>
 +
<tt style="color:rgb(102,0,102);font-size:100%;" >setupbtxlistvariant : editor</tt>
 +
   
 +
<table>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >no specific settings</tt></td><td></td></tr>
 +
</table>
  
*I have download preprint of EUROTEX 2005 [http://www.gutenberg.eu.org/EuroTeX2005/] It's very interesting.<br/>
+
<p></p>
 +
The ex­act ren­der­ing of list en­tries is de­ter­mined by the <tt style="color:rgb(0,102,102);font-size:100%;" >alternative</tt> key and de­faults to <tt style="color:rgb(0,102,102);font-size:100%;" >apa</tt> which uses de­f­i­n­i­tions 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 cat­e­gory has its own setup. You may also no­tice that ad­di­tional tests are needed to make sure that empty fields don’t trig­ger sep­a­ra­tors and such.
 +
<p></p>
 +
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 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 in­stance be­cause you don’t want fences or punc­tu­a­tion that be­longs to a field.
 +
   
 +
<pre style="color:rgb(102,0,102);font-size:100%">\btxdoif {title} {
 +
    \bold{\btxfield{title}},
 +
}
 +
</pre>
 +
<p></p>
 +
There are three test macros:
 +
   
 +
<pre style="color:rgb(102,0,102);font-size:100%">\btxdoifelse{fieldname}{action when found}{action when not found}
 +
\btxdoif    {fieldname}{action when found}
 +
\btxdoifnot {fieldname}                  {action when not found}
 +
</pre>
 +
<p></p>
 +
An ex­tra con­di­tional is avail­able for test­ing in­ter­ac­tiv­ity:
 +
   
 +
<pre style="color:rgb(102,0,102);font-size:100%">\btxdoifelseinteraction{action when true}{action when false}
 +
</pre>
 +
<p></p>
 +
In ad­di­tion there is also a con­di­tional <tt style="color:rgb(0,102,102);font-size:100%;" >\btxinteractive</tt> which is more ef­fi­cient, al­though in prac­tice ef­fi­ciency is not so im­por­tant here.
 +
<p></p>
 +
There are three com­mands to flush data:
 +
   
 +
<table>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >\btxfield</tt></td><td>fetch a ex­plicit 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 de­rived 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 de­rived or ex­plicit field</td></tr>
 +
</table>
  
*For EUROTEX 2006, see slides here:http://www.matexhu.org/eurotex2006/lectures/
+
<p></p>
 +
Nor­mally 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 de­rived fields just like an­a­lyzed au­thor fields are flushed in a spe­cial way.
 +
<p></p>
 +
You can im­prove read­abil­ity by us­ing se­tups, for in­stance:
 +
   
 +
<pre style="color:rgb(102,0,102);font-size:100%">\btxdoifelse {author} {
 +
    \btxsetup{btx:apa:author:yes}
 +
} {
 +
    \btxsetup{btx:apa:author:nop}
 +
}
 +
</pre>
 +
<p></p>
 +
Keep in mind that nor­mally you don’t need to mess with de­f­i­n­i­tions like this be­cause stan­dard ren­der­ing styles are pro­vided. These styles use a few helpers that in­ject sym­bols but also take care of lead­ing and trail­ing spaces:
 +
   
 +
<table>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >\btxspace</tt></td><td>be­fore af­ter</td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >\btxperiod</tt></td><td>be­fore. af­ter</td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >\btxcomma</tt></td><td>be­fore, af­ter</td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >\btxlparent</tt></td><td>be­fore (af­ter</td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >\btxrparent</tt></td><td>be­fore) af­ter</td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >\btxlbracket</tt></td><td>be­fore [af­ter</td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >\btxrbracket</tt></td><td>be­fore] af­ter</td></tr>
 +
</table>
  
<!--* For EUROTEX 2007, see some slides here: http://www.logosrl.it/context/EuroTeX2007/ -->
+
<p></p>
*Also very interesting are colors (here [http://contextgarden.net/index.php?title=Colors])
+
So, the pre­vi­ous ex­am­ple setup can be rewrit­ten as:
 +
   
 +
<pre style="color:rgb(102,0,102);font-size:100%">\btxdoif {title} {
 +
    \bold{\btxfield{title}}
 +
    \btxcomma
 +
}
 +
</pre>
 +
<p></p>
 +
There is a spe­cial com­mand for ren­der­ing a (com­bi­na­tion) of au­thors:
 +
   
 +
<pre style="color:rgb(102,0,102);font-size:100%">\btxflushauthor{author}
 +
\btxflushauthor{editor}
 +
\btxflushauthor[inverted]{editor}
 +
</pre>
 +
<p></p>
 +
In­stead 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 (con­fig­urable) de­fault or pass di­rec­tives: Valid di­rec­tives are
 +
   
 +
<table>
 +
<tr><td>con­ver­sion</td><td>ren­der­ing</td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >inverted</tt></td><td>the Frog jr, Ker­mit</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>Ker­mit, 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>
  
----
+
   
*Is Indesign CS2 better than ConTeXt ?
+
   
----
+
<h1>Ci­ta­tions</h1>
  
=Cool links=
+
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:
*http://gnupdf.org
+
   
 +
<pre style="color:rgb(102,0,102);font-size:100%">\cite[author][example::demo-003]
 +
\cite[authoryear][example::demo-003]
 +
\cite[authoryears][example::demo-003]
 +
\cite[author][example::demo-003,demo-004]
 +
\cite[authoryear][example::demo-003,demo-004]
 +
\cite[authoryears][example::demo-003,demo-004]
 +
\cite[author][example::demo-004,demo-003]
 +
\cite[authoryear][example::demo-004,demo-003]
 +
\cite[authoryears][example::demo-004,demo-003]
 +
</pre>
 +
   
 +
<div>
 +
:(Hans Ha­gen and Ton Ot­ten)
 +
:(Hans Ha­gen and Ton Ot­ten (1996))
 +
:(Hans Ha­gen and Ton Ot­ten, 1996)
 +
:(Hans Ha­gen and Ton Ot­ten, Luigi Scarso)
 +
:(Hans Ha­gen and Ton Ot­ten (1996), Luigi Scarso (2021))
 +
:(Hans Ha­gen and Ton Ot­ten, 1996, Luigi Scarso, 2021)
 +
:(Luigi Scarso, Hans Ha­gen and Ton Ot­ten)
 +
:(Luigi Scarso (2021), Hans Ha­gen and Ton Ot­ten (1996))
 +
:(Luigi Scarso, 2021, Hans Ha­gen and Ton Ot­ten, 1996)
 +
</div>
  
 +
<p></p>
 +
The first ar­gu­ment is op­tional.
 +
<div style="border:thin solid black;" >
 +
<span style="font-style:oblique;" > setup definition cite </span >
 +
</div>
 +
<p></p>
 +
You can tune the way a ci­ta­tion shows up:
 +
   
 +
<pre style="color:rgb(102,0,102);font-size:100%">\setupbtxcitevariant[author]    [sorttype=author,color=darkyellow]
 +
\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]
 +
\cite[authoryears][example::demo-004,demo-003]
 +
</pre>
 +
<p></p>
 +
Here we sort the au­thors and color the ci­ta­tion:
 +
   
 +
<div>
 +
:(Hans Ha­gen and Ton Ot­ten, Luigi Scarso)
 +
:(Hans Ha­gen and Ton Ot­ten (1996), Luigi Scarso (2021))
 +
:(Hans Ha­gen and Ton Ot­ten, 1996, Luigi Scarso, 2021)
 +
</div>
  
*http://pdfedit.petricek.net/ pdfeditor
+
<p></p>
 +
For rea­sons of back­ward com­pat­i­bil­ity the <tt style="color:rgb(0,102,102);font-size:100%;" >\cite</tt> com­mand is a bit picky about spaces be­tween the two ar­gu­ments, of which the first is op­tional. This is a con­se­quence of al­low­ing its use with the key spec­i­fied be­tween curly brack­ets as is the tra­di­tional prac­tice. (We do en­cour­age users to adopt the more co­her­ent <span tag="MKIV" style="font-style:sans;">ConTEXt</span> syn­tax by us­ing square brack­ets for key­words and re­serv­ing curly brack­ets to re­group text to be type­set.)
 +
<p></p>
 +
The <tt style="color:rgb(0,102,102);font-size:100%;" >\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 style="color:rgb(102,0,102);font-size:100%">\citation[author]    [example::demo-004,demo-003]
 +
\citation[authoryear] [example::demo-004,demo-003]
 +
\citation[authoryears][example::demo-004,demo-003]
 +
</pre>
 +
<p></p>
 +
There is a whole bunch of cite op­tions and more can be eas­ily de­fined.  
 +
   
 +
<table>
 +
<tr><td>key</td><td>ren­der­ing</td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >author</tt></td><td>(au­thor)</td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >authornum</tt></td><td>[au­thor [btx er­ror 1]]</td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >authoryear</tt></td><td>(au­thor (year))</td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >authoryears</tt></td><td>(au­thor, 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 er­ror 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>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >short</tt></td><td>[aut00]</td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >type</tt></td><td>[book]</td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >url</tt></td><td>[todo: url]</td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >year</tt></td><td>(year)</td></tr>
 +
</table>
  
 +
<p></p>
 +
Be­cause we are deal­ing with data­base in­put and be­cause we gen­er­ally need to ma­nip­u­late en­tries, much of the work is del­e­gated to <span tag="MKIV" style="font-style:sans;">Lua</span>. This makes it eas­ier to main­tain and ex­tend the code. Of course <span tag="MKIV" style="font-style:sans;">TEX</span> still does the ren­der­ing. The ty­po­graphic de­tails are con­trolled by pa­ra­me­ters but not all are used in all vari­ants. As with most <span tag="MKIV" style="font-style:sans;">ConTEXt</span> com­mands, it starts out with a gen­eral setup com­mand:
 +
<div style="border:thin solid black;" >
 +
<span style="font-style:oblique;" > setup definition setupbtxcitevariant </span >
 +
</div>
 +
<p></p>
 +
On top of that we can de­fine in­stances that in­herit ei­ther from a given par­ent or from the top­most setup.
 +
<div style="border:thin solid black;" >
 +
<span style="font-style:oblique;" > setup definition definebtxcitevariant </span >
 +
</div>
 +
<p></p>
 +
But, spe­cific vari­ants can have them over­loaded:
 +
<p></p>
 +
<tt style="color:rgb(102,0,102);font-size:100%;" >setupbtxcitevariant : author</tt>
 +
   
 +
<table>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >right</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >)</tt></td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >middle</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >, </tt></td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >left</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >(</tt></td></tr>
 +
</table>
  
*http://www.mail-archive.com/poppler@lists.freedesktop.org/msg00334.html There is a Ruby binding, Ruby/Poppler, in Ruby-GNOME2 project.
+
<p></p>
 +
<tt style="color:rgb(102,0,102);font-size:100%;" >setupbtxcitevariant : authornum</tt>
 +
   
 +
<table>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >right</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >]</tt></td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >middle</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >, </tt></td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >left</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >[</tt></td></tr>
 +
</table>
  
 +
<p></p>
 +
<tt style="color:rgb(102,0,102);font-size:100%;" >setupbtxcitevariant : authoryear</tt>
 +
   
 +
<table>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >compress</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >yes</tt></td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >inbetween</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >, </tt></td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >right</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >)</tt></td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >middle</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >, </tt></td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >left</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >(</tt></td></tr>
 +
</table>
  
*http://podofo.sourceforge.net/ PDF parsing library
+
<p></p>
 +
<tt style="color:rgb(102,0,102);font-size:100%;" >setupbtxcitevariant : authoryears</tt>
 +
   
 +
<table>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >compress</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >yes</tt></td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >inbetween</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >, </tt></td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >right</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >)</tt></td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >middle</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >, </tt></td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >left</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >(</tt></td></tr>
 +
</table>
  
*http://search.cpan.org/dist/CAM-PDF/ PDF manipulation library
+
<p></p>
 +
<tt style="color:rgb(102,0,102);font-size:100%;" >setupbtxcitevariant : doi</tt>
 +
   
 +
<table>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >right</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >]</tt></td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >left</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >[</tt></td></tr>
 +
</table>
  
 +
<p></p>
 +
<tt style="color:rgb(102,0,102);font-size:100%;" >setupbtxcitevariant : key</tt>
 +
   
 +
<table>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >right</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >]</tt></td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >left</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >[</tt></td></tr>
 +
</table>
  
*http://www.coherentgraphics.co.uk/camlpdf.html `` an OCaml library for reading, writing and manipulating Adobe portable document files``
+
<p></p>
 +
<tt style="color:rgb(102,0,102);font-size:100%;" >setupbtxcitevariant : none</tt>
 +
   
 +
<table>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >no specific settings</tt></td><td></td></tr>
 +
</table>
  
 +
<p></p>
 +
<tt style="color:rgb(102,0,102);font-size:100%;" >setupbtxcitevariant : num</tt>
 +
   
 +
<table>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >compress</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >yes</tt></td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >inbetween</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >--</tt></td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >right</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >]</tt></td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >left</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >[</tt></td></tr>
 +
</table>
  
*http://hackage.haskell.org/cgi-bin/hackage-scripts/package/HPDF-1.3
+
<p></p>
 +
<tt style="color:rgb(102,0,102);font-size:100%;" >setupbtxcitevariant : page</tt>
 +
   
 +
<table>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >inbetween</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >–</tt></td></tr>
 +
</table>
  
 +
<p></p>
 +
<tt style="color:rgb(102,0,102);font-size:100%;" >setupbtxcitevariant : serial</tt>
 +
   
 +
<table>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >right</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >]</tt></td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >left</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >[</tt></td></tr>
 +
</table>
  
 +
<p></p>
 +
<tt style="color:rgb(102,0,102);font-size:100%;" >setupbtxcitevariant : short</tt>
 +
   
 +
<table>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >right</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >]</tt></td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >left</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >[</tt></td></tr>
 +
</table>
  
*http://poppler.freedesktop.org/ (waiting for a python binding..)
+
<p></p>
 +
<tt style="color:rgb(102,0,102);font-size:100%;" >setupbtxcitevariant : type</tt>
 +
   
 +
<table>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >right</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >]</tt></td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >left</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >[</tt></td></tr>
 +
</table>
  
*http://pybrary.net/pyPdf/  
+
<p></p>
 +
<tt style="color:rgb(102,0,102);font-size:100%;" >setupbtxcitevariant : url</tt>
 +
   
 +
<table>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >right</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >]</tt></td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >left</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >[</tt></td></tr>
 +
</table>
  
*http://www.boddie.org.uk/david/Projects/Python/pdftools/.
+
<p></p>
 +
<tt style="color:rgb(102,0,102);font-size:100%;" >setupbtxcitevariant : year</tt>
 +
   
 +
<table>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >right</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >)</tt></td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >left</tt></td><td><tt style="color:rgb(0,102,102);font-size:100%;" >(</tt></td></tr>
 +
</table>
  
 +
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 style="color:rgb(0,102,102);font-size:100%;" >publ-imp-*.mkiv</tt> files. Here we stick to the con­cept.
 +
   
 +
<pre style="color:rgb(102,0,102);font-size:100%">\startsetups btx:cite:author
 +
    \btxcitevariant{author}
 +
\stopsetups
 +
</pre>
 +
<p></p>
 +
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 style="color:rgb(0,102,102);font-size:100%;" >\btxcitevariant</tt> com­mand is one of the build in ac­ces­sors and it calls out to <span tag="MKIV" style="font-style:sans;">Lua</span> 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 style="color:rgb(0,102,102);font-size:100%;" >\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 style="color:rgb(0,102,102);font-size:100%;" >\cite</tt>. For spe­cial pur­poses you can use these com­mands
 +
   
 +
<pre style="color:rgb(102,0,102);font-size:100%">\setbtxdataset[example]
 +
\setbtxentry[hh2013]
 +
</pre>
 +
<p></p>
 +
But don’t ex­pect too much sup­port for such low level ren­der­ing con­trol.
 +
<p></p>
 +
Un­less you use <tt style="color:rgb(0,102,102);font-size:100%;" >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 style="color:rgb(0,102,102);font-size:100%;" >\usecitation</tt>, for ex­am­ple:
 +
   
 +
<pre style="color:rgb(102,0,102);font-size:100%">\usecitation[example::demo-004,demo-003]
 +
</pre>
 +
<p></p>
 +
This com­mand has two syn­onyms: <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 what­ever fits you best.
 +
<div style="border:thin solid black;" >
 +
<span style="font-style:oblique;" > setup definition nocite </span >
 +
</div>
 +
   
 +
   
 +
<h1>The LUA view</h1>
  
* http://www.fpdf.org/ (PHP)
+
Be­cause we man­age data at the <span tag="MKIV" style="font-style:sans;">Lua</span> end it is tempt­ing to ac­cess it there for other pur­poses. This is fine as long as you keep in mind that as­pects of the im­ple­men­ta­tion may change over time, al­though this is un­likely once the mod­ules be­come sta­ble.
 +
<p></p>
 +
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 style="color:rgb(0,102,102);font-size:100%;" >example</tt>. A dataset ta­ble has sev­eral fields, and prob­a­bly the one of most in­ter­est is the <tt style="color:rgb(0,102,102);font-size:100%;" >luadata</tt> field. Each en­try in this ta­ble de­scribes a pub­li­ca­tion:
 +
   
 +
<pre style="color:rgb(102,0,102);font-size:100%">t={
 +
["author"]="Hans Hagen",
 +
["category"]="book",
 +
["index"]=1,
 +
["tag"]="demo-001",
 +
["title"]="\\btxcmd{BIBTEX}, the \\btxcmd{CONTEXT}\\ way",
 +
["year"]="2013",
 +
}
 +
</pre>
 +
This is <tt style="color:rgb(0,102,102);font-size:100%;" >publications.datasets.example.luadata["demo-001"]</tt>. There can be a com­pan­ion en­try in the par­al­lel <tt style="color:rgb(0,102,102);font-size:100%;" >details</tt> ta­ble.
 +
   
 +
<pre style="color:rgb(102,0,102);font-size:100%">t={
 +
["author"]={
 +
  {
 +
  ["firstnames"]={ "Hans" },
 +
  ["initials"]={ "H" },
 +
  ["original"]="Hans Hagen",
 +
  ["surnames"]={ "Hagen" },
 +
  ["vons"]={},
 +
  },
 +
},
 +
["short"]="Hag13",
 +
}
 +
</pre>
 +
These de­tails are ac­cessed as <tt style="color:rgb(0,102,102);font-size:100%;" >publications.datasets.example.details["demo-001"]</tt> and by us­ing a sep­a­rate ta­ble we can over­load fields in the orig­i­nal en­try with­out los­ing the orig­i­nal.
 +
<p></p>
 +
You can loop over the en­tries us­ing reg­u­lar <span tag="MKIV" style="font-style:sans;">Lua</span> code com­bined 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
 +
context.starttabulate { "|l|l|l|" }
 +
for tag, entry in table.sortedhash(dataset.luadata) do
 +
    local detail = dataset.details[tag] or { }
 +
    context.NC() context.type(tag)
 +
    context.NC() context(detail.short)
 +
    context.NC() context(entry.title)
 +
    context.NC() context.NR()
 +
end
 +
context.stoptabulate()
 +
</pre>
 +
<p></p>
 +
This re­sults 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>Type­set­ting ed­u­ca­tion doc­u­ments</td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >demo-004</tt></td><td>Sca21</td><td>De­sign­ing 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>ti­tle</td></tr>
 +
</table>
  
 
+
<p></p>
*http://www.ghostscript.com  With a bit of hacking, using ctypes (default from python 2.5) one can make a rapid binding to libgs.so or gs.dll
+
You can ma­nip­u­late a dataset af­ter load­ing. Of course this as­sumes that you know what kind of con­tent you have and what you need for ren­der­ing. As ex­am­ple we load a small dataset.  
 
+
   
* http://ccxvii.net/apparition/
+
<pre style="color:rgb(102,0,102);font-size:100%">\definebtxdataset[drumming]
 
+
\usebtxdataset[drumming][mkiv-publications.lua]
 
+
</pre>
 
+
<p></p>
* http://portablesigner.sourceforge.net/ (sign PDFs
+
Be­cause we’re go­ing 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>
*http://wiki.contextgarden.net/HTML_and_ConTeXt
+
The dataset has three en­tries:
 
+
<p></p>
*http://www.fauskes.net/ pgf and so.
+
As you can see, we can have a sub­ti­tle. We will com­bine the ti­tle and sub­ti­tle into one:  
 
+
   
 
+
<pre style="color:rgb(102,0,102);font-size:100%">\startluacode
*http://context.aanhet.net/svn some sources
+
for tag, entry in next, publications.datasets.drumming.luadata do
 
+
    if entry.subtitle then
= Luatex examples =
+
        if entry.title then
Examples from <tt>Vyatcheslav Yatskovsky <yatskovsky at gmail.com> </tt>
+
            entry.title = entry.title .. ", " .. entry.subtitle
 
+
        else
*Say you needed to prepare about twenty test papers with 10 questions per a paper, that is, 200 questions. Examples: "1. convert Dec 36 into Hex", "2. convert Bin 10010101 into Dec", etc. The wording of every question should remain the same, only figures have to be changed through papers. Instead of inventing 200 numbers, you can write simple Lua scripts that generate random values and put them inside your question text:
+
            entry.title = entry.subtitle
<pre>
+
        end
% random decimal number
+
        entry.subtitle = nil
Convert
+
        logs.report("btx","combining title and subtitle of entry tagged %a",tag)
\ctxlua{n=math.random(30,60); tex.print(n);}\low{10}
+
    end
into Bin.
 
 
 
% random binary number
 
Convert
 
\startluacode
 
for c = 1, 16 do
 
n = math.random(0,1)
 
tex.sprint(n)
 
 
end
 
end
\stopluacode\low{2} into Hex.
 
 
% a pair of random hexadecimals
 
Perform logical AND, OR and XOR under the following pair of hexadecimal numbers:
 
\startluacode
 
n = math.random(10,255)
 
m = math.random(10,255)
 
tex.print(string.format("%X, %X", n, m))
 
 
\stopluacode
 
\stopluacode
 +
</pre>
 +
<p></p>
 +
We can now type­set the en­tries with:
 +
   
 +
<pre style="color:rgb(102,0,102);font-size:100%">\definebtxrendering[drumming][dataset=drumming,method=dataset]
 +
\placebtxrendering[drumming]
 +
</pre>
 +
<p></p>
 +
Be­cause we just want to show the en­tries, and have no ci­ta­tions 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>
  
% random word
+
The <tt style="color:rgb(0,102,102);font-size:100%;" >luadata</tt> ta­ble can be con­verted into an <span tag="MKIV" style="font-style:sans;">xml</span> rep­re­sen­ta­tion. This is a fol­low up on ear­lier ex­per­i­ments with an <span tag="MKIV" style="font-style:sans;">xml</span>-only ap­proach. I de­cided in the end to stick to a <span tag="MKIV" style="font-style:sans;">Lua</span> ap­proach and pro­vide some sim­ple <span tag="MKIV" style="font-style:sans;">xml</span> sup­port in ad­di­tion.
Encode your full name as  
+
<p></p>
\startluacode
+
Once a dataset is ac­ces­si­ble as <span tag="MKIV" style="font-style:sans;">xml</span> tree, you can use the reg­u­lar <tt style="color:rgb(0,102,102);font-size:100%;" >\xml...</tt> com­mands. We start with load­ing a dataset, in this case from just one file.
a = {'null-terminated', 'dollar-terminated', 'Pascal shortstring'}
+
   
tex.print( string.format('%s string.', a[math.random(1,3)]) );
+
<pre style="color:rgb(102,0,102);font-size:100%">\usebtxdataset[tugboat][tugboat.bib]
\stopluacode
+
</pre>
 +
<p></p>
 +
The dataset has to be con­verted 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 ac­ces­si­ble by its root ref­er­ence <tt style="color:rgb(0,102,102);font-size:100%;" >btx:tugboat</tt>. If we want sim­ple field ac­cess we can use a few se­tups:
 +
   
 +
<pre style="color:rgb(102,0,102);font-size:100%">\startxmlsetups btx:initialize
 +
    \xmlsetsetup{#1}{bibtex|entry|field}{btx:*}
 +
    \xmlmain{#1}
 +
\stopxmlsetups
 +
\startxmlsetups btx:field
 +
    \xmlflushcontext{#1}
 +
\stopxmlsetups
 +
\xmlsetup{btx:tugboat}{btx:initialize}
 +
</pre>
 +
<p></p>
 +
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 style="color:rgb(102,0,102);font-size:100%">\starttabulate[|||]
 +
    \NC \type {tag}  \NC \xmlfirst {btx:tugboat}
 +
        {/bibtex/entry[string.find(@tag,'Hagen')]/attribute('tag')}
 +
    \NC \NR
 +
    \NC \type {title} \NC \xmlfirst {btx:tugboat}
 +
        {/bibtex/entry[string.find(@tag,'Hagen')]/field[@name='title']}
 +
    \NC \NR
 +
\stoptabulate
 
</pre>
 
</pre>
 +
   
 +
<table>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >tag</tt></td><td>Ha­gen:TB17-1-54</td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >title</tt></td><td>PPCHTEX: type­set­ting chem­i­cal for­mu­las in TEX</td></tr>
 +
</table>
  
= Luatex hosts python =
+
   
Following [http://labix.org/lunatic-python] I was able, in a linux box, to modify luatex-snapshot-20070820.tar.bz2  so that <tt>luatex --luaonly</tt> can  host python. Of course <tt>\directlua0{....}</tt> also works.<br/>
+
<pre style="color:rgb(102,0,102);font-size:100%">\startxmlsetups btx:demo
(also http://rubyluabridge.rubyforge.org<br/>
+
    \xmlcommand
http://lua-users.org/wiki/LibrariesAndBindings)<br/>
+
        {#1}
'''WARNING: these modifications break security and portability''' <br/>
+
        {/bibtex/entry[string.find(@tag,'Hagen')][1]}{btx:table}
'''WARNING: these are not examples of proprer context mkiv code''' <br/>
+
\stopxmlsetups
 +
\startxmlsetups btx:table
 +
\starttabulate[|||]
 +
    \NC \type {tag}  \NC \xmlatt{#1}{tag} \NC \NR
 +
    \NC \type {title} \NC \xmlfirst{#1}{/field[@name='title']} \NC \NR
 +
\stoptabulate
 +
\stopxmlsetups
 +
\xmlsetup{btx:tugboat}{btx:demo}
 +
</pre>
 +
   
 +
<table>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >tag</tt></td><td>Ha­gen:TB17-1-54</td></tr>
 +
<tr><td><tt style="color:rgb(0,102,102);font-size:100%;" >title</tt></td><td>PPCHTEX: type­set­ting chem­i­cal for­mu­las in TEX</td></tr>
 +
</table>
  
<pre>
+
<p></p>
% engine=luatex
+
Here is an­other ex­am­ple:
\def\TestA#1{%
+
   
\directlua0{%
+
<pre style="color:rgb(102,0,102);font-size:100%">\startxmlsetups btx:row
require('python')
+
    \NC \xmlatt{#1}{tag}
re = python.import("re")
+
    \NC \xmlfirst{#1}{/field[@name='title']}
pattern = re.compile(".*(TeX).*")
+
    \NC \NR
match = pattern.match("#1")
+
\stopxmlsetups
if match
+
\startxmlsetups btx:demo
then
+
    \xmlfilter {#1} {
  print( 'match.group(1)===>',match.group(1))
+
        /bibtex
else
+
        /entry[@category='article']
print ('#1 no match')
+
        /field[@name='author' and (find(text(),'Knuth') or find(text(),'DEK'))]
end
+
        /../command(btx:row)
}}
+
    }
 +
\stopxmlsetups
 +
\starttabulate[|||]
 +
    \xmlsetup{btx:tugboat}{btx:demo}
 +
\stoptabulate
 +
</pre>
 +
   
 +
<table>
 +
<tr><td>Knuth:TB10-1-31</td><td>Type­set­ting Con­crete Math­e­mat­ics</td></tr>
 +
<tr><td>Knuth:TB10-1-8</td><td>TEX would find it dif­fi­cult …</td></tr>
 +
<tr><td>Knuth:TB10-3-325</td><td>The new ver­sions of TEX and MF</td></tr>
 +
<tr><td>Knuth:TB10-4-529</td><td>The er­rors of TEX</td></tr>
 +
<tr><td>Knuth:TB11-1-13</td><td>Vir­tual Fonts: More Fun for Grand Wiz­ards</td></tr>
 +
<tr><td>Knuth:TB11-2-165</td><td>Ex­er­cises for TEX: The Pro­gram</td></tr>
 +
<tr><td>Knuth:TB11-4-489</td><td>The fu­ture 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>An­swers to Ex­er­cises for TEX: The Pro­gram</td></tr>
 +
<tr><td>Knuth:TB12-2-313</td><td>Fixed-point glue set­ting: Er­rata</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>Im­por­tant mes­sage re­gard­ing CM fonts</td></tr>
 +
<tr><td>Knuth:TB2-3-5</td><td>The cur­rent state of things</td></tr>
 +
<tr><td>Knuth:TB3-1-10</td><td>Fixed-point glue set­ting­Dash an ex­am­ple of WEB</td></tr>
 +
<tr><td>Knuth:TB31-2-121</td><td>An Earth­shak­ing An­nounce­ment</td></tr>
 +
<tr><td>Knuth:TB4-2-64</td><td>A note on hy­phen­ation</td></tr>
 +
<tr><td>Knuth:TB5-1-4</td><td>TEX in­cunab­ula</td></tr>
 +
<tr><td>Knuth:TB5-1-67</td><td>Com­ments on qual­ity in pub­lish­ing</td></tr>
 +
<tr><td>Knuth:TB5-2-105</td><td>A course on MF pro­gram­ming</td></tr>
 +
<tr><td>Knuth:TB6-1-36</td><td>Recipes and frac­tions</td></tr>
 +
<tr><td>Knuth:TB7-2-101</td><td>The TEX logo in var­i­ous fonts</td></tr>
 +
<tr><td>Knuth:TB7-2-95</td><td>Re­marks to cel­e­brate the pub­li­ca­tion of Com­put­ers & Type­set­ting</td></tr>
 +
<tr><td>Knuth:TB8-1-14</td><td>Mix­ing right-to-left texts with left-to-right texts</td></tr>
 +
<tr><td>Knuth:TB8-1-6</td><td>It hap­pened: an­nounce­ment of TEX 2.1</td></tr>
 +
<tr><td>Knuth:TB8-1-73</td><td>Prob­lem for a Sat­ur­day af­ter­noon</td></tr>
 +
<tr><td>Knuth:TB8-2-135</td><td>Fonts for dig­i­tal halftones</td></tr>
 +
<tr><td>Knuth:TB8-2-210</td><td>Sat­ur­day morn­ing prob­lem­Dash so­lu­tion</td></tr>
 +
<tr><td>Knuth:TB8-2-217</td><td>Re­ply: Print­ing out se­lected 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>
 +
</table>
  
\def\TestB#1{%
+
<p></p>
\directlua1{%
+
A more ex­ten­sive ex­am­ple is the fol­low­ing. Of course this as­sumes that you know what <span tag="MKIV" style="font-style:sans;">xml</span> sup­port mech­a­nisms and macros are avail­able.
require('python')
+
   
re = python.import("re")
+
<pre style="color:rgb(102,0,102);font-size:100%">\startxmlsetups btx:getkeys
pattern = re.compile(".*(TeX).*")
+
    \xmladdsortentry{btx}{#1}{\xmlfilter{#1}{/field[@name='author']/text()}}
match = pattern.match("#1")
+
    \xmladdsortentry{btx}{#1}{\xmlfilter{#1}{/field[@name='year'  ]/text()}}
if match
+
    \xmladdsortentry{btx}{#1}{\xmlatt{#1}{tag}}
then
+
\stopxmlsetups
   print( 'match.group(1)===>',match.group(1))
+
\startxmlsetups btx:sorter
else
+
    \xmlresetsorter{btx}
  print ('#1 no match')
+
   % \xmlfilter{#1}{entry/command(btx:getkeys)}
end
+
    \xmlfilter{#1}{
}}
+
        /bibtex
 +
        /entry[@category='article']
 +
        /field[@name='author' and find(text(),'Knuth')]
 +
        /../command(btx:getkeys)}
 +
    \xmlsortentries{btx}
 +
    \starttabulate[||||]
 +
        \xmlflushsorter{btx}{btx:entry:flush}
 +
    \stoptabulate
 +
\stopxmlsetups
 +
\startxmlsetups btx:entry:flush
 +
    \NC \xmlfilter{#1}{/field[@name='year' ]/context()}
 +
    \NC \xmlatt{#1}{tag}
 +
    \NC \xmlfilter{#1}{/field[@name='author']/context()}
 +
    \NC \NR
 +
\stopxmlsetups
 +
\xmlsetup{btx:tugboat}{btx:sorter}
 +
</pre>
 +
   
 +
<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>Don­ald E. Knuth</td></tr>
 +
<tr><td>1984</td><td>Knuth:TB5-2-105</td><td>Don­ald E. Knuth</td></tr>
 +
<tr><td>1985</td><td>Knuth:TB6-1-36</td><td>Don­ald E. Knuth</td></tr>
 +
<tr><td>1986</td><td>Knuth:TB7-2-101</td><td>Don­ald E. Knuth</td></tr>
 +
<tr><td>1987</td><td>Knuth:TB8-2-135</td><td>Don­ald E. Knuth</td></tr>
 +
<tr><td>1987</td><td>Knuth:TB8-3-309</td><td>Don­ald E. Knuth</td></tr>
 +
<tr><td>1988</td><td>Knuth:TB9-2-152</td><td>Don­ald E. Knuth</td></tr>
 +
<tr><td>1989</td><td>Knuth:TB10-3-325</td><td>Don­ald E. Knuth</td></tr>
 +
<tr><td>1989</td><td>Knuth:TB10-4-529</td><td>Don­ald E. Knuth</td></tr>
 +
<tr><td>1990</td><td>Knuth:TB11-4-489</td><td>Don­ald E. Knuth</td></tr>
 +
<tr><td>1993</td><td>Knuth:TB14-4-387</td><td>Don­ald E. Knuth</td></tr>
 +
<tr><td>1996</td><td>Knuth:TB17-1-29</td><td>Don­ald E. Knuth</td></tr>
 +
<tr><td>1987</td><td>Knuth:TB8-1-14</td><td>Don­ald Knuth and Pierre MacKay</td></tr>
 +
<tr><td>1981</td><td>Knuth:TB2-3-5</td><td>Don­ald Knuth</td></tr>
 +
<tr><td>1982</td><td>Knuth:TB3-1-10</td><td>Don­ald Knuth</td></tr>
 +
<tr><td>1983</td><td>Knuth:TB4-2-64</td><td>Don­ald Knuth</td></tr>
 +
<tr><td>1986</td><td>Knuth:TB7-2-95</td><td>Don­ald Knuth</td></tr>
 +
<tr><td>1987</td><td>Knuth:TB8-1-6</td><td>Don­ald Knuth</td></tr>
 +
<tr><td>1987</td><td>Knuth:TB8-1-73</td><td>Don­ald Knuth</td></tr>
 +
<tr><td>1987</td><td>Knuth:TB8-2-210</td><td>Don­ald Knuth</td></tr>
 +
<tr><td>1987</td><td>Knuth:TB8-2-217</td><td>Don­ald Knuth</td></tr>
 +
<tr><td>1989</td><td>Knuth:TB10-1-8</td><td>Don­ald Knuth</td></tr>
 +
<tr><td>1989</td><td>Knuth:TB10-1-31</td><td>Don­ald Knuth</td></tr>
 +
<tr><td>1990</td><td>Knuth:TB11-1-13</td><td>Don­ald Knuth</td></tr>
 +
<tr><td>1990</td><td>Knuth:TB11-2-165</td><td>Don­ald Knuth</td></tr>
 +
<tr><td>1990</td><td>Knuth:TB11-4-497</td><td>Don­ald Knuth</td></tr>
 +
<tr><td>1990</td><td>Knuth:TB11-4-499</td><td>Don­ald Knuth</td></tr>
 +
<tr><td>1991</td><td>Knuth:TB12-2-313</td><td>Don­ald Knuth</td></tr>
 +
<tr><td>2010</td><td>Knuth:TB31-2-121</td><td>Don­ald Knuth</td></tr>
 +
</table>
  
\def\TestC{%
+
<p></p>
\directlua0{%
+
The orig­i­nal data is stored in a <span tag="MKIV" style="font-style:sans;">Lua</span> ta­ble, hashed by tag. Start­ing 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 dif­fer­ent or­der­ing of such a hash. In older ver­sions, when you looped over a hash, the or­der was un­de­fined, but the same as long as you used the same bi­nary. This had the ad­van­tage that suc­ces­sive runs, some­thing we of­ten have in doc­u­ment pro­cess­ing gave con­sis­tent re­sults. In to­day’s <span tag="MKIV" style="font-style:sans;">Lua</span> we need to do much more sort­ing of hashes be­fore we loop, es­pe­cially when we save multi--pass data. It is for this rea­son that the <span tag="MKIV" style="font-style:sans;">xml</span> tree is sorted by hash key by de­fault. That way lookups (es­pe­cially the first of a set) give con­sis­tent out­comes.
require('python')
+
 
python.execute('n=1')
+
 
n=python.eval('n')
+
<h1>Stan­dards</h1>
print("PYTHON:"..n)
 
%% --[[ --]]
 
python.execute('s="XYZ"')
 
s=python.eval('s')
 
print("PYTHON:"..s,",lenght="..\letterhash s)
 
%% --[[ --]]
 
python.execute('d={"Boo":1}')
 
python.execute('d["FOO"]=2')
 
d=python.eval('d')
 
print("PYTHON:",d)
 
print("PYTHON:",d.Boo,d["Boo"],d.FOO,d["FOO"])
 
%% --[[ --]]
 
python.execute('a=[1,3,2,5,9]')
 
a=python.eval('a')
 
print("PYTHON:",a)
 
print("PYTHON:",a[0],a[1])
 
python.execute('a.append("X")')
 
python.execute('a.sort()')
 
a=python.eval('a')
 
print("PYTHON:",a)
 
print("PYTHON:",a[0],a[1])
 
%% --[[ --]]
 
a=python.eval('[0,3,8,2,-1]')
 
print("PYTHON:",a[3])
 
print("PYTHON:",a,type(a))
 
%%
 
}}
 
  
%%-- testD.lua
+
The ren­der­ing of bib­li­o­graphic en­tries is of­ten stan­dard­ized and pre­scribed by the pub­lisher. If you sub­mit an ar­ti­cle to a jour­nal, nor­mally it will be re­for­mat­ted (or even re- keyed) and the ren­der­ing will hap­pen at the pub­lish­ers end. In that case it may not mat­ter how en­tries were ren­dered when writ­ing the pub­li­ca­tion, be­cause the pub­lisher will do it his or her way. This means that most users prob­a­bly will stick to the stan­dard <span tag="MKIV" style="font-style:sans;">apa</span> rules and for them we pro­vide some con­fig­u­ra­tion. Be­cause we use se­tups it is easy to over­load specifics. If you re­ally want to tweak, best look in the files that deal with it.
%% require('python')
+
<p></p>
%% print("BEGIN PYTHON")
+
Many stan­dards ex­ist and sup­port for other ren­der­ings may be added to the core. In­ter­ested users are in­vited to de­velop and to test al­ter­nate stan­dard ren­der­ings ac­cord­ing to their needs.
%% pycode=[[
+
<p></p>
%% class Test(object):
+
Todo: maybe a list of cat­e­gories and fields.
%%  def __init__(self):
+
 
%%    self.a=[0,3,81,2,-1]
+
    
%%    self.b=self.a[:]
+
<h1>Clean­ing up</h1>
%%    self.a.sort()
 
%%   
 
%%  def get(self):   
 
%%    return self.a,self.b
 
%% ]]
 
%% python.execute(pycode)
 
%% python.execute("t=Test()")
 
%% print(python.eval("t.get()"))
 
%% t=python.eval("Test()")
 
%% print(t.get())
 
%% print(t.get()[0])
 
%% print(t.get()[0][0])
 
%% print(TeX)
 
%% print("END PYTHON")
 
\def\TestD#1{%
 
\directlua0{%
 
TeX='#1'
 
dofile('testD.lua')}%
 
}
 
 
 
%% -- testG.lua
 
%% require('python')
 
%% tex.print("\\ruledvbox{testG}\\blank")
 
%% tex.print("\\ruledvbox{BEGIN PYTHON}\\blank")
 
%% pyg = python.globals()
 
%% pycode=[[
 
%% class Test(object):
 
%%  def __init__(self,tex):
 
%%    self.tex=tex
 
%%   
 
%%   def getbboxpage(self):   
 
%%    return self.tex['hsize'],self.tex['vsize']
 
%%
 
%% ]]
 
%% python.execute(pycode)
 
%% --
 
%% pyg.tex = tex
 
%% python.execute("test=Test(tex)")
 
%% test=python.eval("test")
 
%% bboxpage = test.getbboxpage()
 
%% tex.print(tostring(bboxpage))
 
%% tex.print("\\blank\\ruledvbox{END PYTHON}")
 
\def\TestG{\directlua0{dofile('testG.lua')}}
 
  
 +
Al­though the <span tag="MKIV" style="font-style:sans;">bibTEX</span> for­mat is rea­son­ably well de­fined, in prac­tice there are many ways to or­ga­nize the data. For in­stance, one can use pre­de­fined string con­stants that get used (ei­ther or not com­bined with other strings) later on. A string can be en­closed in curly braces or dou­ble quotes. The strings can con­tain <span tag="MKIV" style="font-style:sans;">TEX</span> com­mands but these are not stan­dard­ized. The data­bases of­ten have some­what com­plex ways to deal with spe­cial char­ac­ters and the use of braces in their de­f­i­n­i­tion is also not nor­mal­ized.
 +
<p></p>
 +
The most com­plex to deal with are the fields that con­tain names of peo­ple. At some point it might be needed to split a com­bi­na­tion of names into in­di­vid­ual ones that then get split into ti­tle, first name, op­tional in­be­tweens, sur­name(s) and ad­di­tional: <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 ex­am­ple of this. The con­ven­tion seems to be not to use com­mas but <tt style="color:rgb(0,102,102);font-size:100%;" >and</tt> to sep­a­rate names (of­ten each name will be spec­i­fied as last­name, first­name).
 +
<p></p>
 +
We don’t see it as chal­lenge nor as a duty to sup­port all kinds of messy de­f­i­n­i­tions. Of course we try to be some­what tol­er­ant, but you will be sure to get bet­ter re­sults if you use nicely setup, con­sis­tent data­bases.
 +
<p></p>
 +
Todo: maybe some ex­am­ples of bad.
 +
 
 +
 
 +
<h1>Tran­si­tion</h1>
  
 +
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 style="color:rgb(102,0,102);font-size:100%">% engine=pdftex
 +
\usemodule[bib]
 +
\usemodule[bibltx]
 +
\setupbibtex
 +
  [database=xampl]
 +
\setuppublications
 +
  [numbering=yes]
 +
\starttext
 +
    As \cite [article-full] already indicated, bibtex is a \LATEX||centric
 +
    program.
 +
    \completepublications
 +
\stoptext
 +
</pre>
 +
<p></p>
 +
For <span tag="MKIV" style="font-style:sans;">MkIV</span> the mod­ules were partly rewrit­ten and ended up in the core so the two com­mands were no longer needed. The over­head as­so­ci­ated with the au­to­matic load­ing of the bib­li­og­ra­phy macros can be ne­glected these days, so stan­dard­ized mod­ules such as <tt style="color:rgb(0,102,102);font-size:100%;" >bib</tt> are all be­ing moved to the core and do not need to be ex­plic­itly loaded.
 +
<p></p>
 +
The first <tt style="color:rgb(0,102,102);font-size:100%;" >\setupbibtex</tt> com­mand in this ex­am­ple is needed to boot­strap the process: it tells what data­base has to be processed by <span tag="MKIV" style="font-style:sans;">bibTEX</span> be­tween runs. The sec­ond <tt style="color:rgb(0,102,102);font-size:100%;" >\setuppublications</tt> com­mand is op­tional. Each ci­ta­tion (tagged with <tt style="color:rgb(0,102,102);font-size:100%;" >\cite</tt>) ends up in the list of pub­li­ca­tions.
 +
<p></p>
 +
In the new ap­proach 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>. 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 style="color:rgb(0,102,102);font-size:100%;" >\cite</tt> com­mand re­mains. The above ex­am­ple be­comes:
 +
   
 +
<pre style="color:rgb(102,0,102);font-size:100%">\definebtxdataset
 +
  [document]
 +
\usebtxdataset
 +
  [document]
 +
  [mybibfile.bib]
 +
\definebtxrendering
 +
  [document]
 +
\setupbtxrendering
 +
  [document]
 +
  [numbering=yes]
 
\starttext
 
\starttext
 
+
    As \cite [article-full] already indicated, bibtex is a \LATEX||centric
\TestD
+
    program.
 
+
    \completebtxrendering[document]
 
\stoptext
 
\stoptext
 +
</pre>
 +
<p></p>
 +
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 style="color:rgb(102,0,102);font-size:100%">\usebtxdataset
 +
  [mybibfile.bib]
 +
\setupbtxrendering
 +
  [numbering=yes]
 +
</pre>
 +
<p></p>
 +
But keep in mind that com­pared to the old <span tag="MKIV" style="font-style:sans;">MkII</span> de­rived method we have moved some of the op­tions to the ren­der­ing, list and cite setup vari­ants.
 +
<p></p>
 +
An­other dif­fer­ence is now the use of lists. When you de­fine a ren­der­ing, you also de­fine a list. How­ever, all en­tries are col­lected in a com­mon list tagged <tt style="color:rgb(0,102,102);font-size:100%;" >btx</tt>. Al­though you will nor­mally con­fig­ure a ren­der­ing you can still set some prop­er­ties of lists, but in that case you need to pre­fix the list iden­ti­fier. In the case of the above ex­am­ple this is <tt style="color:rgb(0,102,102);font-size:100%;" >btx:document</tt>.
 +
 
 +
 
 +
<h1>ML­BIBTEX</h1>
  
 +
Todo: how to plug in <span tag="MKIV" style="font-style:sans;">ML­bibTEX</span> for sort­ing and other ad­vanced op­er­a­tions.
 +
 
 +
 
 +
<h1>Ex­ten­sions</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 ac­ces­si­ble in <span tag="MKIV" style="font-style:sans;">ConTEXt</span> 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 style="color:rgb(102,0,102);font-size:100%">function publications.loaders.myformat(dataset,filename)
 +
    local t = { }
 +
    -- Load data from 'filename' and convert it to a Lua table 't' with
 +
    -- the key as hash entry and fields conforming the luadata table
 +
    -- format.
 +
    loaders.lua(dataset,t)
 +
end
 +
</pre>
 +
<p></p>
 +
This then per­mits load­ing a data­base (into a dataset) with the com­mand:
 +
   
 +
<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> 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 style="color:rgb(102,0,102);font-size:100%">\usebtxdataset[standard][myformat::myfile.txt]
 
</pre>
 
</pre>
 
=Future ConTeXt Users=
 
[[Future_ConTeXt_Users]]
 

Revision as of 23:08, 19 January 2014




The data­base

The bibTEX for­mat is rather pop­u­lar in the TEX com­mu­nity and even with its short­com­ings it will stay around for a while. Many pub­li­ca­tion web­sites can ex­port and many tools are avail­able to work with this data­base for­mat. It is rather sim­ple and looks a bit like Lua ta­bles. Un­for­tu­nately the con­tent can be pol­luted with non-stan­dard­ized TEX com­mands which com­pli­cates pre- or post­pro­cess­ing out­side TEX. In that sense a bibTEX data­base is of­ten not coded neu­trally. Some lim­i­ta­tions, like the use of com­mands to en­code ac­cented char­ac­ters root in the ascii world and can be by­passed by us­ing utf in­stead (as han­dled some­what in LATEX through ex­ten­sions such as bibtex8).

The nor­mal way to deal with a bib­li­og­ra­phy is to re­fer to en­tries us­ing a unique tag or key. When a list of en­tries is type­set, this ref­er­ence can be used for link­ing pur­poses. The type­set list can be processed and sorted us­ing the bibtex pro­gram that con­verts the data­base into some­thing more TEX friendly (a .bbl file). I never used the pro­gram my­self (nor bib­li­ogra­phies) so I will not go into too much de­tail here, if only be­cause all I say can be wrong.

In ConTEXt we no longer use the bibtex pro­gram: we just use data­base files and deal with the nec­es­sary ma­nip­u­la­tions di­rectly in ConTEXt. One or more such data­bases can be used and com­bined with ad­di­tional en­tries de­fined within the doc­u­ment. We can have sev­eral such datasets ac­tive at the same time.

A bibTEX file looks like this:

@Article{sometag,
    author  = "An Author and Another One",
    title   = "A hopefully meaningful title",
    journal = maps,
    volume  = "25",
    number  = "2",
    pages   = "5--9",
    month   = mar,
    year    = "2013",
    ISSN    = "1234-5678",
}

Nor­mally a value is given be­tween quotes (or curly brack­ets) but sin­gle words are also OK (there is no real ben­e­fit in not us­ing quotes, so we ad­vise to al­ways use them). There can be many more fields and in­stead of strings one can use pre­de­fined short­cuts. The ti­tle for ex­am­ple quite of­ten con­tains TEX macros. Some fields, like pages have funny char­ac­ters such as the en­dash (typ­i­cally as --) so we have a mix­ture of data and type­set­ting di­rec­tives. If you are cov­er­ing non--eng­lish ref­er­ences, you of­ten need char­ac­ters that are not in the ascii sub­set but ConTEXt is quite happy with utf. If your data­base file uses old-fash­ioned TEX ac­cent com­mands then these will be in­ter­nally con­verted au­to­mat­i­cally to utf. Com­mands (macros) are con­verted to an in­di­rect call, which is quite ro­bust.

The bibTEX files are loaded in mem­ory as Lua ta­ble but can be con­verted to xml so that we can ac­cess them in a more flex­i­ble way, but that is a sub­ject for spe­cial­ists.

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.

\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

The split \artauthor fields are col­lapsed into a sin­gle author field as we deal with the split­ting later when it gets parsed in Lua. The \artauthor syn­tax is only kept around for back­ward com­pat­i­bil­ity with the pre­vi­ous use of bibTEX.

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

\startpublication[k=Hagen:Third,t=article]
    \author{Hans Hagen}
    \title{Who knows who?}
    ...
\stoppublication

and

\startpublication[tag=Hagen:Third,category=article]
    \author{Hans Hagen}
    \title{Who knows who?}
    ...
\stoppublication

and

\startpublication
    \tag{Hagen:Third}
    \category{article}
    \author{Hans Hagen}
    \title{Who knows who?}
    ...
\stoppublication

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:

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

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.

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

Todo: Add some re­marks about load­ing End­Note and RIS for­mats, but first we need to com­plete the tag map­ping (on Alan’s plate).

So the user has a rather wide choice of for­mat­ting style for bib­li­og­ra­phy data­base files.

You can load more data than you ac­tu­ally need. Only en­tries that are re­ferred to ex­plic­itly through the \cite and \nocite 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 tugboat.bib gives a long list of com­mands of which we show a small set here:

publications > start used btx commands
publications > standard CONTEXT 1 known
publications > standard ConTeXt 4 known
publications > standard TeXLive 3 KNOWN
publications > standard eTeX    1 known
publications > standard hbox    6 known
publications > standard sltt    1 unknown
publications > stop used btxcommands

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\TUB {TUGboat}
\definebtxcommand\sltt{\tt}
\definebtxcommand\<#1>{\type{#1}}

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 \btxcommand{...}, as in:

commands like \btxcommand{MySpecialCommand} are handled in an indirect way

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

??


Datasets

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

\definebtxdataset[standard]
\usebtxdataset[standard][tugboat.bib]
\usebtxdataset[standard][mtx-bibtex-output.xml]
\usebtxdataset[standard][test-001-btx-standard.lua]

These three suf­fixes are un­der­stood by the loader. Here the dataset has the name standard and the three data­base files are merged, where later en­tries hav­ing the same tag over­load pre­vi­ous ones. De­f­i­n­i­tions in the doc­u­ment source (coded in TEX speak) are also added, and they are saved for suc­ces­sive runs. This means that if you load and de­fine en­tries, they will be known at a next run be­fore­hand, so that ref­er­ences to them are in­de­pen­dent of when load­ing and de­f­i­n­i­tions take place.

setup definition setupbtxdataset

setup definition definebtxdataset

setup definition usebtxdataset

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

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

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

\showbtxdatasetfields[example]

this gives:

tagcat­e­goryfields
demo-001bookau­thor in­dex ti­tle year
demo-002bookcross­ref in­dex year
demo-003bookau­thor com­ment in­dex ti­tle year
demo-004bookau­thor com­ment in­dex ti­tle year
demo-005bookau­thor doi in­dex pages se­r­ial ti­tle url year

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

\setbtxdataset[standard]

but most pub­li­ca­tion-re­lated com­mands ac­cept op­tional ar­gu­ments that de­note the dataset and ref­er­ences to en­tries can be pre­fixed with a dataset iden­ti­fier.. More about that later.


Ren­der­ings

A list of pub­li­ca­tions can be ren­dered at any place in the doc­u­ment. A data­base can be much larger than needed for a doc­u­ment. The same is true for the fields that make up an en­try. Here is the list of fields that are cur­rently han­dled, but of course there can be ad­di­tional ones:

abstract, address, annotate, assignee, author, bibnumber, booktitle, chapter, comment, country, day, dayfiled, doi, edition, editor, eprint, howpublished, institution, isbn, issn, journal, key, keyword, keywords, language, lastchecked, month, monthfiled, names, nationality, note, notes, number, organization, pages, publisher, revision, school, series, size, title, type, url, volume, year, yearfiled

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:

\definebtxrendering
  [example]
  [dataset=example,
   method=local,
   alternative=apa]
\placelistofpublications % \placebtxrendering
  [example]
  [criterium=all]

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

The ren­der­ing it­self is some­what com­plex to set up be­cause we have not only many dif­fer­ent stan­dards but also many fields that can be set up. This means that there are sev­eral com­mands in­volved. Of­ten there is a pre­scribed style to ren­der bib­li­o­graphic de­scrip­tions, for ex­am­ple apa. A ren­der­ing is setup and de­fined with:

setup definition setupbtxrendering

setup definition definebtxrendering

And a list of such de­scrip­tions is gen­er­ated with:

setup definition placebtxrendering

A dataset can have all kind of en­tries:

article, book, booklet, conference, inbook, incollection, inproceedings, manual, mastersthesis, misc, phdthesis, proceedings, techreport, unpublished

Each has its own ren­der­ing vari­ant. To keep things sim­ple we have their set­tings sep­a­rated. How­ever, these set­tings are shared for all ren­der­ing al­ter­na­tives. In prac­tice this is sel­dom a prob­lem in a pub­li­ca­tion as only one ren­der­ing al­ter­na­tive will be ac­tive. If this be not suf­fi­cient, you can al­ways group lo­cal set­tings in a setup and hook that into the spe­cific ren­der­ing.

setup definition setupbtxlistvariant

setup definition definebtxlistvariant

Ex­am­ples of list vari­ants are:

setupbtxlistvariant : artauthor

no specific settings

setupbtxlistvariant : author

no specific settings

setupbtxlistvariant : editor

no specific settings

The ex­act ren­der­ing of list en­tries is de­ter­mined by the alternative key and de­faults to apa which uses de­f­i­n­i­tions from publ-imp-apa.mkiv. If you look at that file you will see that each cat­e­gory has its own setup. You may also no­tice that ad­di­tional tests are needed to make sure that empty fields don’t trig­ger sep­a­ra­tors and such.

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

\btxdoif {title} {
    \bold{\btxfield{title}},
}

There are three test macros:

\btxdoifelse{fieldname}{action when found}{action when not found}
\btxdoif    {fieldname}{action when found}
\btxdoifnot {fieldname}                   {action when not found}

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

\btxdoifelseinteraction{action when true}{action when false}

In ad­di­tion there is also a con­di­tional \btxinteractive which is more ef­fi­cient, al­though in prac­tice ef­fi­ciency is not so im­por­tant here.

There are three com­mands to flush data:

\btxfieldfetch a ex­plicit field (e.g. year)
\btxdetailfetch a de­rived field (e.g. short)
\btxflushfetch a de­rived or ex­plicit field

Nor­mally you can use \btxfield or \btxflush as de­rived fields just like an­a­lyzed au­thor fields are flushed in a spe­cial way.

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

\btxdoifelse {author} {
    \btxsetup{btx:apa:author:yes}
} {
    \btxsetup{btx:apa:author:nop}
}

Keep in mind that nor­mally you don’t need to mess with de­f­i­n­i­tions like this be­cause stan­dard ren­der­ing styles are pro­vided. These styles use a few helpers that in­ject sym­bols but also take care of lead­ing and trail­ing spaces:

\btxspacebe­fore af­ter
\btxperiodbe­fore. af­ter
\btxcommabe­fore, af­ter
\btxlparentbe­fore (af­ter
\btxrparentbe­fore) af­ter
\btxlbracketbe­fore [af­ter
\btxrbracketbe­fore] af­ter

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

\btxdoif {title} {
    \bold{\btxfield{title}}
    \btxcomma
}

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

\btxflushauthor{author}
\btxflushauthor{editor}
\btxflushauthor[inverted]{editor}

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

\btxflushauthorinverted{editor}

You can use a (con­fig­urable) de­fault or pass di­rec­tives: Valid di­rec­tives are

con­ver­sionren­der­ing
invertedthe Frog jr, Ker­mit
invertedshortthe Frog jr, K
normalKer­mit, the Frog, jr
normalshortK, the Frog, jr


Ci­ta­tions

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[author][example::demo-003]
\cite[authoryear][example::demo-003]
\cite[authoryears][example::demo-003]
\cite[author][example::demo-003,demo-004]
\cite[authoryear][example::demo-003,demo-004]
\cite[authoryears][example::demo-003,demo-004]
\cite[author][example::demo-004,demo-003]
\cite[authoryear][example::demo-004,demo-003]
\cite[authoryears][example::demo-004,demo-003]
(Hans Ha­gen and Ton Ot­ten)
(Hans Ha­gen and Ton Ot­ten (1996))
(Hans Ha­gen and Ton Ot­ten, 1996)
(Hans Ha­gen and Ton Ot­ten, Luigi Scarso)
(Hans Ha­gen and Ton Ot­ten (1996), Luigi Scarso (2021))
(Hans Ha­gen and Ton Ot­ten, 1996, Luigi Scarso, 2021)
(Luigi Scarso, Hans Ha­gen and Ton Ot­ten)
(Luigi Scarso (2021), Hans Ha­gen and Ton Ot­ten (1996))
(Luigi Scarso, 2021, Hans Ha­gen and Ton Ot­ten, 1996)

The first ar­gu­ment is op­tional.

setup definition cite

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

\setupbtxcitevariant[author]     [sorttype=author,color=darkyellow]
\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]
\cite[authoryears][example::demo-004,demo-003]

Here we sort the au­thors and color the ci­ta­tion:

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

For rea­sons of back­ward com­pat­i­bil­ity the \cite com­mand is a bit picky about spaces be­tween the two ar­gu­ments, of which the first is op­tional. This is a con­se­quence of al­low­ing its use with the key spec­i­fied be­tween curly brack­ets as is the tra­di­tional prac­tice. (We do en­cour­age users to adopt the more co­her­ent ConTEXt syn­tax by us­ing square brack­ets for key­words and re­serv­ing curly brack­ets to re­group text to be type­set.)

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

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

There is a whole bunch of cite op­tions and more can be eas­ily de­fined.

keyren­der­ing
author(au­thor)
authornum[au­thor [btx er­ror 1]]
authoryear(au­thor (year))
authoryears(au­thor, year)
doi[todo: doi]
key[demo-005]
none
numbtx er­ror 1
pagepages
serial[5]
short[aut00]
type[book]
url[todo: url]
year(year)

Be­cause we are deal­ing with data­base in­put and be­cause we gen­er­ally need to ma­nip­u­late en­tries, much of the work is del­e­gated to Lua. This makes it eas­ier to main­tain and ex­tend the code. Of course TEX still does the ren­der­ing. The ty­po­graphic de­tails are con­trolled by pa­ra­me­ters but not all are used in all vari­ants. As with most ConTEXt com­mands, it starts out with a gen­eral setup com­mand:

setup definition setupbtxcitevariant

On top of that we can de­fine in­stances that in­herit ei­ther from a given par­ent or from the top­most setup.

setup definition definebtxcitevariant

But, spe­cific vari­ants can have them over­loaded:

setupbtxcitevariant : author

right)
middle,
left(

setupbtxcitevariant : authornum

right]
middle,
left[

setupbtxcitevariant : authoryear

compressyes
inbetween,
right)
middle,
left(

setupbtxcitevariant : authoryears

compressyes
inbetween,
right)
middle,
left(

setupbtxcitevariant : doi

right]
left[

setupbtxcitevariant : key

right]
left[

setupbtxcitevariant : none

no specific settings

setupbtxcitevariant : num

compressyes
inbetween--
right]
left[

setupbtxcitevariant : page

inbetween

setupbtxcitevariant : serial

right]
left[

setupbtxcitevariant : short

right]
left[

setupbtxcitevariant : type

right]
left[

setupbtxcitevariant : url

right]
left[

setupbtxcitevariant : year

right)
left(

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 publ-imp-*.mkiv files. Here we stick to the con­cept.

\startsetups btx:cite:author
    \btxcitevariant{author}
\stopsetups

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 \btxcitevariant 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 \btxcitevariant as­sumes that a dataset and spe­cific tag has been set. This is nor­mally done in the wrap­per macros, like \cite. For spe­cial pur­poses you can use these com­mands

\setbtxdataset[example]
\setbtxentry[hh2013]

But don’t ex­pect too much sup­port for such low level ren­der­ing con­trol.

Un­less you use criterium=all 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 \usecitation, for ex­am­ple:

\usecitation[example::demo-004,demo-003]

This com­mand has two syn­onyms: \nocite and \nocitation so you can choose what­ever fits you best.

setup definition nocite


The LUA view

Be­cause we man­age data at the Lua end it is tempt­ing to ac­cess it there for other pur­poses. This is fine as long as you keep in mind that as­pects of the im­ple­men­ta­tion may change over time, al­though this is un­likely once the mod­ules be­come sta­ble.

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 example. A dataset ta­ble has sev­eral fields, and prob­a­bly the one of most in­ter­est is the luadata field. Each en­try in this ta­ble de­scribes a pub­li­ca­tion:

t={ 
 ["author"]="Hans Hagen", 
 ["category"]="book", 
 ["index"]=1, 
 ["tag"]="demo-001", 
 ["title"]="\\btxcmd{BIBTEX}, the \\btxcmd{CONTEXT}\\ way", 
 ["year"]="2013", 
} 

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

t={ 
 ["author"]={ 
  { 
   ["firstnames"]={ "Hans" }, 
   ["initials"]={ "H" }, 
   ["original"]="Hans Hagen", 
   ["surnames"]={ "Hagen" }, 
   ["vons"]={}, 
  }, 
 }, 
 ["short"]="Hag13", 
} 

These de­tails are ac­cessed as publications.datasets.example.details["demo-001"] and by us­ing a sep­a­rate ta­ble we can over­load fields in the orig­i­nal en­try with­out los­ing the orig­i­nal.

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

local dataset = publications.datasets.example
context.starttabulate { "|l|l|l|" }
for tag, entry in table.sortedhash(dataset.luadata) do
    local detail = dataset.details[tag] or { }
    context.NC() context.type(tag)
    context.NC() context(detail.short)
    context.NC() context(entry.title)
    context.NC() context.NR()
end
context.stoptabulate()

This re­sults in:

demo-001Hag13bibTEX, the ConTEXt way
demo-002Hag14bibTEX, the ConTEXt way
demo-003HO96Type­set­ting ed­u­ca­tion doc­u­ments
demo-004Sca21De­sign­ing high speed trains
demo-005aut00ti­tle

You can ma­nip­u­late a dataset af­ter load­ing. Of course this as­sumes that you know what kind of con­tent you have and what you need for ren­der­ing. As ex­am­ple we load a small dataset.

\definebtxdataset[drumming]
\usebtxdataset[drumming][mkiv-publications.lua]

Be­cause we’re go­ing to do some Lua, we could also have loaded the dataset with:

publications.load("drumming","mkiv-publications.lua","lua")

The dataset has three en­tries:

As you can see, we can have a sub­ti­tle. We will com­bine the ti­tle and sub­ti­tle into one:

\startluacode
for tag, entry in next, publications.datasets.drumming.luadata do
    if entry.subtitle then
        if entry.title then
            entry.title = entry.title .. ", " .. entry.subtitle
        else
            entry.title = entry.subtitle
        end
        entry.subtitle = nil
        logs.report("btx","combining title and subtitle of entry tagged %a",tag)
    end
end
\stopluacode

We can now type­set the en­tries with:

\definebtxrendering[drumming][dataset=drumming,method=dataset]
\placebtxrendering[drumming]

Be­cause we just want to show the en­tries, and have no ci­ta­tions that force them to be shown, we have to the method to dataset.1


The XML view

The luadata ta­ble can be con­verted into an xml rep­re­sen­ta­tion. This is a fol­low up on ear­lier ex­per­i­ments with an xml-only ap­proach. I de­cided in the end to stick to a Lua ap­proach and pro­vide some sim­ple xml sup­port in ad­di­tion.

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

\usebtxdataset[tugboat][tugboat.bib]

The dataset has to be con­verted to xml:

\convertbtxdatasettoxml[tugboat]

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

\startxmlsetups btx:initialize
    \xmlsetsetup{#1}{bibtex|entry|field}{btx:*}
    \xmlmain{#1}
\stopxmlsetups
\startxmlsetups btx:field
    \xmlflushcontext{#1}
\stopxmlsetups
\xmlsetup{btx:tugboat}{btx:initialize}

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:

\starttabulate[|||]
    \NC \type {tag}   \NC \xmlfirst {btx:tugboat}
        {/bibtex/entry[string.find(@tag,'Hagen')]/attribute('tag')}
    \NC \NR
    \NC \type {title} \NC \xmlfirst {btx:tugboat}
        {/bibtex/entry[string.find(@tag,'Hagen')]/field[@name='title']}
    \NC \NR
\stoptabulate
tagHa­gen:TB17-1-54
titlePPCHTEX: type­set­ting chem­i­cal for­mu­las in TEX


\startxmlsetups btx:demo
    \xmlcommand
        {#1}
        {/bibtex/entry[string.find(@tag,'Hagen')][1]}{btx:table}
\stopxmlsetups
\startxmlsetups btx:table
\starttabulate[|||]
    \NC \type {tag}   \NC \xmlatt{#1}{tag} \NC \NR
    \NC \type {title} \NC \xmlfirst{#1}{/field[@name='title']} \NC \NR
\stoptabulate
\stopxmlsetups
\xmlsetup{btx:tugboat}{btx:demo}
tagHa­gen:TB17-1-54
titlePPCHTEX: type­set­ting chem­i­cal for­mu­las in TEX

Here is an­other ex­am­ple:

\startxmlsetups btx:row
    \NC \xmlatt{#1}{tag}
    \NC \xmlfirst{#1}{/field[@name='title']}
    \NC \NR
\stopxmlsetups
\startxmlsetups btx:demo
    \xmlfilter {#1} {
        /bibtex
        /entry[@category='article']
        /field[@name='author' and (find(text(),'Knuth') or find(text(),'DEK'))]
        /../command(btx:row)
    }
\stopxmlsetups
\starttabulate[|||]
    \xmlsetup{btx:tugboat}{btx:demo}
\stoptabulate
Knuth:TB10-1-31Type­set­ting Con­crete Math­e­mat­ics
Knuth:TB10-1-8TEX would find it dif­fi­cult …
Knuth:TB10-3-325The new ver­sions of TEX and MF
Knuth:TB10-4-529The er­rors of TEX
Knuth:TB11-1-13Vir­tual Fonts: More Fun for Grand Wiz­ards
Knuth:TB11-2-165Ex­er­cises for TEX: The Pro­gram
Knuth:TB11-4-489The fu­ture of TEX and MF
Knuth:TB11-4-497Arthur Lee Samuel, 1901--1990
Knuth:TB11-4-499An­swers to Ex­er­cises for TEX: The Pro­gram
Knuth:TB12-2-313Fixed-point glue set­ting: Er­rata
Knuth:TB14-4-387Icons for TEX and MF
Knuth:TB17-1-29Im­por­tant mes­sage re­gard­ing CM fonts
Knuth:TB2-3-5The cur­rent state of things
Knuth:TB3-1-10Fixed-point glue set­ting­Dash an ex­am­ple of WEB
Knuth:TB31-2-121An Earth­shak­ing An­nounce­ment
Knuth:TB4-2-64A note on hy­phen­ation
Knuth:TB5-1-4TEX in­cunab­ula
Knuth:TB5-1-67Com­ments on qual­ity in pub­lish­ing
Knuth:TB5-2-105A course on MF pro­gram­ming
Knuth:TB6-1-36Recipes and frac­tions
Knuth:TB7-2-101The TEX logo in var­i­ous fonts
Knuth:TB7-2-95Re­marks to cel­e­brate the pub­li­ca­tion of Com­put­ers & Type­set­ting
Knuth:TB8-1-14Mix­ing right-to-left texts with left-to-right texts
Knuth:TB8-1-6It hap­pened: an­nounce­ment of TEX 2.1
Knuth:TB8-1-73Prob­lem for a Sat­ur­day af­ter­noon
Knuth:TB8-2-135Fonts for dig­i­tal halftones
Knuth:TB8-2-210Sat­ur­day morn­ing prob­lem­Dash so­lu­tion
Knuth:TB8-2-217Re­ply: Print­ing out se­lected pages
Knuth:TB8-3-309Macros for Jill
Knuth:TB9-2-152A Punk Meta-Font

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.

\startxmlsetups btx:getkeys
    \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}
  % \xmlfilter{#1}{entry/command(btx:getkeys)}
    \xmlfilter{#1}{
        /bibtex
        /entry[@category='article']
        /field[@name='author' and find(text(),'Knuth')]
        /../command(btx:getkeys)}
    \xmlsortentries{btx}
    \starttabulate[||||]
        \xmlflushsorter{btx}{btx:entry:flush}
    \stoptabulate
\stopxmlsetups
\startxmlsetups btx:entry:flush
    \NC \xmlfilter{#1}{/field[@name='year'  ]/context()}
    \NC \xmlatt{#1}{tag}
    \NC \xmlfilter{#1}{/field[@name='author']/context()}
    \NC \NR
\stopxmlsetups
\xmlsetup{btx:tugboat}{btx:sorter}
1984Knuth:TB5-1-67Don Knuth
1984Knuth:TB5-1-4Don­ald E. Knuth
1984Knuth:TB5-2-105Don­ald E. Knuth
1985Knuth:TB6-1-36Don­ald E. Knuth
1986Knuth:TB7-2-101Don­ald E. Knuth
1987Knuth:TB8-2-135Don­ald E. Knuth
1987Knuth:TB8-3-309Don­ald E. Knuth
1988Knuth:TB9-2-152Don­ald E. Knuth
1989Knuth:TB10-3-325Don­ald E. Knuth
1989Knuth:TB10-4-529Don­ald E. Knuth
1990Knuth:TB11-4-489Don­ald E. Knuth
1993Knuth:TB14-4-387Don­ald E. Knuth
1996Knuth:TB17-1-29Don­ald E. Knuth
1987Knuth:TB8-1-14Don­ald Knuth and Pierre MacKay
1981Knuth:TB2-3-5Don­ald Knuth
1982Knuth:TB3-1-10Don­ald Knuth
1983Knuth:TB4-2-64Don­ald Knuth
1986Knuth:TB7-2-95Don­ald Knuth
1987Knuth:TB8-1-6Don­ald Knuth
1987Knuth:TB8-1-73Don­ald Knuth
1987Knuth:TB8-2-210Don­ald Knuth
1987Knuth:TB8-2-217Don­ald Knuth
1989Knuth:TB10-1-8Don­ald Knuth
1989Knuth:TB10-1-31Don­ald Knuth
1990Knuth:TB11-1-13Don­ald Knuth
1990Knuth:TB11-2-165Don­ald Knuth
1990Knuth:TB11-4-497Don­ald Knuth
1990Knuth:TB11-4-499Don­ald Knuth
1991Knuth:TB12-2-313Don­ald Knuth
2010Knuth:TB31-2-121Don­ald Knuth

The orig­i­nal data is stored in a Lua ta­ble, hashed by tag. Start­ing with Lua 5.2 each run of Lua gets a dif­fer­ent or­der­ing of such a hash. In older ver­sions, when you looped over a hash, the or­der was un­de­fined, but the same as long as you used the same bi­nary. This had the ad­van­tage that suc­ces­sive runs, some­thing we of­ten have in doc­u­ment pro­cess­ing gave con­sis­tent re­sults. In to­day’s Lua we need to do much more sort­ing of hashes be­fore we loop, es­pe­cially when we save multi--pass data. It is for this rea­son that the xml tree is sorted by hash key by de­fault. That way lookups (es­pe­cially the first of a set) give con­sis­tent out­comes.


Stan­dards

The ren­der­ing of bib­li­o­graphic en­tries is of­ten stan­dard­ized and pre­scribed by the pub­lisher. If you sub­mit an ar­ti­cle to a jour­nal, nor­mally it will be re­for­mat­ted (or even re- keyed) and the ren­der­ing will hap­pen at the pub­lish­ers end. In that case it may not mat­ter how en­tries were ren­dered when writ­ing the pub­li­ca­tion, be­cause the pub­lisher will do it his or her way. This means that most users prob­a­bly will stick to the stan­dard apa rules and for them we pro­vide some con­fig­u­ra­tion. Be­cause we use se­tups it is easy to over­load specifics. If you re­ally want to tweak, best look in the files that deal with it.

Many stan­dards ex­ist and sup­port for other ren­der­ings may be added to the core. In­ter­ested users are in­vited to de­velop and to test al­ter­nate stan­dard ren­der­ings ac­cord­ing to their needs.

Todo: maybe a list of cat­e­gories and fields.


Clean­ing up

Al­though the bibTEX for­mat is rea­son­ably well de­fined, in prac­tice there are many ways to or­ga­nize the data. For in­stance, one can use pre­de­fined string con­stants that get used (ei­ther or not com­bined with other strings) later on. A string can be en­closed in curly braces or dou­ble quotes. The strings can con­tain TEX com­mands but these are not stan­dard­ized. The data­bases of­ten have some­what com­plex ways to deal with spe­cial char­ac­ters and the use of braces in their de­f­i­n­i­tion is also not nor­mal­ized.

The most com­plex to deal with are the fields that con­tain names of peo­ple. At some point it might be needed to split a com­bi­na­tion of names into in­di­vid­ual ones that then get split into ti­tle, first name, op­tional in­be­tweens, sur­name(s) and ad­di­tional: Prof. Dr. Alfred B. C. von Kwik Kwak Jr. II and P. Q. Olet is just one ex­am­ple of this. The con­ven­tion seems to be not to use com­mas but and to sep­a­rate names (of­ten each name will be spec­i­fied as last­name, first­name).

We don’t see it as chal­lenge nor as a duty to sup­port all kinds of messy de­f­i­n­i­tions. Of course we try to be some­what tol­er­ant, but you will be sure to get bet­ter re­sults if you use nicely setup, con­sis­tent data­bases.

Todo: maybe some ex­am­ples of bad.


Tran­si­tion

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

% engine=pdftex
\usemodule[bib]
\usemodule[bibltx]
\setupbibtex
  [database=xampl]
\setuppublications
  [numbering=yes]
\starttext
    As \cite [article-full] already indicated, bibtex is a \LATEX||centric
    program.
    \completepublications
\stoptext

For MkIV the mod­ules were partly rewrit­ten and ended up in the core so the two com­mands were no longer needed. The over­head as­so­ci­ated with the au­to­matic load­ing of the bib­li­og­ra­phy macros can be ne­glected these days, so stan­dard­ized mod­ules such as bib are all be­ing moved to the core and do not need to be ex­plic­itly loaded.

The first \setupbibtex com­mand in this ex­am­ple is needed to boot­strap the process: it tells what data­base has to be processed by bibTEX be­tween runs. The sec­ond \setuppublications com­mand is op­tional. Each ci­ta­tion (tagged with \cite) ends up in the list of pub­li­ca­tions.

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 \cite com­mand re­mains. The above ex­am­ple be­comes:

\definebtxdataset
  [document]
\usebtxdataset
  [document]
  [mybibfile.bib]
\definebtxrendering
  [document]
\setupbtxrendering
  [document]
  [numbering=yes]
\starttext
    As \cite [article-full] already indicated, bibtex is a \LATEX||centric
    program.
    \completebtxrendering[document]
\stoptext

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:

\usebtxdataset
  [mybibfile.bib]
\setupbtxrendering
  [numbering=yes]

But keep in mind that com­pared to the old MkII de­rived method we have moved some of the op­tions to the ren­der­ing, list and cite setup vari­ants.

An­other dif­fer­ence is now the use of lists. When you de­fine a ren­der­ing, you also de­fine a list. How­ever, all en­tries are col­lected in a com­mon list tagged btx. Al­though you will nor­mally con­fig­ure a ren­der­ing you can still set some prop­er­ties of lists, but in that case you need to pre­fix the list iden­ti­fier. In the case of the above ex­am­ple this is btx:document.


ML­BIBTEX

Todo: how to plug in ML­bibTEX for sort­ing and other ad­vanced op­er­a­tions.


Ex­ten­sions

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.

function publications.loaders.myformat(dataset,filename)
    local t = { }
    -- Load data from 'filename' and convert it to a Lua table 't' with
    -- the key as hash entry and fields conforming the luadata table
    -- format.
    loaders.lua(dataset,t)
end

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

\usebtxdataset[standard][myfile.myformat]

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

\usebtxdataset[standard][myformat::myfile.txt]