Difference between revisions of "Alternate Versification/Canon Definition Format"

Revision as of 18:46, 8 July 2011

Canon definition files are found in the sword-tools SVN repository (https://crosswire.org/svn/sword-tools/trunk/versification/).

Within this repository are a number of different files aimed at generating both canon.h analogues for alternative versification systems and the canon_abbrevs.h file, which defines the abbreviations used by all Sword Bibles.

The files named canon.*.xml define sets of books in various collections. E.g. canon.bible.xml defines all the books of the Bible (in any versification system). This is the only canon.*.xml file currently being employed in Sword. (Others, such as canon.af.xml, canon.nta.xml, and canon.otp.xml, which define Apostolic Fathers, NT apocrypha, & OT pseudepigrapha respectively, may be employed in a future version.)

Header & footer

The canon.*.xml files can be validated with the canon.xsd XML Schema. The format starts with a header:

<?xml version="1.0" encoding="UTF-8"?>
<collection xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="canon.xsd">

And concludes by closing the collection:

</collection>

Book definitions

The contents of the <collection> element is a set of book definitions such as the following, for 1 Chronicles. Book definitions are enclosed in a <book> element.

<book>
 <id>1Chr</id>
 1Ch
 1Chron
 1Chro
 1C
 1Pa
 1Par
 1Para
 1Paral
 1Paralip
 <name>I Chronicles</name>
 <name>IChronicles</name>
 <name>1 Chronicles</name>
 <name>1Chronicles</name>
 <name>I Paralipomenon</name>
 <name>IParalipomenon</name>
 <name>1 Paralipomenon</name>
 <name>1Paralipomenon</name>
</book>

<id>

The first element within the <book> is an <id> element. This contains the unique osisID for the book, used broadly within Sword.

<abbr>

Following the <id> are an arbitrary number (>=0)of <abbr> elements. These values are used in the creation of versification definition files (canon.h analogues). These abbreviations will be recognized when they appear in VPL or IMP files processed by v11msys.pl, but they are not used by the Sword API directly. (They do not get copied into canon_abbrevs.h in any way.)

<abbr> elements also accept a mode attribute, as in <abbr mode="westminster">1C</abbr> above. When an abbreviation mode value is specified by the --abbr attribute of v11nsys.pl, if that mode value equals the mode attribute on the <abbr> element, then the specified abbreviation will override any other mapping for that abbreviation. In the above case, "1C" ordinarily maps to 1 Corinthians. But if v11nsys.pl is given the argument "--abbr westminster", then "1C" will instead map to 1 Chronicles.

<name>

Following the <abbr> definitions are an arbitrary number (>0) of <name> definitions. These values serve three purposes:

1. As with <abbr>, all <name> values are recognized by v11nsys.pl as book abbreviations for the purpose of creating canon.h analogues for different versification systems.
2. All <abbr> values will be used to build the abbreviations found in canon_abbrevs.h.
3. The first <abbr> value is special, because this value will be used as the English name of the book in Sword.