diff options
Diffstat (limited to 'doc/context/sources/general/manuals/publications/publications-citations.tex')
| -rw-r--r-- | doc/context/sources/general/manuals/publications/publications-citations.tex | 881 |
1 files changed, 881 insertions, 0 deletions
diff --git a/doc/context/sources/general/manuals/publications/publications-citations.tex b/doc/context/sources/general/manuals/publications/publications-citations.tex new file mode 100644 index 000000000..aabdd5328 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-citations.tex @@ -0,0 +1,881 @@ +\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 |