Difference between revisions of "DevTools:conf Files"

From CrossWire Bible Society
Jump to: navigation, search
(→‎Elements to indicate features)
(→‎Copyright & Licensing related elements)
 
(291 intermediate revisions by 8 users not shown)
Line 1: Line 1:
−
=Creating a .conf File=
+
This page describes important information about module configuration (.conf) files. All SWORD modules require one.  
−
==.conf File Layout==
 
−
The conf file tells the Sword engine how to treat installed module files, etc. which kind of markup they contain, and so forth.
 
  
−
Below is a listing of the possible directives in that file. Each of these directives of the form key=value. Some keys can be repeated. Some can have values that span more than 1 line with '\' at the end of a line indicating that the text on the next line continues the value. Some values allow RTF and some allow HTML <a href="xxx">label</a>hypertext links. HTML is not allowed otherwise.
+
Please look also at our detailed and commented [[Tutorial:Writing Conf files|tutorial]].
  
−
Note on RTF, only the following are allowed:
+
== Key elements of a SWORD module.conf ==
−
* \qc - for centering
+
 
−
* \par - for paragraph breaks
+
Some keys can be repeated. Many not.
−
* \pard - for resetting paragraph attributes, i.e. turning off centering.
+
 
−
* \u{num}? - for unicode characters, where {num} is a signed, 16-bit representation of the code point and where ? is the  ASCII character used in case unicode is not supported. If the {num} is less than 0 then add 65536 to it. This should only be used in modules that have an Encoding=UTF-8, but using the actual UTF-8 character is preferred.
+
Some can have values that span more than 1 line with '\' at the end of a line indicating that the text on the next line continues the value. Don't use continuation unless allowed. It will produce different results in different front ends.
 +
 
 +
RTF is allowed in some values.
 +
 
 +
Some allow HTML <a href="xxx">label</a>hypertext links. HTML is not allowed otherwise.
 +
 
 +
Values specifications are shown as '''<content spec>'''. The < and > are not to be included.
 +
 
 +
Enumerated values are shown in '''bold'''. These should be used exactly as given and no other values should be used.
  
−
Enumerated values are shown in bold. These should be used exactly as given and no other values should be used.
+
The order of elements specified in a conf file is immaterial, except where specified otherwise.
  
 
===Required Elements===
 
===Required Elements===
Line 21: Line 27:
 
! width="10%"|Allows
 
! width="10%"|Allows
 
|-  
 
|-  
−
| [name]
+
| [ModName]
−
| Each conf file begins with [name], replacing "name" with be a short well known abbreviation. This must be on the first line, and start the first line. It can only contain A-Z, a-z, 0-9 and _.<br/>
+
| Each conf file begins with a unique identifier for a module placed within brackets, e.g., [KJV1611]. This must be first in the file. Valid characters for this abbreviation are limited to [https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions PCRE] class <tt>[A-Za-z0-9_]</tt>.<ref>That excludes the space and hyphen characters!</ref><br/>
−
The name of the file should be the lowercase of this name followed by .conf. For example, [MyModule] would be mymodule.conf.
+
The Abbreviation element is meant to allow for localization of this field.<br/>
 +
The .conf file should be named the lowercase of this abbreviation followed by .conf. For example, kjv1611.conf.
 
| &nbsp;
 
| &nbsp;
 
| &nbsp;
 
| &nbsp;
 +
|-
 +
| Abbreviation<ref>We advise against explicitly declaring a redundant Abbreviation identical to the ModName.  Abbreviation values should try to be unique to avoid user confusion.</ref>
 +
|
 +
'''&lt;string&gt;'''<br/>
 +
The abbreviation displayed to the user. If not supplied, the unique ModName will be used.  This field allows for localization-- showing a different abbreviation depending on the user's locale.
 +
 +
| [ModName]
 +
| [[DevTools:conf Files#Localization|Localization]]
 +
|-
 +
| Description
 +
|
 +
'''&lt;string&gt;'''<br/>
 +
This is a short (1 line) title of the module.
 +
| &nbsp;
 +
| [[DevTools:conf Files#Localization|Localization]]
 
|-  
 
|-  
 
| DataPath
 
| DataPath
−
| &lt;relative system path&gt;
+
| &lt;relative system path pointing to the data files&gt;
−
DataPath is the path to the module relative to the SWORD module root directory. This path should start with "./modules". If the DataPath indicates a directory it should end with a '/'. Otherwise the module name is both the directory and the prefix for each file in that directory.
+
DataPath is the path to the module data files relative to the SWORD module library root directory. This path should start with "./modules". If the DataPath indicates a directory it should end with a '/'. Otherwise the module name is both the directory and the prefix for each file in that directory. Although DataPath can point to any folder or files under the root of the SWORD module library, the following conventions are recommended and must be used for modules wishing to be included in a CrossWire repository:
−
Typical paths are for a module named [mymodule] are:
+
 
 +
Paths used for a module named [MyModule], depending on<BR>(a) the type of module (Bible text, commentary, lexicon or dictionary<ref>Daily devotionals & glossaries go in subdirectories under lexdict. A glossary is between two languages.</ref>, general book) and<BR>(b) the data driver (ModDrv parameter) are:
  
 
:./modules/texts/rawtext/mymodule/
 
:./modules/texts/rawtext/mymodule/
−
 
+
:./modules/texts/rawtext4/mymodule/
 
:./modules/texts/ztext/mymodule/
 
:./modules/texts/ztext/mymodule/
−
 
+
:./modules/texts/ztext4/mymodule/
 
:./modules/comments/zcom/mymodule/
 
:./modules/comments/zcom/mymodule/
−
 
+
:./modules/comments/zcom4/mymodule/
 
:./modules/comments/hrefcom/mymodule/
 
:./modules/comments/hrefcom/mymodule/
−
 
 
:./modules/comments/rawcom/mymodule/
 
:./modules/comments/rawcom/mymodule/
−
 
 
:./modules/comments/rawcom4/mymodule/
 
:./modules/comments/rawcom4/mymodule/
−
 
 
:./modules/comments/rawfiles/mymodule/
 
:./modules/comments/rawfiles/mymodule/
−
 
 
:./modules/lexdict/zld/mymodule/mymodule
 
:./modules/lexdict/zld/mymodule/mymodule
−
 
 
:./modules/lexdict/rawld/mymodule/mymodule
 
:./modules/lexdict/rawld/mymodule/mymodule
−
 
 
:./modules/lexdict/rawld/devotionals/mymodule/mymodule
 
:./modules/lexdict/rawld/devotionals/mymodule/mymodule
−
 
 
:./modules/lexdict/rawld/glossaries/mymodule/mymodule
 
:./modules/lexdict/rawld/glossaries/mymodule/mymodule
−
 
 
:./modules/lexdict/rawld4/mymodule/mymodule
 
:./modules/lexdict/rawld4/mymodule/mymodule
−
 
 
:./modules/genbook/rawgenbook/mymodule/mymodule
 
:./modules/genbook/rawgenbook/mymodule/mymodule
  
−
But when it really comes down to it, a valid path could be:
 
−
 
−
:./xxx/ or ./xxx/mymodule
 
−
| &nbsp;
 
−
| &nbsp;
 
−
|-
 
−
| Description
 
−
| &lt;string&gt;<br/>
 
−
This is a short (1 line) title of the module.
 
 
| &nbsp;
 
| &nbsp;
 
| &nbsp;
 
| &nbsp;
 
|-  
 
|-  
 
| ModDrv
 
| ModDrv
−
| <b>RawText</b> (for uncompressed Bibles)<br/><b>zText</b> (for compressed Bibles)<br/><b>RawCom</b> (for uncompressed Commentaries)<br/><b>RawCom4</b> (for uncompressed Commentaries having entries greater than 32K bytes)<br/><b>zCom</b> (for compressed Commentaries)<br/><b>HREFCom</b> (currently no module uses this type)<br/><b>RawFiles</b> (for Personal Commentary)<br/><b>RawLD</b> (for uncompressed Dictionaries)<br/><b>RawLD4</b> (for uncompressed Dictionaries having entries greater than 32K bytes)<br/><b>zLD</b> (for compressed Dictionaries)<br/><b>RawGenBook</b> (for uncompressed tree keyed modules)
+
|
 +
'''RawText''' (for uncompressed Bibles)<br/>
 +
'''RawText4''' (for uncompressed Bibles having entries greater than 64K bytes)<ref name="text4">e.g. If the Bible contains large introduction sections</ref><br/>
 +
'''zText''' (for compressed Bibles)<br/>
 +
'''zText4''' (for compressed Bibles having entries greater than 64K bytes)<ref name="text4">e.g. If the Bible contains large introduction sections</ref><ref name="sv">zText4 & zCom4 modules require MinimumVersion=1.8 or later.</ref><br/>
 +
'''RawCom''' (for uncompressed Commentaries)<br/>
 +
'''RawCom4''' (for uncompressed Commentaries having entries greater than 64K bytes)<br/>
 +
'''zCom''' (for compressed Commentaries)<br/>
 +
'''zCom4''' (for compressed Commentaries having entries greater than 64K bytes)<ref name="sv">zText4 & zCom4 modules require SwordVersion=1.8 or later.</ref><br/>
 +
'''HREFCom''' (each module entry must be only a URL to the body for the entry; experimental)<br/>
 +
'''RawFiles''' (stores each entry in a simple text file in the datapath; recommended for Personal Commentary)<br/>
 +
'''RawLD''' (for uncompressed Dictionaries)<br/>
 +
'''RawLD4''' (for uncompressed Dictionaries having entries greater than 64K bytes)<br/>
 +
'''zLD''' (for compressed Dictionaries)<br/>
 +
'''RawGenBook''' (for uncompressed tree keyed modules)
 
| &nbsp;
 
| &nbsp;
 
| &nbsp;
 
| &nbsp;
 
|}
 
|}
  
−
===Elements to indicate features ===
+
<references />
 +
 
 +
===Required Elements with defaults ===
  
 
{|  width="100%" border="1" class="sortable"
 
{|  width="100%" border="1" class="sortable"
Line 83: Line 104:
 
! width="10%"|Default Value
 
! width="10%"|Default Value
 
! width="10%"|Allows
 
! width="10%"|Allows
 +
|-
 +
| SourceType<ref>Omitting this for a non-plaintext module has unpredictable effects.</ref>
 +
|
 +
'''Plaintext'''<br/>
 +
'''OSIS''' ([http://www.bibletechnologies.net Open Scriptural Information Standard])<br/>
 +
'''TEI''' ([http://www.tei-c.org Text Encoding Initiative])<br/>
 +
Specifies the '''markup''' used in the module. The preferred markup is OSIS. TEI is preferred for dictionaries until OSIS supports dictionaries. While SourceType has a default, it is a best practice to specify it.<br/>
 +
 +
Legacy modules may have a key here stating:
 +
 +
'''GBF''' ([http://www.ebible.org/bible/gbf.htm General Bible Format])<br/>
 +
'''ThML''' ([http://www.ccel.org/ThML Theological Markup Language])<br/>
 +
 +
In SWORD, for modules encoded with ThML, OSIS or TEI, each verse, dictionary entry, and book division needs to be well-formed XML or it will result in display problems in some front-ends.
 +
| Plaintext
 +
| &nbsp;
 +
|-
 +
| Encoding
 +
|
 +
'''UTF-8'''<br/>
 +
'''UTF-16'''<br/>
 +
'''SCSU''' ([http://en.wikipedia.org/wiki/Standard_Compression_Scheme_for_Unicode Standard Compression Scheme for Unicode])<br/>
 +
Indicates how the text in the conf and in the module are encoded.
 +
 +
The preferred encoding of texts is UTF-8. Other than Hebrew, UTF-8 modules must be encoded with [http://unicode.org/reports/tr15/ Normalization Form C (NFC)]. Biblical Hebrew requires special handling.<ref>Unicode normalization can easily break Biblical Hebrew text. See on page 9 in the [http://www.sbl-site.org/Fonts/SBLHebrewUserManual1.5x.pdf SBL Hebrew Font User Manual].</ref> A few other languages may require special handling.<ref>e.g. If they are mentioned in Table 10 in the [http://unicode.org/reports/tr15/#Corrigendum_5_Sequences Corrigendum 5 Sequences].</ref><ref>The improper normalization of exceptional codepoints can be prevented by inserting a [https://en.wikipedia.org/wiki/Combining_Grapheme_Joiner Combining Grapheme Joiner].</ref>
 +
 +
To date, no modules use UTF-16 or SCSU. Legacy modules may hold a key here '''Latin-1''' referring solely to Windows Codepage 1252, a superset of ISO-8859-1. Front-end implementors wishing to use such modules should use "cp1252" or "windows1252" explicitly, not "Latin-1" provided by some programming language libraries.''
 +
| Latin-1
 +
| &nbsp;
 
|-  
 
|-  
 
| CompressType
 
| CompressType
−
| <b>ZIP</b><br/><b>LZSS</b>
+
|
−
Used to indicate how a compressed modules (zText, zCom, & zLD) is compressed.
+
'''ZIP'''<br/>
−
ZIP is the preferred format. And as of today, no compressed modules use LZSS.
+
'''LZSS''' ([http://en.wikipedia.org/wiki/Lempel%E2%80%93Ziv%E2%80%93Storer%E2%80%93Szymanski Lempel Ziv Storer Szymanski])<br/>
 +
'''BZIP2'''<br/>
 +
'''XZ'''<br/>
 +
Used for modules having a ModDrv of zText, zCom or zLD to indicate the compression algorithm.
 +
While CompressType has a default, it is best practice to specify it.
 +
ZIP is the preferred format.
 
| LZSS
 
| LZSS
 
| &nbsp;
 
| &nbsp;
 
|-  
 
|-  
 
| BlockType
 
| BlockType
−
| <b>BOOK</b><br/><b>CHAPTER</b><br/><b>VERSE</b><br/>
+
|
−
Used for zText and zCom to indicate how much of the work is compressed into a block. The trade off is size for speed, with BOOK taking the least overall space and the longest time and VERSE taking the greatest overall space and the least time. While BlockType has a default, it is a best practice to specify it. Most Bibles use BOOK and larger Commentaries use CHAPTER. To date, no module uses VERSE.
+
'''BOOK'''<br/>
 +
'''CHAPTER'''<br/>
 +
'''VERSE'''<br/>
 +
Used for modules having a ModDrv of zText (Bibles) and zCom (Commentaries) to indicate how much of the work is compressed into a block. The trade off is size for speed, with BOOK taking the least overall space and the longest time and VERSE taking the greatest overall space and the least time. While BlockType has a default, it is a best practice to specify it. Most Bibles use BOOK and larger Commentaries use CHAPTER. To date, no module uses VERSE.
 
| CHAPTER
 
| CHAPTER
 
| &nbsp;
 
| &nbsp;
 
|-  
 
|-  
 
| BlockCount
 
| BlockCount
−
| &lt;integer&gt;<br/>
+
|
−
Used for zLD to indicate the number of entries in a compressed block. Higher values will make the module slower, but smaller.
+
'''&lt;integer&gt;'''<br/>
 +
Used for modules having a ModDrv of zLD to indicate the number of entries in a compressed block. Higher values will make the module slower, but smaller. It is best practice to take the default and not specify it.
 
| 200
 
| 200
 
| &nbsp;
 
| &nbsp;
 
|-  
 
|-  
−
| KeyType
+
| Versification
−
| <b>TreeKey</b><br/><b>VerseKey</b><br/>
+
|
−
Used for RawGenBook to indicate whether the module contains a book or a Bible. At this time VerseKey is being developed as the solution for [[Alternate_Versification&#124;alternate versification]].
+
'''Calvin'''<br/>
−
| TreeKey
+
'''Catholic'''<br/>
 +
'''Catholic2'''<br/>
 +
'''Darby_Fr'''<br/>
 +
'''German'''<br/>
 +
'''KJV'''<br/>
 +
'''KJVA'''<br/>
 +
'''LXX'''<br/>
 +
'''Leningrad'''<br/>
 +
'''Luther'''<br/>
 +
'''MT'''<br/>
 +
'''NRSV'''<br/>
 +
'''NRSVA'''<br/>
 +
'''Orthodox'''<br/>
 +
'''Segond'''<br/>
 +
'''Synodal'''<br/>
 +
'''SynodalProt'''<br/>
 +
'''Vulg'''<br/>
 +
Used to specify the versification employed by a Bible module<ref>i.e. Specify this ''only'' for a module that uses '''VerseKey'''.</ref>. Refer to [[Alternate Versification]].
 +
| KJV
 
| &nbsp;
 
| &nbsp;
 
|-  
 
|-  
 
| CipherKey
 
| CipherKey
−
| &lt;string&gt;<br/>
+
|
−
Contains the unlock key for enciphered modules. A good key is something that is hard to guess. Typically in a format matching the pattern: /[0-9]{4}[A-Za-z]{4}[0-9]{4}[A-Za-z]{4}/. Internally the key can be any byte sequence from 1 to 255 bytes in length. But this file needs it to be readable, plain text, without leading or trailing spaces. Leave a blank line ("CipherKey=") to indicate that the module is enciphered but has no unlock key. (Omit for unlocked modules.)
+
'''&lt;string&gt;'''<br/>
 +
Indicates that a module is enciphered and that the module is (un)locked. When the key has no value ("CipherKey=") the module is locked. When it has a value, the module is unlocked.
 +
 
 +
A good key is something that is hard to guess. Typically in a format matching the pattern: /[0-9]{4}[A-Za-z]{4}[0-9]{4}[A-Za-z]{4}/. Internally the key can be any byte sequence from 1 to 255 bytes in length. But it needs to be readable, plain text, without leading or trailing spaces.
 
| &nbsp;
 
| &nbsp;
 
| &nbsp;
 
| &nbsp;
 
|-  
 
|-  
−
| Versification
+
| KeyType
−
| <b>KJV</b><br/><b>KJVA</b><br/><b>NRSV</b><br/><b>NRSVA</b><br/><b>Leningrad</b><br/><b>MT</b>
+
|
−
Used to specify the versification employed by a Bible module.
+
'''TreeKey'''<br/>
−
| KJV
+
'''VerseKey'''<br/>
 +
Used for RawGenBook to indicate whether the module contains a book or a Bible. At this time VerseKey is not yet supported and is being developed as a solution for Bibles which do not conform to any supported versification system in SWORD. It is best practice to take the default and not specify it.
 +
| TreeKey
 +
| &nbsp;
 +
|-
 +
| CaseSensitiveKeys
 +
|
 +
Used for Dictionaries whose keys are case sensitive. This key is used to suppress normalization to UPPER CASE before comparison.<br/>
 +
Only allowable value: '''true'''
 +
| false
 
| &nbsp;
 
| &nbsp;
 
|}
 
|}
 +
 +
<references />
  
 
=== Elements required for proper rendering ===
 
=== Elements required for proper rendering ===
Line 131: Line 222:
 
|-  
 
|-  
 
| GlobalOptionFilter
 
| GlobalOptionFilter
−
| <b>GBFStrongs</b> (For GBF texts having Strong's Numbers)<br/><b>GBFFootnotes</b> (For GBF texts having footnotes)<br/><b>GBFMorph</b> (For GBF texts having morphology information)<br/><b>GBFHeadings</b> (For GBF texts having headings)<br/><b>GBFRedLetterWords</b> (For GBF texts marking the Words of Christ)<br/><b>ThMLStrongs</b> (For THML texts having Strong's Numbers)<br/><b>ThMLFootnotes</b> (For THML texts having footnotes)<br/><b>ThMLScripref</b> (For THML texts having cross references)<br/><b>ThMLMorph</b> (For THML texts having morphology information)<br/><b>ThMLHeadings</b> (For THML texts having headings)<br/><b>ThMLVariants</b> (For THML texts having variant readings)<br/><b>ThMLLemma</b> (For THML texts having lemmas)<br/><b>UTF8Cantillation</b> (For Hebrew texts having cantillation marks)<br/><b>UTF8GreekAccents</b> (For Greek texts having accents)<br/><b>UTF8HebrewPoints</b> (For Hebrew texts having vowel points)<br/><b>OSISStrongs</b> (For OSIS texts having Strong's Numbers)<br/><b>OSISFootnotes</b> (For OSIS texts having informational notes)<br/><b>OSISScripref</b> (For OSIS texts having cross reference type notes)<br/><b>OSISMorph</b> (For OSIS texts having morphology information)<br/><b>OSISHeadings</b> (For OSIS texts having non-canonical headings)<br/><b>OSISRedLetterWords</b> (For OSIS texts marking the Words of Christ)<br/><b>OSISLemma</b> (For OSIS texts having lemmas)<br/><b>OSISRuby</b> (For Japanese OSIS texts with [http://www.w3.org/TR/ruby/ ruby]: Kana glosses of Han characters)<br/>
+
|
−
Each of these filters removes/hides the text's feature, when activated by the application.
+
'''UTF8Cantillation''' (For Hebrew texts having cantillation marks)<ref>See https://en.wikipedia.org/wiki/Cantillation</ref><br/>
−
These filters are applied in the order that they are listed in the conf.
+
'''UTF8GreekAccents''' (For Greek texts having accents)<ref>For detailed background, see https://en.wikipedia.org/wiki/Greek_diacritics</ref><ref>This filter can have undesirable side-effects when applied to non-Greek text!</ref><br/>
 +
'''UTF8HebrewPoints''' (For Hebrew texts having vowel points)<ref>See https://en.wikipedia.org/wiki/Niqqud</ref><br/>
 +
'''UTF8ArabicPoints''' (For Arabic texts having vowel points)<ref>See https://en.wikipedia.org/wiki/Arabic_diacritics</ref><br/>
 +
'''OSISLemma''' (For OSIS texts having lemmas)<ref>Must precede OSISStrongs.</ref><br/>
 +
'''OSISMorphSegmentation''' (For OSIS texts having morphological segmentation elements)<ref>Currently, only some JSword based front-ends seem to support this feature. The SWORD engine has the switch available, but no change in output is effected.</ref><br/>
 +
'''OSISStrongs''' (For OSIS texts having Strong's Numbers)<ref name="strongs">See https://en.wikipedia.org/wiki/Strong%27s_Concordance#Strong.27s_numbers</ref><br/>
 +
'''OSISFootnotes''' (For OSIS texts having informational notes)<br/>
 +
'''OSISScripref''' (For OSIS texts having [[OSIS Bibles#Marking_cross-references_note|cross reference]] type notes)<br/>
 +
'''OSISMorph''' (For OSIS texts having morphology information)<br/>
 +
'''OSISHeadings''' (For OSIS texts having non-canonical headings)<br/>
 +
'''OSISVariants''' (For OSIS texts having variant readings)<br/>
 +
'''OSISRedLetterWords''' (For OSIS texts marking the Words of Christ)<ref name="red">See https://en.wikipedia.org/wiki/Red_letter_edition</ref><br/>
 +
'''OSISGlosses''' (For OSIS texts with glosses)<ref>Minimum SWORD version of 1.7.0 in the module .conf is required for OSISGlosses.</ref><br/>
 +
'''OSISXlit''' (For OSIS texts that include transliterated forms)<ref>The Samaritan Pentateuch module SP is an example of using xlit.</ref><br/>
 +
'''OSISEnum''' (For OSIS texts with enumerated words)<ref>The Samaritan Pentateuch module SP is an example of using enum.</ref><br/>
 +
'''OSISReferenceLinks''' (For OSIS texts with glossary links)<ref>New in SWORD 1.7.0 - This filter requires six vertical bar-delimited fields, of which the following is an example.
 +
<pre>
 +
GlobalOptionFilter=OSISReferenceLinks|Reference Material Links|Hide or show links to study helps in the Biblical text.|x-glossary||On
 +
</pre>
 +
Here are the different field meanings:
 +
# "OSISReferenceLinks" = option filter class name (option class name internal to the engine). Always the same for this kind of filter.
 +
# "Reference Material Links" = Visible name of this OSISReferenceLinks filter. This is what the user will see in the Global Options toggle lists.
 +
# "Hide or show..." = A readable user tip explaining what the filter does.
 +
# "x-glossary" = Tells this OSISReferenceLinks filter to filter all references with type="x-glossary".
 +
# (empty) = Tells this OSISReferenceLinks filter to also require that subType="something" in order to filter. Empty means ALL type="x-glossary" references will be filtered regardless of subType.
 +
# "On" = Default filter toggle value ("On" or "Off")
 +
</ref><ref>It is allowed to have multiple OSISReferenceLinks entries in a single conf file.</ref><br/>
 +
Each of these filters removes/hides the text's feature, when activated by the application.<ref>It's not implied that every front-end supports all of the listed option filters.</ref>
 +
 
 +
These filters are applied in the order that they are listed in the conf. Some filters are dependent on each other for certain features - e.g. cross-references in notes require both the '''OSISFootnotes''' and the '''OSISScriprefs''' filters enabled.
 +
 
 +
Legacy modules may also have following keys:
 +
 
 +
'''OSISRuby'''<ref>See [https://en.wikipedia.org/wiki/Ruby_character Ruby character] and [https://en.wikipedia.org/wiki/Furigana Furigana]</ref> (For OSIS texts with glosses)<ref>Deprecated in 1.7.0. Use OSISGlosses instead.</ref><br/>
 +
'''GBFStrongs''' (For GBF texts having Strong's Numbers)<ref name="strongs">See https://en.wikipedia.org/wiki/Strong%27s_Concordance#Strong.27s_numbers</ref><br/>
 +
'''GBFFootnotes''' (For GBF texts having footnotes)<br/>
 +
'''GBFMorph''' (For GBF texts having morphology information)<br/>
 +
'''GBFHeadings''' (For GBF texts having headings)<br/>
 +
'''GBFRedLetterWords''' (For GBF texts marking the Words of Christ)<ref name="red">See https://en.wikipedia.org/wiki/Red_letter_edition</ref><br/>
 +
'''ThMLStrongs''' (For THML texts having Strong's Numbers)<ref name="strongs">See https://en.wikipedia.org/wiki/Strong%27s_Concordance#Strong.27s_numbers</ref><br/>
 +
'''ThMLFootnotes''' (For THML texts having footnotes)<br/>
 +
'''ThMLScripref''' (For THML texts having cross references)<br/>
 +
'''ThMLMorph''' (For THML texts having morphology information)<br/>
 +
'''ThMLHeadings''' (For THML texts having headings)<br/>
 +
'''ThMLVariants''' (For THML texts having variant readings)<br/>
 +
'''ThMLLemma''' (For THML texts having lemmas)<br/>
 +
 
 
| &nbsp;
 
| &nbsp;
 
| Repeats
 
| Repeats
 
|-  
 
|-  
 
| Direction
 
| Direction
−
| <b>LtoR</b> (<u>L</u>eft to <u>R</u>ight)<br/><b>RtoL</b> (<u>R</u>ight to <u>L</u>eft)<br/>
+
|
−
Indicate whether the language's script is a left to right script or a right to left script. Languages such as Hebrew, Arabic, Urdu, and Farsi have a right to left script (technically [http://en.wikipedia.org/wiki/Bi-directional_text bi-directional]). If the RtoL script is transliterated into a LtoR script, set the value to LtoR.
+
'''LtoR''' (<u>L</u>eft to <u>R</u>ight)<br/>
 +
'''RtoL''' (<u>R</u>ight to <u>L</u>eft)<br/>
 +
'''BiDi''' (<u>Bidi</u>rectional)<br/>
 +
Indicate whether the language's script is a left to right script or a right to left script.<ref>JSword validates the direction property against the Lang of the module.</ref> Languages such as Hebrew, Arabic, Urdu, and Farsi have a right to left script. If the RtoL script is transliterated into a LtoR script, set the value to LtoR. If a module has both RtoL and LtoR text, then it is BiDi.
 
| LtoR
 
| LtoR
−
| &nbsp;
 
−
|-
 
−
| SourceType
 
−
| <b>Plaintext</b><br/><b>GBF</b> General Bible Format: http://www.ebible.org/bible/gbf.htm<br/><b>ThML</b> Theological Markup Language: http://www.ccel.org/ThML<br/><b>OSIS</b> Open Scriptural Information Standard: http://www.bibletechnologies.net<br/><b>TEI</b> Text Encoding Initiative: http://www.tei-c.org/P4X/DI.html<br/>
 
−
These are various ways that the text can be encoded. The preferred encoding is OSIS. TEI is preferred for dictionaries until OSIS supports dictionaries.<br/>
 
−
In SWORD, for modules encoded with ThML, OSIS or TEI, each verse, dictionary entry, and book division needs to be well-formed XML or it will result in display problems in some frontends.
 
−
| Plaintext
 
−
| &nbsp;
 
−
|-
 
−
| Encoding
 
−
| <b>UTF-8</b><br/><b>Latin-1</b> (cp1252; see the warning)<br/>
 
−
The preferred encoding of texts is UTF-8. UTF-8 modules must be encoded with [http://unicode.org/reports/tr15/ Normalization Form C (NFC)]. Latin-1 is defined by [http://en.wikipedia.org/wiki/Windows-1252 Windows Codepage 1252 (cp1252)] which is a superset of ISO 8859-1.
 
−
This encoding indicates how the conf and the module are encoded.
 
−
<i><b>Warning</b>: "Latin-1" is an ambiguously used term. See [http://en.wikipedia.org/wiki/ISO_8859-1 ISO 8859-1 at Wikipedia] for technical details; in reality Latin-1 is regularly used as a synonym for ISO-8859-1. Frontend implementors should use "cp1252" or "windows1252" explicitly, not "Latin-1" provided by some programming language libraries.</i>
 
−
| Latin-1
 
 
| &nbsp;
 
| &nbsp;
 
|-  
 
|-  
 
| DisplayLevel
 
| DisplayLevel
−
| &lt;integer&gt;
+
| '''&lt;integer&gt;'''<br/>
 +
Used for General Book module types (these are keyed with a TreeKey table of contents).  Indicates the preferred level from a leaf in the tree to display for context. e.g., 1 will only show the requested entry; 2 will show the entry, surrounded by all siblings, etc.
 
| 1
 
| 1
 
| &nbsp;
 
| &nbsp;
 
|-  
 
|-  
 
| Font
 
| Font
−
| &lt;string&gt;<br/>
+
| '''&lt;string&gt;'''<br/>
−
Specify the font to be used for display of the module if it is available. Omit this line to use the default font. Do not make use of font-specific encodings in your documents, but use Unicode instead and the Private Use Area if necessary for codepoints that are not handled by Unicode.
+
Specify the [[Fonts|font]] to be used for display of the module if it is available.<ref>Specifying a font may not be sufficient for some modules. The required font features may depend on a particular smart font engine, which may not be compiled into the front-end application.</ref> Omit this line to use the default font. Do not make use of font-specific encodings in your documents, but use Unicode instead and the Private Use Area if necessary for codepoints that are not handled by Unicode.
 
| &nbsp;
 
| &nbsp;
 
| &nbsp;
 
| &nbsp;
 
|-  
 
|-  
−
| OSISqToTick
+
| <del>OSISqToTick</del> (deprecated)<ref>For further details, refer to [http://www.crosswire.org/bugs/browse/MOD-188 MOD-188] in CrossWire bugs.</ref>
−
| true/false<br/>
+
| This attribute is deprecated in favor of the marker attribute on the q element. E.g.: <pre><q who="Jesus" marker="">....</q></pre><br/>
−
When set to false indicates that OSIS quote elements without a marker attribute are not to produce a quotation mark. This is useful for languages (e.g. Thai) and texts (e.g. KJV) that do not have quotation marks. It is also useful for modules that mark the "Words of Christ" on a verse by verse basis, when the quote spans more than one verse.
+
<del>true/false</del><br/>
 +
<del>When set to false indicates that OSIS quote elements without a marker attribute are not to produce a quotation mark. This is useful for languages (e.g. Thai) and texts (e.g. KJV) that do not have quotation marks. It is also useful for modules that mark the "Words of Christ" on a verse by verse basis, when the quote spans more than one verse.</del>
 
| true
 
| true
 
| &nbsp;
 
| &nbsp;
 
|-
 
|-
 
| Feature
 
| Feature
−
| <b>StrongsNumbers</b> (for modules that include Strong's numbers)<br/><b>GreekDef</b> (for modules with Strong's number encoded Greek definitions)<br/><b>HebrewDef</b> (for modules with Strong's number encoded Hebrew definitions)<br/><b>GreekParse</b> (for modules with Greek morphology expansions)<br/><b>HebrewParse</b> (for modules with Hebrew morphology expansions)<br/><b>DailyDevotion</b> (for daily devotionals using one of the LD drivers and keyed with MM.DD)<br/><b>Glossary</b> (for collections of glosses using one of the LD drivers)<br/><b>Images</b> (for modules that contain images of any type)
+
|
 +
'''StrongsNumbers''' (for modules that include Strong's numbers)<br/>
 +
'''GreekDef''' (for dictionary modules with Strong's number encoded Greek definitions)<br/>
 +
'''HebrewDef''' (for dictionary modules with Strong's number encoded Hebrew definitions)<br/>
 +
'''GreekParse''' (for dictionary modules with Greek morphology expansions)<br/>
 +
'''HebrewParse''' (for dictionary modules with Hebrew morphology expansions)<br/>
 +
'''DailyDevotion''' (for daily devotionals using one of the LD drivers and keyed with MM.DD)<br/>
 +
'''Glossary''' (for collections of glosses using one of the LD drivers)<br/>
 +
'''Images''' (for modules that contain images of any type)<br/>
 +
'''NoParagraphs''' (for modules without any paragraphing information, which are typically typeset with a verse per line<ref>This feature is intended to be informational to front-end developers. Ideally, front-ends will render these modules with a verse per line rather than as a single big chapter-length paragraph block.</ref><ref>The occurrence of a small number of paragraph elements in a module (such as might be used merely to format the colophon at the end of each Pauline epistle) does not rule out the use of this feature.</ref>)
 
| &nbsp;
 
| &nbsp;
 
| Repeats
 
| Repeats
 
|-  
 
|-  
 
| GlossaryFrom
 
| GlossaryFrom
−
| &lt;xml:lang identifier&gt;<br/>
+
| '''&lt;lang identifier&gt;'''<br/>
 
Glossaries map one language to another. This value indicates the language being translated from.
 
Glossaries map one language to another. This value indicates the language being translated from.
 
See Lang below for a discussion of valid values.
 
See Lang below for a discussion of valid values.
Line 188: Line 324:
 
|-  
 
|-  
 
| GlossaryTo
 
| GlossaryTo
−
| &lt;xml:lang identifier&gt;<br/>
+
| '''&lt;lang identifier&gt;'''<br/>
 
Glossaries map one language to another. This value indicates the language being translated to.
 
Glossaries map one language to another. This value indicates the language being translated to.
 
See Lang below for a discussion of valid values.
 
See Lang below for a discussion of valid values.
 +
| &nbsp;
 +
| &nbsp;
 +
|-
 +
| PreferredCSSXHTML
 +
| '''&lt;filename&gt;'''<br/>
 +
Names a file in the module's DataPath that should be referenced for the renderer as CSS display controls.
 +
Generality is advised: Use controls that are not specific to any particular rendering engine, e.g. WebKit.
 
| &nbsp;
 
| &nbsp;
 
| &nbsp;
 
| &nbsp;
 
|}
 
|}
 +
<references />
 +
 +
=== Optional elements to support particular features ===
 +
==== CaseInsensitiveKeys ====
 +
Intended for use with Lexicon/Dictionary & Glossary modules. This field will make the order of the keys based upon the mixed case keys, but the index is still sorted by byte order of those keys. There are some scripts that don’t have upper/lower case (e.g. Arabic) and some languages where a naïve toUpper() will result in the wrong character (e.g. Turkish/Azeri lowercase dotted i and capital dotted İ).
 +
 +
CaseInsensitiveKeys=true|false
 +
 +
It is fine to use toUpper() for internal normalization, but having keys in all caps when showing to a user is annoying. The problem is that the display order needs to follow something that makes sense to a user when the dictionary is presented as a list.
 +
 +
[https://github.com/JohnAustinDev/xulsword xulsword] has a different solution involving a configuration item not yet used by SWORD master.
 +
 +
LangSortOrder=AaBbCcDdEe...
 +
 +
This is used by xulsword to sort the keys of a dictionary/glossary in original alphabetical order. Here's an actual example for module TKLDICT which has Lang=tk-Latn (i.e. Türkmençe):
 +
 +
LangSortOrder=AaBbCcÇçDdEeÄ䯿FfGgHhIiJjKkLlMmNnŇňOoÖöPpQqRrSsŞşTtUuÜüVvWwXxYyÝýZzŽž
 +
 +
This method would need to be modified in order to support alphabets (such as [http://en.wikipedia.org/wiki/Welsh_orthography Welsh]) that include any [http://en.wikipedia.org/wiki/Digraph_%28orthography%29 digraphs].
 +
 +
==== StrongsPadding ====
 +
At the heart of our lexicon/dictionary drivers, we have some old logic which tries to detect if a key value is a Strong's number, and if so, then pad it with leading zeros accordingly. To support this logic, the recognition has recently been added for an optional new .conf entry for lexicon/dictionary modules:
 +
 +
StrongsPadding=true|false
 +
 +
'''Notes:'''
 +
# So as not to break everything, this currently defaults to true if it is not present in the lexdict module's .conf file
 +
# It can be set to false if you are building a lexdict module which has entries which may be misconstrued as Strong's numbers.
 +
# In a couple years, we'll probably switch the default to false, so it would be nice to add this line and set the value to true on modules which really do require the logic.
 +
# This is only available in SWORD version 1.7 or later. JSword never had this problem.
 +
 +
==== Strip Filters ====
 +
SWORD has the concept of "filtering" a module's text at different processing points for purposes other than rendering.<br>One of these filter-points is for searching and we call these filters '''Strip Filters'''.
 +
 +
Strip Filters are typically named something like '''OSISPlain''' or '''GBFPlain''', etc.  These typically take all the markup out of an entry and prepare the text to be searched, but anything can be done to the text to prepare it further for searching.  We typically remove accents and vowel points from Greek and Hebrew respectively.
 +
 +
Any Strip Filter can be added to a module by the module author with a line in the .conf file, such as:
 +
 +
LocalStripFilter=GBFPlain
 +
 +
If diacritics need to be removed from Arabic, then we can certainly add a filter for this as well. The conf line would be:
 +
 +
LocalStripFilter=UTF8ArabicPoints
 +
 +
Our current list of filters can be found by browsing the source folder here:
 +
 +
http://crosswire.org/svn/sword/trunk/src/modules/filters/
 +
 +
They're pretty concise and don't involve much knowledge from the rest of the engine, making them easy to write if we need a new one.
 +
 +
This processing can replace or be complimentary to any processing done by clucene. Here's an example of what's used with the [http://papyri.info/docs/ddbdp Duke Databank of Papyri] with specialist software that's based on SWORD.
 +
 +
LocalStripFilter=PapyriPlain
 +
 +
Since we need to strip markup, and other things clucene will likely never support (see '''PapyriPlain''' &ndash; annotations like [,],?{,}, underdot) we need this preprocessing mechanism to prepare the text before searching.  We also maintain searching functionality apart from "fast indexed searching".<ref>Currently supplied by clucene, but could be implemented by any other fast search framework that we might want to integrate in future.</ref>
 +
 +
'''Note:'''
 +
<references />
  
 
=== General informatic and installer elements ===
 
=== General informatic and installer elements ===
Line 203: Line 404:
 
! width="10%"|Allows
 
! width="10%"|Allows
 
|-  
 
|-  
−
| Abbreviation
+
| About
−
| &lt;string&gt;<br/>
+
|
−
A shorter abbreviation which can be displayed instead of the full name. For example, KJV for the King James Version.
+
'''&lt;string&gt;'''<br/>
−
| The module name.
+
A lengthier description and may include copyright, source, etc. information, possibly duplicating information in other elements.
 
| &nbsp;
 
| &nbsp;
 +
| [[DevTools:conf Files#Continuation|Continuation]]<br/>[[DevTools:conf Files#RTF|RTF]]<br/>[[DevTools:conf Files#Localization|Localization]]
 
|-  
 
|-  
−
| About
+
| SwordVersionDate
−
| &lt;string&gt;<br/>
+
|
−
A lengthier description and may include copyright, source, etc. information, possibly duplicating information in other elements.
+
'''&lt;yyyy-mm-dd&gt;''' ([http://en.wikipedia.org/wiki/ISO_8601#Calendar_dates ISO 8601 Date])<br/>
 +
Indicates the date that the module was changed.
 +
| &nbsp;
 
| &nbsp;
 
| &nbsp;
−
| Continuation<br/>RTF
 
 
|-  
 
|-  
 
| Version
 
| Version
−
| &lt;version string&gt;<br/>
+
|
−
Gives the module's revision number. Incrementing it when changes are made alerts users of the SWORD Installers to the presence of updated modules. Please start with version 1.0 and increment by 0.1 for minor updates and by larger values for more major updates such as a new text source. Changes to this conf file should also increment the version number. Do not use non-numbers, such as 1.4a or 1.1.3.
+
'''&lt;version string&gt;'''<br/>
 +
Gives the module's revision number. Incrementing it when changes are made alerts users of the SWORD Installers to the presence of updated modules. Please start with version 1.0 and increment by 0.1 for minor updates and by larger values for more major updates such as a new text source. Changes to this conf file should also increment the version number. Do not use non-numbers, such as 1.4a.
 +
 
 +
CrossWire's standard practice is to indicate updates that only require a .conf-file update/download by incrementing the third most significant number (the revision number). For example, if module version 1.2 requires a .conf-file update. A new .conf file with version number 1.2.1 could be released.
 
| 1.0
 
| 1.0
 
| &nbsp;
 
| &nbsp;
 
|-  
 
|-  
 
| History_x.x
 
| History_x.x
−
| &lt;string&gt;<br/>
+
| '''&lt;string&gt;'''<ref>Maximum line length is 1024 characters!</ref><br/>
−
Used to alert users to what has changed between different versions. Each time a version is incremented a history line with that version number should explain the change.
+
x.x is taken from the Version value.
 +
 
 +
Indicates what has changed between different versions. Each time a version is incremented a history line with that version number should explain the change.
 +
 
 +
It is recommended that each explanation be suffixed by the corresponding SwordVersionDate value.
 
| &nbsp;
 
| &nbsp;
−
| Repeats
+
| Repeats<br/>[[DevTools:conf Files#Localization|Localization]]
 
|-  
 
|-  
−
| MinimumVersion
+
| MinimumVersion<ref>See http://tracker.crosswire.org/browse/API-201</ref>
−
| &lt;version string&gt;<br/>
+
|
−
Identifies the minimum version of the Sword library required for this module.
+
'''&lt;version string&gt;'''<br/>
 +
Identifies the [[Sword library versions | minimum version]] of the SWORD library required for this module.<ref>Required to support a Bible/Commentary module that has an [[Alternate Versification]].</ref>
 
| 1.5.1a
 
| 1.5.1a
 
| &nbsp;
 
| &nbsp;
 
|-  
 
|-  
 
| Category
 
| Category
−
| <b>Daily Devotional</b> (for modules with Feature=DailyDevotion)<br/><b>Glossaries</b> (for modules with Feature=Glossary)<br/><b>Cults / Unorthodox / Questionable Material</b><br/><b>Essays</b> (for essays)<br/><b>Maps</b> (for modules that primarily consist of maps)<br/><b>Images</b> (for modules that primarily consist of images)<br/><b>Biblical Texts</b> (for Bibles)<br/><b>Commentaries</b><br/><b>Lexicons / Dictionaries</b><br/><b>Generic Books</b> (for anything else....)<br/>
+
|valign="top"|
−
This is used by installers to further categorize the modules beyond what can be figured out by the ModDrv and Feature.
+
This is used by installers to further categorize the modules beyond what can be figured out by the ModDrv and Feature.<br/>
−
| Biblical Texts (for /(Raw&#124;z)Text4?/)<br/>
+
'''Biblical Texts''' (for Bibles)<br/>
−
Commentaries (for /(Raw&#124;z&#124;HREF)Com4?/)<br/>
+
'''Commentaries'''<br/>
−
Lexicons / Dictionaries (for /(Raw&#124;z)LD4?/<br/>
+
'''Lexicons / Dictionaries'''<br/>
−
Generic Books (for RawGenBook)
+
'''Glossaries''' (for modules with Feature=Glossary)<br/>
 +
'''Daily Devotional''' (for modules with Feature=DailyDevotion)<br/>
 +
'''Generic Books''' (for anything else....)<br/>
 +
'''Maps''' (for modules that primarily consist of maps)<br/>
 +
'''Images''' (for modules that primarily consist of images)<br/>
 +
'''Cults / Unorthodox / Questionable Material'''<br/>
 +
'''Essays''' (for essays)<ref>'''Essays''' is handled as a subset of '''Generic Books'''.</ref>
 +
|
 +
Biblical Texts<br/>
 +
&nbsp;&nbsp;''ModDrv=RawText'' or<br/>
 +
&nbsp;&nbsp;''ModDrv=RawText4'' or<br/>
 +
&nbsp;&nbsp;''ModDrv=zText'' or<br/>
 +
&nbsp;&nbsp;''ModDrv=zText4''<br/>
 +
Commentaries<br/>
 +
&nbsp;&nbsp;''ModDrv=HRefCom'' or<br/>
 +
&nbsp;&nbsp;''ModDrv=RawCom'' or<br/>
 +
&nbsp;&nbsp;''ModDrv=RawCom4'' or<br/>
 +
&nbsp;&nbsp;''ModDrv=RawFiles'' or<br/>
 +
&nbsp;&nbsp;''ModDrv=zCom'' or<br/>
 +
&nbsp;&nbsp;''ModDrv=zCom4''<br/>
 +
Lexicons / Dictionaries<br/>
 +
&nbsp;&nbsp;''ModDrv=RawLD'' or<br/>
 +
&nbsp;&nbsp;''ModDrv=RawLD4'' or<br/>
 +
&nbsp;&nbsp;''ModDrv=zLD''<br/>
 +
Glossaries<br/>
 +
&nbsp;&nbsp;''Feature=Glossary'' and<br/>
 +
&nbsp;&nbsp;''ModDrv=RawLD'' or<br/>
 +
&nbsp;&nbsp;''ModDrv=RawLD4'' or<br/>
 +
&nbsp;&nbsp;''ModDrv=zLD''<br/>
 +
Daily Devotional<br/>
 +
&nbsp;&nbsp;''Feature=DailyDevotion'' and<br/>
 +
&nbsp;&nbsp;''ModDrv=RawLD'' or<br/>
 +
&nbsp;&nbsp;''ModDrv=RawLD4'' or<br/>
 +
&nbsp;&nbsp;''ModDrv=zLD''<br/>
 +
Generic Books<br/>
 +
&nbsp;&nbsp;''ModDrv=RawGenBook''<br/>
 
| &nbsp;
 
| &nbsp;
 
|-  
 
|-  
 
| LCSH
 
| LCSH
−
| &lt;tree/string&gt;<br/>
+
| '''&lt;tree/string&gt;'''<br/>
 
Library of Congress Subject Heading. You may search the [http://catalog.loc.gov Library of Congress catalog] or use it as a guide for determining an appropriate LCSH for books that are not in the Library of Congress.
 
Library of Congress Subject Heading. You may search the [http://catalog.loc.gov Library of Congress catalog] or use it as a guide for determining an appropriate LCSH for books that are not in the Library of Congress.
 
| &nbsp;
 
| &nbsp;
Line 249: Line 495:
 
|-  
 
|-  
 
| Lang
 
| Lang
−
| &lt;xml:lang identifier&gt;<br/>
+
|
−
This is the primary language code of the module and should include a value according to RFC 4646 using ISO639 codes when possible. ISO 639-1 codes are the preferred code (e.g. en for English). If there is none for the given language, use an ISO 639-2/T code (e.g. ceb for Cebuano). Failing that, use ISO 639-3, which covers over 7000 languages. See: http://www.sil.org/iso639-3/codes.asp for ISO 639-1, 639-2/T and 639-3 codes.<br/>
+
'''&lt;Language[-Script]?[-Region]?&gt;'''<br/>
−
If a text is country specific, such as the Anglicized NIV, include the [http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html ISO 3166-1 country code] after the language code and an underscore (e.g. en_GB for UK English).
+
The language identifier is a combination of sub-tags for '''Language''' and optionally '''Script''', and/or '''Region''', according to [http://www.rfc-editor.org/rfc/bcp/bcp47.txt BCP 47] and [http://tools.ietf.org/html/rfc4647 RFC 4647]. Private use extensions defined by BCP 47 (e.g. x-, qaa, and Qaaa) should be avoided wherever possible.
 +
 
 +
'''Language sub-tag''' ''(Regex: /[a-z]{2,3}/)'':<br/>
 +
This is the primary language code of the module according to [http://en.wikipedia.org/wiki/ISO_639 ISO 639 parts 1, 2, 3 and 5]. Some languages have several codes. Use the following to determine the best choice:<br/>
 +
:When available use a 2-letter [http://en.wikipedia.org/wiki/ISO_639-1 ISO 639-1] code ([http://www.loc.gov/standards/iso639-2/php/code_list.php registrar]), (e.g. ''en'' for English).
 +
:If there is none for the given language, use an [http://en.wikipedia.org/wiki/ISO_639-2 ISO 639-2/T] code ([http://www.loc.gov/standards/iso639-2/php/code_list.php registrar])  (e.g. ceb for Cebuano).
 +
:Failing that, use a [http://en.wikipedia.org/wiki/ISO_639-3 ISO 639-3] code ([http://www-01.sil.org/iso639-3/codes.asp registrar]), which covers over 7000 languages.
 +
:Finally, use a [http://en.wikipedia.org/wiki/ISO_639-5 ISO 639-5] code ([http://www.loc.gov/standards/iso639-5/id.php registrar]) for macro languages.
 +
The [http://www-01.sil.org/iso639-3/codes.asp ISO639-3 registrar] page gives up-to-date table on all of the above.
 +
 
 +
'''Script sub-tag''' ''(Regex:  /[A-Z][a-z]{3}/)'':<br/>
 +
If a text is script-specific, such as a Latin vs. Cyrillic Serbian Bible or a Bible transliterated into other than its native script, include the [http://en.wikipedia.org/wiki/ISO_15924 ISO 15924 script code] ([http://unicode.org/iso15924/iso15924-codes.html registrar]) after the language code (e.g. sr-Latn for Latin script Serbian, sr-Cyrl for Cyrillic script Serbian).
 +
 
 +
'''Region sub-tag''': ''(Regex: /[A-Z]{2}/)''<br/>
 +
If a text is region (country)-specific, such as the Anglicized NIV, include the [http://en.wikipedia.org/wiki/ISO_3166-1 ISO 3166-1 region code] ([http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html registrar]) after the script code (or language code if no country code is present) (e.g. en-GB for UK English).
 +
 
 +
'''Combinations'''''(Regex: /[a-z]{2,3}(-[A-Z][a-z]{3})?(-[A-Z]{2})?/)'':<br/>
 +
Individual sub-tags (language, script, and region) are always separated by a hyphen. Identifiers should be as basic and succinct as possible. A script should not be specified for a language written in its expected script, unless the language has multiple common scripts (as in the case of Serbian above). A region should not be specified unless a text should be categorized separately from others texts in that language that do not specify a region.
 
| en
 
| en
 
| &nbsp;
 
| &nbsp;
 
|-  
 
|-  
 
| InstallSize
 
| InstallSize
−
| &lt;integer (indicating bytes)&gt;
+
|
 +
'''&lt;integer&gt;'''<br/>
 +
Indicates the total byte size of the module on disk, excluding the the size of any Lucene index files.
 +
 
 +
For modules in the CrossWire repositories, this is automatically generated and overwritten if needed.
 
| &nbsp;
 
| &nbsp;
 
| &nbsp;
 
| &nbsp;
 
|-  
 
|-  
−
| SwordVersionDate
+
| Obsoletes
−
| &lt;ISO date string (yyyy-mm-dd)&gt;
+
|
−
Indicates the date that the module was changed.
+
'''&lt;ModName&gt;'''<br/>
 +
Each instance of this element gives a former ModName that is made obsolete by this module.
 
| &nbsp;
 
| &nbsp;
 +
| Repeats
 +
|-
 +
| OSISVersion
 +
|
 +
'''&lt;version string&gt;'''<br/>
 +
Identifies the OSIS schema version employed in the OSIS source document. The current version is 2.1.1
 +
 +
It is recommended that this be present for every OSIS module.
 
| &nbsp;
 
| &nbsp;
 +
|
 
|-  
 
|-  
−
| Obsoletes
+
| Companion<ref>Many (xulsword compatible) modules in the [[Official and Affiliated Module Repositories#Institute_for_Bible_Translation|IBT Repository]] make use of this field. See also https://github.com/johnaustindev/osis-converters</ref>
−
| &lt;name of module&gt;<br/>
+
|
−
Each instance of this element names a module that is made obsolete by this module, usually indicated by the former name of the module.
+
'''&lt;ModName[, ModName]*&gt;'''<br/>
 +
Specifies companion module(s) that should be opened together<br/>
 +
e.g. When Bible and Commentary and/or Glossary modules are distributed together.
 
| &nbsp;
 
| &nbsp;
−
| Repeats
+
|  
 
|}
 
|}
−
 
+
'''Note:'''
 +
<references/>
  
 
=== Copyright &amp; Licensing related elements ===
 
=== Copyright &amp; Licensing related elements ===
Line 283: Line 563:
 
|-  
 
|-  
 
| Copyright
 
| Copyright
−
| &lt;string&gt;<br/>
+
|
 +
'''&lt;string&gt;'''<br/>
 
Contains the copyright notice for the work, including the year of copyright and the owner of the copyright.
 
Contains the copyright notice for the work, including the year of copyright and the owner of the copyright.
 
| &nbsp;
 
| &nbsp;
−
| Continuation
+
| [[DevTools:conf Files#Continuation|Continuation]]<br/>[[DevTools:conf Files#Localization|Localization]]
 
|-  
 
|-  
 
| CopyrightHolder
 
| CopyrightHolder
−
| &lt;string&gt;<br/>
+
|
 +
'''&lt;string&gt;'''<br/>
 
Contains the name of the copyright holder.
 
Contains the name of the copyright holder.
 
| &nbsp;
 
| &nbsp;
−
| &nbsp;
+
| [[DevTools:conf Files#Localization|Localization]]
 
|-  
 
|-  
 
| CopyrightDate
 
| CopyrightDate
−
| &lt;integer (indicating year)&gt;
+
|
−
| &nbsp;
+
'''&lt;yyyy&gt;''' ([http://en.wikipedia.org/wiki/ISO_8601#Years ISO 8601 Year])
 
| &nbsp;
 
| &nbsp;
 +
| [[DevTools:conf Files#Localization|Localization]]
 
|-  
 
|-  
 
| CopyrightNotes
 
| CopyrightNotes
−
| &lt;string&gt;
+
|
 +
'''&lt;string&gt;'''
 
| &nbsp;
 
| &nbsp;
−
| Continuation
+
| [[DevTools:conf Files#Continuation|Continuation]]<br/>[[DevTools:conf Files#Localization|Localization]]
 
|-  
 
|-  
 
| CopyrightContactName
 
| CopyrightContactName
−
| &lt;string&gt;<br/>
+
|
 +
'''&lt;string&gt;'''<br/>
 
Contains the name of the copyright holder.
 
Contains the name of the copyright holder.
 
| &nbsp;
 
| &nbsp;
−
| Continuation
+
| [[DevTools:conf Files#Continuation|Continuation]]<br/>[[DevTools:conf Files#Localization|Localization]]
 
|-  
 
|-  
 
| CopyrightContactNotes
 
| CopyrightContactNotes
−
| &lt;string&gt;
+
|
 +
'''&lt;string&gt;'''
 
| &nbsp;
 
| &nbsp;
−
| Continuation
+
| [[DevTools:conf Files#Continuation|Continuation]]<br/>[[DevTools:conf Files#Localization|Localization]]
 
|-  
 
|-  
 
| CopyrightContactAddress
 
| CopyrightContactAddress
−
| &lt;string&gt;<br/>
+
|
 +
'''&lt;string&gt;'''<br/>
 
Contains the mailing address of the copyright holder.
 
Contains the mailing address of the copyright holder.
 
| &nbsp;
 
| &nbsp;
−
| Continuation
+
| [[DevTools:conf Files#Continuation|Continuation]]<br/>[[DevTools:conf Files#Localization|Localization]]
 
|-  
 
|-  
 
| CopyrightContactEmail
 
| CopyrightContactEmail
−
| &lt;string&gt;<br/>
+
|
−
Contains the email address of the copyright holder, preferably in the form:<br/> name at xyz dot com.
+
'''&lt;string&gt;'''<br/>
−
| &nbsp;
+
Contains the email address of the copyright holder, preferably in the form:<br/> name at xyz dot com
 
| &nbsp;
 
| &nbsp;
 +
| [[DevTools:conf Files#Localization|Localization]]
 
|-  
 
|-  
 
| ShortPromo
 
| ShortPromo
−
| &lt;string&gt;<br/>
+
|
 +
'''&lt;string&gt;'''<br/>
 
A link to the home page for the module, perhaps with an encouragement to visit the site.
 
A link to the home page for the module, perhaps with an encouragement to visit the site.
 
| &nbsp;
 
| &nbsp;
−
| HTML Link
+
| HTML Link<br/>[[DevTools:conf Files#Localization|Localization]]
 
|-  
 
|-  
 
| ShortCopyright
 
| ShortCopyright
−
| &lt;string&gt;
+
|
−
| &nbsp;
+
'''&lt;string&gt;'''
 
| &nbsp;
 
| &nbsp;
−
|-  
+
| [[DevTools:conf Files#Localization|Localization]]
 +
|- id="distlic"
 
| DistributionLicense
 
| DistributionLicense
−
| <b>Public Domain</b><br/><b>Copyrighted</b><br/><b>Copyrighted; Permission to distribute granted to CrossWire</b><br/><b>Copyrighted; Free non-commercial distribution</b><br/><b>Copyrighted; Freely distributable</b><br/><b>Copyrighted; Permission granted to distribute non-commercially in Sword format</b><br/><b>[http://www.gnu.org/copyleft/fdl.html GFDL]</b><br/><b>[http://www.gnu.org/copyleft/gpl.html GPL]</b><br/><b>Creative Commons: [http://creativecommons.org/licenses/by-nc-nd by-nc-nd]</b><br/><b>Creative Commons: [http://creativecommons.org/licenses/by-nc-sa by-nc-sa]</b><br/><b>Creative Commons: [http://creativecommons.org/licenses/by-nc by-nc]</b><br/><b>Creative Commons: [http://creativecommons.org/licenses/by-nd by-nd]</b><br/><b>Creative Commons: [http://creativecommons.org/licenses/by-sa by-sa]</b><br/><b>Creative Commons: [http://creativecommons.org/licenses/by by]</b><br/><br/>
+
|
−
Use one of these strings verbatim. The actual copyright and/or license information is held in other elements. The last six licenses are [http://creativecommons.org/ Creative Commons] licenses.
+
'''Public Domain'''<br/>
 +
'''Copyrighted'''<br/>
 +
'''Copyrighted; Permission to distribute granted to CrossWire'''<ref>Modules in other repositories may have a different organization name instead of CrossWire.</ref><br/>
 +
'''Copyrighted; Permission granted to distribute non-commercially in SWORD format'''<br/>
 +
'''Copyrighted; Free non-commercial distribution'''<br/>
 +
'''Copyrighted; Freely distributable'''<br/>
 +
'''[http://www.gnu.org/copyleft/fdl.html GFDL]'''<br/>
 +
'''[http://www.gnu.org/copyleft/gpl.html GPL]'''<br/>
 +
'''Creative Commons: BY-NC-ND 4.0'''<br/>
 +
'''Creative Commons: BY-NC-SA 4.0'''<br/>
 +
'''Creative Commons: BY-NC 4.0'''<br/>
 +
'''Creative Commons: BY-ND 4.0'''<br/>
 +
'''Creative Commons: BY-SA 4.0'''<br/>
 +
'''Creative Commons: BY 4.0'''<br/>
 +
'''Creative Commons: [http://creativecommons.org/publicdomain/zero/1.0/ CC0]'''<br/>
 +
Use one of these strings '''verbatim'''. The actual copyright and/or license information is held in other elements.<br/>The last seven are different [https://creativecommons.org/licenses/ Creative Commons licenses].
 
| &nbsp;
 
| &nbsp;
 
| &nbsp;
 
| &nbsp;
 
|-  
 
|-  
 
| DistributionNotes
 
| DistributionNotes
−
| &lt;string&gt;<br/>
+
|
 +
'''&lt;string&gt;'''<br/>
 
Indicates any additional notes about distribution of the module.
 
Indicates any additional notes about distribution of the module.
 
| &nbsp;
 
| &nbsp;
−
| Continuation
+
| [[DevTools:conf Files#Continuation|Continuation]]<br/>[[DevTools:conf Files#Localization|Localization]]
−
|-  
+
|- id="txtsrc"
 
| TextSource
 
| TextSource
−
| &lt;string, probably a URL&gt;<br/>
+
|
 +
'''&lt;string&gt;'''<br/>
 
Indicates, either in prose (such as "CCEL") or as a URL of the source of the text
 
Indicates, either in prose (such as "CCEL") or as a URL of the source of the text
 
| &nbsp;
 
| &nbsp;
−
| Continuation
+
| [[DevTools:conf Files#Continuation|Continuation]]
 +
|-
 +
| UnlockInfo
 +
|
 +
'''&lt;string&gt;'''<br/>
 +
Contains unlock instructions for the user, intended to be displayed upon attempt to install the module.  These instructions typically include a URL pointing to an exact location within a publisher's online store where a user can directly purchase an unlock key (CipherKey) for the module.
 +
| &nbsp;
 +
| [[DevTools:conf Files#RTF|RTF]]<br/>[[DevTools:conf Files#Continuation|Continuation]]<br/>[[DevTools:conf Files#Localization|Localization]]<br/>HTML Link
 
|}
 
|}
 +
'''Note:'''
 +
<references/>
 +
 +
=== Comments and blank lines ===
 +
Early in 2021, CrossWire began providing comment lines and blank lines in released and updated modules.
 +
Here's and example showing that there may sometimes be both ''even before'' the module ID.
 +
<pre>
 +
## Sword module configuration file
 +
 +
## Required elements
 +
# Module Unique Identifier.
 +
[GerMenge]
 +
...
 +
</pre>Some other module providers and repositories are already moving in the same direction.
 +
 +
== Further details ==
 +
=== Continuation ===
 +
A value can span multiple lines by escaping the return with '\'. This is not a mechanism to make long lines more readable in the module.conf file. It is a means to introducing a break in the rendered output of that field when viewed by a front-end or installer. It is akin to a xHTML &lt;br/&gt;. That is, continuation is a formatting feature.
 +
 +
Most elements in a SWORD conf are expected to have short, one-line values. Elements that are expected to have multiple lines are noted.
 +
 +
=== RTF ===
 +
A module.conf supports a very small, restricted subset of RTF markup. Only the following are allowed:
 +
* \qc - for centering
 +
* \par - for paragraph breaks
 +
* \pard - for resetting paragraph attributes, i.e. turning off centering.
 +
* \u{num}? - for unicode characters, where {num} is a signed, 16-bit representation of the code point and where ? is the  ASCII character used in case unicode is not supported. If the {num} is less than 0 then add 65536 to it. This should only be used in modules that have an Encoding=UTF-8, but using the actual UTF-8 character is preferred.
 +
 +
The only uniqueness that RTF provides is centering. If centering is not needed, then use continuation lines instead of RTF.
 +
 +
=== Localization ===
 +
Those .conf fields that are essentially text intended for presentation to the end-user may be localized by appending _''locale'' to the field name, where ''locale'' is replaced by an appropriate locale code, according to [http://www.rfc-editor.org/rfc/bcp/bcp47.txt BCP 47]. See '''Lang''' key for details.
 +
 +
For example, to give a French description, you can have a key:
 +
:Description_fr=....
 +
 +
In order to distinguish a regional form from the primary form of a language, e.g. Brazilian Portuguese vs. the Portuguese of Portugal, append the country code as in:
 +
:Description_pt-BR=....
 +
 +
Script variants can be given as in:
 +
:Description_zh-Hans=.... simplified Chinese ....
 +
:Description_zh-Hant=.... traditional Chinese ....
 +
 +
In order for a .conf entry to appear in a localized form, a non-localized form of the same field must also occur within the .conf. For example, in order for a ''Description_en'' field to appear, a file  must also possess a ''Description'' field. The locale of .conf entries without the locale modifier is the default and must reflect the locale/language of the module itself (as specified in Lang=) or English (if there are no localized versions of the field). In general, fields should be provided in the language of the module itself with English translations provided in parallel fields localized with _''en''. There is no explicit upper bound on the quantity of localized fields, but all localized and localizable fields should be unique.
 +
 +
# See also [[Localized Language Names]].
  
−
== Localization ==
+
=== Uniqueness ===
 +
For comparing two versions of a module during module development, the module names and locations must be unique. For JSword based front-ends such as Bible Desktop, there is a further requirement, the Description items must be different.
  
−
Where it makes sense, the values in the .conf file may be internationalized by appending _lang to it, where lang is replaced by an appropriate [http://www.rfc-editor.org/rfc/bcp/bcp47.txt BCP 47] the language code.
+
=== Analysis Tools ===
 +
* [[User:Dmsmith|DMSmith]] and [[User:Domcox|Domcox]] have created scripts to analyse conf files and report anomalies.
 +
* [[User:David Haslam|David Haslam]] has created a '''User Defined Language''' called '''CONF''' as a Syntax Highlighter for '''Notepad++''' (Windows). Download from [https://github.com/DavidHaslam/CONF].
  
−
For example, to give a French description, you can have a field Description_fr=...
+
== Automated generation ==
 +
* For new module submissions to CrossWire, [[User:DomCox|DomCox]] now maintains a script that includes the ''automated generation'' of module conf files, given the minimum ''non-automatable'' requirements by the module submitter. See [[Module Submission]] for more details.
  
−
The language for .conf entries without the language modifier is the language of the module itself (as specified in Lang=).
+
== See also ==
 +
* [[BibTeX entries]]
  
−
'''Note''': At the present, this is only a planned feature. Module .confs can & should make use of this facility, but at the moment, there is no Sword library or front end support for it.
+
[[Category:Development tools|Conf files]]
 +
[[Category:Localization|Conf files]]
 +
[[Category:Versification|Conf files]]
 +
[[Category:Copyright|Conf files]]

Latest revision as of 06:22, 20 February 2024

This page describes important information about module configuration (.conf) files. All SWORD modules require one.

Please look also at our detailed and commented tutorial.

Key elements of a SWORD module.conf

Some keys can be repeated. Many not.

Some can have values that span more than 1 line with '\' at the end of a line indicating that the text on the next line continues the value. Don't use continuation unless allowed. It will produce different results in different front ends.

RTF is allowed in some values.

Some allow HTML <a href="xxx">label</a>hypertext links. HTML is not allowed otherwise.

Values specifications are shown as <content spec>. The < and > are not to be included.

Enumerated values are shown in bold. These should be used exactly as given and no other values should be used.

The order of elements specified in a conf file is immaterial, except where specified otherwise.

Required Elements

Element Values (type or enumerated) Default Value Allows
[ModName] Each conf file begins with a unique identifier for a module placed within brackets, e.g., [KJV1611]. This must be first in the file. Valid characters for this abbreviation are limited to PCRE class [A-Za-z0-9_].[1]

The Abbreviation element is meant to allow for localization of this field.
The .conf file should be named the lowercase of this abbreviation followed by .conf. For example, kjv1611.conf.

   
Abbreviation[2]

<string>
The abbreviation displayed to the user. If not supplied, the unique ModName will be used. This field allows for localization-- showing a different abbreviation depending on the user's locale.

[ModName] Localization
Description

<string>
This is a short (1 line) title of the module.

  Localization
DataPath <relative system path pointing to the data files>

DataPath is the path to the module data files relative to the SWORD module library root directory. This path should start with "./modules". If the DataPath indicates a directory it should end with a '/'. Otherwise the module name is both the directory and the prefix for each file in that directory. Although DataPath can point to any folder or files under the root of the SWORD module library, the following conventions are recommended and must be used for modules wishing to be included in a CrossWire repository:

Paths used for a module named [MyModule], depending on
(a) the type of module (Bible text, commentary, lexicon or dictionary[3], general book) and
(b) the data driver (ModDrv parameter) are:

./modules/texts/rawtext/mymodule/
./modules/texts/rawtext4/mymodule/
./modules/texts/ztext/mymodule/
./modules/texts/ztext4/mymodule/
./modules/comments/zcom/mymodule/
./modules/comments/zcom4/mymodule/
./modules/comments/hrefcom/mymodule/
./modules/comments/rawcom/mymodule/
./modules/comments/rawcom4/mymodule/
./modules/comments/rawfiles/mymodule/
./modules/lexdict/zld/mymodule/mymodule
./modules/lexdict/rawld/mymodule/mymodule
./modules/lexdict/rawld/devotionals/mymodule/mymodule
./modules/lexdict/rawld/glossaries/mymodule/mymodule
./modules/lexdict/rawld4/mymodule/mymodule
./modules/genbook/rawgenbook/mymodule/mymodule
    
ModDrv

RawText (for uncompressed Bibles)
RawText4 (for uncompressed Bibles having entries greater than 64K bytes)[4]
zText (for compressed Bibles)
zText4 (for compressed Bibles having entries greater than 64K bytes)[4][5]
RawCom (for uncompressed Commentaries)
RawCom4 (for uncompressed Commentaries having entries greater than 64K bytes)
zCom (for compressed Commentaries)
zCom4 (for compressed Commentaries having entries greater than 64K bytes)[5]
HREFCom (each module entry must be only a URL to the body for the entry; experimental)
RawFiles (stores each entry in a simple text file in the datapath; recommended for Personal Commentary)
RawLD (for uncompressed Dictionaries)
RawLD4 (for uncompressed Dictionaries having entries greater than 64K bytes)
zLD (for compressed Dictionaries)
RawGenBook (for uncompressed tree keyed modules)

   
  1. ↑ That excludes the space and hyphen characters!
  2. ↑ We advise against explicitly declaring a redundant Abbreviation identical to the ModName. Abbreviation values should try to be unique to avoid user confusion.
  3. ↑ Daily devotionals & glossaries go in subdirectories under lexdict. A glossary is between two languages.
  4. ↑ 4.0 4.1 e.g. If the Bible contains large introduction sections
  5. ↑ 5.0 5.1 zText4 & zCom4 modules require MinimumVersion=1.8 or later. Cite error: Invalid <ref> tag; name "sv" defined multiple times with different content

Required Elements with defaults

Element Values (type or enumerated) Default Value Allows
SourceType[1]

Plaintext
OSIS (Open Scriptural Information Standard)
TEI (Text Encoding Initiative)
Specifies the markup used in the module. The preferred markup is OSIS. TEI is preferred for dictionaries until OSIS supports dictionaries. While SourceType has a default, it is a best practice to specify it.

Legacy modules may have a key here stating:

GBF (General Bible Format)
ThML (Theological Markup Language)

In SWORD, for modules encoded with ThML, OSIS or TEI, each verse, dictionary entry, and book division needs to be well-formed XML or it will result in display problems in some front-ends.

Plaintext  
Encoding

UTF-8
UTF-16
SCSU (Standard Compression Scheme for Unicode)
Indicates how the text in the conf and in the module are encoded.

The preferred encoding of texts is UTF-8. Other than Hebrew, UTF-8 modules must be encoded with Normalization Form C (NFC). Biblical Hebrew requires special handling.[2] A few other languages may require special handling.[3][4]

To date, no modules use UTF-16 or SCSU. Legacy modules may hold a key here Latin-1 referring solely to Windows Codepage 1252, a superset of ISO-8859-1. Front-end implementors wishing to use such modules should use "cp1252" or "windows1252" explicitly, not "Latin-1" provided by some programming language libraries.

Latin-1  
CompressType

ZIP
LZSS (Lempel Ziv Storer Szymanski)
BZIP2
XZ
Used for modules having a ModDrv of zText, zCom or zLD to indicate the compression algorithm. While CompressType has a default, it is best practice to specify it. ZIP is the preferred format.

LZSS  
BlockType

BOOK
CHAPTER
VERSE
Used for modules having a ModDrv of zText (Bibles) and zCom (Commentaries) to indicate how much of the work is compressed into a block. The trade off is size for speed, with BOOK taking the least overall space and the longest time and VERSE taking the greatest overall space and the least time. While BlockType has a default, it is a best practice to specify it. Most Bibles use BOOK and larger Commentaries use CHAPTER. To date, no module uses VERSE.

CHAPTER  
BlockCount

<integer>
Used for modules having a ModDrv of zLD to indicate the number of entries in a compressed block. Higher values will make the module slower, but smaller. It is best practice to take the default and not specify it.

200  
Versification

Calvin
Catholic
Catholic2
Darby_Fr
German
KJV
KJVA
LXX
Leningrad
Luther
MT
NRSV
NRSVA
Orthodox
Segond
Synodal
SynodalProt
Vulg
Used to specify the versification employed by a Bible module[5]. Refer to Alternate Versification.

KJV  
CipherKey

<string>
Indicates that a module is enciphered and that the module is (un)locked. When the key has no value ("CipherKey=") the module is locked. When it has a value, the module is unlocked.

A good key is something that is hard to guess. Typically in a format matching the pattern: /[0-9]{4}[A-Za-z]{4}[0-9]{4}[A-Za-z]{4}/. Internally the key can be any byte sequence from 1 to 255 bytes in length. But it needs to be readable, plain text, without leading or trailing spaces.

   
KeyType

TreeKey
VerseKey
Used for RawGenBook to indicate whether the module contains a book or a Bible. At this time VerseKey is not yet supported and is being developed as a solution for Bibles which do not conform to any supported versification system in SWORD. It is best practice to take the default and not specify it.

TreeKey  
CaseSensitiveKeys

Used for Dictionaries whose keys are case sensitive. This key is used to suppress normalization to UPPER CASE before comparison.
Only allowable value: true

false  
  1. ↑ Omitting this for a non-plaintext module has unpredictable effects.
  2. ↑ Unicode normalization can easily break Biblical Hebrew text. See on page 9 in the SBL Hebrew Font User Manual.
  3. ↑ e.g. If they are mentioned in Table 10 in the Corrigendum 5 Sequences.
  4. ↑ The improper normalization of exceptional codepoints can be prevented by inserting a Combining Grapheme Joiner.
  5. ↑ i.e. Specify this only for a module that uses VerseKey.

Elements required for proper rendering

Element Values (type or enumerated) Default Value Allows
GlobalOptionFilter

UTF8Cantillation (For Hebrew texts having cantillation marks)[1]
UTF8GreekAccents (For Greek texts having accents)[2][3]
UTF8HebrewPoints (For Hebrew texts having vowel points)[4]
UTF8ArabicPoints (For Arabic texts having vowel points)[5]
OSISLemma (For OSIS texts having lemmas)[6]
OSISMorphSegmentation (For OSIS texts having morphological segmentation elements)[7]
OSISStrongs (For OSIS texts having Strong's Numbers)[8]
OSISFootnotes (For OSIS texts having informational notes)
OSISScripref (For OSIS texts having cross reference type notes)
OSISMorph (For OSIS texts having morphology information)
OSISHeadings (For OSIS texts having non-canonical headings)
OSISVariants (For OSIS texts having variant readings)
OSISRedLetterWords (For OSIS texts marking the Words of Christ)[9]
OSISGlosses (For OSIS texts with glosses)[10]
OSISXlit (For OSIS texts that include transliterated forms)[11]
OSISEnum (For OSIS texts with enumerated words)[12]
OSISReferenceLinks (For OSIS texts with glossary links)[13][14]
Each of these filters removes/hides the text's feature, when activated by the application.[15]

These filters are applied in the order that they are listed in the conf. Some filters are dependent on each other for certain features - e.g. cross-references in notes require both the OSISFootnotes and the OSISScriprefs filters enabled.

Legacy modules may also have following keys:

OSISRuby[16] (For OSIS texts with glosses)[17]
GBFStrongs (For GBF texts having Strong's Numbers)[8]
GBFFootnotes (For GBF texts having footnotes)
GBFMorph (For GBF texts having morphology information)
GBFHeadings (For GBF texts having headings)
GBFRedLetterWords (For GBF texts marking the Words of Christ)[9]
ThMLStrongs (For THML texts having Strong's Numbers)[8]
ThMLFootnotes (For THML texts having footnotes)
ThMLScripref (For THML texts having cross references)
ThMLMorph (For THML texts having morphology information)
ThMLHeadings (For THML texts having headings)
ThMLVariants (For THML texts having variant readings)
ThMLLemma (For THML texts having lemmas)

   Repeats
Direction

LtoR (Left to Right)
RtoL (Right to Left)
BiDi (Bidirectional)
Indicate whether the language's script is a left to right script or a right to left script.[18] Languages such as Hebrew, Arabic, Urdu, and Farsi have a right to left script. If the RtoL script is transliterated into a LtoR script, set the value to LtoR. If a module has both RtoL and LtoR text, then it is BiDi.

LtoR  
DisplayLevel <integer>

Used for General Book module types (these are keyed with a TreeKey table of contents). Indicates the preferred level from a leaf in the tree to display for context. e.g., 1 will only show the requested entry; 2 will show the entry, surrounded by all siblings, etc.

1  
Font <string>

Specify the font to be used for display of the module if it is available.[19] Omit this line to use the default font. Do not make use of font-specific encodings in your documents, but use Unicode instead and the Private Use Area if necessary for codepoints that are not handled by Unicode.

   
OSISqToTick (deprecated)[20] This attribute is deprecated in favor of the marker attribute on the q element. E.g.: 
<q who="Jesus" marker="">....</q>

true/false
When set to false indicates that OSIS quote elements without a marker attribute are not to produce a quotation mark. This is useful for languages (e.g. Thai) and texts (e.g. KJV) that do not have quotation marks. It is also useful for modules that mark the "Words of Christ" on a verse by verse basis, when the quote spans more than one verse.

true  
Feature

StrongsNumbers (for modules that include Strong's numbers)
GreekDef (for dictionary modules with Strong's number encoded Greek definitions)
HebrewDef (for dictionary modules with Strong's number encoded Hebrew definitions)
GreekParse (for dictionary modules with Greek morphology expansions)
HebrewParse (for dictionary modules with Hebrew morphology expansions)
DailyDevotion (for daily devotionals using one of the LD drivers and keyed with MM.DD)
Glossary (for collections of glosses using one of the LD drivers)
Images (for modules that contain images of any type)
NoParagraphs (for modules without any paragraphing information, which are typically typeset with a verse per line[21][22])

  Repeats
GlossaryFrom <lang identifier>

Glossaries map one language to another. This value indicates the language being translated from. See Lang below for a discussion of valid values.

   
GlossaryTo <lang identifier>

Glossaries map one language to another. This value indicates the language being translated to. See Lang below for a discussion of valid values.

   
PreferredCSSXHTML <filename>

Names a file in the module's DataPath that should be referenced for the renderer as CSS display controls. Generality is advised: Use controls that are not specific to any particular rendering engine, e.g. WebKit.

   
  1. ↑ See https://en.wikipedia.org/wiki/Cantillation
  2. ↑ For detailed background, see https://en.wikipedia.org/wiki/Greek_diacritics
  3. ↑ This filter can have undesirable side-effects when applied to non-Greek text!
  4. ↑ See https://en.wikipedia.org/wiki/Niqqud
  5. ↑ See https://en.wikipedia.org/wiki/Arabic_diacritics
  6. ↑ Must precede OSISStrongs.
  7. ↑ Currently, only some JSword based front-ends seem to support this feature. The SWORD engine has the switch available, but no change in output is effected.
  8. ↑ 8.0 8.1 8.2 See https://en.wikipedia.org/wiki/Strong%27s_Concordance#Strong.27s_numbers
  9. ↑ 9.0 9.1 See https://en.wikipedia.org/wiki/Red_letter_edition
  10. ↑ Minimum SWORD version of 1.7.0 in the module .conf is required for OSISGlosses.
  11. ↑ The Samaritan Pentateuch module SP is an example of using xlit.
  12. ↑ The Samaritan Pentateuch module SP is an example of using enum.
  13. ↑ New in SWORD 1.7.0 - This filter requires six vertical bar-delimited fields, of which the following is an example. 
    GlobalOptionFilter=OSISReferenceLinks|Reference Material Links|Hide or show links to study helps in the Biblical text.|x-glossary||On

    Here are the different field meanings:

    1. "OSISReferenceLinks" = option filter class name (option class name internal to the engine). Always the same for this kind of filter.
    2. "Reference Material Links" = Visible name of this OSISReferenceLinks filter. This is what the user will see in the Global Options toggle lists.
    3. "Hide or show..." = A readable user tip explaining what the filter does.
    4. "x-glossary" = Tells this OSISReferenceLinks filter to filter all references with type="x-glossary".
    5. (empty) = Tells this OSISReferenceLinks filter to also require that subType="something" in order to filter. Empty means ALL type="x-glossary" references will be filtered regardless of subType.
    6. "On" = Default filter toggle value ("On" or "Off")
  14. ↑ It is allowed to have multiple OSISReferenceLinks entries in a single conf file.
  15. ↑ It's not implied that every front-end supports all of the listed option filters.
  16. ↑ See Ruby character and Furigana
  17. ↑ Deprecated in 1.7.0. Use OSISGlosses instead.
  18. ↑ JSword validates the direction property against the Lang of the module.
  19. ↑ Specifying a font may not be sufficient for some modules. The required font features may depend on a particular smart font engine, which may not be compiled into the front-end application.
  20. ↑ For further details, refer to MOD-188 in CrossWire bugs.
  21. ↑ This feature is intended to be informational to front-end developers. Ideally, front-ends will render these modules with a verse per line rather than as a single big chapter-length paragraph block.
  22. ↑ The occurrence of a small number of paragraph elements in a module (such as might be used merely to format the colophon at the end of each Pauline epistle) does not rule out the use of this feature.

Optional elements to support particular features

CaseInsensitiveKeys

Intended for use with Lexicon/Dictionary & Glossary modules. This field will make the order of the keys based upon the mixed case keys, but the index is still sorted by byte order of those keys. There are some scripts that don’t have upper/lower case (e.g. Arabic) and some languages where a naïve toUpper() will result in the wrong character (e.g. Turkish/Azeri lowercase dotted i and capital dotted İ). 

CaseInsensitiveKeys=true|false

It is fine to use toUpper() for internal normalization, but having keys in all caps when showing to a user is annoying. The problem is that the display order needs to follow something that makes sense to a user when the dictionary is presented as a list.

xulsword has a different solution involving a configuration item not yet used by SWORD master. 

LangSortOrder=AaBbCcDdEe...

This is used by xulsword to sort the keys of a dictionary/glossary in original alphabetical order. Here's an actual example for module TKLDICT which has Lang=tk-Latn (i.e. Türkmençe): 

LangSortOrder=AaBbCcÇçDdEeÄ䯿FfGgHhIiJjKkLlMmNnŇňOoÖöPpQqRrSsŞşTtUuÜüVvWwXxYyÝýZzŽž

This method would need to be modified in order to support alphabets (such as Welsh) that include any digraphs.

StrongsPadding

At the heart of our lexicon/dictionary drivers, we have some old logic which tries to detect if a key value is a Strong's number, and if so, then pad it with leading zeros accordingly. To support this logic, the recognition has recently been added for an optional new .conf entry for lexicon/dictionary modules: 

StrongsPadding=true|false

Notes:

  1. So as not to break everything, this currently defaults to true if it is not present in the lexdict module's .conf file
  2. It can be set to false if you are building a lexdict module which has entries which may be misconstrued as Strong's numbers.
  3. In a couple years, we'll probably switch the default to false, so it would be nice to add this line and set the value to true on modules which really do require the logic.
  4. This is only available in SWORD version 1.7 or later. JSword never had this problem.

Strip Filters

SWORD has the concept of "filtering" a module's text at different processing points for purposes other than rendering.
One of these filter-points is for searching and we call these filters Strip Filters.

Strip Filters are typically named something like OSISPlain or GBFPlain, etc. These typically take all the markup out of an entry and prepare the text to be searched, but anything can be done to the text to prepare it further for searching. We typically remove accents and vowel points from Greek and Hebrew respectively.

Any Strip Filter can be added to a module by the module author with a line in the .conf file, such as: 

LocalStripFilter=GBFPlain

If diacritics need to be removed from Arabic, then we can certainly add a filter for this as well. The conf line would be: 

LocalStripFilter=UTF8ArabicPoints

Our current list of filters can be found by browsing the source folder here:

http://crosswire.org/svn/sword/trunk/src/modules/filters/

They're pretty concise and don't involve much knowledge from the rest of the engine, making them easy to write if we need a new one.

This processing can replace or be complimentary to any processing done by clucene. Here's an example of what's used with the Duke Databank of Papyri with specialist software that's based on SWORD. 

LocalStripFilter=PapyriPlain

Since we need to strip markup, and other things clucene will likely never support (see PapyriPlain – annotations like [,],?{,}, underdot) we need this preprocessing mechanism to prepare the text before searching. We also maintain searching functionality apart from "fast indexed searching".[1]

Note:

  1. ↑ Currently supplied by clucene, but could be implemented by any other fast search framework that we might want to integrate in future.

General informatic and installer elements

Element Values (type or enumerated) Default Value Allows
About

<string>
A lengthier description and may include copyright, source, etc. information, possibly duplicating information in other elements.

  Continuation
RTF
Localization
SwordVersionDate

<yyyy-mm-dd> (ISO 8601 Date)
Indicates the date that the module was changed.

   
Version

<version string>
Gives the module's revision number. Incrementing it when changes are made alerts users of the SWORD Installers to the presence of updated modules. Please start with version 1.0 and increment by 0.1 for minor updates and by larger values for more major updates such as a new text source. Changes to this conf file should also increment the version number. Do not use non-numbers, such as 1.4a.

CrossWire's standard practice is to indicate updates that only require a .conf-file update/download by incrementing the third most significant number (the revision number). For example, if module version 1.2 requires a .conf-file update. A new .conf file with version number 1.2.1 could be released.

1.0  
History_x.x <string>[1]

x.x is taken from the Version value.

Indicates what has changed between different versions. Each time a version is incremented a history line with that version number should explain the change.

It is recommended that each explanation be suffixed by the corresponding SwordVersionDate value.

  Repeats
Localization
MinimumVersion[2]

<version string>
Identifies the minimum version of the SWORD library required for this module.[3]

1.5.1a  
Category

This is used by installers to further categorize the modules beyond what can be figured out by the ModDrv and Feature.
Biblical Texts (for Bibles)
Commentaries
Lexicons / Dictionaries
Glossaries (for modules with Feature=Glossary)
Daily Devotional (for modules with Feature=DailyDevotion)
Generic Books (for anything else....)
Maps (for modules that primarily consist of maps)
Images (for modules that primarily consist of images)
Cults / Unorthodox / Questionable Material
Essays (for essays)[4]

Biblical Texts
  ModDrv=RawText or
  ModDrv=RawText4 or
  ModDrv=zText or
  ModDrv=zText4
Commentaries
  ModDrv=HRefCom or
  ModDrv=RawCom or
  ModDrv=RawCom4 or
  ModDrv=RawFiles or
  ModDrv=zCom or
  ModDrv=zCom4
Lexicons / Dictionaries
  ModDrv=RawLD or
  ModDrv=RawLD4 or
  ModDrv=zLD
Glossaries
  Feature=Glossary and
  ModDrv=RawLD or
  ModDrv=RawLD4 or
  ModDrv=zLD
Daily Devotional
  Feature=DailyDevotion and
  ModDrv=RawLD or
  ModDrv=RawLD4 or
  ModDrv=zLD
Generic Books
  ModDrv=RawGenBook

  
LCSH <tree/string>

Library of Congress Subject Heading. You may search the Library of Congress catalog or use it as a guide for determining an appropriate LCSH for books that are not in the Library of Congress.

   
Lang

<Language[-Script]?[-Region]?>
The language identifier is a combination of sub-tags for Language and optionally Script, and/or Region, according to BCP 47 and RFC 4647. Private use extensions defined by BCP 47 (e.g. x-, qaa, and Qaaa) should be avoided wherever possible.

Language sub-tag (Regex: /[a-z]{2,3}/):
This is the primary language code of the module according to ISO 639 parts 1, 2, 3 and 5. Some languages have several codes. Use the following to determine the best choice:

When available use a 2-letter ISO 639-1 code (registrar), (e.g. en for English).
If there is none for the given language, use an ISO 639-2/T code (registrar) (e.g. ceb for Cebuano).
Failing that, use a ISO 639-3 code (registrar), which covers over 7000 languages.
Finally, use a ISO 639-5 code (registrar) for macro languages.

The ISO639-3 registrar page gives up-to-date table on all of the above.

Script sub-tag (Regex: /[A-Z][a-z]{3}/):
If a text is script-specific, such as a Latin vs. Cyrillic Serbian Bible or a Bible transliterated into other than its native script, include the ISO 15924 script code (registrar) after the language code (e.g. sr-Latn for Latin script Serbian, sr-Cyrl for Cyrillic script Serbian).

Region sub-tag: (Regex: /[A-Z]{2}/)
If a text is region (country)-specific, such as the Anglicized NIV, include the ISO 3166-1 region code (registrar) after the script code (or language code if no country code is present) (e.g. en-GB for UK English).

Combinations(Regex: /[a-z]{2,3}(-[A-Z][a-z]{3})?(-[A-Z]{2})?/):
Individual sub-tags (language, script, and region) are always separated by a hyphen. Identifiers should be as basic and succinct as possible. A script should not be specified for a language written in its expected script, unless the language has multiple common scripts (as in the case of Serbian above). A region should not be specified unless a text should be categorized separately from others texts in that language that do not specify a region.

en  
InstallSize

<integer>
Indicates the total byte size of the module on disk, excluding the the size of any Lucene index files.

For modules in the CrossWire repositories, this is automatically generated and overwritten if needed.

   
Obsoletes

<ModName>
Each instance of this element gives a former ModName that is made obsolete by this module.

  Repeats
OSISVersion

<version string>
Identifies the OSIS schema version employed in the OSIS source document. The current version is 2.1.1

It is recommended that this be present for every OSIS module.

 
Companion[5]

<ModName[, ModName]*>
Specifies companion module(s) that should be opened together
e.g. When Bible and Commentary and/or Glossary modules are distributed together.

 

Note:

  1. ↑ Maximum line length is 1024 characters!
  2. ↑ See http://tracker.crosswire.org/browse/API-201
  3. ↑ Required to support a Bible/Commentary module that has an Alternate Versification.
  4. ↑ Essays is handled as a subset of Generic Books.
  5. ↑ Many (xulsword compatible) modules in the IBT Repository make use of this field. See also https://github.com/johnaustindev/osis-converters

Copyright & Licensing related elements

Element Values (type or enumerated) Default Value Allows
Copyright

<string>
Contains the copyright notice for the work, including the year of copyright and the owner of the copyright.

  Continuation
Localization
CopyrightHolder

<string>
Contains the name of the copyright holder.

  Localization
CopyrightDate

<yyyy> (ISO 8601 Year)

  Localization
CopyrightNotes

<string>

  Continuation
Localization
CopyrightContactName

<string>
Contains the name of the copyright holder.

  Continuation
Localization
CopyrightContactNotes

<string>

  Continuation
Localization
CopyrightContactAddress

<string>
Contains the mailing address of the copyright holder.

  Continuation
Localization
CopyrightContactEmail

<string>
Contains the email address of the copyright holder, preferably in the form:
name at xyz dot com

  Localization
ShortPromo

<string>
A link to the home page for the module, perhaps with an encouragement to visit the site.

  HTML Link
Localization
ShortCopyright

<string>

  Localization
DistributionLicense

Public Domain
Copyrighted
Copyrighted; Permission to distribute granted to CrossWire[1]
Copyrighted; Permission granted to distribute non-commercially in SWORD format
Copyrighted; Free non-commercial distribution
Copyrighted; Freely distributable
GFDL
GPL
Creative Commons: BY-NC-ND 4.0
Creative Commons: BY-NC-SA 4.0
Creative Commons: BY-NC 4.0
Creative Commons: BY-ND 4.0
Creative Commons: BY-SA 4.0
Creative Commons: BY 4.0
Creative Commons: CC0
Use one of these strings verbatim. The actual copyright and/or license information is held in other elements.
The last seven are different Creative Commons licenses.

   
DistributionNotes

<string>
Indicates any additional notes about distribution of the module.

  Continuation
Localization
TextSource

<string>
Indicates, either in prose (such as "CCEL") or as a URL of the source of the text

  Continuation
UnlockInfo

<string>
Contains unlock instructions for the user, intended to be displayed upon attempt to install the module. These instructions typically include a URL pointing to an exact location within a publisher's online store where a user can directly purchase an unlock key (CipherKey) for the module.

  RTF
Continuation
Localization
HTML Link

Note:

  1. ↑ Modules in other repositories may have a different organization name instead of CrossWire.

Comments and blank lines

Early in 2021, CrossWire began providing comment lines and blank lines in released and updated modules. Here's and example showing that there may sometimes be both even before the module ID. 

## Sword module configuration file

## Required elements
# Module Unique Identifier.
[GerMenge]
...
Some other module providers and repositories are already moving in the same direction.

Further details

Continuation

A value can span multiple lines by escaping the return with '\'. This is not a mechanism to make long lines more readable in the module.conf file. It is a means to introducing a break in the rendered output of that field when viewed by a front-end or installer. It is akin to a xHTML <br/>. That is, continuation is a formatting feature.

Most elements in a SWORD conf are expected to have short, one-line values. Elements that are expected to have multiple lines are noted.

RTF

A module.conf supports a very small, restricted subset of RTF markup. Only the following are allowed:

  • \qc - for centering
  • \par - for paragraph breaks
  • \pard - for resetting paragraph attributes, i.e. turning off centering.
  • \u{num}? - for unicode characters, where {num} is a signed, 16-bit representation of the code point and where ? is the ASCII character used in case unicode is not supported. If the {num} is less than 0 then add 65536 to it. This should only be used in modules that have an Encoding=UTF-8, but using the actual UTF-8 character is preferred.

The only uniqueness that RTF provides is centering. If centering is not needed, then use continuation lines instead of RTF.

Localization

Those .conf fields that are essentially text intended for presentation to the end-user may be localized by appending _locale to the field name, where locale is replaced by an appropriate locale code, according to BCP 47. See Lang key for details.

For example, to give a French description, you can have a key:

Description_fr=....

In order to distinguish a regional form from the primary form of a language, e.g. Brazilian Portuguese vs. the Portuguese of Portugal, append the country code as in:

Description_pt-BR=....

Script variants can be given as in:

Description_zh-Hans=.... simplified Chinese ....
Description_zh-Hant=.... traditional Chinese ....

In order for a .conf entry to appear in a localized form, a non-localized form of the same field must also occur within the .conf. For example, in order for a Description_en field to appear, a file must also possess a Description field. The locale of .conf entries without the locale modifier is the default and must reflect the locale/language of the module itself (as specified in Lang=) or English (if there are no localized versions of the field). In general, fields should be provided in the language of the module itself with English translations provided in parallel fields localized with _en. There is no explicit upper bound on the quantity of localized fields, but all localized and localizable fields should be unique.

  1. See also Localized Language Names.

Uniqueness

For comparing two versions of a module during module development, the module names and locations must be unique. For JSword based front-ends such as Bible Desktop, there is a further requirement, the Description items must be different.

Analysis Tools

  • DMSmith and Domcox have created scripts to analyse conf files and report anomalies.
  • David Haslam has created a User Defined Language called CONF as a Syntax Highlighter for Notepad++ (Windows). Download from [1].

Automated generation

  • For new module submissions to CrossWire, DomCox now maintains a script that includes the automated generation of module conf files, given the minimum non-automatable requirements by the module submitter. See Module Submission for more details.

See also

Retrieved from "http://wiki.crosswire.org/index.php?title=DevTools:conf_Files&oldid=17607"