685
edits
Changes
Jump to navigation
Jump to search
User:Luigi.scarso/testpage (view source)
Revision as of 17:37, 17 January 2014
, 17:37, 17 January 2014no edit summary
==The database==
The bibTEX format is rather popular in the TEX community and even with its shortcomings it will stay around for a while. Many publication websites can export and many tools are available to work with this database format. It is rather simple and looks a bit like Lua tables. Unfortunately the content can be polluted with non-standardized TEX commands which complicates pre- or postprocessing outside TEX. In that sense a bibTEX database is often not coded neutrally. Some limitations, like the use of commands to encode accented characters root in the ascii world and can be bypassed by using utf instead (as handled somewhat in LATEX through extensions such as ><ttstyle="color:rgb(0,102,102);font-size:120%;" >bibtex8</tt>).
<br/>
The normal way to deal with a bibliography is to refer to entries using a unique tag or key. When a list of entries is typeset, this reference can be used for linking purposes. The typeset list can be processed and sorted using the ><ttstyle="color:rgb(0,102,102);font-size:120%;" >bibtex</tt> program that converts the database into something more TEX friendly (a ><ttstyle="color:rgb(0,102,102);font-size:120%;" >.bbl</tt> file). I never used the program myself (nor bibliographies) so I will not go into too much detail here, if only because all I say can be wrong.
<br/>
In ConTEXt we no longer use the ><ttstyle="color:rgb(0,102,102);font-size:120%;" >bibtex</tt> program: we just use database files and deal with the necessary manipulations directly in ConTEXt. One or more such databases can be used and combined with additional entries defined within the document. We can have several such datasets active at the same time.
<br/>
A bibTEX file looks like this:
</pre>
<br/>
Normally a value is given between quotes (or curly brackets) but single words are also OK (there is no real benefit in not using quotes, so we advise to always use them). There can be many more fields and instead of strings one can use predefined shortcuts. The title for example quite often contains TEX macros. Some fields, like ><ttstyle="color:rgb(0,102,102);font-size:120%;" >pages</tt> have funny characters such as the endash (typically as ><ttstyle="color:rgb(0,102,102);font-size:120%;" >--</tt>) so we have a mixture of data and typesetting directives. If you are covering non--english references, you often need characters that are not in the ascii subset but ConTEXt is quite happy with utf. If your database file uses old-fashioned TEX accent commands then these will be internally converted automatically to utf. Commands (macros) are converted to an indirect call, which is quite robust.
<br/>
The bibTEX files are loaded in memory as Lua table but can be converted to xml so that we can access them in a more flexible way, but that is a subject for specialists.
</pre>
<br/>
The split ><ttstyle="color:rgb(0,102,102);font-size:120%;" >\artauthor</tt> fields are collapsed into a single ><ttstyle="color:rgb(0,102,102);font-size:120%;" >author</tt> field as we deal with the splitting later when it gets parsed in Lua. The ><ttstyle="color:rgb(0,102,102);font-size:120%;" >\artauthor</tt> syntax is only kept around for backward compatibility with the previous use of bibTEX.
<br/>
In the new setup we support these variants as well:
So the user has a rather wide choice of formatting style for bibliography database files.
You can load more data than you actually need. Only entries that are referred to explicitly through the ><ttstyle="color:rgb(0,102,102);font-size:120%;" >\cite</tt> and ><ttstyle="color:rgb(0,102,102);font-size:120%;" >\nocite</tt> commands will be shown in lists. We will cover these details later.
==Commands in entries==
One unfortunate aspect commonly found in bibTEX files is that they often contain TEX commands. Even worse is that there is no standard on what these commands can be and what they mean, at least not formally, as bibTEX is a program intended to be used with many variants of TEX style: plain, LATEX, and others. This means that we need to define our use of these typesetting commands. However, in most cases, they are just abbreviations or font switches and these are often known. Therefore, ConTEXt will try to resolve them before reporting an issue. In the log file there is a list of commands that has been seen in the loaded databases. For instance, loading ><ttstyle="color:rgb(0,102,102);font-size:120%;" >tugboat.bib</tt> gives a long list of commands of which we show a small set here:
<pre style="color:rgb(102,0,102);font-size:120%">publications > start used btx commands
</pre>
<br/>
Unknown commands do not stall processing, but their names are then typeset in a mono- spaced font so they probably stand out for proofreading. You can access the commands with ><ttstyle="color:rgb(0,102,102);font-size:120%;" >\btxcommand{...}</tt>, as in:
commands like \btxcommand{MySpecialCommand} are handled in an indirect way
==Datasets==
Normally in a document you will use only one bibliographic database, whether or not distributed over multiple files. Nevertheless we support multiple databases as well which is why we talk of datasets instead. A dataset is loaded with the ><ttstyle="color:rgb(0,102,102);font-size:120%;" >\usebtxdataset</tt> command. Although currently it is not necessary to define a (default) dataset you can best do this because in the future we might provide more options. Here are some examples:
<pre style="color:rgb(102,0,102);font-size:120%">\definebtxdataset[standard]
</pre>
<br/>
These three suffixes are understood by the loader. Here the dataset has the name ><ttstyle="color:rgb(0,102,102);font-size:120%;" >standard</tt> and the three database files are merged, where later entries having the same tag overload previous ones. Definitions in the document source (coded in TEX speak) are also added, and they are saved for successive runs. This means that if you load and define entries, they will be known at a next run beforehand, so that references to them are independent of when loading and definitions take place.
<div style="border:thin solid black;" >
<span style="font-style:oblique;" > setup definition setupbtxdataset </span >
A list of publications can be rendered at any place in the document. A database can be much larger than needed for a document. The same is true for the fields that make up an entry. Here is the list of fields that are currently handled, but of course there can be additional ones:
<br/>
><ttstyle="color:rgb(0,102,102);font-size:120%;" >abstract</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >address</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >annotate</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >assignee</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >author</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >bibnumber</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >booktitle</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >chapter</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >comment</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >country</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >day</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >dayfiled</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >doi</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >edition</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >editor</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >eprint</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >howpublished</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >institution</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >isbn</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >issn</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >journal</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >key</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >keyword</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >keywords</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >language</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >lastchecked</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >month</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >monthfiled</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >names</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >nationality</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >note</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >notes</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >number</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >organization</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >pages</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >publisher</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >revision</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >school</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >series</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >size</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >title</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >type</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >url</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >volume</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >year</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >yearfiled</tt>
<br/>
If you want to see what publications are in the database, the easiest way is to ask for a complete list:
This gives:1 Hagen, H. and Otten, T. (1996). Typesetting education documents2 Scarso, L. (2021). Designing high speed trains3 author (year). title pages p.
<br/>
The rendering itself is somewhat complex to set up because we have not only many different standards but also many fields that can be set up. This means that there are several commands involved. Often there is a prescribed style to render bibliographic descriptions, for example ><ttstyle="color:rgb(0,102,102);font-size:120%;" >apa</tt>. A rendering is setup and defined with:
<div style="border:thin solid black;" >
<span style="font-style:oblique;" > setup definition setupbtxrendering </span >
A dataset can have all kind of entries:
<br/>
><ttstyle="color:rgb(0,102,102);font-size:120%;" >article</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >book</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >booklet</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >conference</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >inbook</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >incollection</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >inproceedings</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >manual</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >mastersthesis</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >misc</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >phdthesis</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >proceedings</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >techreport</tt>, ><ttstyle="color:rgb(0,102,102);font-size:120%;" >unpublished</tt>
<br/>
Each has its own rendering variant. To keep things simple we have their settings separated. However, these settings are shared for all rendering alternatives. In practice this is seldom a problem in a publication as only one rendering alternative will be active. If this be not sufficient, you can always group local settings in a setup and hook that into the specific rendering.
Examples of list variants are:
<br/>
><ttstyle="color:rgb(0,102,102);font-size:120%;" >setupbtxlistvariant : artauthor</tt>
{|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >no specific settings</tt>
|
<br/>
><ttstyle="color:rgb(0,102,102);font-size:120%;" >setupbtxlistvariant : author</tt>
{|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >no specific settings</tt>
|
<br/>
><ttstyle="color:rgb(0,102,102);font-size:120%;" >setupbtxlistvariant : editor</tt>
{|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >no specific settings</tt>
|
<br/>
The exact rendering of list entries is determined by the ><ttstyle="color:rgb(0,102,102);font-size:120%;" >alternative</tt> key and defaults to ><ttstyle="color:rgb(0,102,102);font-size:120%;" >apa</tt> which uses definitions from ><ttstyle="color:rgb(0,102,102);font-size:120%;" >publ-imp-apa.mkiv</tt>. If you look at that file you will see that each category has its own setup. You may also notice that additional tests are needed to make sure that empty fields don’t trigger separators and such.
<br/>
There are a couple of accessors and helpers to get the job done. When you want to fetch a field from the current entry you use ><ttstyle="color:rgb(0,102,102);font-size:120%;" >\btxfield</tt>. In most cases you want to make sure this field has a value, for instance because you don’t want fences or punctuation that belongs to a field.
<pre style="color:rgb(102,0,102);font-size:120%">\btxdoif {title} {
</pre>
<br/>
In addition there is also a conditional ><ttstyle="color:rgb(0,102,102);font-size:120%;" >\btxinteractive</tt> which is more efficient, although in practice efficiency is not so important here.
<br/>
There are three commands to flush data:
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >\btxfield</tt>
|
|
fetch a explicit field (e.g. ><ttstyle="color:rgb(0,102,102);font-size:120%;" >year</tt>)
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >\btxdetail</tt>
|
|
fetch a derived field (e.g. ><ttstyle="color:rgb(0,102,102);font-size:120%;" >short</tt>)
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >\btxflush</tt>
|
<br/>
Normally you can use ><ttstyle="color:rgb(0,102,102);font-size:120%;" >\btxfield</tt> or ><ttstyle="color:rgb(0,102,102);font-size:120%;" >\btxflush</tt> as derived fields just like analyzed author fields are flushed in a special way.
<br/>
You can improve readability by using setups, for instance:
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >\btxspace</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >\btxperiod</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >\btxcomma</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >\btxlparent</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >\btxrparent</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >\btxlbracket</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >\btxrbracket</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >inverted</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >invertedshort</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >normal</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >normalshort</tt>
|
<br/>
For reasons of backward compatibility the ><ttstyle="color:rgb(0,102,102);font-size:120%;" >\cite</tt> command is a bit picky about spaces between the two arguments, of which the first is optional. This is a consequence of allowing its use with the key specified between curly brackets as is the traditional practice. (We do encourage users to adopt the more coherent ConTEXt syntax by using square brackets for keywords and reserving curly brackets to regroup text to be typeset.)
<br/>
The ><ttstyle="color:rgb(0,102,102);font-size:120%;" >\citation</tt> command is synonymous but is more flexible with respect to spacing of its arguments:
<pre style="color:rgb(102,0,102);font-size:120%">\citation[author] [example::demo-004,demo-003]
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >author</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >authornum</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >authoryear</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >authoryears</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >doi</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >key</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >none</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >num</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >page</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >serial</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >short</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >type</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >url</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >year</tt>
|
But, specific variants can have them overloaded:
<br/>
><ttstyle="color:rgb(0,102,102);font-size:120%;" >setupbtxcitevariant : author</tt>
{|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >right</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >)</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >middle</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >, </tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >left</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >(</tt>
|
<br/>
><ttstyle="color:rgb(0,102,102);font-size:120%;" >setupbtxcitevariant : authornum</tt>
{|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >right</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >]</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >middle</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >, </tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >left</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >[</tt>
|
<br/>
><ttstyle="color:rgb(0,102,102);font-size:120%;" >setupbtxcitevariant : authoryear</tt>
{|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >compress</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >yes</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >inbetween</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >, </tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >right</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >)</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >middle</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >, </tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >left</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >(</tt>
|
<br/>
><ttstyle="color:rgb(0,102,102);font-size:120%;" >setupbtxcitevariant : authoryears</tt>
{|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >compress</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >yes</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >inbetween</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >, </tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >right</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >)</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >middle</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >, </tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >left</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >(</tt>
|
<br/>
><ttstyle="color:rgb(0,102,102);font-size:120%;" >setupbtxcitevariant : doi</tt>
{|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >right</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >]</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >left</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >[</tt>
|
<br/>
><ttstyle="color:rgb(0,102,102);font-size:120%;" >setupbtxcitevariant : key</tt>
{|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >right</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >]</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >left</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >[</tt>
|
<br/>
><ttstyle="color:rgb(0,102,102);font-size:120%;" >setupbtxcitevariant : none</tt>
{|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >no specific settings</tt>
|
<br/>
><ttstyle="color:rgb(0,102,102);font-size:120%;" >setupbtxcitevariant : num</tt>
{|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >compress</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >yes</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >inbetween</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >--</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >right</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >]</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >left</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >[</tt>
|
<br/>
><ttstyle="color:rgb(0,102,102);font-size:120%;" >setupbtxcitevariant : page</tt>
{|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >inbetween</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >–</tt>
|
<br/>
><ttstyle="color:rgb(0,102,102);font-size:120%;" >setupbtxcitevariant : serial</tt>
{|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >right</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >]</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >left</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >[</tt>
|
<br/>
><ttstyle="color:rgb(0,102,102);font-size:120%;" >setupbtxcitevariant : short</tt>
{|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >right</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >]</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >left</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >[</tt>
|
<br/>
><ttstyle="color:rgb(0,102,102);font-size:120%;" >setupbtxcitevariant : type</tt>
{|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >right</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >]</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >left</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >[</tt>
|
<br/>
><ttstyle="color:rgb(0,102,102);font-size:120%;" >setupbtxcitevariant : url</tt>
{|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >right</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >]</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >left</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >[</tt>
|
<br/>
><ttstyle="color:rgb(0,102,102);font-size:120%;" >setupbtxcitevariant : year</tt>
{|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >right</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >)</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >left</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >(</tt>
|
|}
A citation variant is defined in several steps and if you really want to know the dirty details, you should look into the ><ttstyle="color:rgb(0,102,102);font-size:120%;" >publ-imp-*.mkiv</tt> files. Here we stick to the concept.
<pre style="color:rgb(102,0,102);font-size:120%">\startsetups btx:cite:author
</pre>
<br/>
You can overload such setups if needed, but that only makes sense when you cannot configure the rendering with parameters. The ><ttstyle="color:rgb(0,102,102);font-size:120%;" >\btxcitevariant</tt> command is one of the build in accessors and it calls out to Lua where more complex manipulation takes place if needed. If no manipulation is known, the field with the same name (if found) will be flushed. A command like ><ttstyle="color:rgb(0,102,102);font-size:120%;" >\btxcitevariant</tt> assumes that a dataset and specific tag has been set. This is normally done in the wrapper macros, like ><ttstyle="color:rgb(0,102,102);font-size:120%;" >\cite</tt>. For special purposes you can use these commands
<pre style="color:rgb(102,0,102);font-size:120%">\setbtxdataset[example]
But don’t expect too much support for such low level rendering control.
<br/>
Unless you use ><ttstyle="color:rgb(0,102,102);font-size:120%;" >criterium=all</tt> only publications that are cited will end up in the lists. You can force a citation into a list using ><ttstyle="color:rgb(0,102,102);font-size:120%;" >\usecitation</tt>, for example:
<pre style="color:rgb(102,0,102);font-size:120%">\usecitation[example::demo-004,demo-003]
</pre>
<br/>
This command has two synonyms: ><ttstyle="color:rgb(0,102,102);font-size:120%;" >\nocite</tt> and ><ttstyle="color:rgb(0,102,102);font-size:120%;" >\nocitation</tt> so you can choose whatever fits you best.
<div style="border:thin solid black;" >
<span style="font-style:oblique;" > setup definition nocite </span >
Because we manage data at the Lua end it is tempting to access it there for other purposes. This is fine as long as you keep in mind that aspects of the implementation may change over time, although this is unlikely once the modules become stable.
<br/>
The entries are collected in datasets and each set has a unique name. In this document we have the set named ><ttstyle="color:rgb(0,102,102);font-size:120%;" >example</tt>. A dataset table has several fields, and probably the one of most interest is the ><ttstyle="color:rgb(0,102,102);font-size:120%;" >luadata</tt> field. Each entry in this table describes a publication:
<pre style="color:rgb(102,0,102);font-size:120%">t={
}
</pre>
This is ><ttstyle="color:rgb(0,102,102);font-size:120%;" >publications.datasets.example.luadata["demo-001"]</tt>. There can be a companion entry in the parallel ><ttstyle="color:rgb(0,102,102);font-size:120%;" >details</tt> table.
<pre style="color:rgb(102,0,102);font-size:120%">t={
}
</pre>
These details are accessed as ><ttstyle="color:rgb(0,102,102);font-size:120%;" >publications.datasets.example.details["demo-001"]</tt> and by using a separate table we can overload fields in the original entry without losing the original.
<br/>
You can loop over the entries using regular Lua code combined with MkIV helpers:
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >demo-001</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >demo-002</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >demo-003</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >demo-004</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >demo-005</tt>
|
==The XML view==
The ><ttstyle="color:rgb(0,102,102);font-size:120%;" >luadata</tt> table can be converted into an xml representation. This is a follow up on earlier experiments with an xml-only approach. I decided in the end to stick to a Lua approach and provide some simple xml support in addition.
<br/>
Once a dataset is accessible as xml tree, you can use the regular ><ttstyle="color:rgb(0,102,102);font-size:120%;" >\xml...</tt> commands. We start with loading a dataset, in this case from just one file.
\usebtxdataset[tugboat][tugboat.bib]
<br/>
The tree is now accessible by its root reference ><ttstyle="color:rgb(0,102,102);font-size:120%;" >btx:tugboat</tt>. If we want simple field access we can use a few setups:
\startxmlsetups btx:initialize
\xmlsetsetup{#1}{bibtex|entry|field}{btx:*}
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >tag</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >title</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >tag</tt>
|
|
><ttstyle="color:rgb(0,102,102);font-size:120%;" >title</tt>
|
Although the bibTEX format is reasonably well defined, in practice there are many ways to organize the data. For instance, one can use predefined string constants that get used (either or not combined with other strings) later on. A string can be enclosed in curly braces or double quotes. The strings can contain TEX commands but these are not standardized. The databases often have somewhat complex ways to deal with special characters and the use of braces in their definition is also not normalized.
<br/>
The most complex to deal with are the fields that contain names of people. At some point it might be needed to split a combination of names into individual ones that then get split into title, first name, optional inbetweens, surname(s) and additional: ><ttstyle="color:rgb(0,102,102);font-size:120%;" >Prof. Dr. Alfred B. C. von Kwik Kwak Jr. II and P. Q. Olet</tt> is just one example of this. The convention seems to be not to use commas but ><ttstyle="color:rgb(0,102,102);font-size:120%;" >and</tt> to separate names (often each name will be specified as lastname, firstname).
<br/>
We don’t see it as challenge nor as a duty to support all kinds of messy definitions. Of course we try to be somewhat tolerant, but you will be sure to get better results if you use nicely setup, consistent databases.
</pre>
<br/>
For MkIV the modules were partly rewritten and ended up in the core so the two commands were no longer needed. The overhead associated with the automatic loading of the bibliography macros can be neglected these days, so standardized modules such as ><ttstyle="color:rgb(0,102,102);font-size:120%;" >bib</tt> are all being moved to the core and do not need to be explicitly loaded.
<br/>
The first ><ttstyle="color:rgb(0,102,102);font-size:120%;" >\setupbibtex</tt> command in this example is needed to bootstrap the process: it tells what database has to be processed by bibTEX between runs. The second ><ttstyle="color:rgb(0,102,102);font-size:120%;" >\setuppublications</tt> command is optional. Each citation (tagged with ><ttstyle="color:rgb(0,102,102);font-size:120%;" >\cite</tt>) ends up in the list of publications.
<br/>
In the new approach we no longer use bibTEXso we don’t need to setup bibTEX. Instead we define dataset(s). We also no longer set up publications with one command, but have split that up in rendering-, list-, and cite-variants. The basic ><ttstyle="color:rgb(0,102,102);font-size:120%;" >\cite</tt> command remains. The above example becomes:
<pre style="color:rgb(102,0,102);font-size:120%">\definebtxdataset
But keep in mind that compared to the old MkII derived method we have moved some of the options to the rendering, list and cite setup variants.
<br/>
Another difference is now the use of lists. When you define a rendering, you also define a list. However, all entries are collected in a common list tagged ><ttstyle="color:rgb(0,102,102);font-size:120%;" >btx</tt>. Although you will normally configure a rendering you can still set some properties of lists, but in that case you need to prefix the list identifier. In the case of the above example this is ><ttstyle="color:rgb(0,102,102);font-size:120%;" >btx:document</tt>.
</pre>
<br/>
The ><ttstyle="color:rgb(0,102,102);font-size:120%;" >myformat</tt> suffix is recognized automatically. If you want to use another suffix, you can do this:
<pre style="color:rgb(102,0,102);font-size:120%">\usebtxdataset[standard][myformat::myfile.txt]
</pre>
