User:Luigi.scarso/testpage

1 The data­base

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

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

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

A bibTEX file looks like this:

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

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

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

In the old MkII setup we have two kinds of en­tries: the ones that come from the bibTEX run and user sup­plied ones. We no longer rely on bibTEX out­put but we do still sup­port the user sup­plied de­f­i­n­i­tions. These were in fact pre­pared in a way that suits the pro­cess­ing of bibTEX gen­er­ated en­tries. The next vari­ant re­flects the ConTEXt re­cod­ing of the old bibTEX out­put.

\startpublication[k=Hagen:Second,t=article,a={Hans Hagen},y=2013,s=HH01]
\artauthor[]{Hans}[H.]{}{Hagen}
\arttitle{Who knows more?}
\journal{MyJournal}
\pubyear{2013}
\month{8}
\volume{1}
\issue{3}
\issn{1234-5678}
\pages{123--126}
\stoppublication

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

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

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

and

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

and

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

Be­cause in­ter­nally the en­tries are Lua ta­bles, we also sup­port load­ing of Lua based de­f­i­n­i­tions:

return {
["Hagen:First"] = {
author = "Hans Hagen",
category = "article",
issn = "1234-5678",
issue = "3",
journal = "MyJournal",
month = "8",
pages = "123--126",
tag = "Hagen:First",
title = "Who knows nothing?",
volume = "1",
year = "2013",
},
}

Files set up like this can be loaded too. The fol­low­ing xml in­put is rather close to this, and is also ac­cepted as in­put.

<?xml version="2.0" standalone="yes" ?>
<bibtex>
<entry tag="Hagen:First" category="article">
<field name="author">Hans Hagen</field>
<field name="category">article</field>
<field name="issn">1234-5678</field>
<field name="issue">3</field>
<field name="journal">MyJournal</field>
<field name="month">8</field>
<field name="pages">123--126</field>
<field name="tag">Hagen:First</field>
<field name="title">Who knows nothing?</field>
<field name="volume">1</field>
<field name="year">2013</field>
</entry>
</bibtex>

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

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

You can load more data than you ac­tu­ally need. Only en­tries that are re­ferred to ex­plic­itly through the \cite and \nocite com­mands will be shown in lists. We will cover these de­tails later.

2 Com­mands in en­tries

One un­for­tu­nate as­pect com­monly found in bibTEX files is that they of­ten con­tain TEX com­mands. Even worse is that there is no stan­dard on what these com­mands can be and what they mean, at least not for­mally, as bibTEX is a pro­gram in­tended to be used with many vari­ants of TEX style: plain, LATEX , and oth­ers. This means that we need to de­fine our use of these type­set­ting com­mands. How­ever, in most cases, they are just ab­bre­vi­a­tions or font switches and these are of­ten known. There­fore, ConTEXt will try to re­solve them be­fore re­port­ing an is­sue. In the log file there is a list of com­mands that has been seen in the loaded data­bases. For in­stance, load­ing tugboat.bib gives a long list of com­mands of which we show a small set here:

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

You can de­fine un­known com­mands, or over­load ex­ist­ing de­f­i­n­i­tions in the fol­low­ing way:

\definebtxcommand\TUB {TUGboat}
\definebtxcommand\sltt{\tt}
\definebtxcommand\<#1>{\type{#1}}

Un­known com­mands do not stall pro­cess­ing, but their names are then type­set in a mono- spaced font so they prob­a­bly stand out for proof­read­ing. You can ac­cess the com­mands with \btxcommand{...} , as in:

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

As this is an un­de­fined com­mand we get: “com­mands like MySpe­cial­Com­mand are han­dled in an in­di­rect way”.

??

3 Datasets

Nor­mally in a doc­u­ment you will use only one bib­li­o­graphic data­base, whether or not dis­trib­uted over mul­ti­ple files. Nev­er­the­less we sup­port mul­ti­ple data­bases as well which is why we talk of datasets in­stead. A dataset is loaded with the \usebtxdataset com­mand. Al­though cur­rently it is not nec­es­sary to de­fine a (de­fault) dataset you can best do this be­cause in the fu­ture we might pro­vide more op­tions. Here are some ex­am­ples:

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

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

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

\definebtxdataset[example]

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

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

\showbtxdatasetfields[example]

this gives:

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

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

\setbtxdataset[standard]

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

4 Ren­der­ings

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

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

If you want to see what pub­li­ca­tions are in the data­base, the eas­i­est way is to ask for a com­plete list:

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

This gives:1 Hans Ha­gen and Ton Ot­ten (1996). Type­set­ting ed­u­ca­tion doc­u­ments2 Luigi Scarso (2021). De­sign­ing high speed trains3 au­thor (year). ti­tle pages p.

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

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

A dataset can have all kind of en­tries:

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

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

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

    
 setupbtxlistvariant : artauthor  no specific settings 
 setupbtxlistvariant : author  no specific settings 
 setupbtxlistvariant : editor  no specific settings 

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

There are a cou­ple of ac­ces­sors and helpers to get the job done. When you want to fetch a field from the cur­rent en­try you use \btxfield . In most cases you want to make sure this field has a value, for in­stance be­cause you don’t want fences or punc­tu­a­tion that be­longs to a field.

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

There are three test macros:

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

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

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

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

There are three com­mands to flush data:

     \btxfield fetch a ex­plicit field (e.g.  year ) \btxdetail fetch a de­rived field (e.g.  short ) \btxflush fetch a de­rived or ex­plicit field

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

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

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

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

     \btxspace be­fore af­ter \btxperiod be­fore. af­ter \btxcomma be­fore, af­ter \btxlparent be­fore (af­ter \btxrparent be­fore) af­ter \btxlbracket be­fore [af­ter \btxrbracket be­fore] af­ter

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

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

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

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

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

\btxflushauthorinverted{editor}

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

    con­ver­sionren­der­ing inverted the Frog jr, Ker­mit invertedshort the Frog jr, K normal Ker­mit, the Frog, jr normalshort K, the Frog, jr

5 Ci­ta­tions

Ci­ta­tions are ref­er­ences to bib­li­o­graphic en­tries that nor­mally show up in lists some­place in the doc­u­ment: at the end of a chap­ter, in an ap­pen­dix, at the end of an ar­ti­cle, etc. We dis­cussed the ren­der­ing of these lists in the pre­vi­ous chap­ter. A ci­ta­tion is nor­mally pretty short as its main pur­pose is to re­fer uniquely to a more de­tailed de­scrip­tion. But, there are sev­eral ways to re­fer, which is why the ci­ta­tion sub­sys­tem is con­fig­urable and ex­ten­si­ble. Just look at the fol­low­ing com­mands:

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

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

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

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

\setupbtxcitevariant[author] [sorttype=author,color=darkyellow]
\setupbtxcitevariant[authoryear] [sorttype=author,color=darkyellow]
\setupbtxcitevariant[authoryears][sorttype=author,color=darkyellow]

\cite[author][example::demo-004,demo-003]

\cite[authoryear][example::demo-004,demo-003] \cite[authoryears][example::demo-004,demo-003]
Here we sort the au­thors and color the ci­ta­tion:

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

For rea­sons of back­ward com­pat­i­bil­ity the \cite com­mand is a bit picky about spaces be­tween the two ar­gu­ments, of which the first is op­tional.

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

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

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

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

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.