[sword-devel] Miscellaneous Sword API Questions

[Jeremy Erickson]

I have a few questions about the Sword API, relevant to coding the Sword 
plugin for BibleMemorizer 0.3.

I plan to have a second identifier for the book in each verse, as there will 
be some differences between the Sword naming and the default BibleMemorizer 
plugin (e.g. "Revalation" instead of "Revalation of John", "2 Corinthians" 
instead of "II Corinthians").  The identifier will have a testament 
identification as well as a book number within each testament.  Here on (as 
well as in the code), this will be referred to as the "uBook", where "u" 
stands for "universal".  This system should also prevent problems if someone 
creates a non-English plugin for BibleMemorizer.  In addition, it will make 
it easier to sort the verses, regardless of what plugin was used when a given 
file was created.  This brings up the following questions:

1.) Can I rely on the values from the "Testament()" function within VerseKey?  
In other words, will the Old Testament always be 1 and the New Testament 2?  
Would the Apocrypha, for example, be 3?  Or would it be 2 and push the New 
Testament back to 3?  Would the New Testament still be 2 in a NT-only 
translation?  For the purposes of BibleMemorizer's plugin system, the same 
testament identifier in the uBook needs to be consistent across translations 
and across plugins.  A reference to the book of Mark should always refer to 
the book of Mark, not the second book of the Apocrypha.  It need not be the 
same as Sword if a consistent algorithm can be used to convert the two.  (API 
suggestion:  There should be a consistent way to do this.  An enum would make 
this very easy.)

2.) What is the most efficient way to tell if Sword recognizes a particular 
book?  I would like the Sword plugin to fall back onto using the uBook if the 
book name passed to it is not recognized, but only then.  Users will not see 
the uBook unless they manually browse the XML output, so the book name should 
be the primary determination to avoid unexpected behavior.

A few other questions I have:

3.) What is the best way to check how many chapters a given book has?  Is 
there a function that returns this, or do I need to deal with the struct that 
has this information?

4.) Does Sword use UTF-8 encoding by default?  Is there a way to globally 
force UTF-8 usage, or would I have to manually convert with the functions in 
the *utf8.h files?  (For consistency, I would like the plugins to always use 
UTF-8 for strings.  I plan to use char arrays instead of QStrings so that the 
plugins might me more generally useful to other programs that just need 
simple features from Sword or any other interface for which a plugin may be 
written.)

5.) Is there a way to prevent Sword from accepting verses like "Romans 1:40" 
and then parsing them to (in this case) "Romans 2:8"?  This behavior might 
not be what users expect.  Is there a way to check if the verse reference is 
really valid?

6.) Does Sword offer categorizations of the books of the Bible (e.g. "Gospels" 
and "Prophets")?  I know BibleTime has these categorizations available when 
searching.  Is this a BibleTime feature or a Sword feature?  If it is a Sword 
feature, how is it accessed?

Thanks in advance.

-Jeremy Erickson