publications-rendering.tex /size: 20 Kb    last modification: 2020-07-01 14:35
1\environment publications-style
2
3\startcomponent publications-rendering
4
5\startchapter[title=Renderings,reference=ch:renderings]
6
7\startsection
8  [reference=sec:styles,
9   title={Generating lists of publications}]
10
11A list of publications can be rendered at any place in the document, and multiple
12renderings can appear under certain limitations (according to \Index {scope}).
13The specification introduced previously defines the style of the rendering as
14well as what data it will contain.
15
16If you want to see what publications are in the database, the easiest way is to
17ask for a complete list:
18
19\startbuffer
20\usebtxdataset            % illustrated again here
21  [example]               % although already loaded
22  [mkiv-publications.bib] % in the previous chapter
23
24\definebtxrendering
25  [example]               % named rendering
26  [apa]                   % parent namespace
27  [dataset=example,
28   group=examples]        % group will be presented later
29
30\placelistofpublications  % aka \placebtxrendering
31  [example]               % rendering defined above
32  [method=dataset]        % i.e. all entries
33\stopbuffer
34
35\cindex{definebtxrendering}
36\cindex{placelistofpublications}
37\cindex{placebtxrendering}
38
39\typeTEXbuffer
40
41The commands \Cindex {placelistofpublications} (that is just a synonym for
42\Cindex {placebtxrendering}) refer to a named rendering and accept a list of
43options (inherited from \Cindex {setupbtxrendering}). When applied to a named
44dataset (other than \TEXcode {default}), a named rendering needs to be associated
45through \Cindex {definebtxrendering} as is done here.
46
47Note that the define shown above explicitly inherits from a rendering named
48\TEXcode {apa} that was itself defined when loading the specification file.
49\startfootnote The rendering parent \index {style+APA}\TEXcode {[apa]} sets the
50parameters: \TEXcode {specification=apa,} \TEXcode {sorttype=authoryear,} and
51\TEXcode {numbering=no,} described below. It also sets various list parameters in
52a protected \TEXcode {apa} namespace to produce a \quote {hanging} bibliography
53list. \stopfootnote Had this inheritance not been specified, the new rendering
54would inherit default, minimal settings. This notion of inheritance will be
55further illustrated later.
56
57The bibliography list rendering of our example dataset, following the \index
58{style+APA}APA style, is:
59
60\getbuffer
61
62The rendering is a list whose appearance can be tuned, as any list in \CONTEXT.
63It is somewhat more complex to manage, though, because we can have not only many
64different standards but also many fields that can be set up. This means that
65there are several commands involved. As we saw demonstrated above, a rendering is
66defined and setup using the commands:
67
68\cindex{definebtxrendering}
69
70\showsetup{definebtxrendering}
71
72\cindex{setupbtxrendering}
73
74\showsetup{setupbtxrendering}
75
76A rendering is then placed using \Cindex {placebtxrendering}, a \CONTEXT\ command
77that accepts the same arguments as for its setup. Using \TEXcode
78{method=dataset}, as above, one renders the entire contents of the dataset.
79Normally, however, one would not use this \TEXcode {method} and place only a
80selection of entries that are to be used in the document, whereas the dataset may
81very well contain many other, unused references. The \TEXcode {method=global} or
82\TEXcode {method=local} option can be used to specify if this use is to be global
83for the entire document or else local to a structure element such as a part or a
84chapter.
85
86\cindex{placebtxrendering}
87
88\showsetup{placebtxrendering}
89
90\cindex{placelistofpublications}
91
92\showsetup{placelistofpublications}
93
94The rendering is a \TEXcode {list} and this reference list is numbered. These
95numbers can be displayed, or not, depending on the bibliography style
96specification through the use of the \index {numbering}\TEXcode {numbering=yes}
97or \TEXcode {no} parameter values. The \index {style+APA}APA style, illustrated
98above, normally does not number the bibliography list.
99
100The reference list is also \index {sorting}sorted, controlled by the parameter
101\TEXcode {sorttype}; here \TEXcode {sorttype=authoryear}, appropriate for the
102\index {style+APA}APA style, \Index {sorting} first by author list, then by
103publication year, then by title, finally by page. One can sort the list in many
104ways: for example \TEXcode {sorttype=index} will render the list in the order in
105which it was loaded into the dataset (see \in {table} [tab:sorttype] for an
106explanation of list sorting schemes).
107
108\startplacetable [location=force,
109  title={\TEXcode {sorttype=}},
110  reference=tab:sorttype]
111\index{sorting}
112\starttabulate [|Tp(5.5em)|p(.75\textwidth)|]
113\HL
114\NC default\\none\\cite\\list
115\NC render the list in the order in which it was built,
116    that is, in the order that references were selected from the dataset for
117    inclusion in the list. \NC \NR
118\HL
119\NC dataset\\index
120\NC sort the list according to the dataset index, that is, in the order in that
121    references were added to the dataset. \NC \NR
122\HL
123\NC reference
124\NC sort the list in alphabetical order of the citation \Index{tag}s of the
125    dataset. Note that all entries missing tags get assigned the dataset index as
126    their tag. \NC \NR
127\HL
128\NC key
129\NC sort the list in alphabetical order of the entry field \TEXcode {key}
130    (traditionally used in \BIBTEX\ as an alternate sorting key). Falls back on
131    the dataset index if no such field is present. \NC \NR
132\HL
133\NC short
134\NC sort the list in alphabetical order of the short tag (first three letters
135    of the author name or first letter of the first three authors followed by
136    the last two digits of the year). \NC \NR
137\HL
138\NC authoryear
139\NC sort the list in alphabetical order of the authors (or editors or publisher),
140    then by publication year, then by title (or by journal and volume) and
141    finally by page. \NC \NR
142\stoptabulate
143\stopplacetable
144
145As a concrete example, the rendering named \TEXcode {example} above inherits from
146the rendering instance named \TEXcode {apa} that is defined in the specification
147file as:
148
149\cindex{definebtxrendering}
150
151\startTEX
152\definebtxrendering
153  [apa]
154  [specification=apa,
155   sorttype=authoryear,
156   numbering=no]
157\stopTEX
158
159\startaside
160A more subtle characteristic of renderings is that one generally would not want a
161bibliography list to appear redundantly in a document as that would be confusing,
162unless of course it is desired that elements of the list reappear in later lists,
163for example when placing partial bibliographies at the end of each chapter and a
164complete bibliography list at the end of a book. One must specify \TEXcode
165{repeat=yes} in order to get multiple renderings of a bibliography list;
166otherwise, as they appear, entries get marked as placed and will be inhibited
167from being placed again elsewhere.
168\stopaside
169
170All renderings of bibliography lists such as the one shown earlier in this
171section also depend on a set of general list parameters that apply to each
172individual entry (a cited publication), as for any list item in \CONTEXT. These
173can be adjusted through the command \Cindex {setupbtxlist} (further described in
174\in {section} [sec:list], below). As an example, the \TEXcode {apa} specification
175file includes:
176
177\cindex{setupbtxlist}
178
179\startTEX
180\setupbtxlist
181  [apa]
182  [alternative=paragraph,
183   width=fit,
184   distance=.5em,
185   margin=3em]
186\stopTEX
187
188Such settings (yielding a hanging list that would be inappropriate with a
189numbered bibliography list) get inherited from the \TEXcode {apa} namespace in
190the rendering that we named \TEXcode {example} above.
191
192Let's try a new example (using a file taken from the \index {TUG bibliography
193archive}\goto {TUG bibliography archive}
194[url(http://ftp.math.utah.edu/pub/tex/bib/index.html)]): \startfootnote \index
195{template.bib} The file \TEXcode {template-clean.bib} is simply a copy of \TEXcode
196{template.bib} that has been cleaned|-|up to remove the empty entries.
197\stopfootnote
198
199\startbuffer
200\definebtxdataset[template]
201\usebtxdataset   [template][template-clean.bib]
202
203\loadbtxdefinitionfile[aps]
204\definebtxrendering
205  [template]
206  [aps]
207  [dataset=template,
208   group=examples]
209
210\placelistofpublications
211  [template]
212  [method=dataset]
213\stopbuffer
214
215\cindex{definebtxdataset}
216\cindex{usebtxdataset}
217\cindex{loadbtxdefinitionfile}
218\cindex{definebtxrendering}
219\cindex{placelistofpublications}
220
221\typeTEXbuffer
222
223Here, the new rendering is defined to inherit explicitly from a rendering named
224\index {style+APS}\TEXcode {aps} (whose specification is loaded but not activated
225here). Notice, in particular, compared to the previous rendering example, that
226the list is numbered and that there is no hanging margin (it uses the standard
227list \TEXcode {alternative=b}):
228
229\getbuffer
230
231The \Index {numbering} of the references are unique and pick|-|up from where the
232previous numbering stops (the first example contains 33 references, although this
233numbering is not displayed). This behavior can be \TEXcode {method=global} for
234the entire document, or else \TEXcode {method=local}, limited to a structural
235element such as a chapter or a part. Furthermore, one can associate renderings
236into particular number groups, effectively isolating them from any other
237renderings. For example, as seen above in the rendering definitions, the present
238manual uses:
239
240\cindex{setupbtxrendering}
241
242\startTEX
243\setupbtxrendering[example] [group=examples]
244\setupbtxrendering[template][group=examples]
245\stopTEX
246
247thus setting the numbering of the group \TEXcode {examples} apart from the
248numbering of the dataset \TEXcode {default} and its named rendering (which contains
249this manual's own bibliography, to be placed later, on \at {page} [ch:biblio]).
250
251\stopsection
252
253\startsection
254  [reference=sec:styles,
255   title={Rendering styles, or more on specifications}]
256
257The default rendering style implemented in the \MKII\ module was loosely based on
258the \index {style+APA}APA standard. In contrast, we made a design choice in the
259present \MKIV\ system to provide a very minimal \TEXcode {default} style, and one
260should not expect much from this default: in fact, it only recognizes \type
261{article} and \type {book} entries (see the bibliography on \at {page}
262[ch:biblio]). A user requiring a more complete rendering will want to explicitly
263load and activate another style file. One such complete specification,
264illustrated above and appropriately named \index {style+APA}\TEXcode {apa}, is
265described in the \cite [title] [default::APA2010]. \cite [num]
266[default::APA2010]
267
268\startaside
269\emphasis {A note on the \index {style+APA}APA style:} We get the strong
270impression that the APA bibliography style standard was made with the implicit
271assumption that manual intervention would be involved in the editing and
272production process; It has been an arduous task to create a system capable of
273fully conforming to these specifications.
274
275Furthermore, we note that it has sometimes been argued that a numbered citation
276system and bibliography list is supposedly superior to the author|-|year scheme
277as is employed in the \index {style+APA}APA style (amongst others); indeed,
278handling numbered citations is certainly much easier from the point of view of
279the programmer of an automated typesetting system such as \TEX. Yet many find
280that the longer author|-|year citations can be of great use to the reader (as
281well as the writer) so we take no stand in this debate and provide both
282possibilities.
283
284We have made (and continue to make) a great effort to scrupulously respect the
285\index {style+APA}APA style in the so|-|named rendering. Yet be warned that very
286few editors and publishers in fact follow this style exactly so some
287customization will always be required.
288\stopaside
289
290In addition to the APA specification, there are many prescribed styles to render
291bibliographic descriptions that can be programmed as standards. Alternatives to
292\index {style+APA}\TEXcode {specification=apa} might be \index
293{style+MLA}\TEXcode {mla}, \index {style+Chicago}\TEXcode {chicago}, \index
294{style+Harvard}\TEXcode {harvard}, \index {style+IEEE}\TEXcode {ieee}, \index
295{style+APS}\TEXcode {aps} (commonly used in the physical sciences), \index
296{style+Vancouver}\TEXcode {vancouver} (used in the biological sciences), or many
297others. At this time, we only provide two description files, with \index
298{style+APS}\TEXcode {aps} being an example\startfootnote The \index
299{style+APS}APS style attempts to be very compact, providing complete yet minimal
300information, in contrast to the \index {style+APA}APA style which is rather
301verbose. \stopfootnote of a number|-|based rather than an authoryear|-|based
302scheme; more style schemes may be added in the future and the customization of a
303rendering style will be described in a later chapter.
304
305The rendering style usually also implies a particular bibliography list \Index
306{sorting} scheme as well as the use of a particular citation style. Indeed, the
307rendering of bibliography lists and references to it are intimately coupled. This
308question will be explained a bit later. The \index {style+APA}APA style, for
309example, specifies that the bibliography list be sorted by author and then by
310year, then by title. The list is not numbered (references are cited by author and
311year). Note, however, as can be seen from the two examples shown above that the
312references were indeed assigned numbers even though they are not displayed in the
313\index {style+APA}\TEXcode {apa} rendering (the user can easily choose to display
314these numbers, if desired).
315
316\stopsection
317
318\startsection
319  [list={Bibliography list scope},
320   title={Bibliography list \Index{scope}}]
321
322A single dataset can by used with multiple renderings. Although these renderings
323may illustrate different styles (as here for the purpose of demonstration in a
324manual on bibliographies), this would not be a coherent choice for a document
325that would normally employ a single bibliography style.
326
327The most obvious use of multiple renderings (employing a single specification) is
328the placement of bibliography lists localized by structure elements: parts,
329chapters in a book, sections, etc. through the option \TEXcode
330{criterium=chapter}, for example. This can be setup using:
331
332\cindex{setupbtxrendering}
333
334\startTEX
335\setupbtxrendering
336    [default]
337    [repeat=yes,
338     continue=yes,
339     method=global]
340\stopTEX
341
342followed at the end of each chapter by
343
344\cindex{placelistofpublications}
345
346\startTEX
347\placelistofpublications
348    [criterium=chapter]
349\stopTEX
350
351The numbering might alternately be made local through the option \TEXcode
352{method=local}. If desired, the reference numbers can also get prefixed:
353
354\cindex{setupbtxlist}
355
356\startTEX
357\setupbtxlist
358    [default]
359    [prefix=yes,
360     width=1cm]
361\stopTEX
362
363A bibliography list rendering placed at a single location, at the end of a book,
364for example, can also be easily split into structural parts. The following code
365(given without any explanation) illustrates this idea nicely:
366
367\cindex{placelistofpublications}
368
369\startTEX
370\startbackmatter
371    \startchapter [title=Bibliography,number=no,incrementnumber=no]
372        \startsubject [title=Introduction]
373            \placelistofpublications
374                [criterium=reference,reference=introduction]
375        \stopsubject
376        \dorecurse{12} {
377            \startsubject [title={Chapter #1}]
378                \placelistofpublications
379                    [criterium=bodypart:chapter,reference=#1]
380            \stopsubject
381        }
382    \stopchapter
383\stopbackmatter
384\stopTEX
385
386Note, as the above demonstrates, that the list of bibliography citations for
387\emphasis {any} referenced structural element can be placed \emphasis {anywhere}
388in the document, not simply within the structural element itself.
389
390\stopsection
391
392\startsection[title=Language]
393
394Bibliography lists (and citations in the text, see below) are rendered in the
395language of the document (\Cindex {mainlanguage}). However, a bibliography entry
396can contain a \TEXcode {language=} field and this can be used (if present),
397depending on the specification, in the rendering and hyphenation of the \TEXcode
398{title}, for example.
399
400One might choose to override this behavior and impose a single language for all
401bibliography entries (as well as for all other \CONTEXT\ constructs) using
402\Cindex {setupdelimitedtext} \TEXcode {[language=global]}.
403
404Since this directive is general for all delimited text in \CONTEXT\ and is not
405specific to bibliographies, one can apply it to force a particular language
406within a unique section, as in:
407
408\cindex{setupdelimitedtext}
409\cindex{placelistofpublications}
410
411\startTEX
412\startsection[title=Bibliografía]
413    \setupdelimitedtext[language=es]
414    \placelistofpublications
415\stopsection
416\stopTEX
417
418% to Hans: This currently does not work!
419% to Alan: I need an example!
420
421The language setting also influences the sorting of \UTF\ strings, in particular
422authors and titles.
423
424\cindex   {setupdelimitedtext}
425\showsetup[setupdelimitedtext]
426
427\startplacetable [title={\cindex{setupdelimitedtext}\TEXcode{\setupdelimitedtext[language=]}}]
428    \starttabulate [|Tl|p(.7\textwidth)|]
429        \NC language= \NC \NC \NR
430        \HL
431        \NC {\it<blank>} \NC (the default) use the current active language; \NC \NR
432        \NC local        \NC respect local language directives (such as the
433                             entry's \TEXcode {language={},} field, if present
434                             and managed by the rendering specification) \NC \NR
435        \NC global       \NC impose the main document language; \NC \NR
436        \NC en, de, nl,
437            \unknown     \NC impose the specified language. \NC \NR
438        \HL
439    \stoptabulate
440\stopplacetable
441
442\startsubsubject[title=Translated titles]
443
444Going beyond this handling of punctuation, labels and sorting, we have also
445introduced an entirely new feature, allowing for dataset entries to contain
446fields describing translated titles, for example. This is particularly useful
447when including citations to references published in languages other than the
448document language.
449
450Below is an example including \emphasis{three} languages: \startfootnote In this
451reference, the \TEXcode {title} and the \TEXcode {booktitle} are in different
452languages and the \TEXcode {language = {french},} field refers to the cited text.
453Both titles would have been rendered using French hyphenation rules had this not
454been overridden by including the switch \TEXcode {\de} that otherwise should be
455avoided in a database. The solution used here is sloppy, but fortunately, a
456complicated situation such as this is not very common.
457\stopfootnote
458
459% We could have
460%   booktitle:de = {Die ...},
461%
462% but what simple logic could be used to indicate choosing this title?
463% The present case could, perhaps should, have language = {german}, but this
464% would simply switch the problem to title = {\fr Principes ...},
465
466\startbuffer
467\startbuffer[leibniz]
468@INCOLLECTION{Leibniz1885,
469  author       = {Leibniz, G. W.},
470  title        = {Principes de la nature et de la grâce fondés en raison, 1714},
471  title:en     = {Principles of Nature and Grace Founded in Reason},
472  booktitle    = {\de Die Philosophischen Schriften von Gottfried Wilhelm Leibniz},
473  booktitle:en = {The Philosophical Writings of Gottfried Wilhelm Leibniz},
474  editor       = {Gerhardt, C. G.},
475  publisher    = {Weidmann},
476  year         = {1885},
477  volume       = {6},
478  chapter      = {8},
479  pages        = {598606},
480  address      = {Berlin},
481  language     = {french},
482}
483\stopbuffer
484\stopbuffer
485
486\typeTEXbuffer \getbuffer
487
488\startbuffer
489\usebtxdataset     [leibniz][leibniz.buffer]
490\definebtxrendering[leibniz][apa][group=examples,dataset=leibniz]
491\placebtxrendering [leibniz][method=dataset]
492\stopbuffer
493
494with
495
496\typeTEXbuffer
497
498that gets rendered as:
499
500\getbuffer
501
502In the \index {style+APA}APA bibliography style, the original reference title is
503listed followed by the translated title (within square brackets), the translation
504chosen being that of the \Cindex {mainlanguage} of the document (if present in
505the entry, of course). In other bibliography styles, this feature might not be
506implemented or may be ignored.
507
508\stopsubsubject
509
510\startsubsubject
511  [title=Multilingual bibliographies]
512
513The present handling of languages is only the beginning, and these features will
514be developed further in the future: multilingual typesetting being one of the
515great strengths behind \CONTEXT.
516
517\stopsubsubject
518
519\stopsection
520
521\startsection
522  [title=Page index]
523
524The list renderings can also include a page index of citations to each entry.
525This can be enabled using the parameter \TEXcode {pagestate}:
526
527\cindex{setupbtxrendering}
528
529\startTEX
530\setupbtxrendering [pagestate=start]
531\stopTEX
532
533As this is more of a subject related to the citation mechanism, it will be
534described in the following chapter (see \in {section} [sec:index], \at {p.}
535[sec:index]).
536
537\stopsection
538
539\stopchapter
540
541\stopcomponent
542