User:Dnessett/Template/Bref/doc

Usage

The Bref template utilizes CITE extension functionality to provide citation, footnote and reference structures more applicable to books and other long texts. It assumes a book contains three structures: 1) one or more citations list page(s) where all citation and footnote information is specified, 2) one or more references sections where citation and footnote information is rendered, and 3) a set of book pages, where citations and footnotes are referenced. Distinguishing between types 1 and 2 is necessary to overcome certain unwelcome CITE extension behavior.

The Bref template family consists of one core template (Bref) and several helper templates that utilize it. The core template should not be directly called, since doing so causes template loop errors. Instead, authors should insert calls to the appropriate helper templates into their documents.

Terminology: A citation comprises data identifying either a textual source or a footnote. It includes a name (e.g., "Tolkien1954a") and associated text. A reference is the name of a citation inserted into a document.

Bref Template Call

The Bref template is the core engine of the Bref template family. A Bref template call has the following skeleton:

{{Bref | OP = <op value> | CLP = <citations list pagename> | NAME = <citation name> | GROUP = <group name> | TEXT = <citation data>}}. The "<" and ">" specified in this skeleton simply deliminate a description of the parameter values. They do not appear in an actual Bref call.

The parameter values are:

OP: the specific Bref operation performed. Default=nop

CLP: the name of a Citations List Page holding citation information (in the form of {{Bref | OP=cite}} or equivalently Bref/Citation_Definition data). Default=Page_Parent/Citations_List.

To build the default CLP pagename, "Page_Parent" is replaced by the parent pagename. The parent is the page located at one higher level in the pagename hierarchy. For example, if the page containing the Bref call is: Tales_Told_By_An_Idiot/Chapter 1, then the default CLP for that call is: Tales_Told_By_An_Idiot/Citations_List. Note: if the CLP is a page in the main namespace, it must be specifically indicated. That is, using it as the value of the CLP parameter requires a colon before the pagename, i.e., CLP=:BookName/Citations_List

NAME: the name of a citation. Default="".

Bref calls with OP=ref or OP=cite (equivalently, Bref/Citation_Reference or Bref/Citation_Definition) must contain a NAME parameter and may contain a GROUP parameter. Bref calls with OP=note (equivalently, Bref/Footnote_Reference) must contain a GROUP parameter and may contain a NAME parameter. The value of NAME is ignored for all other Bref OP values. For Bref OP=ref, OP=cite, and Bref OP=note calls, the paired values of NAME and GROUP must be unique in the scope of all citation lists presented on the page. In a OP=cite call, NAME and GROUP associate their values with the provided citation information (i.e., the TEXT value). In a OP=ref call, they identify the citation information (again, the TEXT value) referenced. In a OP=note call, they identify the footnote (the TEXT value) referenced.

GROUP: The name of a group of footnotes or citations. Default="".

The value of GROUP is the name of a group. When rendered in document text, references to a footnote or citation with a non-null GROUP parameter are prefixed with the value of GROUP. A Bref call with OP=cite (equivalently, Bref/Citation_Definition), GROUP=fn and NAME=<some value> places an entry in a Citations List grouped with all others inserted with GROUP=fn. If a Bref call with OP=ref or OP=note (equivalently, Bref/Citation_Reference or Bref/Footnote_Reference), GROUP=fn and NAME=<some value> is placed on a document page, the reference will appear as "fn xxx", where xxx is the numerical order of the entry in the Citations List. For example, if a Citations List contains three footnotes in group GROUP=fn and the third is referenced in a document's text by a Bref call with OP=note, GROUP=fn and NAME=<identifier of third footnote>, the reference in the text will be : "fn 3" (without the quotes). Defining and referencing footnotes without an identifying NAME value should only be used when all footnotes and the rendered footnote list appear on the same page. Otherwise, it is difficult to synchronize the footnote's reference name with its numerical label in the footnote list (footnote references without a NAME value are given a numerical value based on the order in which they appear on a document page). When specified in a Bref call with OP=rcd (equivalently, Bref/Render_Citation_Data), only footnotes or citations in the identified group are rendered. Consequently, assuming a set of footnotes are grouped together by GROUP=group1 and GROUP=group2, a Bref call with OP=rcd and GROUP=group2 only renders those footnotes in group2.

TEXT: The textual information associated with a citation or footnote. This parameter is used only in Bref calls with OP=cite (equivalently, Bref/Citation_Definition). Default=" ".

It is perfectly legal for TEXT to evaluate to white space, although normally it should evaluate to citation or footnote data, e.g., information formated by the Cite family of templates (e.g., Template:Cite_book) in the case of a citation or contained within tags in the case of footnotes. Using whitespace as citation data allows the insertion of citation references and empty footnotes into a document before the associated text is available. Note: any text not contained within <cite></cite> or tags will be rendered to the null string by the Bref helper script (see below).

The OP parameter may take one of the following values:

OP=nop: No Operation.

This OP value is provided so that Bref template calls may be placed in markup as placeholders for later elaboration. It is also the default OP when Bref is called with an unrecognized value. It returns the text "Bref_Place_Holder" (without the quotes) rendered as a superscript.

OP=scl: Start Citation List.

A Bref call with this OP value is placed at the beginning of a Citations List Page.

OP=ecl: End Citation List.

A Bref call with this OP value is placed at the end of a Citations List Page.

OP=sbp: Start Book Page.

A Bref call with this OP value is placed at the beginning of every document page that includes references to citations.

OP=ebp: End Book Page.

A Bref call with this OP value is placed at the end of every document page that includes references to citations.

OP=aclp: Add Citations List Page.

One or more Bref calls with this OP value must be placed at the beginning of a references section. One or more Bref calls with this OP value may be placed at the beginning of a document page after the Start Book Page call (e.g., so that data in multiple citation lists is available).

OP=rcd: Render Citation Data.

A Bref call with this OP value is placed at the beginning of a references section. If document organization calls for the rendering of multiple citation lists on the same document page, each citation list is identified in a Bref/Add Citations List Page call, which should appear immediately before the relevant Bref/Render_Citation_Data call

OP=cite: Citation Definition.

A Bref call with this OP value is placed within the Citations List page in order to define the citation data associated with the NAME parameter value. A NAME parameter that evaluates to white space generates an error. This call takes an optional GROUP parameter that associates the citation data with a group.

OP=ref: Citation Reference.

A Bref call with this OP value is placed at the location in a document page where a source reference occurs. The NAME parameter specifies the particular citation referenced. A NAME parameter that evaluates to white space generates an error. The optional GROUP parameter specifies the citation's group.

OP=note: Footnote Reference.

A Bref call with this OP value is placed at the location in a document page where a footnote reference occurs. The GROUP parameter identifies the group to which the footnote belongs. A GROUP parameter that evaluates to white space generates an error. The optional NAME parameter specifies the particular footnote referenced.

Helper Templates

These are the helper templates that should be used instead of direct calls to Bref. Parameters and their values are specified. Optional parameters are indicated by placement within square brackets. Currently the templates are in the User:Dnessett/Template/Bref namespace, so at present "Bref" in the text below should be replaced with "User:Dnessett/Template/Bref".

{{Bref/Place_Holder}}.

{{Bref/Start_Citation_List}}.

{{Bref/End_Citation_List}}.

{{Bref/Start_Book_Page [| CLP=<citations list page>]}}.

{{Bref/End_Book_Page}}.

{{Bref/Add_Citations_List_Page [| CLP=<citations list page>]}}.

{{Bref/Render_Citation_Data [| GROUP=<footnote group>]}}.

{{Bref/Citation_Definition | NAME=<citation reference> [| GROUP=<citation group>]}}.

{{Bref/Citation_Reference | NAME=<citation reference> [| GROUP=<citation group>]}}.

{{Bref/Footnote_Reference | GROUP=<footnote group> [|NAME=<footnote reference>]}}.

Typical Use

Assume a book in the main namespace with the title "Tales Told By An Idiot" is organized into numerous book pages, a single citations list page and a single references page (see Example 1 in Examples). Then its pages might be formated as follows (Note: the parameter CLP=Tales_Told_By_An_Idiot/Citations_List is explicitly given, even though that is unnecessary, since its value equals the name of the default Citations List page.):

Tales_Told_By_An_Idiot/Citations_List

{{Bref/Citation_Definition | NAME=reference 1 | TEXT=Citation Information}}

{{Bref/Citation_Definition | NAME=reference 2 | TEXT=Citation Information}}

{{Bref/Citation_Definition | NAME=reference 3 | TEXT=Citation Information}}

{{Bref/Citation_Definition | NAME=reference 4 | TEXT=Citation Information}}

Tales_Told_By_An_Idiot/Some_Book_Page

{{Bref/Start_Book_Page | CLP=Tales_Told_By_An_Idiot/Citations_List}} . . .

Some text {{Bref/Citation_Reference | NAME=reference 3}}

. . .

Some other text {{Bref/Citation_Reference | NAME=reference 1}}

. . .

Tales_Told_By_An_Idiot/References_Page

Some text at the beginning of the References Page . . .

{{Bref/Add_Citations_List_Page | CLP=Tales_Told_By_An_Idiot/Citations_List}}

Cleaning Up Meaningless Back Links (Bref Helper Script)

The Bref template utilizes data held within hidden (i.e., display:none) sections when rendering reference and footnote sections. This means any back links displayed by <references/> (which is called by Render_Citation_Data) are effectively meaningless. Consequently, the Bref template is accompanied by a Helper Script that removes these links. It is simply constructed. Any textual data in a reference list entry that is not encapsulated by <cite></cite> or tags is removed by setting it to the null string.

The Bref helper script is only available to logged on users. In order to utilize it, enable the per-book and/or personal per-book gadgets and place the statement importScript('User:Dnessett/Template/Bref/Clean Back Links.js') on the appropriate page. In the case of the per-book gadget, this page is MediaWiki:Perbook/<book name>.js, For the personal per-book gadget, it is User:<your name>/per_book/<book name>.js. It is also possible to put the importScript call in the user's per-user javascript page, e.g., monobook.js for the monobook skin. While this may be useful for initial development (e.g., before you have a book with which to configure the per-book data), such use is deprecated, since the script will run on every wiki page rendered, even though the page contains no Bref formated data.

To enable the helper script for the Examples, create a page named either MediaWiki:Perbook/Bref_Examples.js (installation wide) or User:<your name>/per_book/Bref_Examples.js (per user) and add the line importScript('User:Dnessett/Template/Bref/Clean Back Links.js').

Examples

The Bref template is sufficiently flexible so that it can be used to implement different book citation styles. A selection of these styles is illustrated by several examples specified on this document's Examples page. In order to eliminate the back reference marks in the examples, use the steps described above for enabling the helper script for the Examples.

Implementation Comments, Installation Notes and Compatibility Testing

The motivation for developing the Bref template arose when it became apparent that cite extension functionality was not designed for use in books. Books are generally long and comprise many wiki pages (organized in a combination of linear and tree structures). It is rare that references in a book occur on the same wiki page as the citation data. The cite extension was designed primarily for wikipedia where this condition generally obtains.

In a perfect world someone would create a new mediawiki extension more suited for use in books. However, getting new extensions onto wikimedia foundation servers is a task of roughly the same difficulty as boiling the ocean. So, Bref was born. Admittedly, it is not a beautiful/lyrical example of programming. It works around a number of irritating cite extension "features" using several hacks. Nevertheless, it appears to work, which is always the most important criterion for a programming tool. If someone eventually decides to replace Bref with an extension for book citations, here are some thoughts that they might find useful.

If you wish to install Bref on a MediaWiki installation other than Wikibooks, read the following Installation Notes.

The Bref Template and its helper script are compatible with: Mac OS X 10.4.11 (Safari 3.2.1, Firefox 3.04, Opera 9.50), Windows Vista SP1 (IE 8.0, Firefox 3.0.10, Opera 9.64, Safari 3.1.2, Chrome 2.0.172.28), Windows XP SP3 (IE 7.0.5730.11, Firefox 3.0.1, Opera 9.64, Safari 4 Public Beta 528.17, Chrome 2.0.172.28), Linux [Ubuntu 8.04:2.6.24-23] (Firefox 3.0.5, Opera 9.50, Epiphany 2.22.2, Konqueror 3.5.10). Skins (Monobook, Chick, Classic, Cologne Blue, Modern, My Skin, Nostalgia, and Simple).

Acknowledgments

User Happy-melon suggested a way to get around the annoying "TEXT error: <ref> tags exist, but no <references/> tag was found" error when <ref> data is on a page without a <references/> call. User dark lama was very helpful answering a number of questions in the Technical Assistance section of the Reading room.