\environment publications-style \startcomponent publications-customize \startchapter[title=Custom renderings,reference=ch:custom] \startsection[title=Introduction] The rendering of citations and bibliography lists is highly configurable and custom rendering schemes can be added. The details can get quite complicated so we will begin with a description of how citation variations can be used in the running text, followed by a description on how to control the rending of the associated bibliography list. \startaside Loading the specification file defines a \Index {namespace}, say \TEXcode {apa}, containing subspaces \TEXcode {apa:list} and \TEXcode {apa:cite} as well as variants, for example \TEXcode {apa:cite:authoryear}, allowing \emphasis {parameters} to be tuned independently for each form. This insures independence but can get somewhat confusing. Most users will not encounter any problems as all of this setup work is taken care of in the specification file; only those needing to fine|-|tune specific settings need to better understand the underlying mechanism. The rendering of the variants can be adjusted through \Cindex {setupbtx} in the appropriate \Index {namespace}, for example modifying (or suppressing) parenthesis or activating or deactivating interaction \Index {hyperlink}s. Beyond the settings of parameters in the appropriate \Index {namespace}, \emphasis{setups} are used to perform the actual renderings of citations as well as of lists. One must be aware of \Index {namespace} \Index {isolation} and \Index {inheritance} as well as fall|-|back when attempting to make changes. When small modifications on one of the pre|-|defined specifications are desired, we suggest loading the specification and then adjusting certain parameters and overloading the appropriate setups. Eventually, a new specification might be necessary. \stopaside A common setup will enable or disable interaction: \startbuffer \setupbtx [interaction=start] \stopbuffer \cindex{setupbtx} \typeTEXbuffer Notice that this is applied to the root \Index {namespace}. Other root|-|\Index {namespace} parameters that have been used are \TEXcode {specification}, \TEXcode {dataset} and \TEXcode {numbering}. Associated with \TEXcode {specification} is an additional parameter \TEXcode {default=} that defines a fall|-|back specification to be used to complete a derived specification. \startfootnote For example, a variant on a specification can be defined by only addressing specific differences, for example \index {style+RMP}\TEXcode {specification=rmp} would be associated with \index {style+APS}\TEXcode {default=aps}, as this describes a style used by the journal: The Review of Modern Physics, mostly based on the style of the American Physical Society. \stopfootnote Further \quote {low|-|level} formatting parameters, mostly dealing with the formatting of names, are also defined by default in the root namespace. These are listed in \in {table} [tab:setupbtx]. Some might eventually be redefined by the specification in other namespaces, and may with good reason differ by context: between the \TEXcode {[cite]} and \TEXcode {[list]} namespaces, for example. In order to insure the independence of specifications, each one defines its own root namespace, for example \TEXcode {[default]}, \TEXcode {[apa]} or \TEXcode {[aps]}, inheriting its settings from root, upon which are built the other namespaces. \startplacetable [reference=tab:setupbtx, list={\TEXcode {\setupbtx} low|-|level formatting parameters}, title={\Cindex {setupbtx} low|-|level formatting parameters. Some may be redefined differently in the \TEXcode {cite} and \TEXcode {list} namespaces.}] \starttabulate [|Tr|Tl|p|] \NC specification \NC default \NC default style \NC \NR \NC default \NC \NC fall|-|back style \NC \NR \NC interaction \NC start \NC active hyperlinks \NC \NR \NC separator \NC \Cindex{btxsemicolon} \NC between multiple references \NC \NR \NC separator:firstnames \NC \Cindex{btxspace} \NC between first names \NC \NR \NC separator:juniors \NC \Cindex{btxspace} \NC before \quote{juniors} \NC \NR \NC separator:vons \NC \Cindex{btxspace} \NC before \quote{vons} \NC \NR \NC separator:initials \NC \Cindex{btxspace} \NC between initials \NC \NR \NC stopper:initials \NC . \NC initialization truncation symbol \NC \NR \NC separator:invertedinitials \NC \Cindex{btxcomma} \NC before initials, inverted form \NC \NR \NC separator:invertedfirstnames \NC \Cindex{btxcomma} \NC before first names, inverted form \NC \NR \NC authorconversion \NC normal \NC normal, normalshort, inverted, invertedshort, name (see \in{table}[tab:authorconversion]) \NC \NR \NC monthconversion \NC number \NC month, month:mnen (see \TEXcode {\convertnumber}) \NC \NR \NC journalconversion \NC normal \NC normal, abbreviated(short?) \NC \NR \NC etallimit \NC 3 \NC length of author list \NC \NR \NC etaldisplay \NC 3 \NC length of truncated author list \NC \NR \NC \tindex{others}otherstext \NC et al. \NC author list truncation text \NC \NR \NC separator:names:2 \NC \Cindex{btxcomma} \NC separates multiple names \NC \NR \NC separator:names:3 \NC \Cindex{btxcomma} \NC before last name in a list \NC \NR \NC separator:names:4 \NC \Cindex{btxcomma} \NC between only two names \NC \NR \NC separator:2 \NC \Cindex{btxsemicolon} \NC separates multiple objects \NC \NR \NC separator:3 \NC \Cindex{btxsemicolon} \NC before last object in a list \NC \NR \NC separator:4 \NC \Cindex{btxsemicolon} \NC between only two objects \NC \NR \stoptabulate \stopplacetable \cindex {setupbtx} \showsetup[setupbtx] \stopsection \startsection [reference=sec:customcite, title=Custom citation renderings] \startsubsubject [title=Parameters] Citation variants are mostly controlled though adjustment of their parameters within the appropriate \Index {namespace}. For example, the cite variant \cindex {cite}\TEXcode {\cite[num]} would be addressed through \cindex {setupbtx} \startTEX \setupbtx[default:cite:num] \stopTEX for the \TEXcode {default} specification, or alternately, through \cindex {setupbtx} \startTEX \setupbtx[apa:cite:num] \stopTEX for the \index {style+APA}\TEXcode {apa} specification. For example, superscript numbered citations in the \index {style+APS}\TEXcode {aps} specification could be obtained through \cindex{setupbtx} \startTEX \setupbtx[aps:cite:num][command=\high] \stopTEX Typical parameters (in addition to those listed in \in {table} [tab:setupbtx]) are presented in \in {table} [tab:setupbtxcite]. \startplacetable [reference=tab:setupbtxcite, location=force, list= {\TEXcode{\setupbtx [cite]} parameters}, title={\cindex{setupbtx}\TEXcode{\setupbtx[cite]} parameters}] \starttabulate [|Tr|l|l|] \NC alternative \NC num \NC default cite form \NC \NR \NC left \NC \NC opening string \NC \NR \NC right \NC \NC closing string \NC \NR \NC inbetween \NC \Cindex{btxspace} \NC \NC \NR \NC range \NC \TEXcode{\endash} \NC \NC \NR \NC command \NC \NC \NC \NR \NC style \NC \NC \NC \NR \NC sorttype \NC normal \NC \NC \NR \NC compress \NC yes \NC \NC \NR \stoptabulate \stopplacetable A demonstration of how these parameters can be manipulated in an individual \TEXcode {\cite} call is shown in \in{table} [tab:authorconversion], which also illustrates the different ways of formatting names. \startplacetable [title={\TEXcode{authorconversion}}, reference=tab:authorconversion] \starttabulate [|Tl|p|] \NC ac \NC \TEXcode{\cite[alternative=author,etallimit=,authorconversion=ac][article]} \NC \NR \HL \NC name \NC \cite[alternative=author,etallimit=,authorconversion=name] [article] \NC \NR \NC normal \NC \cite[alternative=author,etallimit=,authorconversion=normal] [article] \NC \NR \NC normalshort \NC \cite[alternative=author,etallimit=,authorconversion=normalshort] [article] \NC \NR \NC inverted \NC \cite[alternative=author,etallimit=,authorconversion=inverted] [article] \NC \NR \NC invertedshort \NC \cite[alternative=author,etallimit=,authorconversion=invertedshort][article] \NC \NR \stoptabulate \stopplacetable \stopsubsubject \startsubsubject [title=Setups] The next step in the customization of citation variants is through the overlaying of setups that handle the actual rendering of the citation. These rarely will need to be changed as most tuning can be done through the adjustment of parameters such as those given above. \startfootnote An exception is for special features, such as in the \index {style+APA}\TEXcode {apa} specification where a missing date is replaced by the notation \quotation {n..d.}. \stopfootnote It is to be pointed|-|out that original citation variants can be easily added. As an example, imagine that one might like to access the field \TEXcode {abstract} that is normally not rendered (like many other unused dataset fields). One would start by defining a parameter \Index {namespace} inheriting from the \TEXcode {cite} \Index {namespace}, followed by a simple setup (remember that the \TEXcode {apa} specification is currently active): \startbuffer \definebtx[apa:cite:abstract][apa:cite] \startsetups btx:apa:cite:abstract \btxcitereference \btxflush{abstract} \stopsetups \startparagraph [style=slanted] \cite[abstract][boekplan::Hagen2010metafun] \stopparagraph \stopbuffer \cindex{definebtx} \cindex{btxcitereference} \cindex{btxflush} \cindex{cite} \cindex{startsetups} \cindex{stopsetups} \tindex{::} \typeTEXbuffer \getbuffer If no special manipulation is known, the field with the same name (if found) will be simply flushed. This will only work, however, if the field is identified as either required or optional, that is not flagged as ignored in \in {table} [tab:fields] (see also \in {Appendix} [ch:datasetfields]). For the sake of the present manual, the field \BTXcode{abstract} has been defined as optional for the \BTXcode{book} entry in the specification's lua file. But don't expect too much support for such low|-|level rendering control. \stopsubsubject \stopsection \startsection[title=Custom list renderings,reference=sec:list] The rendering of lists is much more flexible and configurable than the rendering of citation markers. This is because the nature of data to be rendered requires many tools and helpers to deal with all of the eventual contingencies inherent in describing bibliographical references. The same \quote {low|-|level} formatting parameters used for citations also apply for \TEXcode {list} \Index {namespace}s, although their settings may differ from those of the citations. Consider the \index {style+APA}\TEXcode {apa} style that specifies the use of \tindex {others} \quotation {et al.} in citations but \quotation {\textellipsis} in the bibliography list, \quotation {and} in citations but \quotation {\textampersand} in lists, last names only in \TEXcode {authoryear} citations, etc. \startsubsubject[title=Bibliographies as lists] At another level of detail, the bibliography list is rendered in a standard \CONTEXT\ list environment that can be setup using the command \Cindex {setupbtxlist} (which is only \Cindex {setuplist} working in the protected bibliography environment: \TEXcode {btx}). The root settings, appropriate for a numbered bibliography list, are: \cindex{setuplist} \startTEX \setuplist [btx] [prefixstopper=:, state=start, alternative=a, before=\blank, after=\blank] \stopTEX whereas an unnumbered, author|-|year sorted list might have: \cindex{setupbtxlist} \startTEX \setupbtxlist [apa] [alternative=paragraph, margin=3\emwidth] \stopTEX as already seen in \in {Chapter} [ch:renderings]. The above demonstrate that \cindex {setupbtxlist}\TEXcode {\setupbtxlist[name]} is just a synonym for \cindex {setuplist}\TEXcode {\setuplist[btx:name]}. \cindex {setupbtxlist} \showsetup[setupbtxlist] \cindex {setuplist} \showsetup[setuplist] % too big for the page! Each specification will have its own list \Index {namespace} (\TEXcode {btx:specification}) that inherits from the root \TEXcode {btx} \Index {namespace}. This model of inheritance holds true for the citation and list details as described earlier. \stopsubsubject \startsubsubject[title=Setups] The layout of the information presented in the list is entirely controlled through setups, with the help of some underlying \LUA\ code organizing the data stored in the dataset. These setups rely on further setups as well as some convenient helpers or defined special commands. To understand this, consider as an illustration the setups defined for the \TEXcode {default} specification (taken from the source file \type {publ-imp-default.mkvi}): \cindex{startsetups} \cindex{stopsetups} \cindex{texdefinition} \cindex{btxperiod} \startTEX \startsetups btx:default:list:book \texdefinition{btx:default:author} \texdefinition{btx:default:title} \texdefinition{btx:default:editionset} \texdefinition{btx:default:publisher} \texdefinition{btx:default:year} \btxperiod \stopsetups \stopTEX \cindex{startsetups} \cindex{stopsetups} \cindex{texdefinition} \cindex{btxperiod} \startTEX \startsetups btx:default:list:article \texdefinition{btx:default:author} \texdefinition{btx:default:title} \texdefinition{btx:default:journal} \texdefinition{btx:default:year} \btxperiod \stopsetups \stopTEX This specification could be extended to handle publication categories other than \TEXcode {book} and \TEXcode {article} simply by defining an additional setup, \emphasis {almost} (see the following). \stopsubsubject \startsubsubject[title=\LUA\ tables] The qualification above is to bring attention to an important \LUA\ component that is defined in a companion source file: \TEXcode {publ-imp-default.lua}. This file defines a hierarchical \LUA\ table containing an element \TEXcode {categories} that itself contains the entries \TEXcode {book}, \TEXcode {article}, etc. The entries for each \Index {category} themselves contain the entries \index {field+required}\TEXcode {required} and \index {field+optional}\TEXcode {optional} listing the dataset fields that are to be used. Any field that is not declared either \index {field+required}required or \index {field+optional}optional will be \index {field+ignored}\emphasis {ignored}. \startfootnote The difference between \index {field+required}\quote {required} and \index {field+optional}\quote {optional} is only a question of diagnostics as described in the Appendices. Their functional meaning is rather \quote {handled} in contrast to \index {field+ignored}\quote {ignored}. \stopfootnote Note that if a category is \emphasis {not} declared in this \LUA\ table, than \emphasis {all} of its fields will be considered \index {field+optional}\quote {optional}. Thus, ignoring this level of control and simply defining additional setups might be sufficient for most use. The advantage of the \LUA\ table is a great simplification of the logic of the helper setups. Fields that might be irrelevant for one category yet used in another can be tested; if the field is to be \index {field+ignored}\quote {ignored}, than a fetch will return nothing. Indeed, the above two setups could be replaced by a single setup as \TEXcode {journal} is irrelevant and thus ignored for the \Index {category} \TEXcode {book} but not for the \Index {category} \TEXcode {journal}. However, an oversimplification such as just described would be rather confusing and would not extend well to a more complete specification (such as \index {style+APA}\TEXcode {apa}) handling many different categories. Note, as well, that fields \index {field+ignored}\quote {ignored} for certain \index {category}categories in the bibliography list will also be ignored in citations. For example, choosing to ignore \TEXcode {title} in some \Index {category}, say \TEXcode {article}, will cause \TEXcode {\cite[title]} to fail (return nothing) when referring to an entry of that category. In the example shown in \in {section} [sec:customcite], the abstract field would not return anything if it did not appear in the \LUA\ table. This \LUA\ table also defines (as \index {type}\quote {types}, outside of \index {category}\quote {categories}) what fields are to be interpreted as names, what fields are to eventually be interpreted as a number or range of numbers, and what fields are to be interpreted specially as a (semi|-|colon) separated list (for example, \TEXcode {keywords}). A more subtle feature of the \LUA\ level is the notion of \index {set}\quote {sets}. Related fields can be grouped into sets, for example. \startLUA book = { sets = { author = { "author", "editor", }, editionset = { "edition", "volume", "number" }, }, }, \stopLUA A fetch of the set \text {author} (i.e. \cindex {btxflush}\TEXcode {\btxflush{author}}, to be described below) will return the \text {author} field if this is present, otherwise it will return the \TEXcode {editor} field, for an edited book, for example. Testing for the presence of a set in a data entry is equivalent to a logical \emphasis{or} in testing for the presence of each element of the set. This mechanism can appear confusing yet it has served to greatly simplify the logic of the various setups. \startfootnote Sometimes a \Index {set} will be defined using the same name as its first element, sometimes it can be given a unique name (typically ending in \quote {set}). \stopfootnote The \TEXcode {author} set is a bit special given its use in the \TEXcode {authoryear(s)}, \TEXcode {authornum}, and \TEXcode {short} citation variants. This \Index {set} determines what fields are to enter into the citation \Index {tag}s, a generalization of the notion of author. For example, in the \index {style+APA}APA style, this set would include the author, editor, or title fields or an article and the author, editor, publisher, or title fields for a book and still other sequences of fields for other categories of publications. \stopsubsubject \startsubsubject[title=Defined helpers] Fetching data from the dataset is performed using the command encountered above: \TEXcode {\btxflush}. If the field (or no elements of the set) is not found, then this command will return nothing. \cindex {btxflush} \showsetup[btxflush] Alternately, one might need to explicitly test for the presence or absence of the field, in order to conditionally include punctuation or not to trigger separators, for example. Three test macros have been defined: \startplacetable [title=Conditional macros] \cindex{btxdoifelse} \cindex{btxdoif} \cindex{btxdoifnot} \startTEX \btxdoifelse{fieldname}{action when found}{action when not found} \btxdoif {fieldname}{action when found} \btxdoifnot {fieldname} {action when not found} \stopTEX \stopplacetable In many cases, the readability can be improved by using further setups, for instance: \cindex{btxdoifelse} \cindex{fastsetup} \startTEX \btxdoifelse {author} { \fastsetup{btx:apa:author:yes} } { \fastsetup{btx:apa:author:nop} } \stopTEX Note that the choice between using setups (defined through \Cindex {startsetups} \unknown\ \Cindex {stopsetups} and recalled through \Cindex {fastsetup}) versus textdefinitions without arguments (defined through \Cindex {starttexdefinition} \unknown\ \Cindex {stoptexdefinition} and recalled through \Cindex {texdefinition}) is a question of taste and opportunity. One should keep in mind not get carried away abusing setups and texdefinitions for simple code fragments that are to be used uniquely. An extra conditional is available for testing interactivity: \cindex{btxdoifelseinteraction} \startTEX \btxdoifelseinteraction{action when true}{action when false} \stopTEX There is also a conditional \Cindex {btxinteractive} which is more efficient, although in practice efficiency is not so important here. \blank In addition to \Index {set}s, there are derived or special fields such as \TEXcode {num} (for the reference number), \TEXcode {suffix} (to be appended in some cases to \TEXcode {year}), \TEXcode {short} (for names), etc. These all can be retrieved using \Cindex {btxflush}. Sometimes one might want to force access to a particular data field (such as \TEXcode {author}) rather than eventually an element of a \Index {set} having the same name. There are three basic commands to flush data and a few others to flush associated information: \startplacetable [title=Field access macros] \starttabulate[|l|l|] \NC \Cindex{btxflush} \NC fetch a derived or explicit field \NC \NR \NC \Cindex{btxdetail} \NC fetch a derived field (e.g.\ \TEXcode {short}) \NC \NR \NC \Cindex{btxfield} \NC fetch a explicit field (e.g.\ \TEXcode {year}) \NC \NR \NR \NC \Cindex{btxfieldname} \NC fetch the field name \NC \NR \NC \Cindex{btxfieldtype} \NC fetch the field type (e.g.\ \TEXcode{author}, \TEXcode{range}, \unknown \NC \NR \NC \Cindex{btxfoundname} \NC fetch the field name of a set (or field) \NC \NR \NC \Cindex{btxfoundtype} \NC fetch the field type of a set (or field) \NC \NR \stoptabulate \stopplacetable A few helpers are provided to inject symbols but also take care of leading and trailing spaces: \startfootnote These make use of the \CONTEXT\ command \Cindex {removeunwantedspaces}. There is also a \quote {secret} command \TEXcode {\removepunctuation} that can be quite useful, but also lead to undesired consequences when wielded blindly! \stopfootnote \startplacetable [title=Punctuation macros] \starttabulate[|||] \NC \Cindex{btxspace} \NC before \btxspace after \NC \NR \NC \Cindex{btxnbsp} \NC before \btxnbsp after \NC \NR \NC \Cindex{btxnobreakspace} \NC before \btxnobreakspace after (same as \Cindex {btxnbsp}) \NC \NR \NC \Cindex{btxperiod} \NC before \btxperiod after \NC \NR \NC \Cindex{btxcomma} \NC before \btxcomma after \NC \NR \NC \Cindex{btxcommabreak} \NC before \btxcommabreak after (allows a line break) \NC \NR \NC \Cindex{btxleftparenthesis} \NC before \btxleftparenthesis after \NC \NR \NC \Cindex{btxrightparenthesis} \NC before \btxrightparenthesis after \NC \NR \NC \Cindex{btxrightparenthesiscomma} \NC before \btxrightparenthesiscomma after \NC \NR \NC \Cindex{btxrightparenthesisperiod} \NC before \btxrightparenthesisperiod after \NC \NR \NC \Cindex{btxleftbracket} \NC before \btxleftbracket after \NC \NR \NC \Cindex{btxrightbracket} \NC before \btxrightbracket after \NC \NR \NC \Cindex{btxrightbracketcomma} \NC before \btxrightbracketcomma after \NC \NR \NC \Cindex{btxrightbracketperiod} \NC before \btxrightbracketperiod after \NC \NR \stoptabulate \stopplacetable \stopsubsubject \starthiding Normally you can use \TEXcode {\btxfield} or \TEXcode {\btxflush} as derived fields just like analyzed author fields are flushed in a special way. There is experimental support for so called manipulators. You can for instance say this: \starttyping \btxflush{lowercase->title} \stoptyping A sequence of manipulators is applied to fetched field, where a sequence is one or more manipulators: \starttyping \btxflush{stripperiod->uppercase->title} \stoptyping Some actions are recognized (built|-|in) but you can also use actions from other namespaces, like in: \starttyping \btxflush{converters.Word -> title} \stoptyping Watch how we can use spaces around the \TEXcode {->} which is nicer for wrapped around usage. Eventually, we might put some more function in the default namespace. So, the previous example setup can be rewritten as: \starttyping \btxdoif {title} { \bold{\btxfield{title}} \btxcomma } \stoptyping There is a special command for rendering a (combination) of authors: \starttyping \btxflushauthor{author} \btxflushauthor{editor} \btxflushauthor[inverted]{editor} \stoptyping Instead of the last one you can also use: \starttyping \btxflushauthorinverted{editor} \stoptyping You can use a (configurable) default or pass directives: Valid directives are \starttabulate \NC \bf conversion \NC \bf rendering \NC \NR \HL \NC \TEXcode{inverted} \NC the Frog jr, Kermit \NC \NR \NC \TEXcode{invertedshort} \NC the Frog jr, K \NC \NR \NC \TEXcode{normal} \NC Kermit, the Frog, jr \NC \NR \NC \TEXcode{normalshort} \NC K, the Frog, jr \NC \NR \stoptabulate The list itself is not a list in the sense of a regular \CONTEXT\ structure related list. We do use the list mechanism to keep track of used entries but that is mostly because we can then reuse filtering mechanisms. The actual rendering of a reference and entry runs on top of so called constructions (other examples of constructions are descriptions, enumerations and notes). \showsetup[setupbtxlist] You need to be aware what command is used to achieve the desired result. For instance, in order to put parentheses around a number reference you say: \starttyping \setupbtxlistvariant [num] [left=(, right=)] \stoptyping If you want automated width calculations, the following does the trick: \starttyping \setupbtxrendering [default] [width=auto] \stoptyping but if you want to control it yourself you say something: \starttyping \setupbtxrendering [width=none] \setupbtxlist [default] [width=3cm, distance=\emwidth, color=red, headcolor=blue, headalign=flushright] \stoptyping In most cases the defaults will work out fine. Normally the references are numbered using one counter for the whole document. If you want each list to have its own number, then you can set the \TEXcode {continue} parameter: \starttyping \setupbtxrendering[continue=no] \stoptyping In a similar fashion you can influence if references are included only once of in each list: \starttyping \setupbtxrendering[repeat=yes] \stoptyping \stophiding \stopsection \stopchapter \stopcomponent