Difference between revisions of "DevTools:SWORD"

From CrossWire Bible Society
Jump to: navigation, search
(Update for 1.6.0)
Line 5: Line 5:
  
 
== Locale file layout ==
 
== Locale file layout ==
 
Requires update!! Not correct after 1.5.11
 
 
 
Locales require a few things.  Let's step through the German locale:
 
Locales require a few things.  Let's step through the German locale:
  
Line 36: Line 33:
 
   
 
   
 
  [Book Abbrevs]
 
  [Book Abbrevs]
  1 C=46
+
  1 C=1Cor
  1 CHRONICLES=13
+
  1 CHRONICLES=1Chr
  1 CORINTHIANS=46
+
  1 CORINTHIANS=1Cor
  1 JN=62
+
  1 JN=1Jn
  
 
These are the abbreviations for each book and are REQUIRED for the
 
These are the abbreviations for each book and are REQUIRED for the
Line 45: Line 42:
 
just abbreviations; they tell the parser how to incrementally parse
 
just abbreviations; they tell the parser how to incrementally parse
 
versekey text.  Notice that 1 Chronicles would come, alphabetically
 
versekey text.  Notice that 1 Chronicles would come, alphabetically
before 1 Corinthians.  The above entries say: book 46 (1 Corinthians)
+
before 1 Corinthians.  The above entries say: 1Cor (which is the OSIS book id for 1 Corinthians)
 
has precedence up through "1 C", any character beyond that will
 
has precedence up through "1 C", any character beyond that will
 
disambiguate the entry anyway, so the default 1 CHRONICLES or 1
 
disambiguate the entry anyway, so the default 1 CHRONICLES or 1
CORINTHIANS entries would take over from there.
+
CORINTHIANS entries would take over from there.
 +
 
 +
Please note that the English abbreviations are no longer required to
 +
be in the abbreviations section as they are in there by default;
 +
in the example above they are in there for demonstration purposes.
  
 
IMPORTANT:
 
IMPORTANT:
  
1) There MUST be at least 1 abbreviation entry for each book name
+
There MUST be at least 1 abbreviation entry for each book name
 
comprised of a toupper (uppercase function) of the entire string
 
comprised of a toupper (uppercase function) of the entire string
 
EXACTLY as you have translated it in the [Text] section.
 
EXACTLY as you have translated it in the [Text] section.
 
2) The English abbreviation entries MUST remain in the locale.
 
The precedence entries may be tweaked, especially if you find them
 
interfering with your precedence entries, but the entire book name--
 
as stated in the first requirement above, must remain for English book
 
names.
 
  
 
Following are the REQUIRED entries from our excerpt book names above.
 
Following are the REQUIRED entries from our excerpt book names above.
 
+
  1. MOSE=Gen
GENESIS=1
+
  2. MOSE=Ex
EXODUS=2
+
  3. MOSE=Lev
LEVITICUS=3
+
+
# <snip rest of english abbrevs>
+
+
  1. MOSE=1
+
  2. MOSE=2
+
  3. MOSE=3
+
  
 
That's it for requirements.  Tuning your locale can be important for the  
 
That's it for requirements.  Tuning your locale can be important for the  
Line 78: Line 66:
 
precedence if, for example, you find you are getting taken to the wrong  
 
precedence if, for example, you find you are getting taken to the wrong  
 
entries from text like: "Ma 1:1" (would be Malachi by default because of  
 
entries from text like: "Ma 1:1" (would be Malachi by default because of  
alphabetical precedence, but might want Matthew or Mark).
+
alphabetical precedence, but might want Matthew or Mark).  
 +
In this case, you would put in an entry MA=Matt or MA=Mark
  
 
You can test your locale with the sword/tests/parsekey test program (this  
 
You can test your locale with the sword/tests/parsekey test program (this  
Line 85: Line 74:
 
how they parse.
 
how they parse.
  
Notice especially that indicating a range is usually done with '-', for example Gen 1-Gen 2. Therefore the '-' character in book names will cause problems with the applications. Currently there is no solution to this. Other non-alphabetic characters are also problematic.
+
Notice especially that indicating a range is usually done with '-', for example Gen 1-Gen 2. Therefore the '-' character in book names will cause problems with the applications.  
 +
Currently there is no solution to this, except for in BPBible, which allows this. Other non-alphabetic characters may also be problematic.
 
   
 
   
 
---
 
---
 
Submissions should be sent to patches@crosswire.org
 
Submissions should be sent to patches@crosswire.org

Revision as of 22:05, 1 July 2009

Documentation

API Documentation

See The SWORD Project - API documentation for the current (or very nearly current) SVN HEAD. Starting with the next version of the documentation (post 1.5.11), there will also be other documentation placed there for developers to keep track of.

Locale file layout

Locales require a few things. Let's step through the German locale:

excerpts from /sword/locales/de.conf:

[Meta]
Name=de
Description=German

The above information is used to define the locale. They should be fairly obvious. Name should be taken from a standard abbrev, probably returned from echo $LANG. Please understand that this, and all entries are case sensitive.

The following entries are translation strings for anything you might want. REQUIRED are the book names of the Bible. Other things might be option name, value, tip, translations, or any text returned from the engine. It may not work right now, but if it doesn't, please post a message that you found a constant string in the engine not being translated.

[Text]
Genesis=1. Mose
Exodus=2. Mose
Leviticus=3. Mose

# <snipped rest of book names>

[Book Abbrevs]
1 C=1Cor
1 CHRONICLES=1Chr
1 CORINTHIANS=1Cor
1 JN=1Jn

These are the abbreviations for each book and are REQUIRED for the locale to work correctly in the engine. They are actually more than just abbreviations; they tell the parser how to incrementally parse versekey text. Notice that 1 Chronicles would come, alphabetically before 1 Corinthians. The above entries say: 1Cor (which is the OSIS book id for 1 Corinthians) has precedence up through "1 C", any character beyond that will disambiguate the entry anyway, so the default 1 CHRONICLES or 1 CORINTHIANS entries would take over from there.

Please note that the English abbreviations are no longer required to be in the abbreviations section as they are in there by default; in the example above they are in there for demonstration purposes.

IMPORTANT:

There MUST be at least 1 abbreviation entry for each book name comprised of a toupper (uppercase function) of the entire string EXACTLY as you have translated it in the [Text] section.

Following are the REQUIRED entries from our excerpt book names above.

1. MOSE=Gen
2. MOSE=Ex
3. MOSE=Lev

That's it for requirements. Tuning your locale can be important for the user experience. Many [Book Abbrevs] entries may be added to assign precedence if, for example, you find you are getting taken to the wrong entries from text like: "Ma 1:1" (would be Malachi by default because of alphabetical precedence, but might want Matthew or Mark). In this case, you would put in an entry MA=Matt or MA=Mark

You can test your locale with the sword/tests/parsekey test program (this program is in the SWORD source along with several other programs that are used to validate the configuration files) and try different strings to see how they parse.

Notice especially that indicating a range is usually done with '-', for example Gen 1-Gen 2. Therefore the '-' character in book names will cause problems with the applications. Currently there is no solution to this, except for in BPBible, which allows this. Other non-alphabetic characters may also be problematic.

--- Submissions should be sent to patches@crosswire.org