Changes

Jump to navigation Jump to search

User:Luigi.scarso/testpage (view source)

Revision as of 18:37, 15 January 2014

200 bytes removed ,  18:37, 15 January 2014
no edit summary
 
 
 
 
=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 <tt>bibtex8</tt> ).
<br/>
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>bibtex</tt> pro­gram that con­verts the data­base into some­thing more TEX friendly (a <tt>.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.
<br/>
In ConTEXt we no longer use the <tt>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 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.
<br/>
A bibTEX file looks like this:
<pre detail='typing'>
ISSN = "1234-5678",
}
</pre><br/>
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 <tt>pages</tt> have funny char­ac­ters such as the en­dash (typ­i­cally as <tt>--</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 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.
<br/>
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.
<br/>
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.
<pre detail='typing'>
\pages{123--126}
\stoppublication
</pre><br/>
The split <tt>\artauthor</tt> fields are col­lapsed into a sin­gle <tt>author</tt> field as we deal with the split­ting later when it gets parsed in Lua . The <tt>\artauthor</tt> syn­tax is only kept around for back­ward com­pat­i­bil­ity with the pre­vi­ous use of bibTEX .
<br/>
In the new setup we sup­port these vari­ants as well:
<pre detail='typing'>
...
\stoppublication
</pre><br/>
and
<pre detail='typing'>
...
\stoppublication
</pre><br/>
and
<pre detail='typing'>
...
\stoppublication
</pre><br/>
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:
<pre detail='typing'>
},
}
</pre><br/>
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.
<pre detail='typing'>
</entry>
</bibtex>
</pre><br/>
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).
<br/>
So the user has a rather wide choice of for­mat­ting style for bib­li­og­ra­phy data­base files.
publications > standard sltt 1 unknown
publications > stop used btxcommands
</pre><br/>
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 detail='typing'>
\definebtxcommand\sltt{\tt}
\definebtxcommand\<#1>{\type{#1}}
</pre><br/>
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>\btxcommand{...}</tt> , as in:
<pre detail='buffer'>
commands like \btxcommand{MySpecialCommand} are handled in an indirect way
</pre><br/>
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”.
<br/>
??
\usebtxdataset[standard][mtx-bibtex-output.xml]
\usebtxdataset[standard][test-001-btx-standard.lua]
</pre><br/>
These three suf­fixes are un­der­stood by the loader. Here the dataset has the name <tt>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 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.
\definebtxdataset[example]
</pre>\usebtxdataset[example][mkiv-publications.bib]
<br/>
You can ask for an overview of en­tries in a dataset with:
<pre detail='buffer'>
</pre>
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<br/>
You can set the cur­rent ac­tive dataset with
<pre detail='typing'>
\setbtxdataset[standard]
</pre><br/>
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.
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:
<br/> <tt>abstract</tt> , <tt>address</tt> , <tt>annotate</tt> , <tt>assignee</tt> , <tt>author</tt> , <tt>bibnumber</tt> , <tt>booktitle</tt> , <tt>chapter</tt> , <tt>comment</tt> , <tt>country</tt> , <tt>day</tt> , <tt>dayfiled</tt> , <tt>doi</tt> , <tt>edition</tt> , <tt>editor</tt> , <tt>eprint</tt> , <tt>howpublished</tt> , <tt>institution</tt> , <tt>isbn</tt> , <tt>issn</tt> , <tt>journal</tt> , <tt>key</tt> , <tt>keyword</tt> , <tt>keywords</tt> , <tt>language</tt> , <tt>lastchecked</tt> , <tt>month</tt> , <tt>monthfiled</tt> , <tt>names</tt> , <tt>nationality</tt> , <tt>note</tt> , <tt>notes</tt> , <tt>number</tt> , <tt>organization</tt> , <tt>pages</tt> , <tt>publisher</tt> , <tt>revision</tt> , <tt>school</tt> , <tt>series</tt> , <tt>size</tt> , <tt>title</tt> , <tt>type</tt> , <tt>url</tt> , <tt>volume</tt> , <tt>year</tt> , <tt>yearfiled</tt> <br/>
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 detail='buffer'>
[example]
[criterium=all]
</pre><br/>
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.
<br/>
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>apa</tt> . A ren­der­ing is setup and de­fined with:
A dataset can have all kind of en­tries:
<br/> <tt>article</tt> , <tt>book</tt> , <tt>booklet</tt> , <tt>conference</tt> , <tt>inbook</tt> , <tt>incollection</tt> , <tt>inproceedings</tt> , <tt>manual</tt> , <tt>mastersthesis</tt> , <tt>misc</tt> , <tt>phdthesis</tt> , <tt>proceedings</tt> , <tt>techreport</tt> , <tt>unpublished</tt> <br/>
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:
<br/> <tt>setupbtxlistvariant : artauthor</tt> <tt>no specific settings</tt> <br/> <tt>setupbtxlistvariant : author</tt> <tt>no specific settings</tt> <br/> <tt>setupbtxlistvariant : editor</tt> <tt>no specific settings</tt> <br/>
The ex­act ren­der­ing of list en­tries is de­ter­mined by the <tt>alternative</tt> key and de­faults to <tt>apa</tt> which uses de­f­i­n­i­tions from <tt>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.
<br/>
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>\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 detail='typing'>
\bold{\btxfield{title}},
}
</pre><br/>
There are three test macros:
<pre detail='typing'>
\btxdoif {fieldname}{action when found}
\btxdoifnot {fieldname} {action when not found}
</pre><br/>
An ex­tra con­di­tional is avail­able for test­ing in­ter­ac­tiv­ity:
<pre detail='typing'>
\btxdoifelseinteraction{action when true}{action when false}
</pre><br/>
In ad­di­tion there is also a con­di­tional <tt>\btxinteractive</tt> which is more ef­fi­cient, al­though in prac­tice ef­fi­ciency is not so im­por­tant here.
<br/>
There are three com­mands to flush data:
<tt>\btxfield</tt> fetch a ex­plicit field (e.g. <tt>year</tt> ) <tt>\btxdetail</tt> fetch a de­rived field (e.g. <tt>short</tt> ) <tt>\btxflush</tt> fetch a de­rived or ex­plicit field<br/>
Nor­mally you can use <tt>\btxfield</tt> or <tt>\btxflush</tt> as de­rived fields just like an­a­lyzed au­thor fields are flushed in a spe­cial way.
<br/>
You can im­prove read­abil­ity by us­ing se­tups, for in­stance:
<pre detail='typing'>
\btxsetup{btx:apa:author:nop}
}
</pre><br/>
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:
<tt>\btxspace</tt> be­fore af­ter <tt>\btxperiod</tt> be­fore. af­ter <tt>\btxcomma</tt> be­fore, af­ter <tt>\btxlparent</tt> be­fore (af­ter <tt>\btxrparent</tt> be­fore) af­ter <tt>\btxlbracket</tt> be­fore [af­ter <tt>\btxrbracket</tt> be­fore] af­ter<br/>
So, the pre­vi­ous ex­am­ple setup can be rewrit­ten as:
<pre detail='typing'>
\btxcomma
}
</pre><br/>
There is a spe­cial com­mand for ren­der­ing a (com­bi­na­tion) of au­thors:
<pre detail='typing'>
\btxflushauthor{editor}
\btxflushauthor[inverted]{editor}
</pre><br/>
In­stead of the last one you can also use:
<pre detail='typing'>
\btxflushauthorinverted{editor}
</pre><br/>
You can use a (con­fig­urable) de­fault or pass di­rec­tives: Valid di­rec­tives are
con­ver­sionren­der­ing <tt>inverted</tt> the Frog jr, Ker­mit <tt>invertedshort</tt> the Frog jr, K <tt>normal</tt> Ker­mit, the Frog, jr <tt>normalshort</tt> K, the Frog, jr
\cite[authoryear][example::demo-004,demo-003]
\cite[authoryears][example::demo-004,demo-003]
</pre>(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)<br/>
The first ar­gu­ment is op­tional.
\cite[authoryear][example::demo-004,demo-003]
\cite[authoryears][example::demo-004,demo-003]
<br/>
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)<br/>
For rea­sons of back­ward com­pat­i­bil­ity the <tt>\cite</tt> com­mand is a bit picky about spaces be­tween the two ar­gu­ments, of which the first is op­tional.
<pre detail='typing'>
\citation[authoryear] [example::demo-004,demo-003]
\citation[authoryears][example::demo-004,demo-003]
</pre><br/>
There is a whole bunch of cite op­tions and more can be eas­ily de­fined.
keyren­der­ing <tt>author</tt> (au­thor) <tt>authornum</tt> [au­thor [btx er­ror 1]] <tt>authoryear</tt> (au­thor (year)) <tt>authoryears</tt> (au­thor, year) <tt>doi</tt> [todo: doi] <tt>key</tt> [demo-005] <tt>none</tt> <tt>num</tt> [[btx er­ror 1]] <tt>page</tt> pages <tt>serial</tt> [5] <tt>short</tt> [aut00] <tt>type</tt> [book] <tt>url</tt> [todo: url] <tt>year</tt> (year)<br/>
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.
Retrieved from "https://wiki.contextgarden.net/Special:MobileDiff/22244"

Navigation menu