Difference between revisions of "User:Luigi.scarso/testpage"
Luigi.scarso (talk | contribs) |
Luigi.scarso (talk | contribs) |
||
Line 1: | Line 1: | ||
+ | |||
+ | |||
+ | |||
+ | |||
=1 The database= | =1 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 | + | 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 <tt>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 | + | 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 <tt>bibtex</tt> program that converts the database into something more TEX friendly (a <tt>.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 | + | In ConTEXt we no longer use the <tt>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: | A bibTEX file looks like this: | ||
<pre detail='typing'> | <pre detail='typing'> | ||
Line 20: | Line 24: | ||
ISSN = "1234-5678", | ISSN = "1234-5678", | ||
} | } | ||
− | </pre> | + | </pre> |
− | 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 | + | <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 <tt>pages</tt> have funny characters such as the endash (typically as <tt>--</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. | 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. | ||
− | + | <br/> | |
In the old MkII setup we have two kinds of entries: the ones that come from the bibTEX run and user supplied ones. We no longer rely on bibTEX output but we do still support the user supplied definitions. These were in fact prepared in a way that suits the processing of bibTEX generated entries. The next variant reflects the ConTEXt recoding of the old bibTEX output. | In the old MkII setup we have two kinds of entries: the ones that come from the bibTEX run and user supplied ones. We no longer rely on bibTEX output but we do still support the user supplied definitions. These were in fact prepared in a way that suits the processing of bibTEX generated entries. The next variant reflects the ConTEXt recoding of the old bibTEX output. | ||
<pre detail='typing'> | <pre detail='typing'> | ||
Line 38: | Line 43: | ||
\pages{123--126} | \pages{123--126} | ||
\stoppublication | \stoppublication | ||
− | </pre> | + | </pre> |
− | The split | + | <br/> |
− | + | The split <tt>\artauthor</tt> fields are collapsed into a single <tt>author</tt> field as we deal with the splitting later when it gets parsed in Lua . The <tt>\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: | In the new setup we support these variants as well: | ||
<pre detail='typing'> | <pre detail='typing'> | ||
Line 48: | Line 54: | ||
... | ... | ||
\stoppublication | \stoppublication | ||
− | </pre> | + | </pre> |
+ | <br/> | ||
and | and | ||
<pre detail='typing'> | <pre detail='typing'> | ||
Line 56: | Line 63: | ||
... | ... | ||
\stoppublication | \stoppublication | ||
− | </pre> | + | </pre> |
+ | <br/> | ||
and | and | ||
<pre detail='typing'> | <pre detail='typing'> | ||
Line 66: | Line 74: | ||
... | ... | ||
\stoppublication | \stoppublication | ||
− | </pre> | + | </pre> |
+ | <br/> | ||
Because internally the entries are Lua tables, we also support loading of Lua based definitions: | Because internally the entries are Lua tables, we also support loading of Lua based definitions: | ||
<pre detail='typing'> | <pre detail='typing'> | ||
Line 84: | Line 93: | ||
}, | }, | ||
} | } | ||
− | </pre> | + | </pre> |
+ | <br/> | ||
Files set up like this can be loaded too. The following xml input is rather close to this, and is also accepted as input. | Files set up like this can be loaded too. The following xml input is rather close to this, and is also accepted as input. | ||
<pre detail='typing'> | <pre detail='typing'> | ||
Line 103: | Line 113: | ||
</entry> | </entry> | ||
</bibtex> | </bibtex> | ||
− | </pre> | + | </pre> |
+ | <br/> | ||
Todo: Add some remarks about loading EndNote and RIS formats, but first we need to complete the tag mapping (on Alan’s plate). | Todo: Add some remarks about loading EndNote and RIS formats, but first we need to complete the tag mapping (on Alan’s plate). | ||
− | + | <br/> | |
So the user has a rather wide choice of formatting style for bibliography database files. | 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 | + | You can load more data than you actually need. Only entries that are referred to explicitly through the <tt>\cite</tt> and <tt>\nocite</tt> commands will be shown in lists. We will cover these details later. |
=2 Commands in entries= | =2 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 | + | 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 <tt>tugboat.bib</tt> gives a long list of commands of which we show a small set here: |
<pre detail='typing'> | <pre detail='typing'> | ||
publications > start used btx commands | publications > start used btx commands | ||
Line 122: | Line 133: | ||
publications > standard sltt 1 unknown | publications > standard sltt 1 unknown | ||
publications > stop used btxcommands | publications > stop used btxcommands | ||
− | </pre> | + | </pre> |
+ | <br/> | ||
You can define unknown commands, or overload existing definitions in the following way: | You can define unknown commands, or overload existing definitions in the following way: | ||
<pre detail='typing'> | <pre detail='typing'> | ||
Line 128: | Line 140: | ||
\definebtxcommand\sltt{\tt} | \definebtxcommand\sltt{\tt} | ||
\definebtxcommand\<#1>{\type{#1}} | \definebtxcommand\<#1>{\type{#1}} | ||
− | </pre> | + | </pre> |
− | 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 | + | <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 <tt>\btxcommand{...}</tt>, as in: | ||
<pre detail='buffer'> | <pre detail='buffer'> | ||
commands like \btxcommand{MySpecialCommand} are handled in an indirect way | commands like \btxcommand{MySpecialCommand} are handled in an indirect way | ||
− | </pre> | + | </pre> |
+ | <br/> | ||
As this is an undefined command we get: “commands like MySpecialCommand are handled in an indirect way”. | As this is an undefined command we get: “commands like MySpecialCommand are handled in an indirect way”. | ||
− | + | <br/> | |
?? | ?? | ||
+ | |||
=3 Datasets= | =3 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 | + | 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 <tt>\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 detail='typing'> | <pre detail='typing'> | ||
\definebtxdataset[standard] | \definebtxdataset[standard] | ||
Line 145: | Line 160: | ||
\usebtxdataset[standard][mtx-bibtex-output.xml] | \usebtxdataset[standard][mtx-bibtex-output.xml] | ||
\usebtxdataset[standard][test-001-btx-standard.lua] | \usebtxdataset[standard][test-001-btx-standard.lua] | ||
− | </pre> | + | </pre> |
− | These three suffixes are understood by the loader. Here the dataset has the name | + | <br/> |
+ | These three suffixes are understood by the loader. Here the dataset has the name <tt>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. | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
In this document we use some example databases, so let’s load one of them now: | In this document we use some example databases, so let’s load one of them now: | ||
<pre detail='buffer'> | <pre detail='buffer'> | ||
\definebtxdataset[example] | \definebtxdataset[example] | ||
− | </pre>\usebtxdataset[example][mkiv-publications.bib] | + | </pre> |
− | + | \usebtxdataset[example][mkiv-publications.bib] | |
+ | |||
+ | <br/> | ||
You can ask for an overview of entries in a dataset with: | You can ask for an overview of entries in a dataset with: | ||
<pre detail='buffer'> | <pre detail='buffer'> | ||
Line 246: | Line 269: | ||
|} | |} | ||
− | + | ||
+ | <br/> | ||
You can set the current active dataset with | You can set the current active dataset with | ||
<pre detail='typing'> | <pre detail='typing'> | ||
\setbtxdataset[standard] | \setbtxdataset[standard] | ||
− | </pre> | + | </pre> |
+ | <br/> | ||
but most publication-related commands accept optional arguments that denote the dataset and references to entries can be prefixed with a dataset identifier.. More about that later. | but most publication-related commands accept optional arguments that denote the dataset and references to entries can be prefixed with a dataset identifier.. More about that later. | ||
+ | |||
=4 Renderings= | =4 Renderings= | ||
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: | 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: | ||
− | <tt>abstract</tt>, <tt>address</tt>, | + | <br/> |
− | <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> | + | <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 publications are in the database, the easiest way is to ask for a complete list: | If you want to see what publications are in the database, the easiest way is to ask for a complete list: | ||
<pre detail='buffer'> | <pre detail='buffer'> | ||
Line 269: | Line 295: | ||
[example] | [example] | ||
[criterium=all] | [criterium=all] | ||
− | </pre> | + | </pre> |
+ | <br/> | ||
This gives:1 Hans Hagen and Ton Otten (1996). Typesetting education documents2 Luigi Scarso (2021). Designing high speed trains3 author (year). title pages p. | This gives:1 Hans Hagen and Ton Otten (1996). Typesetting education documents2 Luigi Scarso (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 | + | 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 <tt>apa</tt>. A rendering is setup and defined with: |
+ | |||
+ | |||
+ | |||
And a list of such descriptions is generated with: | And a list of such descriptions is generated with: | ||
+ | |||
A dataset can have all kind of entries: | A dataset can have all kind of entries: | ||
− | + | <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 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. | 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: | Examples of list variants are: | ||
− | + | <br/> | |
+ | <tt>setupbtxlistvariant : artauthor</tt> | ||
+ | |||
{| | {| | ||
Line 287: | Line 325: | ||
| | | | ||
− | + | <tt>no specific settings</tt> | |
| | | | ||
Line 295: | Line 333: | ||
|} | |} | ||
− | + | ||
+ | <br/> | ||
+ | <tt>setupbtxlistvariant : author</tt> | ||
+ | |||
{| | {| | ||
Line 301: | Line 342: | ||
| | | | ||
− | + | <tt>no specific settings</tt> | |
| | | | ||
Line 309: | Line 350: | ||
|} | |} | ||
− | + | ||
+ | <br/> | ||
+ | <tt>setupbtxlistvariant : editor</tt> | ||
+ | |||
{| | {| | ||
Line 315: | Line 359: | ||
| | | | ||
− | + | <tt>no specific settings</tt> | |
| | | | ||
Line 323: | Line 367: | ||
|} | |} | ||
− | + | ||
− | The exact rendering of list entries is determined by the | + | <br/> |
− | + | 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 a couple of accessors and helpers to get the job done. When you want to fetch a field from the current entry you use | + | <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 <tt>\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 detail='typing'> | <pre detail='typing'> | ||
\btxdoif {title} { | \btxdoif {title} { | ||
\bold{\btxfield{title}}, | \bold{\btxfield{title}}, | ||
} | } | ||
− | </pre> | + | </pre> |
+ | <br/> | ||
There are three test macros: | There are three test macros: | ||
<pre detail='typing'> | <pre detail='typing'> | ||
Line 337: | Line 383: | ||
\btxdoif {fieldname}{action when found} | \btxdoif {fieldname}{action when found} | ||
\btxdoifnot {fieldname} {action when not found} | \btxdoifnot {fieldname} {action when not found} | ||
− | </pre> | + | </pre> |
+ | <br/> | ||
An extra conditional is available for testing interactivity: | An extra conditional is available for testing interactivity: | ||
<pre detail='typing'> | <pre detail='typing'> | ||
\btxdoifelseinteraction{action when true}{action when false} | \btxdoifelseinteraction{action when true}{action when false} | ||
− | </pre> | + | </pre> |
− | In addition there is also a conditional | + | <br/> |
− | + | In addition there is also a conditional <tt>\btxinteractive</tt> which is more efficient, although in practice efficiency is not so important here. | |
+ | <br/> | ||
There are three commands to flush data: | There are three commands to flush data: | ||
Line 351: | Line 399: | ||
| | | | ||
− | + | <tt>\btxfield</tt> | |
| | | | ||
| | | | ||
− | fetch a explicit field (e.g. | + | fetch a explicit field (e.g. <tt>year</tt>) |
| | | | ||
Line 361: | Line 409: | ||
| | | | ||
− | + | <tt>\btxdetail</tt> | |
| | | | ||
| | | | ||
− | fetch a derived field (e.g. | + | fetch a derived field (e.g. <tt>short</tt>) |
| | | | ||
Line 371: | Line 419: | ||
| | | | ||
− | + | <tt>\btxflush</tt> | |
| | | | ||
Line 379: | Line 427: | ||
|} | |} | ||
− | + | ||
− | Normally you can use | + | <br/> |
− | + | 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. | |
+ | <br/> | ||
You can improve readability by using setups, for instance: | You can improve readability by using setups, for instance: | ||
<pre detail='typing'> | <pre detail='typing'> | ||
Line 389: | Line 438: | ||
\btxsetup{btx:apa:author:nop} | \btxsetup{btx:apa:author:nop} | ||
} | } | ||
− | </pre> | + | </pre> |
+ | <br/> | ||
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: | 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: | ||
Line 397: | Line 447: | ||
| | | | ||
− | + | <tt>\btxspace</tt> | |
| | | | ||
Line 407: | Line 457: | ||
| | | | ||
− | + | <tt>\btxperiod</tt> | |
| | | | ||
Line 417: | Line 467: | ||
| | | | ||
− | + | <tt>\btxcomma</tt> | |
| | | | ||
Line 427: | Line 477: | ||
| | | | ||
− | + | <tt>\btxlparent</tt> | |
| | | | ||
Line 437: | Line 487: | ||
| | | | ||
− | + | <tt>\btxrparent</tt> | |
| | | | ||
Line 447: | Line 497: | ||
| | | | ||
− | + | <tt>\btxlbracket</tt> | |
| | | | ||
Line 457: | Line 507: | ||
| | | | ||
− | + | <tt>\btxrbracket</tt> | |
| | | | ||
Line 465: | Line 515: | ||
|} | |} | ||
− | + | ||
+ | <br/> | ||
So, the previous example setup can be rewritten as: | So, the previous example setup can be rewritten as: | ||
<pre detail='typing'> | <pre detail='typing'> | ||
Line 472: | Line 523: | ||
\btxcomma | \btxcomma | ||
} | } | ||
− | </pre> | + | </pre> |
+ | <br/> | ||
There is a special command for rendering a (combination) of authors: | There is a special command for rendering a (combination) of authors: | ||
<pre detail='typing'> | <pre detail='typing'> | ||
Line 478: | Line 530: | ||
\btxflushauthor{editor} | \btxflushauthor{editor} | ||
\btxflushauthor[inverted]{editor} | \btxflushauthor[inverted]{editor} | ||
− | </pre> | + | </pre> |
+ | <br/> | ||
Instead of the last one you can also use: | Instead of the last one you can also use: | ||
<pre detail='typing'> | <pre detail='typing'> | ||
\btxflushauthorinverted{editor} | \btxflushauthorinverted{editor} | ||
− | </pre> | + | </pre> |
+ | <br/> | ||
You can use a (configurable) default or pass directives: Valid directives are | You can use a (configurable) default or pass directives: Valid directives are | ||
Line 500: | Line 554: | ||
| | | | ||
− | + | <tt>inverted</tt> | |
| | | | ||
Line 510: | Line 564: | ||
| | | | ||
− | + | <tt>invertedshort</tt> | |
| | | | ||
Line 520: | Line 574: | ||
| | | | ||
− | + | <tt>normal</tt> | |
| | | | ||
Line 530: | Line 584: | ||
| | | | ||
− | + | <tt>normalshort</tt> | |
| | | | ||
Line 539: | Line 593: | ||
|} | |} | ||
+ | |||
+ | |||
=5 Citations= | =5 Citations= | ||
Line 552: | Line 608: | ||
\cite[authoryear][example::demo-004,demo-003] | \cite[authoryear][example::demo-004,demo-003] | ||
\cite[authoryears][example::demo-004,demo-003] | \cite[authoryears][example::demo-004,demo-003] | ||
− | </pre>(Hans Hagen and Ton Otten)(Hans Hagen and Ton Otten (1996))(Hans Hagen and Ton Otten, 1996)(Hans Hagen and Ton Otten, Luigi Scarso)(Hans Hagen and Ton Otten (1996), Luigi Scarso (2021))(Hans Hagen and Ton Otten, 1996, Luigi Scarso, 2021)(Luigi Scarso, Hans Hagen and Ton Otten)(Luigi Scarso (2021), Hans Hagen and Ton Otten (1996))(Luigi Scarso, 2021, Hans Hagen and Ton Otten, 1996) | + | </pre> |
+ | (Hans Hagen and Ton Otten)(Hans Hagen and Ton Otten (1996))(Hans Hagen and Ton Otten, 1996)(Hans Hagen and Ton Otten, Luigi Scarso)(Hans Hagen and Ton Otten (1996), Luigi Scarso (2021))(Hans Hagen and Ton Otten, 1996, Luigi Scarso, 2021)(Luigi Scarso, Hans Hagen and Ton Otten)(Luigi Scarso (2021), Hans Hagen and Ton Otten (1996))(Luigi Scarso, 2021, Hans Hagen and Ton Otten, 1996) | ||
+ | <br/> | ||
The first argument is optional. | The first argument is optional. | ||
+ | |||
You can tune the way a citation shows up: | You can tune the way a citation shows up: | ||
Line 560: | Line 619: | ||
\setupbtxcitevariant[authoryear] [sorttype=author,color=darkyellow] | \setupbtxcitevariant[authoryear] [sorttype=author,color=darkyellow] | ||
\setupbtxcitevariant[authoryears][sorttype=author,color=darkyellow] | \setupbtxcitevariant[authoryears][sorttype=author,color=darkyellow] | ||
− | </pre>\cite[author][example::demo-004,demo-003] | + | </pre> |
+ | \cite[author][example::demo-004,demo-003] | ||
\cite[authoryear][example::demo-004,demo-003] | \cite[authoryear][example::demo-004,demo-003] | ||
\cite[authoryears][example::demo-004,demo-003] | \cite[authoryears][example::demo-004,demo-003] | ||
− | + | ||
+ | <br/> | ||
Here we sort the authors and color the citation: | Here we sort the authors and color the citation: | ||
− | (Hans Hagen and Ton Otten, Luigi Scarso)(Hans Hagen and Ton Otten (1996), Luigi Scarso (2021))(Hans Hagen and Ton Otten, 1996, Luigi Scarso, 2021) | + | (Hans Hagen and Ton Otten, Luigi Scarso)(Hans Hagen and Ton Otten (1996), Luigi Scarso (2021))(Hans Hagen and Ton Otten, 1996, Luigi Scarso, 2021) |
− | For reasons of backward compatibility the | + | <br/> |
+ | For reasons of backward compatibility the <tt>\cite</tt> command is a bit picky about spaces between the two arguments, of which the first is optional. | ||
<pre detail='typing'> | <pre detail='typing'> | ||
\citation[author] [example::demo-004,demo-003] | \citation[author] [example::demo-004,demo-003] | ||
\citation[authoryear] [example::demo-004,demo-003] | \citation[authoryear] [example::demo-004,demo-003] | ||
\citation[authoryears][example::demo-004,demo-003] | \citation[authoryears][example::demo-004,demo-003] | ||
− | </pre> | + | </pre> |
+ | <br/> | ||
There is a whole bunch of cite options and more can be easily defined. | There is a whole bunch of cite options and more can be easily defined. | ||
Line 589: | Line 652: | ||
| | | | ||
− | + | <tt>author</tt> | |
| | | | ||
Line 599: | Line 662: | ||
| | | | ||
− | + | <tt>authornum</tt> | |
| | | | ||
Line 609: | Line 672: | ||
| | | | ||
− | + | <tt>authoryear</tt> | |
| | | | ||
Line 619: | Line 682: | ||
| | | | ||
− | + | <tt>authoryears</tt> | |
| | | | ||
Line 629: | Line 692: | ||
| | | | ||
− | + | <tt>doi</tt> | |
| | | | ||
Line 639: | Line 702: | ||
| | | | ||
− | + | <tt>key</tt> | |
| | | | ||
Line 649: | Line 712: | ||
| | | | ||
− | + | <tt>none</tt> | |
| | | | ||
Line 659: | Line 722: | ||
| | | | ||
− | + | <tt>num</tt> | |
| | | | ||
Line 669: | Line 732: | ||
| | | | ||
− | + | <tt>page</tt> | |
| | | | ||
Line 679: | Line 742: | ||
| | | | ||
− | + | <tt>serial</tt> | |
| | | | ||
Line 689: | Line 752: | ||
| | | | ||
− | + | <tt>short</tt> | |
| | | | ||
Line 699: | Line 762: | ||
| | | | ||
− | + | <tt>type</tt> | |
| | | | ||
Line 709: | Line 772: | ||
| | | | ||
− | + | <tt>url</tt> | |
| | | | ||
Line 719: | Line 782: | ||
| | | | ||
− | + | <tt>year</tt> | |
| | | | ||
Line 727: | Line 790: | ||
|} | |} | ||
− | + | ||
+ | <br/> | ||
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: | 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. | 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: | But, specific variants can have them overloaded: | ||
− | + | <br/> | |
+ | <tt>setupbtxcitevariant : author</tt> | ||
+ | |||
{| | {| | ||
Line 739: | Line 807: | ||
| | | | ||
− | + | <tt>right</tt> | |
| | | | ||
| | | | ||
− | + | <tt>)</tt> | |
| | | | ||
Line 749: | Line 817: | ||
| | | | ||
− | + | <tt>middle</tt> | |
| | | | ||
| | | | ||
− | + | <tt>, </tt> | |
| | | | ||
Line 759: | Line 827: | ||
| | | | ||
− | + | <tt>left</tt> | |
| | | | ||
| | | | ||
− | + | <tt>(</tt> | |
| | | | ||
|} | |} | ||
− | + | ||
+ | <br/> | ||
+ | <tt>setupbtxcitevariant : authornum</tt> | ||
+ | |||
{| | {| | ||
Line 773: | Line 844: | ||
| | | | ||
− | + | <tt>right</tt> | |
| | | | ||
| | | | ||
− | + | <tt>]</tt> | |
| | | | ||
Line 783: | Line 854: | ||
| | | | ||
− | + | <tt>middle</tt> | |
| | | | ||
| | | | ||
− | + | <tt>, </tt> | |
| | | | ||
Line 793: | Line 864: | ||
| | | | ||
− | + | <tt>left</tt> | |
| | | | ||
| | | | ||
− | + | <tt>[</tt> | |
| | | | ||
|} | |} | ||
− | + | ||
+ | <br/> | ||
+ | <tt>setupbtxcitevariant : authoryear</tt> | ||
+ | |||
{| | {| | ||
Line 807: | Line 881: | ||
| | | | ||
− | + | <tt>compress</tt> | |
| | | | ||
| | | | ||
− | + | <tt>yes</tt> | |
| | | | ||
Line 817: | Line 891: | ||
| | | | ||
− | + | <tt>inbetween</tt> | |
| | | | ||
| | | | ||
− | + | <tt>, </tt> | |
| | | | ||
Line 827: | Line 901: | ||
| | | | ||
− | + | <tt>right</tt> | |
| | | | ||
| | | | ||
− | + | <tt>)</tt> | |
| | | | ||
Line 837: | Line 911: | ||
| | | | ||
− | + | <tt>middle</tt> | |
| | | | ||
| | | | ||
− | + | <tt>, </tt> | |
| | | | ||
Line 847: | Line 921: | ||
| | | | ||
− | + | <tt>left</tt> | |
| | | | ||
| | | | ||
− | + | <tt>(</tt> | |
| | | | ||
|} | |} | ||
− | + | ||
+ | <br/> | ||
+ | <tt>setupbtxcitevariant : authoryears</tt> | ||
+ | |||
{| | {| | ||
Line 861: | Line 938: | ||
| | | | ||
− | + | <tt>compress</tt> | |
| | | | ||
| | | | ||
− | + | <tt>yes</tt> | |
| | | | ||
Line 871: | Line 948: | ||
| | | | ||
− | + | <tt>inbetween</tt> | |
| | | | ||
| | | | ||
− | + | <tt>, </tt> | |
| | | | ||
Line 881: | Line 958: | ||
| | | | ||
− | + | <tt>right</tt> | |
| | | | ||
| | | | ||
− | + | <tt>)</tt> | |
| | | | ||
Line 891: | Line 968: | ||
| | | | ||
− | + | <tt>middle</tt> | |
| | | | ||
| | | | ||
− | + | <tt>, </tt> | |
| | | | ||
Line 901: | Line 978: | ||
| | | | ||
− | + | <tt>left</tt> | |
| | | | ||
| | | | ||
− | + | <tt>(</tt> | |
| | | | ||
|} | |} | ||
− | + | ||
+ | <br/> | ||
+ | <tt>setupbtxcitevariant : doi</tt> | ||
+ | |||
{| | {| | ||
Line 915: | Line 995: | ||
| | | | ||
− | + | <tt>right</tt> | |
| | | | ||
| | | | ||
− | + | <tt>]</tt> | |
| | | | ||
Line 925: | Line 1,005: | ||
| | | | ||
− | + | <tt>left</tt> | |
| | | | ||
| | | | ||
− | + | <tt>[</tt> | |
| | | | ||
|} | |} | ||
− | + | ||
+ | <br/> | ||
+ | <tt>setupbtxcitevariant : key</tt> | ||
+ | |||
{| | {| | ||
Line 939: | Line 1,022: | ||
| | | | ||
− | + | <tt>right</tt> | |
| | | | ||
| | | | ||
− | + | <tt>]</tt> | |
| | | | ||
Line 949: | Line 1,032: | ||
| | | | ||
− | + | <tt>left</tt> | |
| | | | ||
| | | | ||
− | + | <tt>[</tt> | |
| | | | ||
|} | |} | ||
− | + | ||
+ | <br/> | ||
+ | <tt>setupbtxcitevariant : none</tt> | ||
+ | |||
{| | {| | ||
Line 963: | Line 1,049: | ||
| | | | ||
− | + | <tt>no specific settings</tt> | |
| | | | ||
Line 971: | Line 1,057: | ||
|} | |} | ||
− | + | ||
+ | <tt>setupbtxcitevariant : num</tt> | ||
+ | |||
{| | {| | ||
Line 977: | Line 1,065: | ||
| | | | ||
− | + | <tt>compress</tt> | |
| | | | ||
| | | | ||
− | + | <tt>yes</tt> | |
| | | | ||
Line 987: | Line 1,075: | ||
| | | | ||
− | + | <tt>inbetween</tt> | |
| | | | ||
| | | | ||
− | + | <tt>--</tt> | |
| | | | ||
Line 997: | Line 1,085: | ||
| | | | ||
− | + | <tt>right</tt> | |
| | | | ||
| | | | ||
− | + | <tt>]</tt> | |
| | | | ||
Line 1,007: | Line 1,095: | ||
| | | | ||
− | + | <tt>left</tt> | |
| | | | ||
| | | | ||
− | + | <tt>[</tt> | |
| | | | ||
|} | |} | ||
− | + | ||
+ | <br/> | ||
+ | <tt>setupbtxcitevariant : page</tt> | ||
+ | |||
{| | {| | ||
Line 1,021: | Line 1,112: | ||
| | | | ||
− | + | <tt>inbetween</tt> | |
| | | | ||
| | | | ||
− | + | <tt>–</tt> | |
| | | | ||
|} | |} | ||
− | + | ||
+ | <br/> | ||
+ | <tt>setupbtxcitevariant : serial</tt> | ||
+ | |||
{| | {| | ||
Line 1,035: | Line 1,129: | ||
| | | | ||
− | + | <tt>right</tt> | |
| | | | ||
| | | | ||
− | + | <tt>]</tt> | |
| | | | ||
Line 1,045: | Line 1,139: | ||
| | | | ||
− | + | <tt>left</tt> | |
| | | | ||
| | | | ||
− | + | <tt>[</tt> | |
| | | | ||
|} | |} | ||
− | + | ||
+ | <br/> | ||
+ | <tt>setupbtxcitevariant : short</tt> | ||
+ | |||
{| | {| | ||
Line 1,059: | Line 1,156: | ||
| | | | ||
− | + | <tt>right</tt> | |
| | | | ||
| | | | ||
− | + | <tt>]</tt> | |
| | | | ||
Line 1,069: | Line 1,166: | ||
| | | | ||
− | + | <tt>left</tt> | |
| | | | ||
| | | | ||
− | + | <tt>[</tt> | |
| | | | ||
|} | |} | ||
− | + | ||
+ | <br/> | ||
+ | <tt>setupbtxcitevariant : type</tt> | ||
+ | |||
{| | {| | ||
Line 1,083: | Line 1,183: | ||
| | | | ||
− | + | <tt>right</tt> | |
| | | | ||
| | | | ||
− | + | <tt>]</tt> | |
| | | | ||
Line 1,093: | Line 1,193: | ||
| | | | ||
− | + | <tt>left</tt> | |
| | | | ||
| | | | ||
− | + | <tt>[</tt> | |
| | | | ||
|} | |} | ||
− | + | ||
+ | <br/> | ||
+ | <tt>setupbtxcitevariant : url</tt> | ||
+ | |||
{| | {| | ||
Line 1,107: | Line 1,210: | ||
| | | | ||
− | + | <tt>right</tt> | |
| | | | ||
| | | | ||
− | + | <tt>]</tt> | |
| | | | ||
Line 1,117: | Line 1,220: | ||
| | | | ||
− | + | <tt>left</tt> | |
| | | | ||
| | | | ||
− | + | <tt>[</tt> | |
| | | | ||
|} | |} | ||
− | + | ||
+ | <br/> | ||
+ | <tt>setupbtxcitevariant : year</tt> | ||
+ | |||
{| | {| | ||
Line 1,131: | Line 1,237: | ||
| | | | ||
− | + | <tt>right</tt> | |
| | | | ||
| | | | ||
− | + | <tt>)</tt> | |
| | | | ||
Line 1,141: | Line 1,247: | ||
| | | | ||
− | + | <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 | + | <br/> |
+ | 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'> | <pre detail='typing'> | ||
\startsetups btx:cite:author | \startsetups btx:cite:author | ||
\btxcitevariant{author} | \btxcitevariant{author} | ||
\stopsetups | \stopsetups | ||
− | </pre> | + | </pre> |
− | You can overload such setups if needed, but that only makes sense when you cannot configure the rendering with parameters. The | + | <br/> |
+ | 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'> | <pre detail='typing'> | ||
\setbtxdataset[example] | \setbtxdataset[example] | ||
\setbtxentry[hh2013] | \setbtxentry[hh2013] | ||
− | </pre> | + | </pre> |
+ | <br/> | ||
But don’t expect too much support for such low level rendering control. | But don’t expect too much support for such low level rendering control. | ||
− | + | <br/> | |
− | Unless you use | + | 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'> | <pre detail='typing'> | ||
\usecitation[example::demo-004,demo-003] | \usecitation[example::demo-004,demo-003] | ||
− | </pre> | + | </pre> |
− | This command has two synonyms: | + | <br/> |
+ | This command has two synonyms: <tt>\nocite</tt> and <tt>\nocitation</tt> so you can choose whatever fits you best. | ||
+ | |||
+ | |||
+ | |||
=6 The LUA view= | =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. | 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 | + | 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'> | <pre detail='typing'> | ||
t={ | t={ | ||
Line 1,184: | Line 1,297: | ||
} | } | ||
</pre> | </pre> | ||
− | This is | + | 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'> | <pre detail='typing'> | ||
t={ | t={ | ||
Line 1,199: | Line 1,312: | ||
} | } | ||
</pre> | </pre> | ||
− | These details are accessed as | + | 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. |
− | + | <br/> | |
You can loop over the entries using regular Lua code combined with MkIV helpers: | You can loop over the entries using regular Lua code combined with MkIV helpers: | ||
<pre detail='buffer'> | <pre detail='buffer'> | ||
local dataset = publications.datasets.example | local dataset = publications.datasets.example | ||
− | </pre>context.starttabulate { "|l|l|l|" } | + | </pre> |
+ | context.starttabulate { "|l|l|l|" } | ||
for tag, entry in table.sortedhash(dataset.luadata) do | for tag, entry in table.sortedhash(dataset.luadata) do | ||
local detail = dataset.details[tag] or { } | local detail = dataset.details[tag] or { } | ||
Line 1,213: | Line 1,327: | ||
end | end | ||
context.stoptabulate() | context.stoptabulate() | ||
− | + | ||
+ | <br/> | ||
This results in: | This results in: | ||
Line 1,221: | Line 1,336: | ||
| | | | ||
− | + | <tt>demo-001</tt> | |
| | | | ||
Line 1,235: | Line 1,350: | ||
| | | | ||
− | + | <tt>demo-002</tt> | |
| | | | ||
Line 1,249: | Line 1,364: | ||
| | | | ||
− | + | <tt>demo-003</tt> | |
| | | | ||
Line 1,263: | Line 1,378: | ||
| | | | ||
− | + | <tt>demo-004</tt> | |
| | | | ||
Line 1,277: | Line 1,392: | ||
| | | | ||
− | + | <tt>demo-005</tt> | |
| | | | ||
Line 1,290: | Line 1,405: | ||
|} | |} | ||
+ | |||
+ | |||
=7 The XML view= | =7 The XML view= | ||
− | The | + | 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. |
− | + | <br/> | |
− | Once a dataset is accessible as xml tree, you can use the regular | + | 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'> | <pre detail='buffer'> | ||
\usebtxdataset[tugboat][tugboat.bib] | \usebtxdataset[tugboat][tugboat.bib] | ||
− | </pre> | + | </pre> |
+ | <br/> | ||
The dataset has to be converted to xml : | The dataset has to be converted to xml : | ||
<pre detail='buffer'> | <pre detail='buffer'> | ||
\convertbtxdatasettoxml[tugboat] | \convertbtxdatasettoxml[tugboat] | ||
− | </pre> | + | </pre> |
− | The tree is now accessible by its root reference | + | <br/> |
+ | 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'> | <pre detail='buffer'> | ||
\startxmlsetups btx:initialize | \startxmlsetups btx:initialize | ||
Line 1,308: | Line 1,427: | ||
\xmlmain{#1} | \xmlmain{#1} | ||
\stopxmlsetups | \stopxmlsetups | ||
− | </pre>\startxmlsetups btx:field | + | </pre> |
+ | \startxmlsetups btx:field | ||
\xmlflushcontext{#1} | \xmlflushcontext{#1} | ||
\stopxmlsetups | \stopxmlsetups | ||
− | \xmlsetup{btx:tugboat}{btx:initialize} | + | |
− | + | \xmlsetup{btx:tugboat}{btx:initialize} | |
+ | |||
+ | <br/> | ||
The two setups are predefined in the core already, but you might want to change them. They are applied in for instance: | 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'> | <pre detail='buffer'> | ||
Line 1,324: | Line 1,446: | ||
\stoptabulate | \stoptabulate | ||
</pre> | </pre> | ||
+ | |||
{| | {| | ||
Line 1,329: | Line 1,452: | ||
| | | | ||
− | + | <tt>tag</tt> | |
| | | | ||
Line 1,339: | Line 1,462: | ||
| | | | ||
− | + | <tt>title</tt> | |
| | | | ||
Line 1,347: | Line 1,470: | ||
|} | |} | ||
− | <pre detail='buffer'> | + | |
+ | <pre detail='buffer'> | ||
\startxmlsetups btx:demo | \startxmlsetups btx:demo | ||
\xmlcommand | \xmlcommand | ||
Line 1,353: | Line 1,477: | ||
{/bibtex/entry[string.find(@tag,'Hagen')][1]}{btx:table} | {/bibtex/entry[string.find(@tag,'Hagen')][1]}{btx:table} | ||
\stopxmlsetups | \stopxmlsetups | ||
− | </pre>\startxmlsetups btx:table | + | </pre> |
+ | \startxmlsetups btx:table | ||
\starttabulate[|||] | \starttabulate[|||] | ||
\NC \type {tag} \NC \xmlatt{#1}{tag} \NC \NR | \NC \type {tag} \NC \xmlatt{#1}{tag} \NC \NR | ||
Line 1,359: | Line 1,484: | ||
\stoptabulate | \stoptabulate | ||
\stopxmlsetups | \stopxmlsetups | ||
− | |||
+ | \xmlsetup{btx:tugboat}{btx:demo} | ||
+ | |||
+ | |||
{| | {| | ||
Line 1,366: | Line 1,493: | ||
| | | | ||
− | + | <tt>tag</tt> | |
| | | | ||
Line 1,376: | Line 1,503: | ||
| | | | ||
− | + | <tt>title</tt> | |
| | | | ||
Line 1,384: | Line 1,511: | ||
|} | |} | ||
− | + | ||
+ | <br/> | ||
Here is another example: | Here is another example: | ||
<pre detail='buffer'> | <pre detail='buffer'> | ||
Line 1,392: | Line 1,520: | ||
\NC \NR | \NC \NR | ||
\stopxmlsetups | \stopxmlsetups | ||
− | </pre>\startxmlsetups btx:demo | + | </pre> |
+ | \startxmlsetups btx:demo | ||
\xmlfilter {#1} { | \xmlfilter {#1} { | ||
/bibtex | /bibtex | ||
Line 1,400: | Line 1,529: | ||
} | } | ||
\stopxmlsetups | \stopxmlsetups | ||
− | \starttabulate[|||] | + | |
+ | \starttabulate[|||] | ||
\xmlsetup{btx:tugboat}{btx:demo} | \xmlsetup{btx:tugboat}{btx:demo} | ||
\stoptabulate | \stoptabulate | ||
+ | |||
{| | {| | ||
Line 1,707: | Line 1,838: | ||
|} | |} | ||
− | + | ||
+ | <br/> | ||
A more extensive example is the following. Of course this assumes that you know what xml support mechanisms and macros are available. | 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'> | <pre detail='buffer'> | ||
Line 1,715: | Line 1,847: | ||
\xmladdsortentry{btx}{#1}{\xmlatt{#1}{tag}} | \xmladdsortentry{btx}{#1}{\xmlatt{#1}{tag}} | ||
\stopxmlsetups | \stopxmlsetups | ||
− | </pre>\startxmlsetups btx:sorter | + | </pre> |
+ | \startxmlsetups btx:sorter | ||
\xmlresetsorter{btx} | \xmlresetsorter{btx} | ||
% \xmlfilter{#1}{entry/command(btx:getkeys)} | % \xmlfilter{#1}{entry/command(btx:getkeys)} | ||
Line 1,728: | Line 1,861: | ||
\stoptabulate | \stoptabulate | ||
\stopxmlsetups | \stopxmlsetups | ||
− | \startxmlsetups btx:entry:flush | + | |
+ | \startxmlsetups btx:entry:flush | ||
\NC \xmlfilter{#1}{/field[@name='year' ]/context()} | \NC \xmlfilter{#1}{/field[@name='year' ]/context()} | ||
\NC \xmlatt{#1}{tag} | \NC \xmlatt{#1}{tag} | ||
Line 1,734: | Line 1,868: | ||
\NC \NR | \NC \NR | ||
\stopxmlsetups | \stopxmlsetups | ||
− | |||
+ | \xmlsetup{btx:tugboat}{btx:sorter} | ||
+ | |||
+ | |||
{| | {| | ||
Line 2,159: | Line 2,295: | ||
|} | |} | ||
− | + | ||
+ | <br/> | ||
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. | 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= | =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. | 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. | ||
− | + | <br/> | |
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. | 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. | ||
− | + | <br/> | |
Todo: maybe a list of categories and fields. | Todo: maybe a list of categories and fields. | ||
+ | |||
=9 Cleaning up= | =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. | 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: | + | 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). |
− | + | <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. | 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. | ||
− | + | <br/> | |
Todo: maybe some examples of bad. | Todo: maybe some examples of bad. | ||
+ | |||
=10 Transition= | =10 Transition= | ||
Line 2,196: | Line 2,336: | ||
\completepublications | \completepublications | ||
\stoptext | \stoptext | ||
− | </pre> | + | </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 | + | <br/> |
− | + | 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 | + | <br/> |
+ | 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'> | <pre detail='typing'> | ||
\definebtxdataset | \definebtxdataset | ||
Line 2,216: | Line 2,357: | ||
\completebtxrendering[document] | \completebtxrendering[document] | ||
\stoptext | \stoptext | ||
− | </pre> | + | </pre> |
+ | <br/> | ||
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: | 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'> | <pre detail='typing'> | ||
Line 2,223: | Line 2,365: | ||
\setupbtxrendering | \setupbtxrendering | ||
[numbering=yes] | [numbering=yes] | ||
− | </pre> | + | </pre> |
+ | <br/> | ||
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. | 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. | ||
− | + | <br/> | |
− | 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 | + | 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= | =11 MLBIBTEX= | ||
Todo: how to plug in MLbibTEX for sorting and other advanced operations. | Todo: how to plug in MLbibTEX for sorting and other advanced operations. | ||
+ | |||
=12 Extensions= | =12 Extensions= | ||
Line 2,243: | Line 2,388: | ||
loaders.lua(dataset,t) | loaders.lua(dataset,t) | ||
end | end | ||
− | </pre> | + | </pre> |
+ | <br/> | ||
This then permits loading a database (into a dataset) with the command: | This then permits loading a database (into a dataset) with the command: | ||
<pre detail='typing'> | <pre detail='typing'> | ||
\usebtxdataset[standard][myfile.myformat] | \usebtxdataset[standard][myfile.myformat] | ||
− | </pre> | + | </pre> |
− | The | + | <br/> |
+ | The <tt>myformat</tt> suffix is recognized automatically. If you want to use another suffix, you can do this: | ||
<pre detail='typing'> | <pre detail='typing'> | ||
\usebtxdataset[standard][myformat::myfile.txt] | \usebtxdataset[standard][myformat::myfile.txt] | ||
</pre> | </pre> |
Revision as of 08:53, 16 January 2014
Contents
1 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 bibtex8).
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 bibtex program that converts the database into something more TEX friendly (a .bbl 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.
In ConTEXt we no longer use the bibtex 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.
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", }
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 pages have funny characters such as the endash (typically as --) 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.
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.
In the old MkII setup we have two kinds of entries: the ones that come from the bibTEX run and user supplied ones. We no longer rely on bibTEX output but we do still support the user supplied definitions. These were in fact prepared in a way that suits the processing of bibTEX generated entries. The next variant reflects the ConTEXt recoding of the old bibTEX output.
\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 collapsed into a single author field as we deal with the splitting later when it gets parsed in Lua . The \artauthor syntax is only kept around for backward compatibility with the previous use of bibTEX .
In the new setup we support these variants 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
Because internally the entries are Lua tables, we also support loading of Lua based definitions:
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 following xml input is rather close to this, and is also accepted as input.
<?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 remarks about loading EndNote and RIS formats, but first we need to complete the tag mapping (on Alan’s plate).
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 \cite and \nocite commands will be shown in lists. We will cover these details later.
2 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 tugboat.bib gives a long list of commands 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 define unknown commands, or overload existing definitions in the following way:
\definebtxcommand\TUB {TUGboat} \definebtxcommand\sltt{\tt} \definebtxcommand\<#1>{\type{#1}}
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 \btxcommand{...}, as in:
commands like \btxcommand{MySpecialCommand} are handled in an indirect way
As this is an undefined command we get: “commands like MySpecialCommand are handled in an indirect way”.
??
3 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 \usebtxdataset 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:
\definebtxdataset[standard] \usebtxdataset[standard][tugboat.bib] \usebtxdataset[standard][mtx-bibtex-output.xml] \usebtxdataset[standard][test-001-btx-standard.lua]
These three suffixes are understood by the loader. Here the dataset has the name standard 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.
In this document we use some example databases, so let’s load one of them now:
\definebtxdataset[example]
\usebtxdataset[example][mkiv-publications.bib]
You can ask for an overview of entries in a dataset with:
\showbtxdatasetfields[example]
this gives:
tag |
category |
fields |
|||
demo-001 |
book |
author index title year |
|||
demo-002 |
book |
crossref index year |
|||
demo-003 |
book |
author comment index title year |
|||
demo-004 |
book |
author comment index title year |
|||
demo-005 |
book |
author doi index pages serial title url year |
You can set the current active dataset with
\setbtxdataset[standard]
but most publication-related commands accept optional arguments that denote the dataset and references to entries can be prefixed with a dataset identifier.. More about that later.
4 Renderings
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:
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 publications are in the database, the easiest way is to ask for a complete list:
\definebtxrendering [example] [dataset=example, method=local, alternative=apa] \placelistofpublications % \placebtxrendering [example] [criterium=all]
This gives:1 Hans Hagen and Ton Otten (1996). Typesetting education documents2 Luigi Scarso (2021). Designing high speed trains3 author (year). title pages p.
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 apa. A rendering is setup and defined with:
And a list of such descriptions is generated with:
A dataset can have all kind of entries:
article, book, booklet, conference, inbook, incollection, inproceedings, manual, mastersthesis, misc, phdthesis, proceedings, techreport, unpublished
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:
setupbtxlistvariant : artauthor
no specific settings |
setupbtxlistvariant : author
no specific settings |
setupbtxlistvariant : editor
no specific settings |
The exact rendering of list entries is determined by the alternative key and defaults to apa which uses definitions from publ-imp-apa.mkiv. 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 a couple of accessors and helpers to get the job done. When you want to fetch a field from the current entry you use \btxfield. 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.
\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 extra conditional is available for testing interactivity:
\btxdoifelseinteraction{action when true}{action when false}
In addition there is also a conditional \btxinteractive which is more efficient, although in practice efficiency is not so important here.
There are three commands to flush data:
\btxfield |
fetch a explicit field (e.g. year) |
||
\btxdetail |
fetch a derived field (e.g. short) |
||
\btxflush |
fetch a derived or explicit field |
Normally you can use \btxfield or \btxflush as derived fields just like analyzed author fields are flushed in a special way.
You can improve readability by using setups, for instance:
\btxdoifelse {author} { \btxsetup{btx:apa:author:yes} } { \btxsetup{btx:apa:author:nop} }
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:
\btxspace |
before after |
||
\btxperiod |
before. after |
||
\btxcomma |
before, after |
||
\btxlparent |
before (after |
||
\btxrparent |
before) after |
||
\btxlbracket |
before [after |
||
\btxrbracket |
before] after |
So, the previous example setup can be rewritten as:
\btxdoif {title} { \bold{\btxfield{title}} \btxcomma }
There is a special command for rendering a (combination) of authors:
\btxflushauthor{author} \btxflushauthor{editor} \btxflushauthor[inverted]{editor}
Instead of the last one you can also use:
\btxflushauthorinverted{editor}
You can use a (configurable) default or pass directives: Valid directives are
conversion |
rendering |
||
inverted |
the Frog jr, Kermit |
||
invertedshort |
the Frog jr, K |
||
normal |
Kermit, the Frog, jr |
||
normalshort |
K, the Frog, jr |
5 Citations
Citations are references to bibliographic entries that normally show up in lists someplace in the document: at the end of a chapter, in an appendix, at the end of an article, etc. We discussed the rendering of these lists in the previous chapter. A citation is normally pretty short as its main purpose is to refer uniquely to a more detailed description. But, there are several ways to refer, which is why the citation subsystem is configurable and extensible. Just look at the following commands:
\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 Hagen and Ton Otten)(Hans Hagen and Ton Otten (1996))(Hans Hagen and Ton Otten, 1996)(Hans Hagen and Ton Otten, Luigi Scarso)(Hans Hagen and Ton Otten (1996), Luigi Scarso (2021))(Hans Hagen and Ton Otten, 1996, Luigi Scarso, 2021)(Luigi Scarso, Hans Hagen and Ton Otten)(Luigi Scarso (2021), Hans Hagen and Ton Otten (1996))(Luigi Scarso, 2021, Hans Hagen and Ton Otten, 1996)
The first argument is optional.
You can tune the way a citation 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 authors and color the citation:
(Hans Hagen and Ton Otten, Luigi Scarso)(Hans Hagen and Ton Otten (1996), Luigi Scarso (2021))(Hans Hagen and Ton Otten, 1996, Luigi Scarso, 2021)
For reasons of backward compatibility the \cite command is a bit picky about spaces between the two arguments, of which the first is optional.
\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 options and more can be easily defined.
key |
rendering |
||
author |
(author) |
||
authornum |
[author [btx error 1]] |
||
authoryear |
(author (year)) |
||
authoryears |
(author, year) |
||
doi |
[todo: doi] |
||
key |
[demo-005] |
||
none |
|||
num |
|||
page |
pages |
||
serial |
[5] |
||
short |
[aut00] |
||
type |
[book] |
||
url |
[todo: url] |
||
year |
(year) |
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:
setupbtxcitevariant : author
right |
) |
||
middle |
, |
||
left |
( |
setupbtxcitevariant : authornum
right |
] |
||
middle |
, |
||
left |
[ |
setupbtxcitevariant : authoryear
compress |
yes |
||
inbetween |
, |
||
right |
) |
||
middle |
, |
||
left |
( |
setupbtxcitevariant : authoryears
compress |
yes |
||
inbetween |
, |
||
right |
) |
||
middle |
, |
||
left |
( |
setupbtxcitevariant : doi
right |
] |
||
left |
[ |
setupbtxcitevariant : key
right |
] |
||
left |
[ |
setupbtxcitevariant : none
no specific settings |
setupbtxcitevariant : num
compress |
yes |
||
inbetween |
-- |
||
right |
] |
||
left |
[ |
setupbtxcitevariant : page
inbetween |
– |
setupbtxcitevariant : serial
right |
] |
||
left |
[ |
setupbtxcitevariant : short
right |
] |
||
left |
[ |
setupbtxcitevariant : type
right |
] |
||
left |
[ |
setupbtxcitevariant : url
right |
] |
||
left |
[ |
setupbtxcitevariant : year
right |
) |
||
left |
( |
A citation variant is defined in several steps and if you really want to know the dirty details, you should look into the publ-imp-*.mkiv files. Here we stick to the concept.
\startsetups btx:cite:author \btxcitevariant{author} \stopsetups
You can overload such setups if needed, but that only makes sense when you cannot configure the rendering with parameters. The \btxcitevariant 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 \btxcitevariant assumes that a dataset and specific tag has been set. This is normally done in the wrapper macros, like \cite. For special purposes you can use these commands
\setbtxdataset[example] \setbtxentry[hh2013]
But don’t expect too much support for such low level rendering control.
Unless you use criterium=all only publications that are cited will end up in the lists. You can force a citation into a list using \usecitation, for example:
\usecitation[example::demo-004,demo-003]
This command has two synonyms: \nocite and \nocitation 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 example. A dataset table has several fields, and probably the one of most interest is the luadata field. Each entry in this table describes a publication:
t={ ["author"]="Hans Hagen", ["category"]="book", ["index"]=1, ["tag"]="demo-001", ["title"]="\\btxcmd{BIBTEX}, the \\btxcmd{CONTEXT}\\ way", ["year"]="2013", }
This is publications.datasets.example.luadata["demo-001"]. There can be a companion entry in the parallel details table.
t={ ["author"]={ { ["firstnames"]={ "Hans" }, ["initials"]={ "H" }, ["original"]="Hans Hagen", ["surnames"]={ "Hagen" }, ["vons"]={}, }, }, ["short"]="Hag13", }
These details are accessed as publications.datasets.example.details["demo-001"] 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:
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()
This results in:
demo-001 |
Hag13 |
bibTEX , the ConTEXt way |
|||
demo-002 |
Hag14 |
bibTEX , the ConTEXt way |
|||
demo-003 |
HO96 |
Typesetting education documents |
|||
demo-004 |
Sca21 |
Designing high speed trains |
|||
demo-005 |
aut00 |
title |
7 The XML view
The luadata 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 \xml... commands. We start with loading a dataset, in this case from just one file.
\usebtxdataset[tugboat][tugboat.bib]
The dataset has to be converted to xml :
\convertbtxdatasettoxml[tugboat]
The tree is now accessible by its root reference btx:tugboat. If we want simple field access we can use a few setups:
\startxmlsetups btx:initialize \xmlsetsetup{#1}{bibtex|entry|field}{btx:*} \xmlmain{#1} \stopxmlsetups
\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:
\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
tag |
Hagen:TB17-1-54 |
||
title |
PPCHTEX: typesetting chemical formulas in TEX |
\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}
tag |
Hagen:TB17-1-54 |
||
title |
PPCHTEX: typesetting chemical formulas in TEX |
Here is another example:
\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
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.
\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}
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: Prof. Dr. Alfred B. C. von Kwik Kwak Jr. II and P. Q. Olet is just one example of this. The convention seems to be not to use commas but and 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):
% 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
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 \cite) 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 \cite command remains.
\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
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:
\usebtxdataset [mybibfile.bib] \setupbtxrendering [numbering=yes]
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 btx. 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 btx:document.
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.
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
This then permits loading a database (into a dataset) with the command:
\usebtxdataset[standard][myfile.myformat]
The myformat suffix is recognized automatically. If you want to use another suffix, you can do this:
\usebtxdataset[standard][myformat::myfile.txt]