# 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`.