Difference between revisions of "User:Luigi.scarso/testpage"

From Wiki
Jump to navigation Jump to search
(Blanked the page)
 
Line 1: Line 1:
−
<h1>The data­base</h1>
 
  
−
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>).
 
−
<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>
 
−
 
−
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:
 
−
   
 
−
<pre style="color:rgb(102,0,102);font-size:100%">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
 
−
</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>
 
−
 
−
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:
 
−
   
 
−
<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;" >TODO
 
−
<span style="font-style:oblique;" > setup definition setupbtxdataset </span >
 
−
</div>
 
−
<div style="border:thin solid black;" >TODO
 
−
<span style="font-style:oblique;" > setup definition definebtxdataset </span >
 
−
</div>
 
−
<div style="border:thin solid black;" >TODO
 
−
<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>
 
−
<p></p>
 
−
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>
 
−
 
−
<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.
 
−
<p></p>
 
−
Some­times you want to check a data­base. One way of do­ing that is the fol­low­ing:
 
−
   
 
−
<pre style="color:rgb(102,0,102);font-size:100%">\definebtxdataset[check]
 
−
\usebtxdataset[check][mkiv-publications-check.bib]
 
−
\showbtxdatasetcompleteness[check]
 
−
</pre>
 
−
<p></p>
 
−
The data­base like like this:
 
−
<p></p>
 
−
The com­plete­ness check shows (with green field names) the re­quired fields and when one is miss­ing this is in­di­cated in red. In blue we show what gets in­her­ited.
 
−
   
 
−
<table>
 
−
<tr><td>tag</td><td>test1</td></tr>
 
−
<tr><td>au­thor</td><td>Au­thor 1</td></tr>
 
−
<tr><td>ed­i­tor</td><td>Thomas Schmitz and Alan Braslau</td></tr>
 
−
<tr><td>ti­tle</td><td>Ti­tle 1</td></tr>
 
−
<tr><td>pub­lisher</td><td>Thomas and Alan</td></tr>
 
−
<tr><td>year</td><td>2015</td></tr>
 
−
<tr><td>vol­ume</td><td>1</td></tr>
 
−
</table>
 
−
 
−
   
 
−
<table>
 
−
<tr><td>tag</td><td>test2 => test1</td></tr>
 
−
<tr><td>au­thor</td><td>Au­thor 2</td></tr>
 
−
<tr><td>ed­i­tor</td><td>Thomas Schmitz and Alan Braslau</td></tr>
 
−
<tr><td>ti­tle</td><td>Ti­tle 2</td></tr>
 
−
<tr><td>pub­lisher</td><td>Thomas and Alan</td></tr>
 
−
<tr><td>year</td><td>2015</td></tr>
 
−
<tr><td>vol­ume</td><td>2</td></tr>
 
−
</table>
 
−
 
−
   
 
−
<table>
 
−
<tr><td>tag</td><td>test3</td></tr>
 
−
<tr><td>au­thor</td><td>Au­thor 3</td></tr>
 
−
<tr><td>ti­tle</td><td>Ti­tle 3</td></tr>
 
−
<tr><td>pub­lisher</td><td>[miss­ing]</td></tr>
 
−
<tr><td>year</td><td>[miss­ing]</td></tr>
 
−
</table>
 
−
 
−
   
 
−
   
 
−
<h1>Ren­der­ings</h1>
 
−
 
−
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;" >TODO
 
−
<span style="font-style:oblique;" > setup definition setupbtxrendering </span >
 
−
</div>
 
−
<div style="border:thin solid black;" >TODO
 
−
<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;" >TODO
 
−
<span style="font-style:oblique;" > setup definition placebtxrendering </span >
 
−
</div>
 
−
<p></p>
 
−
A dataset can have all kind of en­tries:
 
−
<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;" >TODO
 
−
<span style="font-style:oblique;" > setup definition setupbtxlistvariant </span >
 
−
</div>
 
−
<div style="border:thin solid black;" >TODO
 
−
<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>
 
−
 
−
<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>
 
−
 
−
<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>
 
−
 
−
<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>
 
−
 
−
<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>
 
−
 
−
<p></p>
 
−
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>
 
−
 
−
   
 
−
   
 
−
<h1>Ci­ta­tions</h1>
 
−
 
−
Ci­ta­tions are ref­er­ences to bib­li­o­graphic en­tries that nor­mally show up in lists some­place in the doc­u­ment: at the end of a chap­ter, in an ap­pen­dix, at the end of an ar­ti­cle, etc. We dis­cussed the ren­der­ing of these lists in the pre­vi­ous chap­ter. A ci­ta­tion is nor­mally pretty short as its main pur­pose is to re­fer uniquely to a more de­tailed de­scrip­tion. But, there are sev­eral ways to re­fer, which is why the ci­ta­tion sub­sys­tem is con­fig­urable and ex­ten­si­ble. Just look at the fol­low­ing com­mands:
 
−
   
 
−
<pre 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>
 
−
<div>(Hans Ha­gen and Ton Ot­ten)</div>
 
−
<div>(Hans Ha­gen and Ton Ot­ten (1996))</div>
 
−
<div>(Hans Ha­gen and Ton Ot­ten, 1996)</div>
 
−
<div>(Hans Ha­gen and Ton Ot­ten, Luigi Scarso)</div>
 
−
<div>(Hans Ha­gen and Ton Ot­ten (1996), Luigi Scarso (2021))</div>
 
−
<div>(Hans Ha­gen and Ton Ot­ten, 1996, Luigi Scarso, 2021)</div>
 
−
<div>(Luigi Scarso, Hans Ha­gen and Ton Ot­ten)</div>
 
−
<div>(Luigi Scarso (2021), Hans Ha­gen and Ton Ot­ten (1996))</div>
 
−
<div>(Luigi Scarso, 2021, Hans Ha­gen and Ton Ot­ten, 1996)</div>
 
−
</div>
 
−
<p></p>
 
−
The first ar­gu­ment is op­tional.
 
−
<div style="border:thin solid black;" >TODO
 
−
<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>
 
−
<div>(Hans Ha­gen and Ton Ot­ten, Luigi Scarso)</div>
 
−
<div>(Hans Ha­gen and Ton Ot­ten (1996), Luigi Scarso (2021))</div>
 
−
<div>(Hans Ha­gen and Ton Ot­ten, 1996, Luigi Scarso, 2021)</div>
 
−
</div>
 
−
<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;" >TODO
 
−
<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;" >TODO
 
−
<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>
 
−
 
−
<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>
 
−
 
−
<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>
 
−
 
−
<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>
 
−
 
−
<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>
 
−
 
−
<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>
 
−
 
−
<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>
 
−
 
−
<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>
 
−
 
−
<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;" >TODO
 
−
<span style="font-style:oblique;" > setup definition nocite </span >
 
−
</div>
 
−
   
 
−
   
 
−
<h1>The LUA view</h1>
 
−
 
−
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>
 
−
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.
 
−
   
 
−
<pre style="color:rgb(102,0,102);font-size:100%">\definebtxdataset[drumming]
 
−
\usebtxdataset[drumming][mkiv-publications.lua]
 
−
</pre>
 
−
<p></p>
 
−
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>
 
−
The dataset has three en­tries:
 
−
<p></p>
 
−
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
 
−
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
 
−
</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 Har­ri­son, G. (1996). Rhyth­mic Il­lu­sions, for drums. Warner. Har­ri­son, G. (1999). Rhyth­mic Per­spec­tives, a mul­ti­di­men­sional study of rhyth­mic com­po­si­tion. Al­fred Pub­lish­ing Co., Inc. Har­ri­son, G. and Bran­ham, T. (2010). Rhyth­mic De­signs, a study of prac­ti­cal cre­ativ­ity. Hud­son.
 
−
   
 
−
 
 
−
 
 
−
<h1>The XML view</h1>
 
−
 
−
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.
 
−
<p></p>
 
−
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.
 
−
   
 
−
<pre style="color:rgb(102,0,102);font-size:100%">\usebtxdataset[tugboat][tugboat.bib]
 
−
</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>
 
−
   
 
−
<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 style="color:rgb(102,0,102);font-size:100%">\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}
 
−
</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>
 
−
 
−
<p></p>
 
−
Here is an­other ex­am­ple:
 
−
   
 
−
<pre style="color:rgb(102,0,102);font-size:100%">\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
 
−
</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­Dashan 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>
 
−
 
−
<p></p>
 
−
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.
 
−
   
 
−
<pre style="color:rgb(102,0,102);font-size:100%">\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}
 
−
</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>
 
−
 
−
<p></p>
 
−
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.
 
−
 
 
−
 
 
−
<h1>Stan­dards</h1>
 
−
 
−
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.
 
−
<p></p>
 
−
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.
 
−
<p></p>
 
−
Todo: maybe a list of cat­e­gories and fields.
 
−
 
 
−
 
 
−
<h1>Clean­ing up</h1>
 
−
 
−
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
 
−
    As \cite [article-full] already indicated, bibtex is a \LATEX||centric
 
−
    program.
 
−
    \completebtxrendering[document]
 
−
\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>
 
−
 
 
−
 
 
−
<h1>Notes</h1>
 
−
 
−
The move from ex­ter­nal <span tag="MKIV" style="font-style:sans;">bibTEX</span> pro­cess­ing to in­ter­nal pro­cess­ing has the ad­van­tage that we stay within the same run. In the tra­di­tional ap­proach we had roughly the fol­low­ing steps:
 
−
   
 
−
<div>
 
−
<div><span>• </span><span>the first run in­for­ma­tion is col­lected and writ­ten to file</span></div>
 
−
<div><span>• </span><span>af­ter that run the <span tag="MKIV" style="font-style:sans;">bibTEX</span> pro­gram con­verts that file to an­other one</span></div>
 
−
<div><span>• </span><span>suc­ces­sive runs use that data for ref­er­ences and pro­duc­ing lists</span></div>
 
−
</div>
 
−
 
−
<p></p>
 
−
In the <span tag="MKIV" style="font-style:sans;">MkIV</span> ap­proach the bib­li­o­graphic data­base is loaded in mem­ory each run and pro­cess­ing also hap­pens each run. On pa­per this looks less ef­fi­cient but as <span tag="MKIV" style="font-style:sans;">Lua</span> is quite fast, in prac­tice per­for­mance is much bet­ter.
 
−
<p></p>
 
−
Prob­a­bly most de­mand­ing is the treat­ment of au­thors as we have to an­a­lyze names, split mul­ti­ple au­thors and re­assem­ble first­names, vons, sur­names and ju­niors. When we sort by au­thor sort­ing vec­tors have to be made which also has a penalty. How­ever, in prac­tice the user will not no­tice a per­for­mance degra­da­tion. We did some tests with a list of 500.000 au­thors, sorted them and type­set them as list (pro­duc­ing some 5400 dense pages in a small font and with small mar­gins). This is typ­i­cal one of these cases where us­ing <span tag="MKIV" style="font-style:sans;">Lu­a­jitTEX</span> saves quite time. On my ma­chine it took just over 100 sec­onds to get this done. Un­for­tu­nately not all op­er­at­ing sys­tems per­formed equally well: 32 bit ver­sions worked fine, but 64 bit <span tag="MKIV" style="font-style:sans;">linux</span> ei­ther crashed (stalled) the ma­chine or ran out of mem­ory rather fast, while <span tag="MKIV" style="font-style:sans;">Ma­cOSX</span> and <span tag="MKIV" style="font-style:sans;">Win­dows</span> per­formed fine. In prac­tice you will never run into this, un­less you pro­duce mas­sive amounts of bib­li­o­graphic en­tries. <span tag="MKIV" style="font-style:sans;">Lu­a­JIT</span> has some ben­e­fits but also some draw­backs.
 

Latest revision as of 14:10, 26 January 2014

Retrieved from "https://wiki.contextgarden.net/index.php?title=User:Luigi.scarso/testpage&oldid=22338"