\environment publications-style \startcomponent publications-citations \startchapter [title=Citations, reference=ch:cite] The \index {style+APA}APA Style Guide as well as good practice demand that \emphasis {all} references appearing in the bibliography be cited at least once in the text (and, of course, all citations must have a corresponding bibliographical reference). Other publishing styles, textbooks in particular, might additionally include lists of general references for \quote {further reading} (and these lists might sometimes be split into sections according to subject). An author may, in contrast, choose not to interrupt a text with many citations, nevertheless, including a list of references. Furthermore, one might refer in the text to certain works that need not necessarily be accompanied by a full bibliography listing (for example, \Name {Darwin} {C.}'s \emph {Origin}). \startfootnote \textcite[entry] [default::Darwin1859] \stopfootnote Thus, a system providing tools to handle bibliographies needs to be flexible. A good, general reference on bibliography practice (in the English language), independent of any particular specification, can be found in \cite [title] [default::vanLeunen1992] \cite [default::vanLeunen1992]. Note that rules and traditions may differ slightly in other languages and cultures. The examples of bibliography listings of the previous chapter were simplified by the fact that the entire bibliographical dataset was rendered. In practice, the same dataset source(s) could be used over many documents, and the dataset might contain many more references than are used in any one document. That is, the data source might be more complete than the final rendered bibliography list or lists. The mechanism of citation allows you to select references from the dataset(s) to build the list rendering as well as to place a indicator of the reference (or not) in the text of the document corresponding to a list entry (a publication). These citation renderings can be of many forms. 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: \cindex{cite} \tindex{::} \starttabulate \NC \TEXcode{\cite[num][article]} \NC \cite[num] [article] \NC \NR \NC \TEXcode{\cite[textnum][article]} \NC \cite[textnum] [article] \NC \NR \NC \TEXcode{\cite[authornum][article]} \NC \cite[authornum] [article] \NC \NR \NC \TEXcode{\cite[authoryear][article]} \NC \cite[authoryear] [article] \NC \NR \NC \TEXcode{\cite[authoryears][article]} \NC \cite[authoryears][article] \NC \NR \NC \TEXcode{\cite[short][article]} \NC \cite[short] [article] \NC \NR \NC \TEXcode{\cite[tag][article]} \NC \cite[tag] [article] \NC \NR \NC \TEXcode{\cite[index][article]} \NC \cite[index] [article] \NC \NR \NC \TEXcode{\cite[category][article]} \NC \cite[category] [article] \NC \NR \NC \TEXcode{\cite[author][article]} \NC \cite[author] [article] \NC \NR \NC \TEXcode{\cite[year][article]} \NC \cite[year] [article] \NC \NR \NC \TEXcode{\cite[title][article]} \NC \cite[title] [article] \NC \NR \NC \TEXcode{\cite[keywords][article]} \NC \cite[keywords] [article] \NC \NR \NC \TEXcode{\cite[none][article]} \NC \cite[none] [article] \NC \NR \NC \TEXcode{\cite[X]} \NC \cite[X] \NC \NR \NC \TEXcode{\cite[]} \NC \cite[] \NC \NR \NC \TEXcode{\cite[template::Chen:1988:IPP]} \NC \cite[template::Chen:1988:IPP] \NC \NR \NC \TEXcode{\cite[entry][article]} \NC \cite[entry] [article] \NC \NR \stoptabulate The first argument is optional and if omitted, the default citation rendering (for example, \TEXcode {num} or \TEXcode {authoryear}, depending on the specification) will be selected. \startbuffer \cite[article] \stopbuffer \cindex{cite} \typeTEXbuffer \getbuffer \startaside The default citation alternative is defined via \cindex {setupbtx} \startTEX \setupbtx[alternative=num] \stopTEX However, this is not used as it is overridden by the specification, even the \TEXcode {default} specification: \startTEX \setupbtx[default:cite][alternative=num] \setupbtx [apa:cite][alternative=authoryear] \stopTEX These examples introduce the concept of \Index {namespace}s that is extensively used in the bibliography subsystem. The \TEXcode {cite} namespace will inherit from the root namespace; similarly, the \TEXcode {default} specification will inherit elements from the \TEXcode {cite} namespace, but will be distinct from the \TEXcode {apa} specification's \TEXcode {cite} namespace, and so forth. Normally, we need not to worry about this as it is handled through the loading of the specification. \stopaside \cindex {cite} \showsetup[cite] The \Cindex{citation} command is synonymous to \Cindex{cite}. \cindex {citation} \showsetup[citation] %\showsetup[citation:userdata] \showsetup[citation:alternative] \showsetup[citation:direct] \startaside Note that the \MKII\ module based on \Tindex {bibtex} allowed the use of curly brackets enclosing the \Index {tag} (for reasons of backward compatibility with traditional \LATEX\ practice). A side|-|effect made this a bit picky about spaces between its arguments, the first of which is optional. We have chosen to remove this restriction through the use of standard \CONTEXT\ syntax using square brackets (reserving curly brackets to usually be used to enclose text that is to be typeset). The system will tolerate the \Index {depreciated} syntax \cindex {cite}\TEXcode {\cite{tag}}, but this practice is to be strongly discouraged and cannot be mixed with any other options. \stopaside The most commonly used citation variants (or alternatives) are \TEXcode {num} and \TEXcode {authoryear} introduced above. The first is typically employed in conjunction with a numbered bibliography list, usually sorted in the citation order in the text; the second is typically used in conjunction with a bibliography list sorted by author and year of publication. Other citation variants may be quite useful, even when used in the context of the above standard schemes. One such example would be \Cindex {cite}\TEXcode {[title][tag]} that can be used to include the title of the work in the running text (as can be seen earlier in \in {section} [sec:styles]; another one is \cindex {cite}\TEXcode {\cite[year][tag]} that can be used to include the publication date and \cindex {cite}\TEXcode {\cite[author][tag]} can be used to extract the authors' names. These are examples of a general rule where \cindex {cite}\TEXcode {\cite[field][tag]} will return the contents of the given field for an entry, if the entry contains such a field. The variants \TEXcode {textnum} and \TEXcode {authoryears} are intended to be used in the running text when the reference becomes part of the syntax of the sentence: typically, they will not be set|-|off by parenthesis, for example. \startaside The name \TEXcode {authoryears} (with an \quote{s}) is a shorthand that was used in \MKII. Whereas its name is not immediately obvious at first view, in practice it is a quite convenient variant of \TEXcode {authoryear} that differs only in the style of punctuation, thus its place in a sentence structure. \stopaside Notice that in the example \TEXcode{\cite[template::Chen:1988:IPP]} shown above, the \TEXcode {tag} was prefixed with an alternate dataset name (\tindex {::}\TEXcode {template::}) rather than to the default \TEXcode {dataset=example} that was specified in the \Cindex {setupbtx} command earlier. The reason behind the double|-|colon syntax should be made obvious here (where the \Index {tag} itself uses single colons). In the last of the examples shown above, \TEXcode{\cite[entry][article]}, the full rendered bibliographic entry gets placed. Unless the placed rendering uses \TEXcode {method=dataset}, only publications that are explicitly cited will end up in the lists. You can force a citation into a list using \Cindex {usecitation}, for example: \cindex{usecitation} \startTEX \usecitation[patent] \stopTEX This command has two synonyms: \Cindex {nocite} and \Cindex {nocitation} so you can choose whatever fits you best. \cindex {nocite} \showsetup[nocite] \cindex {nocitation} \showsetup[nocitation] \cindex {usecitation} \showsetup[usecitation] The purpose and utility of these commands (and their synonyms) is not only to draw a citation from the dataset for inclusion in the bibliography, but also to mark the place in the text where the citation is relevant. Normally, one might claim that this should be done through one of the forms of the \Cindex {cite} (or \Cindex {citation}) command, as all references appearing in the bibliography are to be cited at least once in the text. However, even if one does not disagree with this statement, one might still wish attach the citation to the reference in the text of a \Index {floating object} such as a table or a figure, thus establishing a proper order in the numbering since the explicit citation rendering might occur within the table or the figure caption that might get placed on a much later page. Consider the following schematic illustration: \cindex{nocite} \cindex{cite} \startTEX (see \nocite [MyReference]\in {table} [tab:mytable]). \startplacetable[reference=tab:mytable] \unknown\ \cite[MyReference] \stopplacetable \stopTEX The citation rendering and the bibliographic list rendering are intimately coupled reciprocally and cannot be dissociated. This coupling can be through the reference number for example, but unnumbered reference lists also contain interacting hyperlinks. A failure to take into account this interdependence can lead to fundamental misunderstandings in use. \startaside Both the citation and the list must be rendered. For example, a common error would be to omit (or comment|-|out) the list rendering during the writing stage of a document. Such an error will cause the citations to fail to render properly. Whereas this might seem to be an unnecessary limitation, it results from a specific design choice and from the possibility of placing multiple renderings freely, anywhere in a document. It is preferable not to render citations at all than to render these citations possibly incorrectly. \stopaside \startsection[title=Combining citations] \startbuffer \cite[num][article,book,booklet] \stopbuffer A single citation might refer to several sources, obtained through the use of a comma separated list of \Index{tag}s, for example: \getbuffer \cindex{cite} \typeTEXbuffer A comma separated list of three (or more) consecutive numbers will get collapsed or compressed into a range of numbers (if possible). \cindex {cite} The order in which the citation \Index {tag}s appear in the list may or may not be important, depending upon the citation variant and on the style specification. Consider the following examples: \startbuffer \cite[num] [article,book] \cite[textnum] [article,book] \cite[authoryear] [article,book] \cite[authoryears][article,book] \cite[short] [article,book] \cite[author] [article,book] \cite[year] [article,book] \cite[title] [article,book] \stopbuffer \typeTEXbuffer This gives: \cindex{cite} \startlines \getbuffer \stoplines Now we swap the order: \startbuffer \cite[num] [book,article] \cite[textnum] [book,article] \cite[authoryear] [book,article] \cite[authoryears][book,article] \cite[short] [book,article] \cite[author] [book,article] \cite[year] [book,article] \cite[title] [book,article] \stopbuffer \typeTEXbuffer and get: \startlines \getbuffer \stoplines Note that the numbered citation reference is always rendered in numerical order, where the numbers correspond to the order in which the entries appear in the bibliography list. This order depends on the \Index {sorting} of the list rendering (this sorting may be, in some styles, in the order in which the references are cited) and is controlled by the \TEXcode {[list]} \TEXcode {sorttype} parameter. In the \index {style+APA}APA style, presently active, the citations are always sorted according to author and year. Thus, \quotation {BookAuthorLastname} appears before \quotation {Last} in our example here, regardless of the order in which the references appear in the \Cindex {cite} command (i.e. either \TEXcode {\cite[article,book]} or \TEXcode {\cite[book,article]}). The user can control the state of sorting of the \cindex{cite}\TEXcode {cite} variants through the parameter \TEXcode {sorttype=normal}; other choices are \TEXcode {reverse} and \TEXcode {none}: \startTEX \setupbtx[aps:cite:num][sorttype=none] \stopTEX \startsubsubject [title=Single list item containing multiple publication entries] Some bibliography styles admit the combination of several bibliographical sources into a single list item having a unique reference number. The combination of multiple bibliographic entries into as single bibliography list item is more compact and this practice is often encountered in short \quote {letter}|-|type journal articles. (Note, however, that entries combined as such do not make any sense in an authoryear scheme such as \index {style+APA}APA.) One can combine \Index {tag}s using the addition operator symbol (\TEXcode {+}), best illustrated though an example: \startbuffer \METAFUN\ began as an expression of love and appreciation for \METAPOST. \citation [num] [tugboat::Berdnikov:TB21-2-129+Hobby:TB21-2-131] \definebtxrendering[tugboat][aps][dataset=tugboat,group=examples] \placebtxrendering [tugboat][criterium=section] \stopbuffer \cindex{citation} \cindex{definebtxrendering} \cindex{placebtxrendering} \tindex{::} \typeTEXbuffer \getbuffer Combined entries are joined using a separator that can be specified, as in: \startbuffer \setupbtxrendering[tugboat][separator={\break}] \stopbuffer \cindex{setupbtxrendering} \tindex{separator} \typeTEXbuffer or suppressed (using \tindex {separator}\TEXcode {separator=,}); By default, \cindex {removepunctuation}\TEXcode {separator={\removepunctuation;\space}}. Dataset entries that are combined cannot also appear apart (nor does this really make any logical sense). All of the following: \startbuffer \cite[num][tugboat::Berdnikov:TB21-2-129] \cite[num][tugboat::Berdnikov:TB21-2-129,Hobby:TB21-2-131] \cite[num][tugboat::Hobby:TB21-2-131] \stopbuffer \cindex{cite} \tindex{::} \typeTEXbuffer \getbuffer will point to the combined reference (as they should). However, beware that attempting to include any of these references in a \emphasis {different} combined list item is undefined, meaning unsupported. Combining list entries is another instance showing that citations and the rendered bibliography list interact and cannot be separated. \stopsubsubject \stopsection \startsection[title=Additional text] \startsubsubject [title=Additional text in a citation reference] Sometimes one would like to include additional text in a citation, for example a specific commentary or page number reference. \startbuffer \cite[righttext={ p.\nbsp xx}][article] \stopbuffer \cindex{cite} \typeTEXbuffer yielding: \getbuffer The additional text can be either before (\TEXcode {lefttext=}) or after (\TEXcode {righttext=}) \startfootnote The \MKII\ bib module used the keyword \TEXcode {extra=} in the place of \TEXcode {righttext=}. We chose not to support this as a synonym as the name is ambiguous. Furthermore, we seek to limit the number of keywords used in \CONTEXT. \stopfootnote each citation entry and are not to be confused with the delimiters \TEXcode {left={(},} and \TEXcode {right={)},} used to surround the entire citation. The difference becomes important when referencing multiple citations. The following examples further illustrate the syntax: \startbuffer \cite[lefttext={See },righttext={ p.\nbsp yy}][book] \stopbuffer \typeTEXbuffer \getbuffer \startbuffer \cite[alternative=authoryears,righttext={ p.\nbsp xx}][article] \cite[alternative=authornum,righttext={ p.\nbsp xx}][article] \stopbuffer \typeTEXbuffer \getbuffer \startbuffer \cite[alternative=num,righttext={{ p.\nbsp xx},{ p.\nbsp yy}}] [article,book,booklet] \stopbuffer \cindex{cite} \typeTEXbuffer \getbuffer \startbuffer \cite[lefttext={In the article: },righttext={.}][article] \stopbuffer \cindex{cite} \typeTEXbuffer \getbuffer \startbuffer \cite[lefttext={{In the article: },{in the book: }},alternative=title] [article,book] \stopbuffer \cindex{cite} \typeTEXbuffer \getbuffer \startbuffer \cite[righttext={{ p.\nbsp xx},}][article,book] \stopbuffer \cindex{cite} \typeTEXbuffer \getbuffer Because \CONTEXT\ does not allow mixing key|-|value pair lists with single value keys, the keyword \TEXcode {alternative=} must be used, if needed, as shown in the examples above. Note that a double curly|-|bracket (\TEXcode {{{}}}) also needs to be used when the text is to contain a comma. \stopsubsubject \startsubsubject [title=Additional text in a list entry] Additional text such as notes and page numbers can also get placed with the entry in the bibliography list. Of course, the bibliography data entry can contain a \TEXcode {note=} field that may or may not get rendered, but often is, according to the style specification. It is also possible to specify notes or page references to be rendered \TEXcode {before} or \TEXcode {after} a bibliography entry through the citation call. \startbuffer \cite [alternative=num, before={{Introducing MetaPost: },}, after={,{ See, also, the references therein, p.\nbsp 58.}}] [tugboat::Hobby:TB10-4-505,Hobby:TB22-1-46] \blank \placebtxrendering [tugboat][criterium=section] \stopbuffer \cindex{cite} \cindex{placebtxrendering} \tindex{::} \typeTEXbuffer \getbuffer Clearly, such additional text can be added to each entry only once, so the first such \Cindex {cite} call wins. \stopsubsubject \stopsection \startsection[title=Placing a single citation] Sometimes, one would like to place a single citation somewhere in the text without necessarily adding it to a bibliography list. Take, for example, \startbuffer \placecitation[tugboat::Mahajan:TB31-1-88] \stopbuffer \getbuffer obtained by using \cindex{placecitation} \tindex{::} \typeTEXbuffer Note that \Cindex {placecitation}\TEXcode {[tag]} is a synonym for \Cindex {citation}\TEXcode {[entry][tag]} (that was seen earlier). \showsetup[placecitation] As for other citation reference, this will fail if a bibliography list rendering is not placed somewhere in the document so let's do that here: \startbuffer \placebtxrendering[tugboat][criterium=section] \stopbuffer \cindex{placebtxrendering} \typeTEXbuffer \getbuffer Whereas this might seem redundant above (placing the citation entry as well as its list rendering), this will only exceptionally be the case (as in this highly artificial example of this manual); Indeed, all cited work (such as \cite [textnum] [tugboat::Mahajan:TB31-1-88], above) will logically always be placed in a list of references. The placement of a single citation brings to light a subtle point: The \TEXcode {specification} that is used by citations is that set in the root namespace (through \Cindex {setupbtx}\TEXcode {[specification=apa]} or possibly through \Cindex {usebtxdefinitions}\TEXcode {[apa]}. This is \emphasis {not} necessarily the same as that of the rendering (if a different rendering specification is declared). Note that the named rendering used above (\TEXcode {[tugboat]}) was not declared a child of the rendering named \TEXcode {[aps]}, though the \TEXcode {specification=apa} is active. Thus, the style of the citations can be made to differ from the style of their bibliography list, as here, but this is not really a very good practice. \stopsection \startsection[title=Placing citations as footnotes] A \Cindex {placecitation} command can occur inside a footnote or other \Index {floating object} such as a figure or table caption. No specification or style that places its bibliography list renderings as footnotes has been implemented yet. % bibliographies as endnotes intercalated with footnotes... \stopsection \startsection[title=Searching] Finding the right \Index {tag} in a database can be a pain. In particular, datasets having their origin in multiple source files may contain conflicting \Index {tag}s, though duplicate \Index {tag}s get suffixed automatically so this should not be a real problem. On the other hand, asking for a \Index {wildcard} also makes no sense. \startfootnote Note that \cindex {nocite}\TEXcode {\nocite{*}} is a valid \LATEX/\BIBTEX\ practice that is used to include all entries of a \Tindex {.bib} file in the final bibliography. This result can be obtained in \CONTEXT\ through the \TEXcode {method=dataset} list rendering parameter. Alternately, one can use the syntax \cindex {cite}\TEXcode {\cite[match(*:*)]} which is a shorthand to match all values of all fields. \stopfootnote Nevertheless, we provide a powerful mechanism for matching a query. Keep in mind that a \Index {tag} is used as a quick look|-|up in a hashed table whereas a search will look through the entire dataset. If processing speed is critical, one should use the cite \Index {tag} lookup; in practice, even on a big book project employing a very large dataset, the search is not a penalty. Let's look in more detail at the \Cindex {cite} command. In order to distinguish efficiently between a normal reference and a more clever one, we use the \TEXcode {match()} function: \tindex{::} \startTEX match(query) dataset::match(query) dataset :: match ( query ) \stopTEX The handler is rather tolerant for spaces (as well as capitalization) which is handy if you have long queries that wrap around in the source code. Of course the \tindex {::}\TEXcode {dataset::} prefix is optional in which case the current dataset is taken. Such match queries can be mixed in a multiple reference citation indifferently with hashed cite \Index {tag}s so the system is really flexible. \blank To demonstrate the use a search query, we load a small bibliographic database: \startbuffer \usebtxdataset[boekplan][boekplan.bib] \stopbuffer \cindex{usebtxdataset} \typeTEXbuffer \getbuffer We could switch to this base using: \cindex{setupbtx} \startTEX \setupbtx[dataset=boekplan] \stopTEX but instead we shall use a prefix as seen previously. Consider the following: \startbuffer everything that you might want to know about layouts \cite[boekplan::match(author:Egger)] \stopbuffer \cindex{cite} \tindex{::} \typeTEXbuffer We will get: \quotation {\inlinebuffer}. Of course this assumes that we also typeset a list of references somewhere in our document, so let's do that here: \startbuffer \definebtxrendering[boekplan][apa][dataset=boekplan,group=examples] \placebtxrendering [boekplan][criterium=chapter] \stopbuffer \cindex{definebtxrendering} \cindex{placebtxrendering} \typeTEXbuffer \getbuffer \startbuffer \cite[authoryears][ match(title:Lua)]\\ \cite[authoryears][default:: match(title:Lua)]\\ \cite[authoryears][boekplan::match(title:Lua)] \stopbuffer \cindex{cite} \tindex{::} \typeTEXbuffer \getbuffer Notice that no match is found in the \quote {current} dataset (\TEXcode {example}). A query eventually becomes a \LUA\ expression so you can use helpers to achieve your goal. As a convenience there are some shortcuts to access fields. The following examples demonstrate this: \startbuffer \cite [authoryears] [boekplan::match(author:hagen and year:2010-2011)]\\ \cite [authoryears] [boekplan::match(author:{Willi Egger})]\\ \cite [authoryears] [boekplan::match(author:Hans and (tonumber(field:year) or 0) > 2011)] \stopbuffer \cindex{cite} \tindex{::} \typeTEXbuffer \getbuffer You can use grouping braces when spaces are involved. Ranges (of numbers) are recognized. Of course, you can use other characters that the basic alphabet. \startbuffer \cite[authoryears][tugboat::match(author:{Bogusław Jackowski})]\\ \stopbuffer \cindex{cite} \tindex{::} \typeTEXbuffer \getbuffer This demonstrates further the interest in converting classical \TEX\ accent sequences into proper \UTF\ characters. The citations found above \bold{must} correspond to some bibliography list entries, so we will place this list here: \startbuffer \placebtxrendering [tugboat][criterium=section] \stopbuffer \cindex{placebtxrendering} \typeTEXbuffer \getbuffer String lookups are partial and case insensitive. \startbuffer \cite [boekplan::match(author:e)]\\ \cite [boekplan::match(author:h)] \stopbuffer \cindex{cite} \tindex{::} \typeTEXbuffer so one must take care in formulating cite queries as both lookups above will get all five entries: \inlinebuffer, whereas \startbuffer \cite [boekplan::match(author:eg)]\\ \cite [boekplan::match(author:e*r)] \stopbuffer \cindex{cite} \tindex{::} \typeTEXbuffer finds \inlinebuffer. As the match compares the entire author string, and not just each author, it also finds [Hag]en & Br[aslau] as well as [Ho]ekwater[ & Hagen]. % To Hans: It is curious that match(author:e*r) finds [Hag]en and Br[aslau]. % To Alan: We match the whole (original) string. % % Response: Yes, but this is not what one might naively expect. % It would be useful to match author by author, rather than the entire author % string, at least that is how one might want to use it. Oh well... % the mechanism is predictable and the above example explicitly explains this % point. Would it be easy to add match(lastname:h*), for example? I suppose that % this would have to yield hits in ALL author-type fields (author, editor, ...). Note also that the order of the match criteria is not significant. \startaside The search mechanism is very powerful. However, a \bold {major \Index{pitfall}} or risk comes from the possibility to easily under|-|specify the match criteria. For example, \TEXcode {match(author:Hagen and author:Hoekwater)} will find \cite [title] [boekplan::match(title:Fonts)], but it will also find \cite [title] [boekplan::match(title:Layouts)]; Nor would adding the criterium \TEXcode {and year:2011} be of any help. The solution is \startbuffer \cite [authoryear] [boekplan::match(author:Hagen and author:Hoekwater and title:fonts)] \stopbuffer \cindex{cite} \tindex{::} \typeTEXbuffer \getbuffer Note that using \TEXcode {match(title:fonts)} alone would also work, that is until another reference work containing the word \quote {fonts} in its title gets added to the dataset! \startfootnote Multiple hits would have occurred in the examples above containing \TEXcode {title:lua} had only one dataset been used in the typesetting of the present manual. \stopfootnote Thus, whereas it might appear that the match mechanism be a more robust way of identifying dataset entries then short cite \Index {tag}s, incomplete search queries might return unwanted, excess matches. It is quite common in real bibliography databases for some author or authors to appear in many different references published in the same year, perhaps buried in a longer list of authors, so some care has to be taken to uniquely identify the desired work. Of course, this feature can also be a good shorthand as well to select several different matching works when that is the desired result. \stopaside % This only begins to touch on the search mechanism. % This section needs to be expanded. \stopsection \startsection[title={Page index, interaction, and registers},reference=sec:index] Each citation in the text not only marks the dataset entry for inclusion in the bibliography list but also records the page number on which the citation occurs. Each named list rendering can be instructed to include these pages just like an index. \startbuffer \setupbtxrendering [default] [pagestate=start] \stopbuffer \cindex{setupbtxrendering} \typeTEXbuffer The result can be observed in the \about [ch:biblio] on \at {page} [ch:biblio]. If interaction is active (\cindex {setupinteraction}\TEXcode {\setupinteraction[state=start]}), then these page numbers will be \Index {hyperlink}s back to the citations. If \TEXcode {numbering=yes}, then the numbered bibliography entries will also contain \Index {hyperlink}s back to the first occurrence in the text where the entry is cited (which is the same as the first page indexed). Some styles, such as \index {style+APA}\TEXcode {apa}, will have other \Index {hyperlink}s. The author list including the year will be active just like the numbers above (an \TEXcode {authoryear} list is usually not numbered). Furthermore, any doi or url that is included in the entry will be a \Index {hyperlink} to the external resource. Finally, all titles will contain \Index {hyperlink}s to the local downloaded file of the cited work if this exists and was specified (using the data field \TEXcode {file={},}). In addition to the index of pages of citations in the text associated with each entry in the bibliography list, one has the possibility of adding bibliography items to any standard index list. This can be illustrated through the creation of a list of authors or names: \startbuffer \defineregister [indexofauthors] \definebtxregister [authors] [field=author, register=indexofauthors, method=always, dataset=default, alternative=invertedshort] \stopbuffer \cindex{defineregister} \cindex{definebtxregister} \typeTEXbuffer placed in the preamble of the document and to be followed later, typically towards the end of the document, by \cindex{placeregister} \startTEX \startchapter[title=Index of Names] \placeregister[indexofauthors][compress=yes] \stopchapter \stopTEX as can be see in the present manual on \at {page} [ch:indexofauthors]. \cindex {definebtxregister} \showsetup[definebtxregister] \cindex {setupbtxregister} \showsetup[setupbtxregister] Any field can be indexed, as desired, for example \TEXcode {field=title}. One particularly useful field is \TEXcode {keywords={}}: a semi|-|colon separated list of keywords will be split into individual index entries for each cited work. The handling of fields to be interpreted as names (as in \TEXcode {author}) or as keywords (split into fields separated by semi|-|colons), etc. depends on the specification and is declared in a lua file associated with the specification definition file. This will be described in the next chapter. \stopsection \startsection [title=Summary and explanation of the \TEXcode {\cite} mechanism] As the list of cited references is being built in memory, each used dataset entry is flagged. As the list gets placed, either partially or fully, eventual conflits in \TEXcode {short} and in \TEXcode {authoryear} tags are resolved through an assignment of suffixes. These are then fed|-|back to the citation references. A dataset can have multiple renderings and multiple datasets and renderings can be grouped. The many citation variants can be freely used together and this may or may not make coherent sense. For example, an \TEXcode {authoryear} sorted list is assigned numbers that are available for use as numbered citation references, but these numbers will follow the order of the list and not the order of citations. Conversely, a list that is sorted in the order of citations will still have \TEXcode {authoryear} and \TEXcode {short} citation tags, but these will be of less use for the reader in this case than the \TEXcode {authornum} variant. With such flexibility comes complication. \stopsection \stopchapter \stopcomponent