1\environment publicationsstyle
2
3\startcomponent publicationscitations
4
5\startchapter
6 [title=Citations,
7 reference=ch:cite]
8
9The \index {styleAPA}APA Style Guide as well as good practice demand that
10\emphasis {all} references appearing in the bibliography be cited at least once
11in the text (and, of course, all citations must have a corresponding
12bibliographical reference). Other publishing styles, textbooks in particular,
13might additionally include lists of general references for \quote {further
14reading} (and these lists might sometimes be split into sections according to
15subject). An author may, in contrast, choose not to interrupt a text with many
16citations, nevertheless, including a list of references. Furthermore, one might
17refer in the text to certain works that need not necessarily be accompanied by a
18full bibliography listing (for example, \Name {Darwin} {C.}s \emph {Origin}).
19\startfootnote \textcite[entry] [default::Darwin1859] \stopfootnote Thus, a
20system providing tools to handle bibliographies needs to be flexible.
21
22A good, general reference on bibliography practice (in the English language),
23independent of any particular specification, can be found in \cite [title]
24[default::vanLeunen1992] \cite [default::vanLeunen1992]. Note that rules and
25traditions may differ slightly in other languages and cultures.
26
27The examples of bibliography listings of the previous chapter were simplified by
28the fact that the entire bibliographical dataset was rendered. In practice, the
29same dataset source(s) could be used over many documents, and the dataset might
30contain many more references than are used in any one document. That is, the data
31source might be more complete than the final rendered bibliography list or lists.
32The mechanism of citation allows you to select references from the dataset(s) to
33build the list rendering as well as to place a indicator of the reference (or
34not) in the text of the document corresponding to a list entry (a publication).
35These citation renderings can be of many forms.
36
37A citation is normally pretty short as its main purpose is to refer uniquely to a
38more detailed description. But, there are several ways to refer, which is why the
39citation subsystem is configurable and extensible. Just look at the following
40commands:
41
42\cindex{cite}
43\tindex{::}
44
45\starttabulate
46\NC \TEXcode{\cite[num][article]} \NC \cite[num] [article] \NC \NR
47\NC \TEXcode{\cite[textnum][article]} \NC \cite[textnum] [article] \NC \NR
48\NC \TEXcode{\cite[authornum][article]} \NC \cite[authornum] [article] \NC \NR
49\NC \TEXcode{\cite[authoryear][article]} \NC \cite[authoryear] [article] \NC \NR
50\NC \TEXcode{\cite[authoryears][article]} \NC \cite[authoryears][article] \NC \NR
51\NC \TEXcode{\cite[short][article]} \NC \cite[short] [article] \NC \NR
52\NC \TEXcode{\cite[tag][article]} \NC \cite[tag] [article] \NC \NR
53\NC \TEXcode{\cite[index][article]} \NC \cite[index] [article] \NC \NR
54\NC \TEXcode{\cite[category][article]} \NC \cite[category] [article] \NC \NR
55\NC \TEXcode{\cite[author][article]} \NC \cite[author] [article] \NC \NR
56\NC \TEXcode{\cite[year][article]} \NC \cite[year] [article] \NC \NR
57\NC \TEXcode{\cite[title][article]} \NC \cite[title] [article] \NC \NR
58\NC \TEXcode{\cite[keywords][article]} \NC \cite[keywords] [article] \NC \NR
59\NC \TEXcode{\cite[none][article]} \NC \cite[none] [article] \NC \NR
60\NC \TEXcode{\cite[X]} \NC \cite[X] \NC \NR
61\NC \TEXcode{\cite[]} \NC \cite[] \NC \NR
62\NC \TEXcode{\cite[template::Chen:1988:IPP]} \NC \cite[template::Chen:1988:IPP] \NC \NR
63\NC \TEXcode{\cite[entry][article]} \NC \cite[entry] [article] \NC \NR
64\stoptabulate
65
66The first argument is optional and if omitted, the default citation rendering
67(for example, \TEXcode {num} or \TEXcode {authoryear}, depending on the
68specification) will be selected.
69
70\startbuffer
71\cite[article]
72\stopbuffer
73\cindex{cite}
74
75\typeTEXbuffer \getbuffer
76
77\startaside
78The default citation alternative is defined via \cindex {setupbtx}
79
80\startTEX
81\setupbtx[alternative=num]
82\stopTEX
83
84However, this is not used as it is overridden by the specification, even the
85\TEXcode {default} specification:
86
87\startTEX
88\setupbtx[default:cite][alternative=num]
89\setupbtx [apa:cite][alternative=authoryear]
90\stopTEX
91
92These examples introduce the concept of \Index {namespace}s that is extensively
93used in the bibliography subsystem. The \TEXcode {cite} namespace will inherit
94from the root namespace; similarly, the \TEXcode {default} specification will
95inherit elements from the \TEXcode {cite} namespace, but will be distinct from
96the \TEXcode {apa} specifications \TEXcode {cite} namespace, and so forth.
97Normally, we need not to worry about this as it is handled through the loading of
98the specification.
99\stopaside
100
101\cindex {cite}
102\showsetup[cite]
103
104The \Cindex{citation} command is synonymous to \Cindex{cite}.
105
106\cindex {citation}
107\showsetup[citation]
108
109\showsetup[citation:alternative]
110\showsetup[citation:direct]
111
112\startaside
113Note that the \MKII\ module based on \Tindex {bibtex} allowed the use of curly
114brackets enclosing the \Index {tag} (for reasons of backward compatibility with
115traditional \LATEX\ practice). A sideeffect made this a bit picky about spaces
116between its arguments, the first of which is optional. We have chosen to remove
117this restriction through the use of standard \CONTEXT\ syntax using square
118brackets (reserving curly brackets to usually be used to enclose text that is to
119be typeset).
120
121The system will tolerate the \Index {depreciated} syntax \cindex {cite}\TEXcode
122{\cite{tag}}, but this practice is to be strongly discouraged and cannot be mixed
123with any other options.
124\stopaside
125
126The most commonly used citation variants (or alternatives) are \TEXcode {num} and
127\TEXcode {authoryear} introduced above. The first is typically employed in
128conjunction with a numbered bibliography list, usually sorted in the citation
129order in the text; the second is typically used in conjunction with a
130bibliography list sorted by author and year of publication.
131
132Other citation variants may be quite useful, even when used in the context of the
133above standard schemes. One such example would be \Cindex {cite}\TEXcode
134{[title][tag]} that can be used to include the title of the work in the running
135text (as can be seen earlier in \in {section} [sec:styles]; another one is
136\cindex {cite}\TEXcode {\cite[year][tag]} that can be used to include the
137publication date and \cindex {cite}\TEXcode {\cite[author][tag]} can be used to
138extract the authors names. These are examples of a general rule where \cindex
139{cite}\TEXcode {\cite[field][tag]} will return the contents of the given field
140for an entry, if the entry contains such a field.
141
142The variants \TEXcode {textnum} and \TEXcode {authoryears} are intended to be
143used in the running text when the reference becomes part of the syntax of the
144sentence: typically, they will not be setoff by parenthesis, for example.
145
146\startaside
147The name \TEXcode {authoryears} (with an \quote{s}) is a shorthand that was used
148in \MKII. Whereas its name is not immediately obvious at first view, in practice
149it is a quite convenient variant of \TEXcode {authoryear} that differs only in
150the style of punctuation, thus its place in a sentence structure.
151\stopaside
152
153Notice that in the example \TEXcode{\cite[template::Chen:1988:IPP]} shown above,
154the \TEXcode {tag} was prefixed with an alternate dataset name (\tindex
155{::}\TEXcode {template::}) rather than to the default \TEXcode {dataset=example}
156that was specified in the \Cindex {setupbtx} command earlier. The reason behind
157the doublecolon syntax should be made obvious here (where the \Index {tag}
158itself uses single colons).
159
160In the last of the examples shown above, \TEXcode{\cite[entry][article]}, the
161full rendered bibliographic entry gets placed.
162
163Unless the placed rendering uses \TEXcode {method=dataset}, only publications
164that are explicitly cited will end up in the lists. You can force a citation into
165a list using \Cindex {usecitation}, for example:
166
167\cindex{usecitation}
168
169\startTEX
170\usecitation[patent]
171\stopTEX
172
173This command has two synonyms: \Cindex {nocite} and \Cindex {nocitation} so you
174can choose whatever fits you best.
175
176\cindex {nocite}
177\showsetup[nocite]
178
179\cindex {nocitation}
180\showsetup[nocitation]
181
182\cindex {usecitation}
183\showsetup[usecitation]
184
185The purpose and utility of these commands (and their synonyms) is not only to
186draw a citation from the dataset for inclusion in the bibliography, but also to
187mark the place in the text where the citation is relevant. Normally, one might
188claim that this should be done through one of the forms of the \Cindex {cite} (or
189\Cindex {citation}) command, as all references appearing in the bibliography are
190to be cited at least once in the text. However, even if one does not disagree
191with this statement, one might still wish attach the citation to the reference in
192the text of a \Index {floating object} such as a table or a figure, thus
193establishing a proper order in the numbering since the explicit citation
194rendering might occur within the table or the figure caption that might get
195placed on a much later page. Consider the following schematic illustration:
196
197\cindex{nocite}
198\cindex{cite}
199
200\startTEX
201(see \nocite [MyReference]\in {table} [tab:mytable]).
202
203\startplacetable[reference=tab:mytable]
204 \unknown\ \cite[MyReference]
205\stopplacetable
206\stopTEX
207
208The citation rendering and the bibliographic list rendering are intimately
209coupled reciprocally and cannot be dissociated. This coupling can be through the
210reference number for example, but unnumbered reference lists also contain
211interacting hyperlinks. A failure to take into account this interdependence can
212lead to fundamental misunderstandings in use.
213
214\startaside
215Both the citation and the list must be rendered. For example, a common error
216would be to omit (or commentout) the list rendering during the writing stage
217of a document. Such an error will cause the citations to fail to render properly.
218
219Whereas this might seem to be an unnecessary limitation, it results from a
220specific design choice and from the possibility of placing multiple renderings
221freely, anywhere in a document. It is preferable not to render citations at all
222than to render these citations possibly incorrectly.
223\stopaside
224
225\startsection[title=Combining citations]
226
227\startbuffer
228\cite[num][article,book,booklet]
229\stopbuffer
230
231A single citation might refer to several sources, obtained through the use of a
232comma separated list of \Index{tag}s, for example: \getbuffer
233
234\cindex{cite}
235
236\typeTEXbuffer
237
238A comma separated list of three (or more) consecutive numbers will get collapsed
239or compressed into a range of numbers (if possible).
240
241\cindex {cite} The order in which the citation \Index {tag}s appear in the list
242may or may not be important, depending upon the citation variant and on the style
243specification. Consider the following examples:
244
245\startbuffer
246\cite[num] [article,book]
247\cite[textnum] [article,book]
248\cite[authoryear] [article,book]
249\cite[authoryears][article,book]
250\cite[short] [article,book]
251\cite[author] [article,book]
252\cite[year] [article,book]
253\cite[title] [article,book]
254\stopbuffer
255
256\typeTEXbuffer
257
258This gives:
259
260\cindex{cite}
261\startlines \getbuffer \stoplines
262
263Now we swap the order:
264
265\startbuffer
266\cite[num] [book,article]
267\cite[textnum] [book,article]
268\cite[authoryear] [book,article]
269\cite[authoryears][book,article]
270\cite[short] [book,article]
271\cite[author] [book,article]
272\cite[year] [book,article]
273\cite[title] [book,article]
274\stopbuffer
275
276\typeTEXbuffer
277
278and get:
279
280\startlines \getbuffer \stoplines
281
282Note that the numbered citation reference is always rendered in numerical order,
283where the numbers correspond to the order in which the entries appear in the
284bibliography list. This order depends on the \Index {sorting} of the list
285rendering (this sorting may be, in some styles, in the order in which the
286references are cited) and is controlled by the \TEXcode {[list]} \TEXcode
287{sorttype} parameter. In the \index {styleAPA}APA style, presently active, the
288citations are always sorted according to author and year. Thus, \quotation
289{BookAuthorLastname} appears before \quotation {Last} in our example here,
290regardless of the order in which the references appear in the \Cindex {cite}
291command (i.e. either \TEXcode {\cite[article,book]} or \TEXcode
292{\cite[book,article]}).
293
294The user can control the state of sorting of the \cindex{cite}\TEXcode {cite}
295variants through the parameter \TEXcode {sorttype=normal}; other choices are
296\TEXcode {reverse} and \TEXcode {none}:
297
298\startTEX
299\setupbtx[aps:cite:num][sorttype=none]
300\stopTEX
301
302\startsubsubject [title=Single list item containing multiple publication entries]
303
304Some bibliography styles admit the combination of several bibliographical sources
305into a single list item having a unique reference number. The combination of
306multiple bibliographic entries into as single bibliography list item is more
307compact and this practice is often encountered in short \quote {letter}type
308journal articles. (Note, however, that entries combined as such do not make any
309sense in an authoryear scheme such as \index {styleAPA}APA.)
310
311One can combine \Index {tag}s using the addition operator symbol (\TEXcode {}),
312best illustrated though an example:
313
314\startbuffer
315\METAFUN\ began as an expression of love and appreciation for \METAPOST.
316\citation [num] [tugboat::Berdnikov:TB212129Hobby:TB212131]
317
318\definebtxrendering[tugboat][aps][dataset=tugboat,group=examples]
319\placebtxrendering [tugboat][criterium=section]
320\stopbuffer
321
322\cindex{citation}
323\cindex{definebtxrendering}
324\cindex{placebtxrendering}
325\tindex{::}
326
327\typeTEXbuffer
328
329\getbuffer
330
331Combined entries are joined using a separator that can be specified, as in:
332
333\startbuffer
334\setupbtxrendering[tugboat][separator={\break}]
335\stopbuffer
336
337\cindex{setupbtxrendering}
338\tindex{separator}
339
340\typeTEXbuffer
341
342or suppressed (using \tindex {separator}\TEXcode {separator=,}); By default,
343\cindex {removepunctuation}\TEXcode {separator={\removepunctuation;\space}}.
344
345Dataset entries that are combined cannot also appear apart (nor does this really
346make any logical sense). All of the following:
347
348\startbuffer
349\cite[num][tugboat::Berdnikov:TB212129]
350\cite[num][tugboat::Berdnikov:TB212129,Hobby:TB212131]
351\cite[num][tugboat::Hobby:TB212131]
352\stopbuffer
353\cindex{cite}
354\tindex{::}
355
356\typeTEXbuffer \getbuffer
357
358will point to the combined reference (as they should). However, beware that
359attempting to include any of these references in a \emphasis {different} combined
360list item is undefined, meaning unsupported.
361
362Combining list entries is another instance showing that citations and the
363rendered bibliography list interact and cannot be separated.
364
365\stopsubsubject
366
367\stopsection
368
369\startsection[title=Additional text]
370
371\startsubsubject [title=Additional text in a citation reference]
372
373Sometimes one would like to include additional text in a citation, for example
374a specific commentary or page number reference.
375
376\startbuffer
377\cite[righttext={ p.\nbsp xx}][article]
378\stopbuffer
379
380\cindex{cite}
381
382\typeTEXbuffer
383
384yielding:
385
386\getbuffer
387
388The additional text can be either before (\TEXcode {lefttext=}) or after
389(\TEXcode {righttext=}) \startfootnote The \MKII\ bib module used the keyword
390\TEXcode {extra=} in the place of \TEXcode {righttext=}. We chose not to support
391this as a synonym as the name is ambiguous. Furthermore, we seek to limit the
392number of keywords used in \CONTEXT. \stopfootnote each citation entry and are
393not to be confused with the delimiters \TEXcode {left={(},} and \TEXcode
394{right={)},} used to surround the entire citation. The difference becomes
395important when referencing multiple citations.
396
397The following examples further illustrate the syntax:
398
399\startbuffer
400\cite[lefttext={See },righttext={ p.\nbsp yy}][book]
401\stopbuffer
402
403\typeTEXbuffer \getbuffer
404
405\startbuffer
406\cite[alternative=authoryears,righttext={ p.\nbsp xx}][article]
407
408\cite[alternative=authornum,righttext={ p.\nbsp xx}][article]
409\stopbuffer
410
411\typeTEXbuffer \getbuffer
412
413\startbuffer
414\cite[alternative=num,righttext={{ p.\nbsp xx},{ p.\nbsp yy}}]
415 [article,book,booklet]
416\stopbuffer
417
418\cindex{cite}
419
420\typeTEXbuffer \getbuffer
421
422\startbuffer
423\cite[lefttext={In the article: },righttext={.}][article]
424\stopbuffer
425
426\cindex{cite}
427
428\typeTEXbuffer \getbuffer
429
430\startbuffer
431\cite[lefttext={{In the article: },{in the book: }},alternative=title]
432 [article,book]
433\stopbuffer
434
435\cindex{cite}
436
437\typeTEXbuffer \getbuffer
438
439\startbuffer
440\cite[righttext={{ p.\nbsp xx},}][article,book]
441\stopbuffer
442
443\cindex{cite} \typeTEXbuffer \getbuffer
444
445Because \CONTEXT\ does not allow mixing keyvalue pair lists with single value
446keys, the keyword \TEXcode {alternative=} must be used, if needed, as shown in
447the examples above.
448
449Note that a double curlybracket (\TEXcode {{{}}}) also needs to be used when
450the text is to contain a comma.
451
452\stopsubsubject
453
454\startsubsubject [title=Additional text in a list entry]
455
456Additional text such as notes and page numbers can also get placed with the entry
457in the bibliography list. Of course, the bibliography data entry can contain a
458\TEXcode {note=} field that may or may not get rendered, but often is, according
459to the style specification.
460
461It is also possible to specify notes or page references to be rendered \TEXcode
462{before} or \TEXcode {after} a bibliography entry through the citation call.
463
464\startbuffer
465\cite
466 [alternative=num,
467 before={{Introducing MetaPost: },},
468 after={,{ See, also, the references therein, p.\nbsp 58.}}]
469 [tugboat::Hobby:TB104505,Hobby:TB22146]
470\blank
471\placebtxrendering [tugboat][criterium=section]
472\stopbuffer
473
474\cindex{cite}
475\cindex{placebtxrendering}
476\tindex{::}
477
478\typeTEXbuffer \getbuffer
479
480Clearly, such additional text can be added to each entry only once, so the first
481such \Cindex {cite} call wins.
482
483\stopsubsubject
484
485\stopsection
486
487\startsection[title=Placing a single citation]
488
489Sometimes, one would like to place a single citation somewhere in the text
490without necessarily adding it to a bibliography list. Take, for example,
491
492\startbuffer
493\placecitation[tugboat::Mahajan:TB31188]
494\stopbuffer
495
496\getbuffer
497
498obtained by using
499
500\cindex{placecitation}
501\tindex{::}
502
503\typeTEXbuffer
504
505Note that \Cindex {placecitation}\TEXcode {[tag]} is a synonym for \Cindex
506{citation}\TEXcode {[entry][tag]} (that was seen earlier).
507
508\showsetup[placecitation]
509
510As for other citation reference, this will fail if a bibliography list rendering
511is not placed somewhere in the document so lets do that here:
512
513\startbuffer
514\placebtxrendering[tugboat][criterium=section]
515\stopbuffer
516
517\cindex{placebtxrendering}
518
519\typeTEXbuffer \getbuffer
520
521Whereas this might seem redundant above (placing the citation entry as well as
522its list rendering), this will only exceptionally be the case (as in this highly
523artificial example of this manual); Indeed, all cited work (such as \cite
524[textnum] [tugboat::Mahajan:TB31188], above) will logically always be placed in
525a list of references.
526
527The placement of a single citation brings to light a subtle point: The \TEXcode
528{specification} that is used by citations is that set in the root namespace
529(through \Cindex {setupbtx}\TEXcode {[specification=apa]} or possibly through
530\Cindex {usebtxdefinitions}\TEXcode {[apa]}. This is \emphasis {not} necessarily
531the same as that of the rendering (if a different rendering specification is
532declared). Note that the named rendering used above (\TEXcode {[tugboat]}) was
533not declared a child of the rendering named \TEXcode {[aps]}, though the \TEXcode
534{specification=apa} is active. Thus, the style of the citations can be made to
535differ from the style of their bibliography list, as here, but this is not really
536a very good practice.
537
538\stopsection
539
540\startsection[title=Placing citations as footnotes]
541
542A \Cindex {placecitation} command can occur inside a footnote or other \Index
543{floating object} such as a figure or table caption. No specification or style
544that places its bibliography list renderings as footnotes has been implemented
545yet.
546
547
548
549\stopsection
550
551\startsection[title=Searching]
552
553Finding the right \Index {tag} in a database can be a pain. In particular,
554datasets having their origin in multiple source files may contain conflicting
555\Index {tag}s, though duplicate \Index {tag}s get suffixed automatically so this
556should not be a real problem.
557
558On the other hand, asking for a \Index {wildcard} also makes no sense.
559\startfootnote Note that \cindex {nocite}\TEXcode {\nocite{*}} is a valid
560\LATEX\BIBTEX\ practice that is used to include all entries of a \Tindex {.bib}
561file in the final bibliography. This result can be obtained in \CONTEXT\ through
562the \TEXcode {method=dataset} list rendering parameter. Alternately, one can use
563the syntax \cindex {cite}\TEXcode {\cite[match(*:*)]} which is a shorthand to
564match all values of all fields. \stopfootnote Nevertheless, we provide a powerful
565mechanism for matching a query. Keep in mind that a \Index {tag} is used as a
566quick lookup in a hashed table whereas a search will look through the entire
567dataset. If processing speed is critical, one should use the cite \Index {tag}
568lookup; in practice, even on a big book project employing a very large dataset,
569the search is not a penalty.
570
571Lets look in more detail at the \Cindex {cite} command. In order to distinguish
572efficiently between a normal reference and a more clever one, we use the \TEXcode
573{match()} function:
574
575\tindex{::}
576\startTEX
577match(query)
578dataset::match(query)
579dataset :: match ( query )
580\stopTEX
581
582The handler is rather tolerant for spaces (as well as capitalization) which is
583handy if you have long queries that wrap around in the source code. Of course the
584\tindex {::}\TEXcode {dataset::} prefix is optional in which case the current
585dataset is taken. Such match queries can be mixed in a multiple reference
586citation indifferently with hashed cite \Index {tag}s so the system is really
587flexible.
588
589\blank
590
591To demonstrate the use a search query, we load a small bibliographic database:
592
593\startbuffer
594\usebtxdataset[boekplan][boekplan.bib]
595\stopbuffer
596
597\cindex{usebtxdataset}
598
599\typeTEXbuffer
600
601\getbuffer
602
603We could switch to this base using:
604
605\cindex{setupbtx}
606\startTEX
607\setupbtx[dataset=boekplan]
608\stopTEX
609
610but instead we shall use a prefix as seen previously. Consider the following:
611
612\startbuffer
613everything that you might want to know about layouts
614\cite[boekplan::match(author:Egger)]
615\stopbuffer
616
617\cindex{cite}
618\tindex{::}
619
620\typeTEXbuffer
621
622We will get: \quotation {\inlinebuffer}. Of course this assumes that we also
623typeset a list of references somewhere in our document, so lets do that here:
624
625\startbuffer
626\definebtxrendering[boekplan][apa][dataset=boekplan,group=examples]
627\placebtxrendering [boekplan][criterium=chapter]
628\stopbuffer
629
630\cindex{definebtxrendering}
631\cindex{placebtxrendering}
632
633\typeTEXbuffer \getbuffer
634
635\startbuffer
636\cite[authoryears][ match(title:Lua)]\\
637\cite[authoryears][default:: match(title:Lua)]\\
638\cite[authoryears][boekplan::match(title:Lua)]
639\stopbuffer
640
641\cindex{cite}
642\tindex{::}
643
644\typeTEXbuffer \getbuffer
645
646Notice that no match is found in the \quote {current} dataset (\TEXcode {example}).
647
648A query eventually becomes a \LUA\ expression so you can use helpers to achieve
649your goal. As a convenience there are some shortcuts to access fields. The
650following examples demonstrate this:
651
652\startbuffer
653\cite
654 [authoryears]
655 [boekplan::match(author:hagen and year:20102011)]\\
656\cite
657 [authoryears]
658 [boekplan::match(author:{Willi Egger})]\\
659\cite
660 [authoryears]
661 [boekplan::match(author:Hans and (tonumber(field:year) or 0) > 2011)]
662\stopbuffer
663
664\cindex{cite}
665\tindex{::}
666
667\typeTEXbuffer \getbuffer
668
669You can use grouping braces when spaces are involved. Ranges (of numbers) are
670recognized. Of course, you can use other characters that the basic alphabet.
671
672\startbuffer
673\cite[authoryears][tugboat::match(author:{Bogusław Jackowski})]\\
674\stopbuffer
675
676\cindex{cite}
677\tindex{::}
678
679\typeTEXbuffer \getbuffer
680
681This demonstrates further the interest in converting classical \TEX\ accent
682sequences into proper \UTF\ characters. The citations found above \bold{must}
683correspond to some bibliography list entries, so we will place this list here:
684
685\startbuffer
686\placebtxrendering [tugboat][criterium=section]
687\stopbuffer
688
689\cindex{placebtxrendering}
690
691\typeTEXbuffer \getbuffer
692
693String lookups are partial and case insensitive.
694
695\startbuffer
696\cite [boekplan::match(author:e)]\\
697\cite [boekplan::match(author:h)]
698\stopbuffer
699
700\cindex{cite}
701\tindex{::}
702
703\typeTEXbuffer
704
705so one must take care in formulating cite queries as both lookups above will
706get all five entries: \inlinebuffer, whereas
707
708\startbuffer
709\cite [boekplan::match(author:eg)]\\
710\cite [boekplan::match(author:e*r)]
711\stopbuffer
712
713\cindex{cite}
714\tindex{::}
715
716\typeTEXbuffer
717
718finds \inlinebuffer. As the match compares the entire author string, and not
719just each author, it also finds [Hag]en Br[aslau] as well as [Ho]ekwater[
720Hagen].
721
722
723
724
725
726
727
728
729
730
731
732Note also that the order of the match criteria is not significant.
733
734\startaside
735The search mechanism is very powerful. However, a \bold {major \Index{pitfall}}
736or risk comes from the possibility to easily underspecify the match criteria.
737For example, \TEXcode {match(author:Hagen and author:Hoekwater)} will find \cite
738[title] [boekplan::match(title:Fonts)], but it will also find \cite [title]
739[boekplan::match(title:Layouts)]; Nor would adding the criterium \TEXcode {and
740year:2011} be of any help. The solution is
741
742\startbuffer
743\cite
744 [authoryear]
745 [boekplan::match(author:Hagen and author:Hoekwater and title:fonts)]
746\stopbuffer
747
748\cindex{cite}
749\tindex{::}
750
751\typeTEXbuffer \getbuffer
752
753Note that using \TEXcode {match(title:fonts)} alone would also work, that is
754until another reference work containing the word \quote {fonts} in its title gets
755added to the dataset! \startfootnote Multiple hits would have occurred in the
756examples above containing \TEXcode {title:lua} had only one dataset been used in
757the typesetting of the present manual. \stopfootnote Thus, whereas it might
758appear that the match mechanism be a more robust way of identifying dataset
759entries then short cite \Index {tag}s, incomplete search queries might return
760unwanted, excess matches.
761
762It is quite common in real bibliography databases for some author or authors to
763appear in many different references published in the same year, perhaps buried in
764a longer list of authors, so some care has to be taken to uniquely identify the
765desired work. Of course, this feature can also be a good shorthand as well to
766select several different matching works when that is the desired result.
767\stopaside
768
769
770
771
772\stopsection
773
774\startsection[title={Page index, interaction, and registers},reference=sec:index]
775
776Each citation in the text not only marks the dataset entry for inclusion in the
777bibliography list but also records the page number on which the citation occurs.
778Each named list rendering can be instructed to include these pages just like an
779index.
780
781\startbuffer
782\setupbtxrendering
783 [default]
784 [pagestate=start]
785\stopbuffer
786
787\cindex{setupbtxrendering}
788
789\typeTEXbuffer
790
791The result can be observed in the \about [ch:biblio] on \at {page} [ch:biblio].
792If interaction is active (\cindex {setupinteraction}\TEXcode
793{\setupinteraction[state=start]}), then these page numbers will be \Index
794{hyperlink}s back to the citations. If \TEXcode {numbering=yes}, then the
795numbered bibliography entries will also contain \Index {hyperlink}s back to the
796first occurrence in the text where the entry is cited (which is the same as the
797first page indexed).
798
799Some styles, such as \index {styleAPA}\TEXcode {apa}, will have other \Index
800{hyperlink}s. The author list including the year will be active just like the
801numbers above (an \TEXcode {authoryear} list is usually not numbered).
802Furthermore, any doi or url that is included in the entry will be a \Index
803{hyperlink} to the external resource. Finally, all titles will contain \Index
804{hyperlink}s to the local downloaded file of the cited work if this exists and
805was specified (using the data field \TEXcode {file={},}).
806
807In addition to the index of pages of citations in the text associated with each
808entry in the bibliography list, one has the possibility of adding bibliography
809items to any standard index list. This can be illustrated through the creation of
810a list of authors or names:
811
812\startbuffer
813\defineregister
814 [indexofauthors]
815
816\definebtxregister
817 [authors]
818 [field=author,
819 register=indexofauthors,
820 method=always,
821 dataset=default,
822 alternative=invertedshort]
823\stopbuffer
824
825\cindex{defineregister}
826\cindex{definebtxregister}
827
828\typeTEXbuffer
829
830placed in the preamble of the document and to be followed later, typically
831towards the end of the document, by
832
833\cindex{placeregister}
834
835\startTEX
836\startchapter[title=Index of Names]
837 \placeregister[indexofauthors][compress=yes]
838\stopchapter
839\stopTEX
840
841as can be see in the present manual on \at {page} [ch:indexofauthors].
842
843\cindex {definebtxregister}
844\showsetup[definebtxregister]
845
846\cindex {setupbtxregister}
847\showsetup[setupbtxregister]
848
849Any field can be indexed, as desired, for example \TEXcode {field=title}. One
850particularly useful field is \TEXcode {keywords={}}: a semicolon separated
851list of keywords will be split into individual index entries for each cited work.
852
853The handling of fields to be interpreted as names (as in \TEXcode {author}) or as
854keywords (split into fields separated by semicolons), etc. depends on the
855specification and is declared in a lua file associated with the specification
856definition file. This will be described in the next chapter.
857
858\stopsection
859
860\startsection [title=Summary and explanation of the \TEXcode {\cite} mechanism]
861
862As the list of cited references is being built in memory, each used dataset entry
863is flagged. As the list gets placed, either partially or fully, eventual conflits
864in \TEXcode {short} and in \TEXcode {authoryear} tags are resolved through an
865assignment of suffixes. These are then fedback to the citation references.
866
867A dataset can have multiple renderings and multiple datasets and renderings can
868be grouped. The many citation variants can be freely used together and this may
869or may not make coherent sense. For example, an \TEXcode {authoryear} sorted list
870is assigned numbers that are available for use as numbered citation references,
871but these numbers will follow the order of the list and not the order of
872citations. Conversely, a list that is sorted in the order of citations will still
873have \TEXcode {authoryear} and \TEXcode {short} citation tags, but these will be
874of less use for the reader in this case than the \TEXcode {authornum} variant.
875With such flexibility comes complication.
876
877\stopsection
878
879\stopchapter
880
881\stopcomponent
882 |