OSBib-Format v3.0

XML structure ~ Citation (In-text and Footnote style)

A collection of PHP classes to manage bibliographic formatting for OS bibliography software using the OSBib standard. Taken from and originally developed in WIKINDX (http://wikindx.sourceforge.net).

Released through http://bibliophile.sourceforge.net under the GPL licence.

If you make improvements, please consider contacting the administrators at bibliophile.sourceforge.net so that your improvements can be added to the release package.

October 2005
Mark Grimshaw (WIKINDX)
Andrea Rossato (Uniwakka)
Guillaume Gardey (BibOrb)
Christian Boulanger (Bibliograph)


INTRODUCTION
STRUCTURE


INTRODUCTION

Use CITEFORMAT::loadStyle() to load and parse the XML file into usable arrays. The XML file is logically divided into four areas, info (see bibliography_xml), citation (see below), styleCommon (see bibliography_xml) and styleTypes (see bibliography_xml).

The citation array, as returned by CITEFORMAT::loadStyle() will look something like:
Array ( [creatorStyle] => 3 [creatorOtherStyle] => 3 [creatorInitials] => 1 [creatorFirstName] => 1 [twoCreatorsSep] => & [creatorSepFirstBetween] => , [creatorListSubsequentAbbreviation] => et.al. [creatorSepNextBetween] => , [creatorSepNextLast] => & [creatorList] => 0 [creatorListMore] => 2 [creatorListLimit] => 1 [creatorListAbbreviation] => et. al. [creatorListSubsequentAbbreviationItalic] => on [creatorListAbbreviationItalic] => on [creatorListSubsequent] => 1 [creatorListSubsequentMore] => 2 [creatorListSubsequentLimit] => 1 [consecutiveCreatorTemplate] => year|: ^p.^pp.^pages [consecutiveCreatorSep] => , [template] => creator|% %year|: ^p.^pp.^pages [useInitials] => on [consecutiveCitationSep] => ; [yearFormat] => 0 [pageFormat] => 0 [titleCapitalization] => 0 [ibid] => ibid. |creator|%, %[i]title[/i]|% %(year) [idem] => idem |creator |% %(year)| (^p.^pp.^ pages). [opCit] => op. cit. |creator |% %(year)| (^p.^pp.^ pages). [followCreatorTemplate] => year|: ^p.^pp.^pages [firstChars] => ( [lastChars] => ) [citationStyle] => 1 [templateEndnoteInText] => id [templateEndnote] => citation| (^p.^pp.^ pages) [consecutiveCitationEndnoteInTextSep] => ; [firstCharsEndnoteInText] => [ [lastCharsEndnoteInText] => ] [formatEndnoteInText] => 1 [ambiguous] => 1 [ambiguousTemplate] => creator|% %[i]title[/i]|: year|: ^p.^pp.^pages [order1] => 0 [order2] => 2 [order1desc] => 0 [order2desc] => 1 [bookTemplate] => book: | creator| year [personalTemplate] => creator [personal communication]| year )

Not all elements need be present so you should always test with PHP's array_key_exists() function.

Because OSBib uses numeric indexing from 0 upwards, you should be careful to use something like:
if($citation['creatorListSubsequentLimit'] === FALSE)
...

to test for a FALSE value of an array element.


STRUCTURE

The description here relates to the various elements of the citation array. Each element will have either an INTEGER value or a STRING value.

In-text citation style:

Primary creators:
Primary creators are usually the author(s) of a resource but, depending on the type of resource, may be composers, inventors etc. etc. etc.

INTEGER creatorStyle Ordering and display of the name elements for the first of the primary creators.

INTEGER creatorOtherStyle Ordering and display of the name elements for the remaining primary creators.

	 0	=>	'Joe Bloggs'
	 1	=>	'Bloggs, Joe'
	 2	=>	'Bloggs Joe'
	 3	=>	Last name only

STRING useInitials If 'Last name only' is selected above, use initials to differentiate between creators with the same surname The value will be 'on' for yes otherwise the array element does not exist.

INTEGER creatorInitials Formatting of initials for the primary creators.

	 0	=>	'T. U. '
	 1	=>	'T.U.'
	 2	=>	'T U '
	 3	=>	'TU'

INTEGER creatorFirstName Formatting of first name for the primary creators.

	 0	=>	Print the full first name(s)
	 1	=>	Print initial(s) only

STRING twoCreatorsSep Separator in the case of just two primary creators.

STRING creatorSepFirstBetween Separator between the first two primary creators in the case where there are more than two.

STRING creatorSepNextBetween Separator between the following primary creators after the first two in the case where there are more than two.

STRING creatorSepNextLast Separator between the last two primary creators in the case where there are more than two.

STRING creatorUpperCase Uppercase/lowercase primary creator names. The value will be 'on' for yes otherwise the array element does not exist.

INTEGER creatorList Abbreviations for multiple primary creators.

	 0	=>	Print the full creator list
	 1	=>	Limit the creator list

INTEGER creatorListMore If more than this number of primary creators, format as per the limit defined here. Requires creatorList to be '1'.

INTEGER creatorListLimit Print only this number of primary creators if limit is exceeded as defined here. Requires creatorList to be '1'.

STRING creatorListAbbreviation If limit is exceeded as defined here, replace remaining primary creators with this string. Requires creatorList to be '1'.

STRING creatorListAbbreviationItalic Italicize creatorListAbbreviation. Requires creatorList to be '1'. The value will be 'on' for yes otherwise the array element does not exist.

INTEGER consecutiveCreator Consecutive and juxtaposed citations by the same primary creator(s).

	 0	=>	Print the creator list
	 1	=>	Do not print the creator list

STRING consecutiveCreatorSep String to separate consecutive and juxtaposed citations by the same primary creator(s) with if '1' is chosen for consecutiveCreator above. e.g. (Grimshaw, Gardey & Rossato 2005 p.32, 2001 pp.100-123).

Creator subsequent citations:
INTEGER creatorListSubsequent Abbreviations for multiple primary creators.
INTEGER creatorListSubsequentMore If more than this number of primary creators, format as per the limit defined here. Requires creatorListSubsequent to be '1'.
INTEGER creatorListSubsequentLimit Print only this number of primary creators if limit is exceeded as defined here. Requires creatorListSubsequent to be '1'.
STRING creatorListSubsequentAbbreviation If limit is exceeded as defined here, replace remaining primary creators with this string. Requires creatorListSubsequent to be '1'.
STRING creatorListSubsequentAbbreviationItalic Italicize creatorListSubsequentAbbreviation. Requires creatorListSubsequent to be '1'. The value will be 'on' for yes otherwise the array element does not exist.

Citations:
STRING template This is the template definition string such as creator|%, %year|: ^p.^pp.^ pages

STRING followCreatorTemplate This is the template definition string such as year|: ^p.^pp.^ pages if the citation appears in the same sentence as the creator name.

STRING followCreatorPageSplit Split the pages from the main citation placing the main citation immediately after the creator names in the text and the pages immediately following the quote. e.g. if the citation is in the form:
Grimshaw states: "WIKINDX is wonderful" [cite]123:25[/cite],
the result will be
Grimshaw (2005) states: "WIKINDX is wonderful" (p.25) rather than
Grimshaw states: "WIKINDX is wonderful" (2005, p.25).
This is activated if the citation appears in the same sentence as the creator name and works for a single creator name and a single creator name followed by 'et al.' but is likely to produce unexpected results for multiple creators. The value will be 'on' for yes otherwise the array element does not exist.

STRING firstChars
STRING lastChars
Enclose citations with, for example, parentheses.

INTEGER titleCapitalization

	 0	=>	Title as Entered/Stored in the Database
	 1	=>	Only first character of first word capitalised

STRING consecutiveCitationSep String to separate juxtaposed citations with (Grimshaw, Gardey & Rossato 2005 p.32; Boulanger 2001 pp.100-123).

STRING consecutiveCreatorTemplate This is the template definition string such as year|: ^p.^pp.^ pages for juxtaposed citations by the same creator.

STRING consecutiveCreatorSep String to separate juxtaposed citations by the same creator with (Grimshaw, 2005 p.32, 2001 pp.100-123).

INTEGER pageFormat

	 0	=>	'132-9'
	 1	=>	'132-39'
	 2	=>	'132-139'

INTEGER yearFormat

	 0	=>	"1998"
	 1	=>	"'98"
	 2	=>	"98"

Ambiguous citations:

INTEGER ambiguous

	 0	=>	Leave citation unchanged,
	 1	=>	Add a letter after the publication year
	 2	=>	Use a template

STRING ambiguousTemplate Template to use for disambiguating the citation. Requires ambiguous to be '2'.

STRING ambiguousYear Add a lowercase letter after the publication year to disambiguate the citation.

Appended bibliography ordering:

INTEGER order1, order2 and order3

	 0	=>	"First Creator",
	 1	=>	"Publication Year",
	 2	=>	"Title"

INTEGER order1Desc
INTEGER order2Desc
INTEGER order3Desc

These are the orders to be used when extracting the bibliography from the database. order1Desc, order2Desc and order3Desc are '0' for 'ascending' and '1' for descending.

Endnote citation style:

Formatting of citations in the text:
STRING templateEndnoteInText This is the template definition string such as id.

STRING firstCharsEndnoteInText
STRING lastCharsEndnoteInText
Enclose citations with, for example, parentheses.

INTEGER formatEndnoteInText

	 0	=>	"Normal",
	 1	=>	"Superscript", 
	 2	=>	"Subscript"

STRING consecutiveCitationEndnoteInTextSep String to separate juxtaposed citations with ([3; 4]).

INTEGER endnoteStyle

	 0	=>	"Endnotes: incrementing",
	 1	=>	"Endnotes: same ID for same resource",
	 2	=>	"Footnotes: incrementing"

STRING sameIdOrderBib If the value is 'on' and the same id numbers are being used (as above), the ordering of the id numbers in the text will follow the ordering of the appended bibliography rather than incrementing from 1. Otherwise, if the array element does not exist, id numbers will increment and the appended bibliography will follow the order of the id numbers in the text. NB. When using this option, endnotes for RTF exporting are faked (they will simply be plain text) because RTF cannot handle endnotes that do not increment in numerical order. In all other cases, RTF endnotes will be real endnotes as recognised by Word and OpenOffice.org.

Formatting of citations in the appended bibliography:
STRING firstCharsEndnoteID
STRING lastCharsEndnoteID
Enclose citation ID numbers with, for example, parentheses.

INTEGER formatEndnoteID Format the ID number.

	 0	=>	"Normal",
	 1	=>	"Superscript",
	 2	=>	"Subscript"

STRING templateEndnote This is the template definition string such as citation|: pages. If 'citation' exists in the template, then the full bibliographic citation as defined in the bibliography section of OSBib shyould be used and all other fields except 'pages' should be discarded.

STRING ibid Replace consecutive citations for the same resource and the same page with this template. If no template is given, the behaviour should follow that of templateEndnote.

STRING idem Replace consecutive citations for the same resource but a different page with this template. If no template is given, the behaviour should follow that of templateEndnote.

STRING opCit Replace previously cited resources with this template. If no template is given, the behaviour should follow that of templateEndnote.