diff options
Diffstat (limited to 'doc/context/sources/general/manuals/publications/publications-rendering.tex')
| -rw-r--r-- | doc/context/sources/general/manuals/publications/publications-rendering.tex | 541 |
1 files changed, 541 insertions, 0 deletions
diff --git a/doc/context/sources/general/manuals/publications/publications-rendering.tex b/doc/context/sources/general/manuals/publications/publications-rendering.tex new file mode 100644 index 000000000..caa1f61d7 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-rendering.tex @@ -0,0 +1,541 @@ +\environment publications-style + +\startcomponent publications-rendering + +\startchapter[title=Renderings,reference=ch:renderings] + +\startsection + [reference=sec:styles, + title={Generating lists of publications}] + +A list of publications can be rendered at any place in the document, and multiple +renderings can appear under certain limitations (according to \Index {scope}). +The specification introduced previously defines the style of the rendering as +well as what data it will contain. + +If you want to see what publications are in the database, the easiest way is to +ask for a complete list: + +\startbuffer +\usebtxdataset % illustrated again here + [example] % although already loaded + [mkiv-publications.bib] % in the previous chapter + +\definebtxrendering + [example] % named rendering + [apa] % parent namespace + [dataset=example, + group=examples] % group will be presented later + +\placelistofpublications % aka \placebtxrendering + [example] % rendering defined above + [method=dataset] % i.e. all entries +\stopbuffer + +\cindex{definebtxrendering} +\cindex{placelistofpublications} +\cindex{placebtxrendering} + +\typeTEXbuffer + +The commands \Cindex {placelistofpublications} (that is just a synonym for +\Cindex {placebtxrendering}) refer to a named rendering and accept a list of +options (inherited from \Cindex {setupbtxrendering}). When applied to a named +dataset (other than \TEXcode {default}), a named rendering needs to be associated +through \Cindex {definebtxrendering} as is done here. + +Note that the define shown above explicitly inherits from a rendering named +\TEXcode {apa} that was itself defined when loading the specification file. +\startfootnote The rendering parent \index {style+APA}\TEXcode {[apa]} sets the +parameters: \TEXcode {specification=apa,} \TEXcode {sorttype=authoryear,} and +\TEXcode {numbering=no,} described below. It also sets various list parameters in +a protected \TEXcode {apa} namespace to produce a \quote {hanging} bibliography +list. \stopfootnote Had this inheritance not been specified, the new rendering +would inherit default, minimal settings. This notion of inheritance will be +further illustrated later. + +The bibliography list rendering of our example dataset, following the \index +{style+APA}APA style, is: + +\getbuffer + +The rendering is a list whose appearance can be tuned, as any list in \CONTEXT. +It is somewhat more complex to manage, though, because we can have not only many +different standards but also many fields that can be set up. This means that +there are several commands involved. As we saw demonstrated above, a rendering is +defined and setup using the commands: + +\cindex{definebtxrendering} + +\showsetup{definebtxrendering} + +\cindex{setupbtxrendering} + +\showsetup{setupbtxrendering} + +A rendering is then placed using \Cindex {placebtxrendering}, a \CONTEXT\ command +that accepts the same arguments as for its setup. Using \TEXcode +{method=dataset}, as above, one renders the entire contents of the dataset. +Normally, however, one would not use this \TEXcode {method} and place only a +selection of entries that are to be used in the document, whereas the dataset may +very well contain many other, unused references. The \TEXcode {method=global} or +\TEXcode {method=local} option can be used to specify if this use is to be global +for the entire document or else local to a structure element such as a part or a +chapter. + +\cindex{placebtxrendering} + +\showsetup{placebtxrendering} + +\cindex{placelistofpublications} + +\showsetup{placelistofpublications} + +The rendering is a \TEXcode {list} and this reference list is numbered. These +numbers can be displayed, or not, depending on the bibliography style +specification through the use of the \index {numbering}\TEXcode {numbering=yes} +or \TEXcode {no} parameter values. The \index {style+APA}APA style, illustrated +above, normally does not number the bibliography list. + +The reference list is also \index {sorting}sorted, controlled by the parameter +\TEXcode {sorttype}; here \TEXcode {sorttype=authoryear}, appropriate for the +\index {style+APA}APA style, \Index {sorting} first by author list, then by +publication year, then by title, finally by page. One can sort the list in many +ways: for example \TEXcode {sorttype=index} will render the list in the order in +which it was loaded into the dataset (see \in {table} [tab:sorttype] for an +explanation of list sorting schemes). + +\startplacetable [location=force, + title={\TEXcode {sorttype=}}, + reference=tab:sorttype] +\index{sorting} +\starttabulate [|Tp(5.5em)|p(.75\textwidth)|] +\HL +\NC default\\none\\cite\\list +\NC render the list in the order in which it was built, + that is, in the order that references were selected from the dataset for + inclusion in the list. \NC \NR +\HL +\NC dataset\\index +\NC sort the list according to the dataset index, that is, in the order in that + references were added to the dataset. \NC \NR +\HL +\NC reference +\NC sort the list in alphabetical order of the citation \Index{tag}s of the + dataset. Note that all entries missing tags get assigned the dataset index as + their tag. \NC \NR +\HL +\NC key +\NC sort the list in alphabetical order of the entry field \TEXcode {key} + (traditionally used in \BIBTEX\ as an alternate sorting key). Falls back on + the dataset index if no such field is present. \NC \NR +\HL +\NC short +\NC sort the list in alphabetical order of the short tag (first three letters + of the author name or first letter of the first three authors followed by + the last two digits of the year). \NC \NR +\HL +\NC authoryear +\NC sort the list in alphabetical order of the authors (or editors or publisher), + then by publication year, then by title (or by journal and volume) and + finally by page. \NC \NR +\stoptabulate +\stopplacetable + +As a concrete example, the rendering named \TEXcode {example} above inherits from +the rendering instance named \TEXcode {apa} that is defined in the specification +file as: + +\cindex{definebtxrendering} + +\startTEX +\definebtxrendering + [apa] + [specification=apa, + sorttype=authoryear, + numbering=no] +\stopTEX + +\startaside +A more subtle characteristic of renderings is that one generally would not want a +bibliography list to appear redundantly in a document as that would be confusing, +unless of course it is desired that elements of the list reappear in later lists, +for example when placing partial bibliographies at the end of each chapter and a +complete bibliography list at the end of a book. One must specify \TEXcode +{repeat=yes} in order to get multiple renderings of a bibliography list; +otherwise, as they appear, entries get marked as placed and will be inhibited +from being placed again elsewhere. +\stopaside + +All renderings of bibliography lists such as the one shown earlier in this +section also depend on a set of general list parameters that apply to each +individual entry (a cited publication), as for any list item in \CONTEXT. These +can be adjusted through the command \Cindex {setupbtxlist} (further described in +\in {section} [sec:list], below). As an example, the \TEXcode {apa} specification +file includes: + +\cindex{setupbtxlist} + +\startTEX +\setupbtxlist + [apa] + [alternative=paragraph, + width=fit, + distance=.5em, + margin=3em] +\stopTEX + +Such settings (yielding a hanging list that would be inappropriate with a +numbered bibliography list) get inherited from the \TEXcode {apa} namespace in +the rendering that we named \TEXcode {example} above. + +Let's try a new example (using a file taken from the \index {TUG bibliography +archive}\goto {TUG bibliography archive} +[url(http://ftp.math.utah.edu/pub/tex/bib/index.html)]): \startfootnote \index +{template.bib} The file \TEXcode {template-clean.bib} is simply a copy of \TEXcode +{template.bib} that has been cleaned|-|up to remove the empty entries. +\stopfootnote + +\startbuffer +\definebtxdataset[template] +\usebtxdataset [template][template-clean.bib] + +\loadbtxdefinitionfile[aps] +\definebtxrendering + [template] + [aps] + [dataset=template, + group=examples] + +\placelistofpublications + [template] + [method=dataset] +\stopbuffer + +\cindex{definebtxdataset} +\cindex{usebtxdataset} +\cindex{loadbtxdefinitionfile} +\cindex{definebtxrendering} +\cindex{placelistofpublications} + +\typeTEXbuffer + +Here, the new rendering is defined to inherit explicitly from a rendering named +\index {style+APS}\TEXcode {aps} (whose specification is loaded but not activated +here). Notice, in particular, compared to the previous rendering example, that +the list is numbered and that there is no hanging margin (it uses the standard +list \TEXcode {alternative=b}): + +\getbuffer + +The \Index {numbering} of the references are unique and pick|-|up from where the +previous numbering stops (the first example contains 33 references, although this +numbering is not displayed). This behavior can be \TEXcode {method=global} for +the entire document, or else \TEXcode {method=local}, limited to a structural +element such as a chapter or a part. Furthermore, one can associate renderings +into particular number groups, effectively isolating them from any other +renderings. For example, as seen above in the rendering definitions, the present +manual uses: + +\cindex{setupbtxrendering} + +\startTEX +\setupbtxrendering[example] [group=examples] +\setupbtxrendering[template][group=examples] +\stopTEX + +thus setting the numbering of the group \TEXcode {examples} apart from the +numbering of the dataset \TEXcode {default} and its named rendering (which contains +this manual's own bibliography, to be placed later, on \at {page} [ch:biblio]). + +\stopsection + +\startsection + [reference=sec:styles, + title={Rendering styles, or more on specifications}] + +The default rendering style implemented in the \MKII\ module was loosely based on +the \index {style+APA}APA standard. In contrast, we made a design choice in the +present \MKIV\ system to provide a very minimal \TEXcode {default} style, and one +should not expect much from this default: in fact, it only recognizes \type +{article} and \type {book} entries (see the bibliography on \at {page} +[ch:biblio]). A user requiring a more complete rendering will want to explicitly +load and activate another style file. One such complete specification, +illustrated above and appropriately named \index {style+APA}\TEXcode {apa}, is +described in the \cite [title] [default::APA2010]. \cite [num] +[default::APA2010] + +\startaside +\emphasis {A note on the \index {style+APA}APA style:} We get the strong +impression that the APA bibliography style standard was made with the implicit +assumption that manual intervention would be involved in the editing and +production process; It has been an arduous task to create a system capable of +fully conforming to these specifications. + +Furthermore, we note that it has sometimes been argued that a numbered citation +system and bibliography list is supposedly superior to the author|-|year scheme +as is employed in the \index {style+APA}APA style (amongst others); indeed, +handling numbered citations is certainly much easier from the point of view of +the programmer of an automated typesetting system such as \TEX. Yet many find +that the longer author|-|year citations can be of great use to the reader (as +well as the writer) so we take no stand in this debate and provide both +possibilities. + +We have made (and continue to make) a great effort to scrupulously respect the +\index {style+APA}APA style in the so|-|named rendering. Yet be warned that very +few editors and publishers in fact follow this style exactly so some +customization will always be required. +\stopaside + +In addition to the APA specification, there are many prescribed styles to render +bibliographic descriptions that can be programmed as standards. Alternatives to +\index {style+APA}\TEXcode {specification=apa} might be \index +{style+MLA}\TEXcode {mla}, \index {style+Chicago}\TEXcode {chicago}, \index +{style+Harvard}\TEXcode {harvard}, \index {style+IEEE}\TEXcode {ieee}, \index +{style+APS}\TEXcode {aps} (commonly used in the physical sciences), \index +{style+Vancouver}\TEXcode {vancouver} (used in the biological sciences), or many +others. At this time, we only provide two description files, with \index +{style+APS}\TEXcode {aps} being an example\startfootnote The \index +{style+APS}APS style attempts to be very compact, providing complete yet minimal +information, in contrast to the \index {style+APA}APA style which is rather +verbose. \stopfootnote of a number|-|based rather than an authoryear|-|based +scheme; more style schemes may be added in the future and the customization of a +rendering style will be described in a later chapter. + +The rendering style usually also implies a particular bibliography list \Index +{sorting} scheme as well as the use of a particular citation style. Indeed, the +rendering of bibliography lists and references to it are intimately coupled. This +question will be explained a bit later. The \index {style+APA}APA style, for +example, specifies that the bibliography list be sorted by author and then by +year, then by title. The list is not numbered (references are cited by author and +year). Note, however, as can be seen from the two examples shown above that the +references were indeed assigned numbers even though they are not displayed in the +\index {style+APA}\TEXcode {apa} rendering (the user can easily choose to display +these numbers, if desired). + +\stopsection + +\startsection + [list={Bibliography list scope}, + title={Bibliography list \Index{scope}}] + +A single dataset can by used with multiple renderings. Although these renderings +may illustrate different styles (as here for the purpose of demonstration in a +manual on bibliographies), this would not be a coherent choice for a document +that would normally employ a single bibliography style. + +The most obvious use of multiple renderings (employing a single specification) is +the placement of bibliography lists localized by structure elements: parts, +chapters in a book, sections, etc. through the option \TEXcode +{criterium=chapter}, for example. This can be setup using: + +\cindex{setupbtxrendering} + +\startTEX +\setupbtxrendering + [default] + [repeat=yes, + continue=yes, + method=global] +\stopTEX + +followed at the end of each chapter by + +\cindex{placelistofpublications} + +\startTEX +\placelistofpublications + [criterium=chapter] +\stopTEX + +The numbering might alternately be made local through the option \TEXcode +{method=local}. If desired, the reference numbers can also get prefixed: + +\cindex{setupbtxlist} + +\startTEX +\setupbtxlist + [default] + [prefix=yes, + width=1cm] +\stopTEX + +A bibliography list rendering placed at a single location, at the end of a book, +for example, can also be easily split into structural parts. The following code +(given without any explanation) illustrates this idea nicely: + +\cindex{placelistofpublications} + +\startTEX +\startbackmatter + \startchapter [title=Bibliography,number=no,incrementnumber=no] + \startsubject [title=Introduction] + \placelistofpublications + [criterium=reference,reference=introduction] + \stopsubject + \dorecurse{12} { + \startsubject [title={Chapter #1}] + \placelistofpublications + [criterium=bodypart:chapter,reference=#1] + \stopsubject + } + \stopchapter +\stopbackmatter +\stopTEX + +Note, as the above demonstrates, that the list of bibliography citations for +\emphasis {any} referenced structural element can be placed \emphasis {anywhere} +in the document, not simply within the structural element itself. + +\stopsection + +\startsection[title=Language] + +Bibliography lists (and citations in the text, see below) are rendered in the +language of the document (\Cindex {mainlanguage}). However, a bibliography entry +can contain a \TEXcode {language=} field and this can be used (if present), +depending on the specification, in the rendering and hyphenation of the \TEXcode +{title}, for example. + +One might choose to override this behavior and impose a single language for all +bibliography entries (as well as for all other \CONTEXT\ constructs) using +\Cindex {setupdelimitedtext} \TEXcode {[language=global]}. + +Since this directive is general for all delimited text in \CONTEXT\ and is not +specific to bibliographies, one can apply it to force a particular language +within a unique section, as in: + +\cindex{setupdelimitedtext} +\cindex{placelistofpublications} + +\startTEX +\startsection[title=Bibliografía] + \setupdelimitedtext[language=es] + \placelistofpublications +\stopsection +\stopTEX + +% to Hans: This currently does not work! +% to Alan: I need an example! + +The language setting also influences the sorting of \UTF\ strings, in particular +authors and titles. + +\cindex {setupdelimitedtext} +\showsetup[setupdelimitedtext] + +\startplacetable [title={\cindex{setupdelimitedtext}\TEXcode{\setupdelimitedtext[language=…]}}] + \starttabulate [|Tl|p(.7\textwidth)|] + \NC language= \NC \NC \NR + \HL + \NC {\it<blank>} \NC (the default) use the current active language; \NC \NR + \NC local \NC respect local language directives (such as the + entry's \TEXcode {language={…},} field, if present + and managed by the rendering specification) \NC \NR + \NC global \NC impose the main document language; \NC \NR + \NC en, de, nl, + \unknown \NC impose the specified language. \NC \NR + \HL + \stoptabulate +\stopplacetable + +\startsubsubject[title=Translated titles] + +Going beyond this handling of punctuation, labels and sorting, we have also +introduced an entirely new feature, allowing for dataset entries to contain +fields describing translated titles, for example. This is particularly useful +when including citations to references published in languages other than the +document language. + +Below is an example including \emphasis{three} languages: \startfootnote In this +reference, the \TEXcode {title} and the \TEXcode {booktitle} are in different +languages and the \TEXcode {language = {french},} field refers to the cited text. +Both titles would have been rendered using French hyphenation rules had this not +been overridden by including the switch \TEXcode {\de} that otherwise should be +avoided in a database. The solution used here is sloppy, but fortunately, a +complicated situation such as this is not very common. +\stopfootnote + +% We could have +% booktitle:de = {Die ...}, +% +% but what simple logic could be used to indicate choosing this title? +% The present case could, perhaps should, have language = {german}, but this +% would simply switch the problem to title = {\fr Principes ...}, + +\startbuffer +\startbuffer[leibniz] +@INCOLLECTION{Leibniz1885, + author = {Leibniz, G. W.}, + title = {Principes de la nature et de la grâce fondés en raison, 1714}, + title:en = {Principles of Nature and Grace Founded in Reason}, + booktitle = {\de Die Philosophischen Schriften von Gottfried Wilhelm Leibniz}, + booktitle:en = {The Philosophical Writings of Gottfried Wilhelm Leibniz}, + editor = {Gerhardt, C. G.}, + publisher = {Weidmann}, + year = {1885}, + volume = {6}, + chapter = {8}, + pages = {598–606}, + address = {Berlin}, + language = {french}, +} +\stopbuffer +\stopbuffer + +\typeTEXbuffer \getbuffer + +\startbuffer +\usebtxdataset [leibniz][leibniz.buffer] +\definebtxrendering[leibniz][apa][group=examples,dataset=leibniz] +\placebtxrendering [leibniz][method=dataset] +\stopbuffer + +with + +\typeTEXbuffer + +that gets rendered as: + +\getbuffer + +In the \index {style+APA}APA bibliography style, the original reference title is +listed followed by the translated title (within square brackets), the translation +chosen being that of the \Cindex {mainlanguage} of the document (if present in +the entry, of course). In other bibliography styles, this feature might not be +implemented or may be ignored. + +\stopsubsubject + +\startsubsubject + [title=Multilingual bibliographies] + +The present handling of languages is only the beginning, and these features will +be developed further in the future: multilingual typesetting being one of the +great strengths behind \CONTEXT. + +\stopsubsubject + +\stopsection + +\startsection + [title=Page index] + +The list renderings can also include a page index of citations to each entry. +This can be enabled using the parameter \TEXcode {pagestate}: + +\cindex{setupbtxrendering} + +\startTEX +\setupbtxrendering [pagestate=start] +\stopTEX + +As this is more of a subject related to the citation mechanism, it will be +described in the following chapter (see \in {section} [sec:index], \at {p.} +[sec:index]). + +\stopsection + +\stopchapter + +\stopcomponent |