685
edits
Changes
User:Luigi.scarso/testpage (view source)
Revision as of 19:12, 15 January 2014
, 19:12, 15 January 2014no edit summary
=1 The database=
</pre>
this gives:
You can set the current active dataset with
<pre detail='typing'>
Examples of list variants are:
<tt>setupbtxlistvariant : artauthor</tt> {| |+ | <tt>no specific settings</tt> | | | |} <tt>setupbtxlistvariant : author</tt> {| |+ | <tt>no specific settings</tt> | | | |} <tt>setupbtxlistvariant : editor</tt> {| |+ | <tt>no specific settings</tt> | | | |}
The exact rendering of list entries is determined by the <tt>alternative</tt> key and defaults to <tt>apa</tt> which uses definitions from <tt>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.
There are three commands to flush data:
Normally you can use <tt>\btxfield</tt> or <tt>\btxflush</tt> as derived fields just like analyzed author fields are flushed in a special way.
</pre>
Keep in mind that normally you don’t need to mess with definitions like this because standard rendering styles are provided. These styles use a few helpers that inject symbols but also take care of leading and trailing spaces:
So, the previous example setup can be rewritten as:
<pre detail='typing'>
</pre>
You can use a (configurable) default or pass directives: Valid directives are
=5 Citations=
</pre>
There is a whole bunch of cite options and more can be easily defined.
Because we are dealing with database input and because we generally need to manipulate entries, much of the work is delegated to Lua . This makes it easier to maintain and extend the code. Of course TEX still does the rendering. The typographic details are controlled by parameters but not all are used in all variants. As with most ConTEXt commands, it starts out with a general setup command:
On top of that we can define instances that inherit either from a given parent or from the topmost setup.
But, specific variants can have them overloaded:
<tt>setupbtxcitevariant : author</tt>
{|
|+
|
<tt>right</tt>
|
|
<tt>)</tt>
|
|+
|
<tt>middle</tt>
|
|
<tt>, </tt>
|
|+
|
<tt>left</tt>
|
|
<tt>(</tt>
|
|}
<tt>setupbtxcitevariant : authornum</tt>
{|
|+
|
<tt>right</tt>
|
|
<tt>]</tt>
|
|+
|
<tt>middle</tt>
|
|
<tt>, </tt>
|
|+
|
<tt>left</tt>
|
|
<tt>[</tt>
|
|}
<tt>setupbtxcitevariant : authoryear</tt>
{|
|+
|
<tt>compress</tt>
|
|
<tt>yes</tt>
|
|+
|
<tt>inbetween</tt>
|
|
<tt>, </tt>
|
|+
|
<tt>right</tt>
|
|
<tt>)</tt>
|
|+
|
<tt>middle</tt>
|
|
<tt>, </tt>
|
|+
|
<tt>left</tt>
|
|
<tt>(</tt>
|
|}
<tt>setupbtxcitevariant : authoryears</tt>
{|
|+
|
<tt>compress</tt>
|
|
<tt>yes</tt>
|
|+
|
<tt>inbetween</tt>
|
|
<tt>, </tt>
|
|+
|
<tt>right</tt>
|
|
<tt>)</tt>
|
|+
|
<tt>middle</tt>
|
|
<tt>, </tt>
|
|+
|
<tt>left</tt>
|
|
<tt>(</tt>
|
|}
<tt>setupbtxcitevariant : doi</tt>
{|
|+
|
<tt>right</tt>
|
|
<tt>]</tt>
|
|+
|
<tt>left</tt>
|
|
<tt>[</tt>
|
|}
<tt>setupbtxcitevariant : key</tt>
{|
|+
|
<tt>right</tt>
|
|
<tt>]</tt>
|
|+
|
<tt>left</tt>
|
|
<tt>[</tt>
|
|}
<tt>setupbtxcitevariant : none</tt>
{|
|+
|
<tt>no specific settings</tt>
|
|
|
|}
<tt>setupbtxcitevariant : num</tt>
{|
|+
|
<tt>compress</tt>
|
|
<tt>yes</tt>
|
|+
|
<tt>inbetween</tt>
|
|
<tt>--</tt>
|
|+
|
<tt>right</tt>
|
|
<tt>]</tt>
|
|+
|
<tt>left</tt>
|
|
<tt>[</tt>
|
|}
<tt>setupbtxcitevariant : page</tt>
{|
|+
|
<tt>inbetween</tt>
|
|
<tt>–</tt>
|
|}
<tt>setupbtxcitevariant : serial</tt>
{|
|+
|
<tt>right</tt>
|
|
<tt>]</tt>
|
|+
|
<tt>left</tt>
|
|
<tt>[</tt>
|
|}
<tt>setupbtxcitevariant : short</tt>
{|
|+
|
<tt>right</tt>
|
|
<tt>]</tt>
|
|+
|
<tt>left</tt>
|
|
<tt>[</tt>
|
|}
<tt>setupbtxcitevariant : type</tt>
{|
|+
|
<tt>right</tt>
|
|
<tt>]</tt>
|
|+
|
<tt>left</tt>
|
|
<tt>[</tt>
|
|}
<tt>setupbtxcitevariant : url</tt>
{|
|+
|
<tt>right</tt>
|
|
<tt>]</tt>
|
|+
|
<tt>left</tt>
|
|
<tt>[</tt>
|
|}
<tt>setupbtxcitevariant : year</tt>
{|
|+
|
<tt>right</tt>
|
|
<tt>)</tt>
|
|+
|
<tt>left</tt>
|
|
<tt>(</tt>
|
|}
A citation variant is defined in several steps and if you really want to know the dirty details, you should look into the <tt>publ-imp-*.mkiv</tt> files. Here we stick to the concept.
<pre detail='typing'>
\startsetups btx:cite:author
\btxcitevariant{author}
\stopsetups
</pre>
You can overload such setups if needed, but that only makes sense when you cannot configure the rendering with parameters. The <tt>\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 <tt>\btxcitevariant</tt> assumes that a dataset and specific tag has been set. This is normally done in the wrapper macros, like <tt>\cite</tt> . For special purposes you can use these commands
<pre detail='typing'>
\setbtxdataset[example]
\setbtxentry[hh2013]
</pre>
But don’t expect too much support for such low level rendering control.
Unless you use <tt>criterium=all</tt> only publications that are cited will end up in the lists. You can force a citation into a list using <tt>\usecitation</tt> , for example:
<pre detail='typing'>
\usecitation[example::demo-004,demo-003]
</pre>
This command has two synonyms: <tt>\nocite</tt> and <tt>\nocitation</tt> so you can choose whatever fits you best.
=6 The LUA view=
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.
The entries are collected in datasets and each set has a unique name. In this document we have the set named <tt>example</tt> . A dataset table has several fields, and probably the one of most interest is the <tt>luadata</tt> field. Each entry in this table describes a publication:
<pre detail='typing'>
t={
["author"]="Hans Hagen",
["category"]="book",
["index"]=1,
["tag"]="demo-001",
["title"]="\\btxcmd{BIBTEX}, the \\btxcmd{CONTEXT}\\ way",
["year"]="2013",
}
</pre>
This is <tt>publications.datasets.example.luadata["demo-001"]</tt> . There can be a companion entry in the parallel <tt>details</tt> table.
<pre detail='typing'>
t={
["author"]={
{
["firstnames"]={ "Hans" },
["initials"]={ "H" },
["original"]="Hans Hagen",
["surnames"]={ "Hagen" },
["vons"]={},
},
},
["short"]="Hag13",
}
</pre>
These details are accessed as <tt>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.
You can loop over the entries using regular Lua code combined with MkIV helpers:
<pre detail='buffer'>
local dataset = publications.datasets.example
</pre>context.starttabulate { "|l|l|l|" }
for tag, entry in table.sortedhash(dataset.luadata) do
local detail = dataset.details[tag] or { }
context.NC() context.type(tag)
context.NC() context(detail.short)
context.NC() context(entry.title)
context.NC() context.NR()
end
context.stoptabulate()
This results in:
{|
|+
|
<tt>demo-001</tt>
|
|
Hag13
|
|
bibTEX , the ConTEXt way
|
|+
|
<tt>demo-002</tt>
|
|
Hag14
|
|
bibTEX , the ConTEXt way
|
|+
|
<tt>demo-003</tt>
|
|
HO96
|
|
Typesetting education documents
|
|+
|
<tt>demo-004</tt>
|
|
Sca21
|
|
Designing high speed trains
|
|+
|
<tt>demo-005</tt>
|
|
aut00
|
|
title
|
|}
=7 The XML view=
The <tt>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.
Once a dataset is accessible as xml tree, you can use the regular <tt>\xml...</tt> commands. We start with loading a dataset, in this case from just one file.
<pre detail='buffer'>
\usebtxdataset[tugboat][tugboat.bib]
</pre>
The dataset has to be converted to xml :
<pre detail='buffer'>
\convertbtxdatasettoxml[tugboat]
</pre>
The tree is now accessible by its root reference <tt>btx:tugboat</tt> . If we want simple field access we can use a few setups:
<pre detail='buffer'>
\startxmlsetups btx:initialize
\xmlsetsetup{#1}{bibtex|entry|field}{btx:*}
\xmlmain{#1}
\stopxmlsetups
</pre>\startxmlsetups btx:field
\xmlflushcontext{#1}
\stopxmlsetups
\xmlsetup{btx:tugboat}{btx:initialize}
The two setups are predefined in the core already, but you might want to change them. They are applied in for instance:
<pre detail='buffer'>
\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>
{|
|+
|
<tt>tag</tt>
|
|
Hagen:TB17-1-54
|
|+
|
<tt>title</tt>
|
|
PPCHTEX: typesetting chemical formulas in TEX
|
|}
<pre detail='buffer'>
\startxmlsetups btx:demo
\xmlcommand
{#1}
{/bibtex/entry[string.find(@tag,'Hagen')][1]}{btx:table}
\stopxmlsetups
</pre>\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}
{|
|+
|
<tt>tag</tt>
|
|
Hagen:TB17-1-54
|
|+
|
<tt>title</tt>
|
|
PPCHTEX: typesetting chemical formulas in TEX
|
|}
Here is another example:
<pre detail='buffer'>
\startxmlsetups btx:row
\NC \xmlatt{#1}{tag}
\NC \xmlfirst{#1}{/field[@name='title']}
\NC \NR
\stopxmlsetups
</pre>\startxmlsetups btx:demo
\xmlfilter {#1} {
/bibtex
/entry[@category='article']
/field[@name='author' and (find(text(),'Knuth') or find(text(),'DEK'))]
/../command(btx:row)
}
\stopxmlsetups
\starttabulate[|||]
\xmlsetup{btx:tugboat}{btx:demo}
\stoptabulate
{|
|+
|
Knuth:TB10-1-31
|
|
Typesetting Concrete Mathematics
|
|+
|
Knuth:TB10-1-8
|
|
TEX would find it difficult …
|
|+
|
Knuth:TB10-3-325
|
|
The new versions of TEX and MF
|
|+
|
Knuth:TB10-4-529
|
|
The errors of TEX
|
|+
|
Knuth:TB11-1-13
|
|
Virtual Fonts: More Fun for Grand Wizards
|
|+
|
Knuth:TB11-2-165
|
|
Exercises for TEX: The Program
|
|+
|
Knuth:TB11-4-489
|
|
The future of TEX and MF
|
|+
|
Knuth:TB11-4-497
|
|
Arthur Lee Samuel, 1901--1990
|
|+
|
Knuth:TB11-4-499
|
|
Answers to Exercises for TEX: The Program
|
|+
|
Knuth:TB12-2-313
|
|
Fixed-point glue setting: Errata
|
|+
|
Knuth:TB14-4-387
|
|
Icons for TEX and MF
|
|+
|
Knuth:TB17-1-29
|
|
Important message regarding CM fonts
|
|+
|
Knuth:TB2-3-5
|
|
The current state of things
|
|+
|
Knuth:TB3-1-10
|
|
Fixed-point glue settingDash an example of WEB
|
|+
|
Knuth:TB31-2-121
|
|
An Earthshaking Announcement
|
|+
|
Knuth:TB4-2-64
|
|
A note on hyphenation
|
|+
|
Knuth:TB5-1-4
|
|
TEX incunabula
|
|+
|
Knuth:TB5-1-67
|
|
Comments on quality in publishing
|
|+
|
Knuth:TB5-2-105
|
|
A course on MF programming
|
|+
|
Knuth:TB6-1-36
|
|
Recipes and fractions
|
|+
|
Knuth:TB7-2-101
|
|
The TEX logo in various fonts
|
|+
|
Knuth:TB7-2-95
|
|
Remarks to celebrate the publication of Computers & Typesetting
|
|+
|
Knuth:TB8-1-14
|
|
Mixing right-to-left texts with left-to-right texts
|
|+
|
Knuth:TB8-1-6
|
|
It happened: announcement of TEX 2.1
|
|+
|
Knuth:TB8-1-73
|
|
Problem for a Saturday afternoon
|
|+
|
Knuth:TB8-2-135
|
|
Fonts for digital halftones
|
|+
|
Knuth:TB8-2-210
|
|
Saturday morning problemDash solution
|
|+
|
Knuth:TB8-2-217
|
|
Reply: Printing out selected pages
|
|+
|
Knuth:TB8-3-309
|
|
Macros for Jill
|
|+
|
Knuth:TB9-2-152
|
|
A Punk Meta-Font
|
|}
A more extensive example is the following. Of course this assumes that you know what xml support mechanisms and macros are available.
<pre detail='buffer'>
\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
</pre>\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}
{|
|+
|
1984
|
|
Knuth:TB5-1-67
|
|
Don Knuth
|
|+
|
1984
|
|
Knuth:TB5-1-4
|
|
Donald E. Knuth
|
|+
|
1984
|
|
Knuth:TB5-2-105
|
|
Donald E. Knuth
|
|+
|
1985
|
|
Knuth:TB6-1-36
|
|
Donald E. Knuth
|
|+
|
1986
|
|
Knuth:TB7-2-101
|
|
Donald E. Knuth
|
|+
|
1987
|
|
Knuth:TB8-2-135
|
|
Donald E. Knuth
|
|+
|
1987
|
|
Knuth:TB8-3-309
|
|
Donald E. Knuth
|
|+
|
1988
|
|
Knuth:TB9-2-152
|
|
Donald E. Knuth
|
|+
|
1989
|
|
Knuth:TB10-3-325
|
|
Donald E. Knuth
|
|+
|
1989
|
|
Knuth:TB10-4-529
|
|
Donald E. Knuth
|
|+
|
1990
|
|
Knuth:TB11-4-489
|
|
Donald E. Knuth
|
|+
|
1993
|
|
Knuth:TB14-4-387
|
|
Donald E. Knuth
|
|+
|
1996
|
|
Knuth:TB17-1-29
|
|
Donald E. Knuth
|
|+
|
1987
|
|
Knuth:TB8-1-14
|
|
Donald Knuth and Pierre MacKay
|
|+
|
1981
|
|
Knuth:TB2-3-5
|
|
Donald Knuth
|
|+
|
1982
|
|
Knuth:TB3-1-10
|
|
Donald Knuth
|
|+
|
1983
|
|
Knuth:TB4-2-64
|
|
Donald Knuth
|
|+
|
1986
|
|
Knuth:TB7-2-95
|
|
Donald Knuth
|
|+
|
1987
|
|
Knuth:TB8-1-6
|
|
Donald Knuth
|
|+
|
1987
|
|
Knuth:TB8-1-73
|
|
Donald Knuth
|
|+
|
1987
|
|
Knuth:TB8-2-210
|
|
Donald Knuth
|
|+
|
1987
|
|
Knuth:TB8-2-217
|
|
Donald Knuth
|
|+
|
1989
|
|
Knuth:TB10-1-8
|
|
Donald Knuth
|
|+
|
1989
|
|
Knuth:TB10-1-31
|
|
Donald Knuth
|
|+
|
1990
|
|
Knuth:TB11-1-13
|
|
Donald Knuth
|
|+
|
1990
|
|
Knuth:TB11-2-165
|
|
Donald Knuth
|
|+
|
1990
|
|
Knuth:TB11-4-497
|
|
Donald Knuth
|
|+
|
1990
|
|
Knuth:TB11-4-499
|
|
Donald Knuth
|
|+
|
1991
|
|
Knuth:TB12-2-313
|
|
Donald Knuth
|
|+
|
2010
|
|
Knuth:TB31-2-121
|
|
Donald Knuth
|
|}
The original data is stored in a Lua table, hashed by tag. Starting with Lua 5.2 each run of Lua gets a different ordering of such a hash. In older versions, when you looped over a hash, the order was undefined, but the same as long as you used the same binary. This had the advantage that successive runs, something we often have in document processing gave consistent results. In today’s Lua we need to do much more sorting of hashes before we loop, especially when we save multi--pass data. It is for this reason that the xml tree is sorted by hash key by default. That way lookups (especially the first of a set) give consistent outcomes.
=8 Standards=
The rendering of bibliographic entries is often standardized and prescribed by the publisher. If you submit an article to a journal, normally it will be reformatted (or even re- keyed) and the rendering will happen at the publishers end. In that case it may not matter how entries were rendered when writing the publication, because the publisher will do it his or her way. This means that most users probably will stick to the standard apa rules and for them we provide some configuration. Because we use setups it is easy to overload specifics. If you really want to tweak, best look in the files that deal with it.
Many standards exist and support for other renderings may be added to the core. Interested users are invited to develop and to test alternate standard renderings according to their needs.
Todo: maybe a list of categories and fields.
=9 Cleaning up=
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.
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: <tt>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 <tt>and</tt> to separate names (often each name will be specified as lastname, firstname).
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.
Todo: maybe some examples of bad.
=10 Transition=
In the original bibliography support module usage was as follows (example taken from the contextgarden wiki):
<pre detail='typing'>
% 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>
For MkIV the modules were partly rewritten and ended up in the core so the two commands are not needed there. One advantage of explicitly loading a module is that a job that doesn’t need references to publications doesn’t suffer from the associated overhead. Nowadays this overhead can be neglected. The first setup command in this example is needed to bootstrap the process: it tells what database has to be processed by bibTEX between runs. The second setup command is optional. Each citation (tagged with <tt>\cite</tt> ) ends up in the list of publications.
In the new approach again the code is in the ConTEXt kernel, so no modules need to be loaded. But, as we no longer use bibTEX , 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 <tt>\cite</tt> command remains.
<pre detail='typing'>
\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>
So, we have a few more commands to set up things. If you use just one dataset and rendering, the above preamble can be simplified to:
<pre detail='typing'>
\usebtxdataset
[mybibfile.bib]
\setupbtxrendering
[numbering=yes]
</pre>
But keep in mind, that compared to the old MkII derived method we have moved some of the setup options to setting up the list and cite variants.
Another difference is the use of lists. When you define a rendering, you also define a list. However, all entries are collected in a common list tagged <tt>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 <tt>btx:document</tt> .
=11 MLBIBTEX=
Todo: how to plug in MLbibTEX for sorting and other advanced operations.
=12 Extensions=
As TEX and Lua are both open and accessible in ConTEXt it is possible to extend the functionality of the bibliography related code. For instance, you can add extra loaders.
<pre detail='typing'>
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>
This then permits loading a database (into a dataset) with the command:
<pre detail='typing'>
\usebtxdataset[standard][myfile.myformat]
</pre>
The <tt>myformat</tt> suffix is recognized automatically. If you want to use another suffix, you can do this:
<pre detail='typing'>
\usebtxdataset[standard][myformat::myfile.txt]
</pre>