CrossWire Bible Society - User contributions [en]

DevTools:conf Files

2024-02-20T06:22:32Z

Scribe: /* Copyright & Licensing related elements */

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

Please look also at our detailed and commented [[Tutorial:Writing Conf files|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===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|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 [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> 
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<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>
|
'''<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]
| [[DevTools:conf Files#Localization|Localization]]
|-
| Description
|
'''<string>''' 
This is a short (1 line) title of the module.
|  
| [[DevTools:conf Files#Localization|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<ref>Daily devotionals & glossaries go in subdirectories under lexdict. A glossary is between two languages.</ref>, 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)<ref name="text4">e.g. If the Bible contains large introduction sections</ref> 
'''zText''' (for compressed Bibles) 
'''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> 
'''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)<ref name="sv">zText4 & zCom4 modules require SwordVersion=1.8 or later.</ref> 
'''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)
|  
|  
|}

<references />

===Required Elements with defaults ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| SourceType<ref>Omitting this for a non-plaintext module has unpredictable effects.</ref>
|
'''Plaintext''' 
'''OSIS''' ([http://www.bibletechnologies.net Open Scriptural Information Standard]) 
'''TEI''' ([http://www.tei-c.org 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''' ([http://www.ebible.org/bible/gbf.htm General Bible Format]) 
'''ThML''' ([http://www.ccel.org/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''' ([http://en.wikipedia.org/wiki/Standard_Compression_Scheme_for_Unicode 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 [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
|  
|-
| CompressType
|
'''ZIP''' 
'''LZSS''' ([http://en.wikipedia.org/wiki/Lempel%E2%80%93Ziv%E2%80%93Storer%E2%80%93Szymanski 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<ref>i.e. Specify this ''only'' for a module that uses '''VerseKey'''.</ref>. 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
|  
|}

<references />

=== Elements required for proper rendering ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| GlobalOptionFilter
|
'''UTF8Cantillation''' (For Hebrew texts having cantillation marks)<ref>See https://en.wikipedia.org/wiki/Cantillation</ref> 
'''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> 
'''UTF8HebrewPoints''' (For Hebrew texts having vowel points)<ref>See https://en.wikipedia.org/wiki/Niqqud</ref> 
'''UTF8ArabicPoints''' (For Arabic texts having vowel points)<ref>See https://en.wikipedia.org/wiki/Arabic_diacritics</ref> 
'''OSISLemma''' (For OSIS texts having lemmas)<ref>Must precede OSISStrongs.</ref> 
'''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> 
'''OSISStrongs''' (For OSIS texts having Strong's Numbers)<ref name="strongs">See https://en.wikipedia.org/wiki/Strong%27s_Concordance#Strong.27s_numbers</ref> 
'''OSISFootnotes''' (For OSIS texts having informational notes) 
'''OSISScripref''' (For OSIS texts having [[OSIS Bibles#Marking_cross-references_note|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)<ref name="red">See https://en.wikipedia.org/wiki/Red_letter_edition</ref> 
'''OSISGlosses''' (For OSIS texts with glosses)<ref>Minimum SWORD version of 1.7.0 in the module .conf is required for OSISGlosses.</ref> 
'''OSISXlit''' (For OSIS texts that include transliterated forms)<ref>The Samaritan Pentateuch module SP is an example of using xlit.</ref> 
'''OSISEnum''' (For OSIS texts with enumerated words)<ref>The Samaritan Pentateuch module SP is an example of using enum.</ref> 
'''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> 
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> 
'''GBFStrongs''' (For GBF texts having Strong's Numbers)<ref name="strongs">See https://en.wikipedia.org/wiki/Strong%27s_Concordance#Strong.27s_numbers</ref> 
'''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)<ref name="red">See https://en.wikipedia.org/wiki/Red_letter_edition</ref> 
'''ThMLStrongs''' (For THML texts having Strong's Numbers)<ref name="strongs">See https://en.wikipedia.org/wiki/Strong%27s_Concordance#Strong.27s_numbers</ref> 
'''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.<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
|  
|-
| 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 [[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.
|  
|  
|-
| <del>OSISqToTick</del> (deprecated)<ref>For further details, refer to [http://www.crosswire.org/bugs/browse/MOD-188 MOD-188] in CrossWire bugs.</ref>
| This attribute is deprecated in favor of the marker attribute on the q element. E.g.: <pre><q who="Jesus" marker="">....</q></pre> 
<del>true/false</del> 
<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
|  
|-
| 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<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>)
|  
| 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.
|  
|  
|}
<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. 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''' – 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 ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| About
|
'''<string>''' 
A lengthier description and may include copyright, source, etc. information, possibly duplicating information in other elements.
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#RTF|RTF]] [[DevTools:conf Files#Localization|Localization]]
|-
| SwordVersionDate
|
'''<yyyy-mm-dd>''' ([http://en.wikipedia.org/wiki/ISO_8601#Calendar_dates 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>'''<ref>Maximum line length is 1024 characters!</ref> 
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 [[DevTools:conf Files#Localization|Localization]]
|-
| MinimumVersion<ref>See http://tracker.crosswire.org/browse/API-201</ref>
|
'''<version string>''' 
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
|  
|-
| Category
|valign="top"|
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)<ref>'''Essays''' is handled as a subset of '''Generic Books'''.</ref>
|
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 [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.
|  
|  
|-
| Lang
|
'''<Language[-Script]?[-Region]?>''' 
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}/)'': 
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: 
: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}/)'': 
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}/)'' 
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})?/)'': 
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<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>
|
'''<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:'''
<references/>

=== Copyright & Licensing related elements ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| Copyright
|
'''<string>''' 
Contains the copyright notice for the work, including the year of copyright and the owner of the copyright.
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightHolder
|
'''<string>''' 
Contains the name of the copyright holder.
|  
| [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightDate
|
'''<yyyy>''' ([http://en.wikipedia.org/wiki/ISO_8601#Years ISO 8601 Year])
|  
| [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightNotes
|
'''<string>'''
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightContactName
|
'''<string>''' 
Contains the name of the copyright holder.
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightContactNotes
|
'''<string>'''
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightContactAddress
|
'''<string>''' 
Contains the mailing address of the copyright holder.
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightContactEmail
|
'''<string>''' 
Contains the email address of the copyright holder, preferably in the form: name at xyz dot com
|  
| [[DevTools:conf Files#Localization|Localization]]
|-
| ShortPromo
|
'''<string>''' 
A link to the home page for the module, perhaps with an encouragement to visit the site.
|  
| HTML Link [[DevTools:conf Files#Localization|Localization]]
|-
| ShortCopyright
|
'''<string>'''
|  
| [[DevTools:conf Files#Localization|Localization]]
|- id="distlic"
| DistributionLicense
|
'''Public Domain''' 
'''Copyrighted''' 
'''Copyrighted; Permission to distribute granted to CrossWire'''<ref>Modules in other repositories may have a different organization name instead of CrossWire.</ref> 
'''Copyrighted; Permission granted to distribute non-commercially in SWORD format''' 
'''Copyrighted; Free non-commercial distribution''' 
'''Copyrighted; Freely distributable''' 
'''[http://www.gnu.org/copyleft/fdl.html GFDL]''' 
'''[http://www.gnu.org/copyleft/gpl.html 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: [http://creativecommons.org/publicdomain/zero/1.0/ CC0]''' 
Use one of these strings '''verbatim'''. The actual copyright and/or license information is held in other elements. The last seven are different [https://creativecommons.org/licenses/ Creative Commons licenses].
|  
|  
|-
| DistributionNotes
|
'''<string>''' 
Indicates any additional notes about distribution of the module.
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|- id="txtsrc"
| TextSource
|
'''<string>''' 
Indicates, either in prose (such as "CCEL") or as a URL of the source of the text
|  
| [[DevTools:conf Files#Continuation|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.
|  
| [[DevTools:conf Files#RTF|RTF]] [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]] 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 . 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]].

=== 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 ===
* [[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].

== 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.

== See also ==
* [[BibTeX entries]]

[[Category:Development tools|Conf files]]
[[Category:Localization|Conf files]]
[[Category:Versification|Conf files]]
[[Category:Copyright|Conf files]]

User:Gregs650

2022-07-03T17:30:05Z

Scribe: Creating user page for new user.

Greg is new to SWORD. A few programming technologies were learned from internet tutorials on 1 / 3 devices - Acer laptop with Ubuntu server 20.04, Android Samsung tablet (Tab A) and Android Galaxy S9 cell phone. Simple learning included
1. Basic HTML, CSS, and Java-script.
2. Programming languages: recently shell and C++. In the past, python and some hello world programs for swift, java, etc.

Three web sites had been done. The first one attempted now just reports a deactivated message. It is at https://goo.gl/g0v1rE. It is a Google apps script which is capable of reading and writing from / to Google Drive. The second one was a Google App Engine in python. That app engine is not currently running due to a new billing error / warning from the gcloud command line interface. The 3rd web-page needs some work to be restored. It is a server that ran on the Acer laptop.

A simple bible program had been made in C++ to run in the terminal. Instead of continuing with that, the SWORD project is being learned. That simple program was not deployed anywhere, but read KJV text from a Gutenberg file that was divided and reformatted for easier machine reading.

User talk:Gregs650

2022-07-03T17:30:05Z

Scribe: Welcome!

'''Welcome to ''CrossWire Bible Society''!'''
We hope you will contribute much and well.
You will probably want to read the [https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Contents help pages].
Again, welcome and have fun! [[User:Scribe|Scribe]] ([[User talk:Scribe|talk]]) 17:30, 3 July 2022 (UTC)

Main Page

2022-06-28T11:34:08Z

Scribe:

{| cellspacing="1" width="100%"
|- valign="top"
|style="border: 1px solid green;padding-left:1em;padding-right:0.5em;background:#E4FFDF;padding-bottom:0.5em;" width="100%"|
==Welcome to the CrossWire developers' wiki==

Check out our [[Current Projects|current projects]] page to see how you might use your skills. Please also look at our general [[Volunteers|volunteering]] page.

If you want to help in this wiki, please use [https://wiki.crosswire.org/Special:RequestAccount this form] and then send an email to [mailto:support@crosswire.org support@crosswire.org] to remind us to approve your newly requested account.

Here is the [http://tracker.crosswire.org bugs] database. Chat with SWORD developers on IRC: [http://webchat.freenode.net/?randomnick=1&channels=sword&prompt=1 #sword] on FreeNode.

|}
{| cellspacing="1" width="100%"
|- valign="top"

| style="background:#E8F1FF;border-style:solid;border-width:1px;border-color:#00ccFF;padding-left:1em;padding-right:0.5em; padding-bottom:0.5em;" width="50%"|

==Front-end Bible study applications==

===SWORD based front-ends===
* [[Frontends:BibleCS|The SWORD Project for Windows]] (internally known as BibleCS)
* [[Frontends:Bishop|The SWORD Project]] for Android, iOS & iPadOS (internally known as Bishop)
* [[Frontends:Eloquent|Eloquent]] MacOS desktop application
* [[Frontends:Xiphos|Xiphos]] Windows & Linux desktop application
* [[Frontends:BibleTime|BibleTime]] Windows & Linux desktop application
* [[Frontends:The_Bible_Tool|The Bible Tool]] web server application
* [[Frontends:PocketSword|PocketSword]] iOS & iPadOS application
* [[Frontends:Holy Bible|Holy Bible]] Windows Desktop application
* [[Frontends:Ezra Bible App|Ezra Bible App]] Windows, Linux, MacOS desktop & Android tablet application
* [https://www.godehardt.org/losung.html GLosung] Gottes Wort für deinen Desktop
* [https://pierre-amadio.github.io/matheteuo/ matheteuo] flashcards to help study Biblical Hebrew & Greek

===JSword based front-ends===
* [[Frontends:BibleDesktop|BibleDesktop]]
* [http://www.kiyut.com/products/alkitab/ Alkitab Bible Study]
* [[Frontends:GSword|GSword]] – CCIM Online Bible Studio
* [https://mjdenham.github.io/and-bible/ And Bible] – for Android OS
* [https://www.stepbible.org/ STEP Bible] – originally developed at [https://www.tyndalehouse.com/ Tyndale House]

=== Front-ends in general ===
* [[Choosing a SWORD program]]
* [[Frontends:No longer being actively developed|Front-ends no longer being actively developed]]

==SWORD module sources==
* [[SWORD Module Source Discovery and Module Updating|SWORD Module Remote Installation Source Repository Discovery and Module Updating]]
* [[Official and Affiliated Module Repositories]]
* [[Other Module Sources]]
* [[Creating and Maintaining a Module Repository]]

==Public relations, website, user assistance==
* [[Contact| Contact us]]
* CrossWire's [[Copyright|copyright]] policy
* [[EnduserFAQ|Frequently Asked Questions]]
* [[Help:Contents|Help]], [[Help:Bugs|Bugs]] and [[Help:Mailing Lists|Mailing Lists]]
* [[SWORD CD]]

|valign="top" bgcolor="#FFE8E8" style="border-style:solid;border-width:1px;border-color:#FF6060;padding-left:1em;padding-right:0.5em; padding-bottom:0.5em;" width="50%"|

==Back-end API development tools==
* [[DevTools:SWORD|SWORD Engine (C++)]]
** Compiling and installing SWORD
*** on [[Tutorial:Compiling & Installing SWORD| Linux/MacOS/Unix]]
*** on or for [[Tutorial:Compiling & Installing SWORD on Windows|Windows]]
*** with [[DevTools:CMake|CMake]]
** [[:DevTools:Code Examples|Code Examples]]
** [[Tutorial:How SWORD works]]
** [[DevTools:Locale Files|Locale Files]]
** [[DevTools:Bindings|SWIG Bindings]], [[DevTools:CSharp Bindings on Windows|C# Bindings on Windows]], [[DevTools:JNI Bindings for Android|Android Bindings]]
** bug reports with or without appended patches to our [http://tracker.crosswire.org/projects/API/issues/API-119?filter=allopenissues|bug tracker]
* [[DevTools:JSword|JSword Engine (Java)]]
** [[DevTools:JSword/Personal Commentary|Personal Commentary]]
** [[DevTools:JSword/Internationalization|Internationalization]]

==Open Scriptures Information Standard==
* A basic [[OSIS Tutorial|OSIS XML tutorial]]
* [[OSIS 211 CR| OSIS 2.1.1 schema change requests]]
* [https://www.crosswire.org/~dmsmith/osis/osisCore.2.1.1-cw-latest.xsd OSIS schema]
* [[List of eXtensions to OSIS used in SWORD]]

==Ancillary software==
* [[BibleSync]] – for Bible software shared co-navigation
* [[DevTools:ICU|International Components for Unicode (ICU)]]

== Development proposals and discussions ==
* [[Whiteboard]]

==Module development==
* How to create [[DevTools:Modules|SWORD Modules]] & [[DevTools:conf Files|Module Configuration Files]]
* Guides to writing
**[[OSIS Bibles]], [[OSIS Commentaries]],
**[[OSIS Genbooks]], [[TEI Dictionaries]]
* Guide to [[Validate_OSIS_or_TEI_text]]
* Guide to [[Converting SFM Bibles to OSIS]]
* About [[Alternate Versification|Bible Versification]] schemes
* About [[File Formats]] and related [[File Formats#The_SWORD_Project_Utilities|Utility Programs]]
* About Unicode [[Encoding]]s, [[Fonts]] & [[DevTools:Text Editors|Text Editors]]
-----
* [[Module Development Collaboration]]
* [[Notes on particular CrossWire modules]]
* [[Module Requests]] and [[Non-CrossWire Text-Development Projects|Text Development]]
* [[Module Submission]]

|}
{| cellspacing="1" width="100%"
|- valign="top"
|style="border: 1px solid gray;padding-left:1em;padding-right:0.5em;background:#E8E8E8;padding-bottom:0.5em;" width="100%"|

==Getting started in wiki collaboration==
A wiki is a place to share documentation and development information.
* New user account [mailto://support@crosswire.org|requests] are now moderated. Anyone who has been a member for at least 4 days can edit a wiki once they have [[Special:Userlogin|logged in]].
* If you are new to wikis, consult the [http://meta.wikipedia.org/wiki/MediaWiki_User's_Guide User's Guide] or the [http://www.mediawiki.org/wiki/Help:FAQ MediaWiki FAQ] for information on using the wiki software .
* Look to see what might need attention by visiting [[Wiki Maintenance]]
* You may experiment with wiki using our [[CrossWire:Sandbox|Sandbox]].
* Another way to navigate the wiki is to click on [[:Category:Categories]].

|}

[[Category:CrossWire]]
[[Category:SWORD Frontends]]
[[Category:SWORD]]
[[Category:JSword]]
[[Category:OSIS]]
[[Category:Modules]]
[[Category:Development tools]]
[[Category:Support]]
__NOTOC__

Main Page

2022-06-28T11:18:05Z

Scribe:

{| cellspacing="1" width="100%"
|- valign="top"
|style="border: 1px solid green;padding-left:1em;padding-right:0.5em;background:#E4FFDF;padding-bottom:0.5em;" width="100%"|
==Welcome to the CrossWire developers' wiki==

Check out our [[Current Projects|current projects]] page to see how you might use your skills. Please also look at our general [[Volunteers|volunteering]] page.

If you want to help in this wiki, please [mailto:support@crosswire.org request] an account.

Here is the [http://tracker.crosswire.org bugs] database. Chat with SWORD developers on IRC: [http://webchat.freenode.net/?randomnick=1&channels=sword&prompt=1 #sword] on FreeNode.

|}
{| cellspacing="1" width="100%"
|- valign="top"

| style="background:#E8F1FF;border-style:solid;border-width:1px;border-color:#00ccFF;padding-left:1em;padding-right:0.5em; padding-bottom:0.5em;" width="50%"|

==Front-end Bible study applications==

===SWORD based front-ends===
* [[Frontends:BibleCS|The SWORD Project for Windows]] (internally known as BibleCS)
* [[Frontends:Bishop|The SWORD Project]] for Android, iOS & iPadOS (internally known as Bishop)
* [[Frontends:Eloquent|Eloquent]] MacOS desktop application
* [[Frontends:Xiphos|Xiphos]] Windows & Linux desktop application
* [[Frontends:BibleTime|BibleTime]] Windows & Linux desktop application
* [[Frontends:The_Bible_Tool|The Bible Tool]] web server application
* [[Frontends:PocketSword|PocketSword]] iOS & iPadOS application
* [[Frontends:Holy Bible|Holy Bible]] Windows Desktop application
* [[Frontends:Ezra Bible App|Ezra Bible App]] Windows, Linux, MacOS desktop & Android tablet application
* [https://www.godehardt.org/losung.html GLosung] Gottes Wort für deinen Desktop
* [https://pierre-amadio.github.io/matheteuo/ matheteuo] flashcards to help study Biblical Hebrew & Greek

===JSword based front-ends===
* [[Frontends:BibleDesktop|BibleDesktop]]
* [http://www.kiyut.com/products/alkitab/ Alkitab Bible Study]
* [[Frontends:GSword|GSword]] – CCIM Online Bible Studio
* [https://mjdenham.github.io/and-bible/ And Bible] – for Android OS
* [https://www.stepbible.org/ STEP Bible] – originally developed at [https://www.tyndalehouse.com/ Tyndale House]

=== Front-ends in general ===
* [[Choosing a SWORD program]]
* [[Frontends:No longer being actively developed|Front-ends no longer being actively developed]]

==SWORD module sources==
* [[SWORD Module Source Discovery and Module Updating|SWORD Module Remote Installation Source Repository Discovery and Module Updating]]
* [[Official and Affiliated Module Repositories]]
* [[Other Module Sources]]
* [[Creating and Maintaining a Module Repository]]

==Public relations, website, user assistance==
* [[Contact| Contact us]]
* CrossWire's [[Copyright|copyright]] policy
* [[EnduserFAQ|Frequently Asked Questions]]
* [[Help:Contents|Help]], [[Help:Bugs|Bugs]] and [[Help:Mailing Lists|Mailing Lists]]
* [[SWORD CD]]

|valign="top" bgcolor="#FFE8E8" style="border-style:solid;border-width:1px;border-color:#FF6060;padding-left:1em;padding-right:0.5em; padding-bottom:0.5em;" width="50%"|

==Back-end API development tools==
* [[DevTools:SWORD|SWORD Engine (C++)]]
** Compiling and installing SWORD
*** on [[Tutorial:Compiling & Installing SWORD| Linux/MacOS/Unix]]
*** on or for [[Tutorial:Compiling & Installing SWORD on Windows|Windows]]
*** with [[DevTools:CMake|CMake]]
** [[:DevTools:Code Examples|Code Examples]]
** [[Tutorial:How SWORD works]]
** [[DevTools:Locale Files|Locale Files]]
** [[DevTools:Bindings|SWIG Bindings]], [[DevTools:CSharp Bindings on Windows|C# Bindings on Windows]], [[DevTools:JNI Bindings for Android|Android Bindings]]
** bug reports with or without appended patches to our [http://tracker.crosswire.org/projects/API/issues/API-119?filter=allopenissues|bug tracker]
* [[DevTools:JSword|JSword Engine (Java)]]
** [[DevTools:JSword/Personal Commentary|Personal Commentary]]
** [[DevTools:JSword/Internationalization|Internationalization]]

==Open Scriptures Information Standard==
* A basic [[OSIS Tutorial|OSIS XML tutorial]]
* [[OSIS 211 CR| OSIS 2.1.1 schema change requests]]
* [https://www.crosswire.org/~dmsmith/osis/osisCore.2.1.1-cw-latest.xsd OSIS schema]
* [[List of eXtensions to OSIS used in SWORD]]

==Ancillary software==
* [[BibleSync]] – for Bible software shared co-navigation
* [[DevTools:ICU|International Components for Unicode (ICU)]]

== Development proposals and discussions ==
* [[Whiteboard]]

==Module development==
* How to create [[DevTools:Modules|SWORD Modules]] & [[DevTools:conf Files|Module Configuration Files]]
* Guides to writing
**[[OSIS Bibles]], [[OSIS Commentaries]],
**[[OSIS Genbooks]], [[TEI Dictionaries]]
* Guide to [[Validate_OSIS_or_TEI_text]]
* Guide to [[Converting SFM Bibles to OSIS]]
* About [[Alternate Versification|Bible Versification]] schemes
* About [[File Formats]] and related [[File Formats#The_SWORD_Project_Utilities|Utility Programs]]
* About Unicode [[Encoding]]s, [[Fonts]] & [[DevTools:Text Editors|Text Editors]]
-----
* [[Module Development Collaboration]]
* [[Notes on particular CrossWire modules]]
* [[Module Requests]] and [[Non-CrossWire Text-Development Projects|Text Development]]
* [[Module Submission]]

|}
{| cellspacing="1" width="100%"
|- valign="top"
|style="border: 1px solid gray;padding-left:1em;padding-right:0.5em;background:#E8E8E8;padding-bottom:0.5em;" width="100%"|

==Getting started in wiki collaboration==
A wiki is a place to share documentation and development information.
* New user account [mailto://support@crosswire.org|requests] are now moderated. Anyone who has been a member for at least 4 days can edit a wiki once they have [[Special:Userlogin|logged in]].
* If you are new to wikis, consult the [http://meta.wikipedia.org/wiki/MediaWiki_User's_Guide User's Guide] or the [http://www.mediawiki.org/wiki/Help:FAQ MediaWiki FAQ] for information on using the wiki software .
* Look to see what might need attention by visiting [[Wiki Maintenance]]
* You may experiment with wiki using our [[CrossWire:Sandbox|Sandbox]].
* Another way to navigate the wiki is to click on [[:Category:Categories]].

|}

[[Category:CrossWire]]
[[Category:SWORD Frontends]]
[[Category:SWORD]]
[[Category:JSword]]
[[Category:OSIS]]
[[Category:Modules]]
[[Category:Development tools]]
[[Category:Support]]
__NOTOC__

SWORD Module Source Discovery and Module Updating

2021-03-13T23:30:48Z

Scribe:

= SWORD Module Remote Installation Source Repository Discovery, Module Installation, and Updating =

== Overview ==

The SWORD Project Remote Module Source Discovery, Module Installation, and Module Updating is a straightforward process which both the SWORD and JSword engine support programmatically. Each CrossWire frontend makes these steps available to the user by calling the appropriate SWORD or JSword method for them. There also exists a simple command line tool (installmgr) to perform these actions, and this simple tool provides to SWORD frontend developers a great example of how to perform each of these steps from within their application. The steps can generally be list as these; more details about each can be found below:

<ol start="0">
<li>Warn user about the risks.</li>
<li>Query CrossWire to obtain the list of known publishers of SWORD materials.</li>
<li>Query each publisher for a list of available resources.</li>
</ol>
==== Installation ====
<ol start="3">
<li>Present available resources to user.</li>
<li>Display the detail for a selected module.</li>
<li>Install the module.</li>
<li>Check to see if the module is enciphered and obtain that code from the user.</li>
</ol>
==== Update ====
<ol start="7">
<li>Refresh resource list obtained in step #2.</li>
<li>Iterate all installed modules and see if the installed module has a version number less than the version number in the refreshed resource list.</li>
<li>Present to the user the history list between the user's installed version and the available updated version, to inform the user what has changed and ask if an update is desired.</li>
<li>Uninstall the module.</li>
<li>Install the updated module.</li>
</ol>

Each of these steps has a simple method available to the programmer from the SWORD engine.

== 0. Warn user about the risks. ==

CrossWire has a policy to always warn users before enabling Remote Module Installation. Many of our users live in persecuted countries and using CrossWire's systematic method for installing modules from remote sources poses a risk of detection for these users. This is the warning we typically present during an application run the first time any Remote Module Installation action is requested:

<nowiki>
-=+* WARNING *+=- -=+* WARNING *+=-

Although Install Manager provides a convenient way for installing
and upgrading SWORD components, it also uses a systematic method
for accessing sites which gives packet sniffers a target to lock
into for singling out users.

IF YOU LIVE IN A PERSECUTED COUNTRY AND DO NOT WISH TO RISK DETECTION,
YOU SHOULD *NOT* USE INSTALL MANAGER'S REMOTE SOURCE FEATURES.

Also, Remote Sources other than CrossWire may contain less than
quality modules, modules with unorthodox content, or even modules
which are not legitimately distributable. Many repositories
contain wonderfully useful content. These repositories simply
are not reviewed or maintained by CrossWire and CrossWire
cannot be held responsible for their content. CAVEAT EMPTOR.

If you understand this and are willing to enable remote source features
then type yes at the prompt

enable? [no]

</nowiki>

Also, because user from these countries often do not speak English, we ask the user to type a response to enable the feature.

== 1. Query CrossWire to obtain the list of known publishers of SWORD materials. ==

To discover the list of available module remote source repositories from publishers using the installmgr command line tool:

installmgr -sc

==== Details ====
The registry of all known and endorsed module remote source installation repositories is located at this URL and is pull by SWORD and JSword automatically to satisfy this step (e.g., by the command: installmgr -sc)

[https://crosswire.org/ftpmirror/pub/sword/masterRepoList.conf https://crosswire.org/ftpmirror/pub/sword/masterRepoList.conf]

== 2. Query each publisher for a list of available resources. ==

To get a list of available publishers of remote SWORD module sources

installmgr -s

To refresh one of these, e.g., the "CrossWire" source:

installmgr -r "CrossWire"

==== Details ====

A module remote installation source repository is simply a set of SWORD resources installed in the same way as they would be installed for use by a SWORD frontend, but also made available online via FTP or HTTP. There may be optional additional files included which can speed up the use of large repositories, and some additional files currently needed to support JSword (until their install tools are improved to match our main SWORD engine), but essentially, any installed module set can be used as a module installation source for use by other SWORD users to choose and install modules.

== 3. Present available resources to user. ==

To display resources available from a publisher, e.g., from the "CrossWire" source:

installmgr -rl "CrossWire"

== 4. Display the detail for a selected module. ==

To display the details for a module, e.g., the KJV available from CrossWire:

installmgr -rdesc "CrossWire" KJV

== 5. Install the module. ==

To install, e.g., the KJV from CrossWire remote source repository:

installmgr -ri "CrossWire" KJV

== 6. Check to see if the module is enciphered and obtain that code from the user. ==

To check if the NA28 module from the "Deutsche Bibelgesellschaft" source repository needs an unlock key:

installmgr -rdesc "Deutsche Bibelgesellschaft" NA28|grep "^\[CipherKey"

==== Details ====

A modules' .conf file will include a CipherKey entry to designate that the module is enciphered and needs a key to use. Once the user provides the key, it should be entered as the value for the CipherKey entry, e.g.,

[ModuleName]
CipherKey=xyzzy

Typically these and other user-supplied settings for a module should be kept in their own .conf file and merged into the SWORD config, e.g.,

SWMgr library;
library.config->augment(SWConfig("~/.sword/userPreferences.conf"));

Where ~/.sword/userPreferences.conf would contain sections for each module along with the properties to augment:

[ModuleName]
CipherKey=xyzzy

This is valuable when updating a module, so as not to lose the any user-supplied preferences when uninstalling and then re-installing the module during the update.

== 7. Refresh resource list obtained in step #2. ==

== 8. Iterate all installed modules and see if the installed module has a version number less than the version number in the refreshed resource list. ==

To check for updates in, e.g., the CrossWire repository:

installmgr -rd "CrossWire"|grep "^+"

==== Details ====

Each module's .conf file contains a Version property which tells the module's current version. Installmgr's -rd flag will only show new (lines beginning with a '*') and updated (lines beginning with a '+') modules.

== 9. Present to the user the history list between the user's installed version and the available updated version, to inform the user what has changed and ask if an update is desired. ==

installmgr -rdesc CrossWire Nave|grep "^\[History"

==== Details ====

A module's .conf file will include History_version properties which describe what was updated for that version of the module.
It is desirable to only display to the user the History_version lines which are between the user's currently installed module version and the latest version which they are queried if they would like to update.

== 10. Uninstall the module. ==

To uninstall the KJV module:

installmgr -u KJV

== 11. Install the updated module. ==

installmgr -ri "CrossWire" KJV

SWORD Module Source Discovery and Module Updating

2021-03-13T23:20:40Z

Scribe:

= SWORD Module Remote Installation Source Repository Discovery, Module Installation, and Updating =

== Overview ==

The SWORD Project Remote Module Source Discovery, Module Installation, and Module Updating is a straightforward process which both the SWORD and JSword engine support programmatically. Each CrossWire frontend makes these steps available to the user by calling the appropriate SWORD or JSword method for them. There also exists a simple command line tool (installmgr) to perform these actions, and this simple tool provides to SWORD frontend developers a great example of how to perform each of these steps from within their application. The steps can generally be list as these; more details about each can be found below:

{{ordered list|start=0
| Warn user about the risks.
| Query CrossWire to obtain the list of known publishers of SWORD materials.
| Query each publisher for a list of available resources.
}}
==== Installation ====
{{ordered list|start=3
| Present available resources to user.
| Display the detail for a selected module.
| Install the module.
| Check to see if the module is enciphered and obtain that code from the user.
}}
==== Update ====
{{ordered list|start=7
| Refresh resource list obtained in step #2.
| Iterate all installed modules and see if the installed module has a version number less than the version number in the refreshed resource list.
| Present to the user the history list between the user's installed version and the available updated version, to inform the user what has changed and ask if an update is desired.
| Uninstall the module.
| Install the updated module.
}}

Each of these steps has a simple method available to the programmer from the SWORD engine.

== 0. Warn user about the risks. ==

CrossWire has a policy to always warn users before enabling Remote Module Installation. Many of our users live in persecuted countries and using CrossWire's systematic method for installing modules from remote sources poses a risk of detection for these users. This is the warning we typically present during an application run the first time any Remote Module Installation action is requested:

<nowiki>
-=+* WARNING *+=- -=+* WARNING *+=-

Although Install Manager provides a convenient way for installing
and upgrading SWORD components, it also uses a systematic method
for accessing sites which gives packet sniffers a target to lock
into for singling out users.

IF YOU LIVE IN A PERSECUTED COUNTRY AND DO NOT WISH TO RISK DETECTION,
YOU SHOULD *NOT* USE INSTALL MANAGER'S REMOTE SOURCE FEATURES.

Also, Remote Sources other than CrossWire may contain less than
quality modules, modules with unorthodox content, or even modules
which are not legitimately distributable. Many repositories
contain wonderfully useful content. These repositories simply
are not reviewed or maintained by CrossWire and CrossWire
cannot be held responsible for their content. CAVEAT EMPTOR.

If you understand this and are willing to enable remote source features
then type yes at the prompt

enable? [no]

</nowiki>

Also, because user from these countries often do not speak English, we ask the user to type a response to enable the feature.

== 1. Query CrossWire to obtain the list of known publishers of SWORD materials. ==

To discover the list of available module remote source repositories from publishers using the installmgr command line tool:

installmgr -sc

==== Details ====
The registry of all known and endorsed module remote source installation repositories is located at this URL and is pull by SWORD and JSword automatically to satisfy this step (e.g., by the command: installmgr -sc)

[https://crosswire.org/ftpmirror/pub/sword/masterRepoList.conf https://crosswire.org/ftpmirror/pub/sword/masterRepoList.conf]

== 2. Query each publisher for a list of available resources. ==

To get a list of available publishers of remote SWORD module sources

installmgr -s

To refresh one of these, e.g., the "CrossWire" source:

installmgr -r "CrossWire"

==== Details ====

A module remote installation source repository is simply a set of SWORD resources installed in the same way as they would be installed for use by a SWORD frontend, but also made available online via FTP or HTTP. There may be optional additional files included which can speed up the use of large repositories, and some additional files currently needed to support JSword (until their install tools are improved to match our main SWORD engine), but essentially, any installed module set can be used as a module installation source for use by other SWORD users to choose and install modules.

== 3. Present available resources to user. ==

To display resources available from a publisher, e.g., from the "CrossWire" source:

installmgr -rl "CrossWire"

== 4. Display the detail for a selected module. ==

To display the details for a module, e.g., the KJV available from CrossWire:

installmgr -rdesc "CrossWire" KJV

== 5. Install the module. ==

To install, e.g., the KJV from CrossWire remote source repository:

installmgr -ri "CrossWire" KJV

== 6. Check to see if the module is enciphered and obtain that code from the user. ==

To check if the NA28 module from the "Deutsche Bibelgesellschaft" source repository needs an unlock key:

installmgr -rdesc "Deutsche Bibelgesellschaft" NA28|grep "^\[CipherKey"

==== Details ====

A modules' .conf file will include a CipherKey entry to designate that the module is enciphered and needs a key to use. Once the user provides the key, it should be entered as the value for the CipherKey entry, e.g.,

[ModuleName]
CipherKey=xyzzy

Typically these and other user-supplied settings for a module should be kept in their own .conf file and merged into the SWORD config, e.g.,

SWMgr library;
library.config->augment(SWConfig("~/.sword/userPreferences.conf"));

Where ~/.sword/userPreferences.conf would contain sections for each module along with the properties to augment:

[ModuleName]
CipherKey=xyzzy

This is valuable when updating a module, so as not to lose the any user-supplied preferences when uninstalling and then re-installing the module during the update.

== 7. Refresh resource list obtained in step #2. ==

== 8. Iterate all installed modules and see if the installed module has a version number less than the version number in the refreshed resource list. ==

To check for updates in, e.g., the CrossWire repository:

installmgr -rd "CrossWire"|grep "^+"

==== Details ====

Each module's .conf file contains a Version property which tells the module's current version. Installmgr's -rd flag will only show new (lines beginning with a '*') and updated (lines beginning with a '+') modules.

== 9. Present to the user the history list between the user's installed version and the available updated version, to inform the user what has changed and ask if an update is desired. ==

installmgr -rdesc CrossWire Nave|grep "^\[History"

==== Details ====

A module's .conf file will include History_version properties which describe what was updated for that version of the module.
It is desirable to only display to the user the History_version lines which are between the user's currently installed module version and the latest version which they are queried if they would like to update.

== 10. Uninstall the module. ==

To uninstall the KJV module:

installmgr -u KJV

== 11. Install the updated module. ==

installmgr -ri "CrossWire" KJV

SWORD Module Source Discovery and Module Updating

2021-03-13T23:13:33Z

Scribe:

= SWORD Module Remote Installation Source Repository Discovery, Module Installation, and Updating =

== Overview ==

The SWORD Project Remote Module Source Discovery, Module Installation, and Module Updating is a straightforward process which both the SWORD and JSword engine support programmatically. Each CrossWire frontend makes these steps available to the user by calling the appropriate SWORD or JSword method for them. There also exists a simple command line tool (installmgr) to perform these actions, and this simple tool provides to SWORD frontend developers a great example of how to perform each of these steps from within their application. The steps can generally be list as these; more details about each can be found below:

# Warn user about the risks.
# Query CrossWire to obtain the list of known publishers of SWORD materials.
# Query each publisher for a list of available resources.
==== Installation ====
# Present available resources to user.
# Display the detail for a selected module.
# Install the module.
# Check to see if the module is enciphered and obtain that code from the user.
==== Update ====
# Refresh resource list obtained in step #2.
# Iterate all installed modules and see if the installed module has a version number less than the version number in the refreshed resource list.
# Present to the user the history list between the user's installed version and the available updated version, to inform the user what has changed and ask if an update is desired.
# Uninstall the module.
# Install the updated module.

Each of these steps has a simple method available to the programmer from the SWORD engine.

== 0. Warn user about the risks. ==

CrossWire has a policy to always warn users before enabling Remote Module Installation. Many of our users live in persecuted countries and using CrossWire's systematic method for installing modules from remote sources poses a risk of detection for these users. This is the warning we typically present during an application run the first time any Remote Module Installation action is requested:

<nowiki>
-=+* WARNING *+=- -=+* WARNING *+=-

Although Install Manager provides a convenient way for installing
and upgrading SWORD components, it also uses a systematic method
for accessing sites which gives packet sniffers a target to lock
into for singling out users.

IF YOU LIVE IN A PERSECUTED COUNTRY AND DO NOT WISH TO RISK DETECTION,
YOU SHOULD *NOT* USE INSTALL MANAGER'S REMOTE SOURCE FEATURES.

Also, Remote Sources other than CrossWire may contain less than
quality modules, modules with unorthodox content, or even modules
which are not legitimately distributable. Many repositories
contain wonderfully useful content. These repositories simply
are not reviewed or maintained by CrossWire and CrossWire
cannot be held responsible for their content. CAVEAT EMPTOR.

If you understand this and are willing to enable remote source features
then type yes at the prompt

enable? [no]

</nowiki>

Also, because user from these countries often do not speak English, we ask the user to type a response to enable the feature.

== 1. Query CrossWire to obtain the list of known publishers of SWORD materials. ==

To discover the list of available module remote source repositories from publishers using the installmgr command line tool:

installmgr -sc

==== Details ====
The registry of all known and endorsed module remote source installation repositories is located at this URL and is pull by SWORD and JSword automatically to satisfy this step (e.g., by the command: installmgr -sc)

[https://crosswire.org/ftpmirror/pub/sword/masterRepoList.conf https://crosswire.org/ftpmirror/pub/sword/masterRepoList.conf]

== 2. Query each publisher for a list of available resources. ==

To get a list of available publishers of remote SWORD module sources

installmgr -s

To refresh one of these, e.g., the "CrossWire" source:

installmgr -r "CrossWire"

==== Details ====

A module remote installation source repository is simply a set of SWORD resources installed in the same way as they would be installed for use by a SWORD frontend, but also made available online via FTP or HTTP. There may be optional additional files included which can speed up the use of large repositories, and some additional files currently needed to support JSword (until their install tools are improved to match our main SWORD engine), but essentially, any installed module set can be used as a module installation source for use by other SWORD users to choose and install modules.

== 3. Present available resources to user. ==

To display resources available from a publisher, e.g., from the "CrossWire" source:

installmgr -rl "CrossWire"

== 4. Display the detail for a selected module. ==

To display the details for a module, e.g., the KJV available from CrossWire:

installmgr -rdesc "CrossWire" KJV

== 5. Install the module. ==

To install, e.g., the KJV from CrossWire remote source repository:

installmgr -ri "CrossWire" KJV

== 6. Check to see if the module is enciphered and obtain that code from the user. ==

To check if the NA28 module from the "Deutsche Bibelgesellschaft" source repository needs an unlock key:

installmgr -rdesc "Deutsche Bibelgesellschaft" NA28|grep "^\[CipherKey"

==== Details ====

A modules' .conf file will include a CipherKey entry to designate that the module is enciphered and needs a key to use. Once the user provides the key, it should be entered as the value for the CipherKey entry, e.g.,

[ModuleName]
CipherKey=xyzzy

Typically these and other user-supplied settings for a module should be kept in their own .conf file and merged into the SWORD config, e.g.,

SWMgr library;
library.config->augment(SWConfig("~/.sword/userPreferences.conf"));

Where ~/.sword/userPreferences.conf would contain sections for each module along with the properties to augment:

[ModuleName]
CipherKey=xyzzy

This is valuable when updating a module, so as not to lose the any user-supplied preferences when uninstalling and then re-installing the module during the update.

== 7. Refresh resource list obtained in step #2. ==

== 8. Iterate all installed modules and see if the installed module has a version number less than the version number in the refreshed resource list. ==

To check for updates in, e.g., the CrossWire repository:

installmgr -rd "CrossWire"|grep "^+"

==== Details ====

Each module's .conf file contains a Version property which tells the module's current version. Installmgr's -rd flag will only show new (lines beginning with a '*') and updated (lines beginning with a '+') modules.

== 9. Present to the user the history list between the user's installed version and the available updated version, to inform the user what has changed and ask if an update is desired. ==

installmgr -rdesc CrossWire Nave|grep "^\[History"

==== Details ====

A module's .conf file will include History_version properties which describe what was updated for that version of the module.
It is desirable to only display to the user the History_version lines which are between the user's currently installed module version and the latest version which they are queried if they would like to update.

== 10. Uninstall the module. ==

To uninstall the KJV module:

installmgr -u KJV

== 11. Install the updated module. ==

installmgr -ri "CrossWire" KJV

SWORD Module Source Discovery and Module Updating

2021-03-13T23:07:28Z

Scribe:

== Overview ==

The SWORD Project Remote Module Source Discovery, Module Installation, and Module Updating is a straightforward process which both the SWORD and JSword engine support programmatically. Each CrossWire frontend makes these steps available to the user by calling the appropriate SWORD or JSword method for them. There also exists a simple command line tool (installmgr) to perform these actions, and this simple tool provides to SWORD frontend developers a great example of how to perform each of these steps from within their application. The steps can generally be list as these; more details about each can be found below:

0. Warn user about the risks.
1. Query CrossWire to obtain the list of known publishers of SWORD materials.
2. Query each publisher for a list of available resources.

==== Installation ====

3. Present available resources to user.
4. Display the detail for a selected module.
5. Install the module.
6. Check to see if the module is enciphered and obtain that code from the user.

==== Update ====

7. Refresh resource list obtained in step #2.
8. Iterate all installed modules and see if the installed module has a version number less than the version number in the refreshed resource list.
9. Present to the user the history list between the user's installed version and the available updated version, to inform the user what has changed and ask if an update is desired.
10. Uninstall the module.
11. Install the updated module.

Each of these steps has a simple method available to the programmer from the SWORD engine.

== 0. Warn user about the risks. ==

CrossWire has a policy to always warn users before enabling Remote Module Installation. Many of our users live in persecuted countries and using CrossWire's systematic method for installing modules from remote sources poses a risk of detection for these users. This is the warning we typically present during an application run the first time any Remote Module Installation action is requested:

<nowiki>
-=+* WARNING *+=- -=+* WARNING *+=-

Although Install Manager provides a convenient way for installing
and upgrading SWORD components, it also uses a systematic method
for accessing sites which gives packet sniffers a target to lock
into for singling out users.

IF YOU LIVE IN A PERSECUTED COUNTRY AND DO NOT WISH TO RISK DETECTION,
YOU SHOULD *NOT* USE INSTALL MANAGER'S REMOTE SOURCE FEATURES.

Also, Remote Sources other than CrossWire may contain less than
quality modules, modules with unorthodox content, or even modules
which are not legitimately distributable. Many repositories
contain wonderfully useful content. These repositories simply
are not reviewed or maintained by CrossWire and CrossWire
cannot be held responsible for their content. CAVEAT EMPTOR.

If you understand this and are willing to enable remote source features
then type yes at the prompt

enable? [no]

</nowiki>

Also, because user from these countries often do not speak English, we ask the user to type a response to enable the feature.

== 1. Query CrossWire to obtain the list of known publishers of SWORD materials. ==

To discover the list of available module remote source repositories from publishers using the installmgr command line tool:

installmgr -sc

==== Details ====
The registry of all known and endorsed module remote source installation repositories is located at this URL and is pull by SWORD and JSword automatically to satisfy this step (e.g., by the command: installmgr -sc)

[https://crosswire.org/ftpmirror/pub/sword/masterRepoList.conf|https://crosswire.org/ftpmirror/pub/sword/masterRepoList.conf]

== 2. Query each publisher for a list of available resources. ==

To get a list of available publishers of remote SWORD module sources

installmgr -s

To refresh one of these, e.g., the "CrossWire" source:

installmgr -r "CrossWire"

==== Details ====

A module remote installation source repository is simply a set of SWORD resources installed in the same way as they would be installed for use by a SWORD frontend, but also made available online via FTP or HTTP. There may be optional additional files included which can speed up the use of large repositories, and some additional files currently needed to support JSword (until their install tools are improved to match our main SWORD engine), but essentially, any installed module set can be used as a module installation source for use by other SWORD users to choose and install modules.

== 3. Present available resources to user. ==

To display resources available from a publisher, e.g., from the "CrossWire" source:

installmgr -rl "CrossWire"

== 4. Display the detail for a selected module. ==

To display the details for a module, e.g., the KJV available from CrossWire:

installmgr -rdesc "CrossWire" KJV

== 5. Install the module. ==

To install, e.g., the KJV from CrossWire remote source repository:

installmgr -ri "CrossWire" KJV

== 6. Check to see if the module is enciphered and obtain that code from the user. ==

To check if the NA28 module from the "Deutsche Bibelgesellschaft" source repository needs an unlock key:

installmgr -rdesc "Deutsche Bibelgesellschaft" NA28|grep "^\[CipherKey"

==== Details ====

A modules' .conf file will include a CipherKey entry to designate that the module is enciphered and needs a key to use. Once the user provides the key, it should be entered as the value for the CipherKey entry, e.g.,

[ModuleName]
CipherKey=xyzzy

Typically these and other user-supplied settings for a module should be kept in their own .conf file and merged into the SWORD config, e.g.,

SWMgr library;
library.config->augment(SWConfig("~/.sword/userPreferences.conf"));

Where ~/.sword/userPreferences.conf would contain sections for each module along with the properties to augment:

[ModuleName]
CipherKey=xyzzy

This is valuable when updating a module, so as not to lose the any user-supplied preferences when uninstalling and then re-installing the module during the update.

== 7. Refresh resource list obtained in step #2. ==

== 8. Iterate all installed modules and see if the installed module has a version number less than the version number in the refreshed resource list. ==

To check for updates in, e.g., the CrossWire repository:

installmgr -rd "CrossWire"|grep "^+"

==== Details ====

Each module's .conf file contains a Version property which tells the module's current version. Installmgr's -rd flag will only show new (lines beginning with a '*') and updated (lines beginning with a '+') modules.

== 9. Present to the user the history list between the user's installed version and the available updated version, to inform the user what has changed and ask if an update is desired. ==

installmgr -rdesc CrossWire Nave|grep "^\[History"

==== Details ====

A module's .conf file will include History_version properties which describe what was updated for that version of the module.
It is desirable to only display to the user the History_version lines which are between the user's currently installed module version and the latest version which they are queried if they would like to update.

== 10. Uninstall the module. ==

To uninstall the KJV module:

installmgr -u KJV

== 11. Install the updated module. ==

installmgr -ri "CrossWire" KJV

Main Page

2021-03-13T22:55:44Z

Scribe:

{| cellspacing="1" width="100%"
|- valign="top"
|style="border: 1px solid green;padding-left:1em;padding-right:0.5em;background:#E4FFDF;padding-bottom:0.5em;" width="100%"|
==Welcome to the CrossWire developers' wiki==

Check out our [[Current Projects|current projects]] page to see how you might use your skills. Please also look at our general [[Volunteers|volunteering]] page.

If you want to help in this wiki, please [mailto://support@crosswire.org request] an account.

Here is the [http://tracker.crosswire.org bugs] database. Chat with SWORD developers on IRC: [http://webchat.freenode.net/?randomnick=1&channels=sword&prompt=1 #sword] on FreeNode.

|}
{| cellspacing="1" width="100%"
|- valign="top"

| style="background:#E8F1FF;border-style:solid;border-width:1px;border-color:#00ccFF;padding-left:1em;padding-right:0.5em; padding-bottom:0.5em;" width="50%"|

==Front-end Bible study applications==

===SWORD based front-ends===
* [[Frontends:BibleCS|The SWORD Project for Windows]] (internally known as BibleCS)
* [[Frontends:Bishop|The SWORD Project]] for Android, iOS & iPadOS (internally known as Bishop)
* [[Frontends:Eloquent|Eloquent]] MacOS desktop application
* [[Frontends:Xiphos|Xiphos]] Windows & Linux desktop application
* [[Frontends:BibleTime|BibleTime]] Windows & Linux desktop application
* [[Frontends:The_Bible_Tool|The Bible Tool]] web server application
* [[Frontends:PocketSword|PocketSword]] iOS & iPadOS application
* [[Frontends:Holy Bible|Holy Bible]] Windows Desktop application
* [[Frontends:Ezra Project|Ezra Project]] Windows, Linux, MacOS desktop & Android tablet application
* [https://www.godehardt.org/losung.html GLosung] Gottes Wort für deinen Desktop
* [https://pierre-amadio.github.io/matheteuo/ matheteuo] flashcards to help study Biblical Hebrew & Greek

===JSword based front-ends===
* [[Frontends:BibleDesktop|BibleDesktop]]
* [http://www.kiyut.com/products/alkitab/ Alkitab Bible Study]
* [[Frontends:GSword|GSword]] – CCIM Online Bible Studio
* [https://mjdenham.github.io/and-bible/ And Bible] – for Android OS
* [https://www.stepbible.org/ STEP Bible] – originally developed at [https://www.tyndalehouse.com/ Tyndale House]

=== Front-ends in general ===
* [[Choosing a SWORD program]]
* [[Frontends:No longer being actively developed|Front-ends no longer being actively developed]]

==SWORD module sources==
* [[SWORD Module Source Discovery and Module Updating|SWORD Module Remote Installation Source Repository Discovery and Module Updating]]
* [[Official and Affiliated Module Repositories]]
* [[Other Module Sources]]
* [[Creating and Maintaining a Module Repository]]

==Public relations, website, user assistance==
* [[Contact| Contact us]]
* CrossWire's [[Copyright|copyright]] policy
* [[EnduserFAQ|Frequently Asked Questions]]
* [[Help:Contents|Help]], [[Help:Bugs|Bugs]] and [[Help:Mailing Lists|Mailing Lists]]
* [[SWORD CD]]

|valign="top" bgcolor="#FFE8E8" style="border-style:solid;border-width:1px;border-color:#FF6060;padding-left:1em;padding-right:0.5em; padding-bottom:0.5em;" width="50%"|

==Back-end API development tools==
* [[DevTools:SWORD|SWORD Engine (C++)]]
** Compiling and installing SWORD
*** on [[Tutorial:Compiling & Installing SWORD| Linux/MacOS/Unix]]
*** on or for [[Tutorial:Compiling & Installing SWORD on Windows|Windows]]
*** with [[DevTools:CMake|CMake]]
** [[:DevTools:Code Examples|Code Examples]]
** [[Tutorial:How SWORD works]]
** [[DevTools:Locale Files|Locale Files]]
** [[DevTools:Bindings|SWIG Bindings]], [[DevTools:CSharp Bindings on Windows|C# Bindings on Windows]], [[DevTools:JNI Bindings for Android|Android Bindings]]
** bug reports with or without appended patches to our [http://tracker.crosswire.org/projects/API/issues/API-119?filter=allopenissues|bug tracker]
* [[DevTools:JSword|JSword Engine (Java)]]
** [[DevTools:JSword/Personal Commentary|Personal Commentary]]
** [[DevTools:JSword/Internationalization|Internationalization]]

==Open Scriptures Information Standard==
* A basic [[OSIS Tutorial|OSIS XML tutorial]]
* [[OSIS 211 CR| OSIS 2.1.1 schema change requests]]
* [https://www.crosswire.org/~dmsmith/osis/osisCore.2.1.1-cw-latest.xsd OSIS schema]
* [[List of eXtensions to OSIS used in SWORD]]

==Ancillary software==
* [[BibleSync]] – for Bible software shared co-navigation
* [[DevTools:ICU|International Components for Unicode (ICU)]]

== Development proposals and discussions ==
* [[Whiteboard]]

==Module development==
* How to create [[DevTools:Modules|SWORD Modules]] & [[DevTools:conf Files|Module Configuration Files]]
* Guides to writing
**[[OSIS Bibles]], [[OSIS Commentaries]],
**[[OSIS Genbooks]], [[TEI Dictionaries]]
* Guide to [[Validate_OSIS_or_TEI_text]]
* Guide to [[Converting SFM Bibles to OSIS]]
* About [[Alternate Versification|Bible Versification]] schemes
* About [[File Formats]] and related [[File Formats#The_SWORD_Project_Utilities|Utility Programs]]
* About Unicode [[Encoding]]s, [[Fonts]] & [[DevTools:Text Editors|Text Editors]]
-----
* [[Module Development Collaboration]]
* [[Notes on particular CrossWire modules]]
* [[Module Requests]] and [[Non-CrossWire Text-Development Projects|Text Development]]
* [[Module Submission]]

|}
{| cellspacing="1" width="100%"
|- valign="top"
|style="border: 1px solid gray;padding-left:1em;padding-right:0.5em;background:#E8E8E8;padding-bottom:0.5em;" width="100%"|

==Getting started in wiki collaboration==
A wiki is a place to share documentation and development information.
* New user account [mailto://support@crosswire.org|requests] are now moderated. Anyone who has been a member for at least 4 days can edit a wiki once they have [[Special:Userlogin|logged in]].
* If you are new to wikis, consult the [http://meta.wikipedia.org/wiki/MediaWiki_User's_Guide User's Guide] or the [http://www.mediawiki.org/wiki/Help:FAQ MediaWiki FAQ] for information on using the wiki software .
* Look to see what might need attention by visiting [[Wiki Maintenance]]
* You may experiment with wiki using our [[CrossWire:Sandbox|Sandbox]].
* Another way to navigate the wiki is to click on [[:Category:Categories]].

|}

[[Category:CrossWire]]
[[Category:SWORD Frontends]]
[[Category:SWORD]]
[[Category:JSword]]
[[Category:OSIS]]
[[Category:Modules]]
[[Category:Development tools]]
[[Category:Support]]
__NOTOC__

SWORD Module Source Discovery and Module Updating

2021-03-13T22:54:05Z

Scribe: SWORD Module Remote Installation Source Repository Discovery and Module Updating

== Overview ==

The SWORD Project Remote Module Source Discovery, Module Installation, and Module Updating is a straightforward process which both the SWORD and JSword engine support programmatically. Each CrossWire frontend makes these steps available to the user by calling the appropriate SWORD or JSword method for them. There also exists a simple command line tool (installmgr) to perform these actions, and this simple tool provides to SWORD frontend developers a great example of how to perform each of these steps from within their application. The steps can generally be list as these; more details about each can be found below:

0. Warn user about the risks of detection and ask them to enable Remote Source features.
1. Query CrossWire to obtain the list of known publishers of SWORD material.
2. Query each publisher for a list of available resources.

==== Installation ====

3. Download required files for the resource.
4. Check to see if the module is enciphered and obtain that code from the user.

==== Update ====

5. Refresh resource list obtained in step #2.
6. Iterate all installed modules and see if the installed module has a version number less than the version number in the refreshed resource list.
7. Present to the user the history list between the user's installed version and the available updated version, to inform the user what has changed and ask if an update is desired.
8. Uninstall the module.
9. Install the updated module.

Each of these steps has a simple method available to the programmer from the SWORD engine.

== 0. Warn user about the risks. ==

CrossWire has a policy to always warn users before enabling Remote Module Installation. Many of our users live in persecuted countries and using CrossWire's systematic method for installing modules from remote sources poses a risk of detection for these users. This is the warning we typically present during an application run the first time any Remote Module Installation action is requested:

<nowiki>
-=+* WARNING *+=- -=+* WARNING *+=-

Although Install Manager provides a convenient way for installing
and upgrading SWORD components, it also uses a systematic method
for accessing sites which gives packet sniffers a target to lock
into for singling out users.

IF YOU LIVE IN A PERSECUTED COUNTRY AND DO NOT WISH TO RISK DETECTION,
YOU SHOULD *NOT* USE INSTALL MANAGER'S REMOTE SOURCE FEATURES.

Also, Remote Sources other than CrossWire may contain less than
quality modules, modules with unorthodox content, or even modules
which are not legitimately distributable. Many repositories
contain wonderfully useful content. These repositories simply
are not reviewed or maintained by CrossWire and CrossWire
cannot be held responsible for their content. CAVEAT EMPTOR.

If you understand this and are willing to enable remote source features
then type yes at the prompt

enable? [no]

</nowiki>

Also, because user from these countries often do not speak English, we ask the user to type a response to enable the feature.

== 1. Query CrossWire to obtain the list of known publishers of SWORD materials. ==

To discover the list of available module remote source repositories from publishers using the installmgr command line tool:

installmgr -sc

==== Details ====
The registry of all known and endorsed module remote source installation repositories is located at this URL and is pull by SWORD and JSword automatically to satisfy this step (e.g., by the command: installmgr -sc)

[https://crosswire.org/ftpmirror/pub/sword/masterRepoList.conf]

== 2. Query each publisher for a list of available resources.

To get a list of available publishers of remote SWORD module sources

installmgr -s

To refresh one of these, e.g., the "CrossWire" source:

installmgr -r "CrossWire"

==== Details ====

A module remote installation source repository is simply a set of SWORD resources installed in the same way as they would be installed for use by a SWORD frontend, but also made available online via FTP or HTTP. There may be optional additional files included which can speed up the use of large repositories, and some additional files currently needed to support JSword (until their install tools are improved to match our main SWORD engine), but essentially, any installed module set can be used as a module installation source for use by other SWORD users to choose and install modules.

== 3. Present available resources to user.

To display resources available from a publisher, e.g., from the "CrossWire" source:

installmgr -rl "CrossWire"

== 4. Display the detail for a selected module.

To display the details for a module, e.g., the KJV available from CrossWire:

installmgr -rdesc "CrossWire" KJV

== 5. Install the module.

To install, e.g., the KJV from CrossWire remote source repository:

installmgr -ri "CrossWire" KJV

== 4. Check to see if the module is enciphered and obtain that code from the user.

To check if the NA28 module from the "Deutsche Bibelgesellschaft" source repository needs an unlock key:

installmgr -rdesc "Deutsche Bibelgesellschaft" NA28|grep "^\[CipherKey"

==== Details ====

A modules' .conf file will include a CipherKey entry to designate that the module is enciphered and needs a key to use. Once the user provides the key, it should be entered as the value for the CipherKey entry, e.g.,

[ModuleName]
CipherKey=xyzzy

Typically these and other user-supplied settings for a module should be kept in their own .conf file and merged into the SWORD config, e.g.,

SWMgr library;
library.config->augment(SWConfig("~/.sword/userPreferences.conf"));

Where ~/.sword/userPreferences.conf would contain sections for each module along with the properties to augment:

[ModuleName]
CipherKey=xyzzy

This is valuable when updating a module, so as not to lose the any user-supplied preferences when uninstalling and then re-installing the module during the update.

== 5. Refresh resource list obtained in step #2.

== 6. Iterate all installed modules and see if the installed module has a version number less than the version number in the refreshed resource list.

To check for updates in, e.g., the CrossWire repository:

installmgr -rd "CrossWire"|grep "^+"

==== Details ====

Each module's .conf file contains a Version property which tells the module's current version. Installmgr's -rd flag will only show new (lines beginning with a '*') and updated (lines beginning with a '+') modules.

== 7. Present to the user the history list between the user's installed version and the available updated version, to inform the user what has changed and ask if an update is desired.

installmgr -rdesc CrossWire Nave|grep "^\[History"

==== Details ====

A module's .conf file will include History_version properties which describe what was updated for that version of the module.
It is desirable to only display to the user the History_version lines which are between the user's currently installed module version and the latest version which they are queried if they would like to update.

== 8. Uninstall the module.

To uninstall the KJV module:

installmgr -u KJV

== 9. Install the updated module.

installmgr -ri "CrossWire" KJV

Main Page

2021-03-13T19:21:05Z

Scribe:

{| cellspacing="1" width="100%"
|- valign="top"
|style="border: 1px solid green;padding-left:1em;padding-right:0.5em;background:#E4FFDF;padding-bottom:0.5em;" width="100%"|
==Welcome to the CrossWire developers' wiki==

Check out our [[Current Projects|current projects]] page to see how you might use your skills. Please also look at our general [[Volunteers|volunteering]] page.

If you want to help in this wiki, please [mailto://support@crosswire.org request] an account.

Here is the [http://tracker.crosswire.org bugs] database. Chat with SWORD developers on IRC: [http://webchat.freenode.net/?randomnick=1&channels=sword&prompt=1 #sword] on FreeNode.

|}
{| cellspacing="1" width="100%"
|- valign="top"

| style="background:#E8F1FF;border-style:solid;border-width:1px;border-color:#00ccFF;padding-left:1em;padding-right:0.5em; padding-bottom:0.5em;" width="50%"|

==Front-end Bible study applications==

===SWORD based front-ends===
* [[Frontends:BibleCS|The SWORD Project for Windows]] (internally known as BibleCS)
* [[Frontends:Bishop|The SWORD Project]] for Android, iOS & iPadOS (internally known as Bishop)
* [[Frontends:Eloquent|Eloquent]] MacOS desktop application
* [[Frontends:Xiphos|Xiphos]] Windows & Linux desktop application
* [[Frontends:BibleTime|BibleTime]] Windows & Linux desktop application
* [[Frontends:The_Bible_Tool|The Bible Tool]] web server application
* [[Frontends:PocketSword|PocketSword]] iOS & iPadOS application
* [[Frontends:Holy Bible|Holy Bible]] Windows Desktop application
* [[Frontends:Ezra Project|Ezra Project]] Windows, Linux, MacOS desktop & Android tablet application
* [https://www.godehardt.org/losung.html GLosung] Gottes Wort für deinen Desktop
* [https://pierre-amadio.github.io/matheteuo/ matheteuo] flashcards to help study Biblical Hebrew & Greek

===JSword based front-ends===
* [[Frontends:BibleDesktop|BibleDesktop]]
* [http://www.kiyut.com/products/alkitab/ Alkitab Bible Study]
* [[Frontends:GSword|GSword]] – CCIM Online Bible Studio
* [https://mjdenham.github.io/and-bible/ And Bible] – for Android OS
* [https://www.stepbible.org/ STEP Bible] – originally developed at [https://www.tyndalehouse.com/ Tyndale House]

=== Front-ends in general ===
* [[Choosing a SWORD program]]
* [[Frontends:No longer being actively developed|Front-ends no longer being actively developed]]

==SWORD module sources==
* [[SWORD Module Source Discovery and Module Updating]]
* [[Official and Affiliated Module Repositories]]
* [[Other Module Sources]]
* [[Creating and Maintaining a Module Repository]]

==Public relations, website, user assistance==
* [[Contact| Contact us]]
* CrossWire's [[Copyright|copyright]] policy
* [[EnduserFAQ|Frequently Asked Questions]]
* [[Help:Contents|Help]], [[Help:Bugs|Bugs]] and [[Help:Mailing Lists|Mailing Lists]]
* [[SWORD CD]]

|valign="top" bgcolor="#FFE8E8" style="border-style:solid;border-width:1px;border-color:#FF6060;padding-left:1em;padding-right:0.5em; padding-bottom:0.5em;" width="50%"|

==Back-end API development tools==
* [[DevTools:SWORD|SWORD Engine (C++)]]
** Compiling and installing SWORD
*** on [[Tutorial:Compiling & Installing SWORD| Linux/MacOS/Unix]]
*** on or for [[Tutorial:Compiling & Installing SWORD on Windows|Windows]]
*** with [[DevTools:CMake|CMake]]
** [[:DevTools:Code Examples|Code Examples]]
** [[Tutorial:How SWORD works]]
** [[DevTools:Locale Files|Locale Files]]
** [[DevTools:Bindings|SWIG Bindings]], [[DevTools:CSharp Bindings on Windows|C# Bindings on Windows]], [[DevTools:JNI Bindings for Android|Android Bindings]]
** bug reports with or without appended patches to our [http://tracker.crosswire.org/projects/API/issues/API-119?filter=allopenissues|bug tracker]
* [[DevTools:JSword|JSword Engine (Java)]]
** [[DevTools:JSword/Personal Commentary|Personal Commentary]]
** [[DevTools:JSword/Internationalization|Internationalization]]

==Open Scriptures Information Standard==
* A basic [[OSIS Tutorial|OSIS XML tutorial]]
* [[OSIS 211 CR| OSIS 2.1.1 schema change requests]]
* [https://www.crosswire.org/~dmsmith/osis/osisCore.2.1.1-cw-latest.xsd OSIS schema]
* [[List of eXtensions to OSIS used in SWORD]]

==Ancillary software==
* [[BibleSync]] – for Bible software shared co-navigation
* [[DevTools:ICU|International Components for Unicode (ICU)]]

== Development proposals and discussions ==
* [[Whiteboard]]

==Module development==
* How to create [[DevTools:Modules|SWORD Modules]] & [[DevTools:conf Files|Module Configuration Files]]
* Guides to writing
**[[OSIS Bibles]], [[OSIS Commentaries]],
**[[OSIS Genbooks]], [[TEI Dictionaries]]
* Guide to [[Validate_OSIS_or_TEI_text]]
* Guide to [[Converting SFM Bibles to OSIS]]
* About [[Alternate Versification|Bible Versification]] schemes
* About [[File Formats]] and related [[File Formats#The_SWORD_Project_Utilities|Utility Programs]]
* About Unicode [[Encoding]]s, [[Fonts]] & [[DevTools:Text Editors|Text Editors]]
-----
* [[Module Development Collaboration]]
* [[Notes on particular CrossWire modules]]
* [[Module Requests]] and [[Non-CrossWire Text-Development Projects|Text Development]]
* [[Module Submission]]

|}
{| cellspacing="1" width="100%"
|- valign="top"
|style="border: 1px solid gray;padding-left:1em;padding-right:0.5em;background:#E8E8E8;padding-bottom:0.5em;" width="100%"|

==Getting started in wiki collaboration==
A wiki is a place to share documentation and development information.
* New user account [mailto://support@crosswire.org|requests] are now moderated. Anyone who has been a member for at least 4 days can edit a wiki once they have [[Special:Userlogin|logged in]].
* If you are new to wikis, consult the [http://meta.wikipedia.org/wiki/MediaWiki_User's_Guide User's Guide] or the [http://www.mediawiki.org/wiki/Help:FAQ MediaWiki FAQ] for information on using the wiki software .
* Look to see what might need attention by visiting [[Wiki Maintenance]]
* You may experiment with wiki using our [[CrossWire:Sandbox|Sandbox]].
* Another way to navigate the wiki is to click on [[:Category:Categories]].

|}

[[Category:CrossWire]]
[[Category:SWORD Frontends]]
[[Category:SWORD]]
[[Category:JSword]]
[[Category:OSIS]]
[[Category:Modules]]
[[Category:Development tools]]
[[Category:Support]]
__NOTOC__

Tutorial:Writing Conf files

2020-02-14T06:47:14Z

Scribe: /* Common mistakes */

==Creating a .conf File==

=== module.conf File Layout===
SWORD uses a plain text [[DevTools:conf Files|configuration file]] to store information about modules, one for each module. This file is used by the SWORD engine to process modules, by installers to help users install modules and by front-ends to render the module appropriately.

Different [http://en.wikipedia.org/wiki/Newline End-of-Line] styles should be not be mixed in the same file.

=== Overview by Example ===
The module.conf file starts with an INI section, giving the ModName.
:[KJV]

This is then followed by key=value pairs.
: # A line that starts with a # is a comment
: DataPath=./modules/texts/ztext/kjv/
: ModDrv=Text
: Encoding=UTF-8
: BlockType=BOOK
: CompressType=ZIP
: SourceType=OSIS
: Lang=en

Some keys can be repeated with different values:
: GlobalOptionFilter=OSISStrongs
: GlobalOptionFilter=OSISMorph
: GlobalOptionFilter=OSISFootnotes
: GlobalOptionFilter=OSISHeadings
: GlobalOptionFilter=OSISRedLetterWords

Some keys support [[DevTools:conf Files#Localization|localization]]:
: Abbreviation=和合本
: Abbreviation_en=ChiUn
: Description=和合本 (繁體字)
: Description_en=Chinese Union Version (Traditional)

Some fields can have [[DevTools:conf Files#RTF|RTF]] in a single line:
: About=This is the King James Version of the Holy Bible (also known as the Authorized Version) with embedded Strong's Numbers. The rights to the base text are held by the Crown of England. The Strong's numbers in the OT were obtained from The Bible Foundation: http://www.bf.org. The NT Strong's data was obtained from The KJV2003 Project at CrossWire: http://www.crosswire.org. These mechanisms provide a useful means for looking up the exact original language word in a lexicon that is keyed to Strong's numbers.\par\par Special thanks to the volunteers at Bible Foundation for keying the Hebrew/English data and of Project KJV2003 for working toward the completion of synchronizing the English phrases to the Stephanas Textus Receptus, and to Dr. Maurice Robinson for providing the base Greek text with Strong's and Morphology. We are also appreciative of formatting markup that was provided by Michael Paul Johnson at http://www.ebible.org. Their time and generosity to contribute such for the free use of the Body of Christ is a great blessing and this derivative work could not have been possible without these efforts of so many individuals. It is in this spirit that we in turn offer the KJV2003 Project text freely for any purpose. Any copyright that might be obtained for this effort is held by CrossWire Bible Society (c) 2003 and CrossWire Bible Society hereby grants a general public license to use this text for any purpose.\par Inquiries and comments may be directed to:\par\par CrossWire Bible Society\par kjv2003@crosswire.org\par http://www.crosswire.org
Some fields allow multiple lines using \ to escape the newline:
:About=This is the King James Version of the Holy Bible (also known as the Authorized Version) with embedded Strong's Numbers. The rights to the base text are held by the Crown of England. The Strong's numbers in the OT were obtained from The Bible Foundation: http://www.bf.org. The NT Strong's data was obtained from The KJV2003 Project at CrossWire: http://www.crosswire.org. These mechanisms provide a useful means for looking up the exact original language word in a lexicon that is keyed to Strong's numbers. \
: \
:Special thanks to the volunteers at Bible Foundation for keying the Hebrew/English data and of Project KJV2003 for working toward the completion of synchronizing the English phrases to the Stephanas Textus Receptus, and to Dr. Maurice Robinson for providing the base Greek text with Strong's and Morphology. We are also appreciative of formatting markup that was provided by Michael Paul Johnson at http://www.ebible.org. Their time and generosity to contribute such for the free use of the Body of Christ is a great blessing and this derivative work could not have been possible without these efforts of so many individuals. It is in this spirit that we in turn offer the KJV2003 Project text freely for any purpose. Any copyright that might be obtained for this effort is held by CrossWire Bible Society (c) 2003 and CrossWire Bible Society hereby grants a general public license to use this text for any purpose. \
: Inquiries and comments may be directed to: \
: \
:CrossWire Bible Society \
:kjv2003@crosswire.org \
:http://www.crosswire.org

=== Common mistakes ===
Using Latin-1 or CP1252 when:
: Encoding=UTF-8

Having a [http://en.wikipedia.org/wiki/Byte_order_mark Byte Order Mark (BOM)] at the beginning of the file<ref>Windows Notepad and Wordpad may silently add these to the file</ref><ref>This can even cause some front-ends to crash!</ref>
: U+FEFF
: [KJV]

Repeating the same element with the same value:
: Lang=en
: ...
: Lang=en

Repeating the same element with different values, when the element doesn't allow repeats:
: Lang=en
: Lang=de

Not supplying a value:
: About=

Having a continuation marker on the last line, causing the next key=value to be appended to the prior field:
: this is text that continues from the prior line \
: Lang=en

Omitting the space after an otherwise valid RTF tag:
: About=Module name\parModule details...

'''Notes:'''
<references/>

=== 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 . 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 below for details.

For example, to give a French description, you can have a field:
: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.

'''Notes''':
# 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 front-end support for it.
# See also [[Localized Language Names]].

== See also ==
* The main reference [[DevTools:conf Files|page for .conf files]]

== External links ==

* [https://github.com/DavidHaslam/CONF CONF] – User Defined Language file to be used with [https://notepad-plus-plus.org/ Notepad++] for syntax highlighting SWORD module CONF text files.

[[Category:Development tools|Conf files]]
[[Category:Localization|Conf files]]
[[Category:Copyright|Conf files]]
[[Category:Tutorials|Conf files]]

Tutorial:Writing Conf files

2020-02-14T06:45:14Z

Scribe: /* Overview by Example */

==Creating a .conf File==

=== module.conf File Layout===
SWORD uses a plain text [[DevTools:conf Files|configuration file]] to store information about modules, one for each module. This file is used by the SWORD engine to process modules, by installers to help users install modules and by front-ends to render the module appropriately.

Different [http://en.wikipedia.org/wiki/Newline End-of-Line] styles should be not be mixed in the same file.

=== Overview by Example ===
The module.conf file starts with an INI section, giving the ModName.
:[KJV]

This is then followed by key=value pairs.
: # A line that starts with a # is a comment
: DataPath=./modules/texts/ztext/kjv/
: ModDrv=Text
: Encoding=UTF-8
: BlockType=BOOK
: CompressType=ZIP
: SourceType=OSIS
: Lang=en

Some keys can be repeated with different values:
: GlobalOptionFilter=OSISStrongs
: GlobalOptionFilter=OSISMorph
: GlobalOptionFilter=OSISFootnotes
: GlobalOptionFilter=OSISHeadings
: GlobalOptionFilter=OSISRedLetterWords

Some keys support [[DevTools:conf Files#Localization|localization]]:
: Abbreviation=和合本
: Abbreviation_en=ChiUn
: Description=和合本 (繁體字)
: Description_en=Chinese Union Version (Traditional)

Some fields can have [[DevTools:conf Files#RTF|RTF]] in a single line:
: About=This is the King James Version of the Holy Bible (also known as the Authorized Version) with embedded Strong's Numbers. The rights to the base text are held by the Crown of England. The Strong's numbers in the OT were obtained from The Bible Foundation: http://www.bf.org. The NT Strong's data was obtained from The KJV2003 Project at CrossWire: http://www.crosswire.org. These mechanisms provide a useful means for looking up the exact original language word in a lexicon that is keyed to Strong's numbers.\par\par Special thanks to the volunteers at Bible Foundation for keying the Hebrew/English data and of Project KJV2003 for working toward the completion of synchronizing the English phrases to the Stephanas Textus Receptus, and to Dr. Maurice Robinson for providing the base Greek text with Strong's and Morphology. We are also appreciative of formatting markup that was provided by Michael Paul Johnson at http://www.ebible.org. Their time and generosity to contribute such for the free use of the Body of Christ is a great blessing and this derivative work could not have been possible without these efforts of so many individuals. It is in this spirit that we in turn offer the KJV2003 Project text freely for any purpose. Any copyright that might be obtained for this effort is held by CrossWire Bible Society (c) 2003 and CrossWire Bible Society hereby grants a general public license to use this text for any purpose.\par Inquiries and comments may be directed to:\par\par CrossWire Bible Society\par kjv2003@crosswire.org\par http://www.crosswire.org
Some fields allow multiple lines using \ to escape the newline:
:About=This is the King James Version of the Holy Bible (also known as the Authorized Version) with embedded Strong's Numbers. The rights to the base text are held by the Crown of England. The Strong's numbers in the OT were obtained from The Bible Foundation: http://www.bf.org. The NT Strong's data was obtained from The KJV2003 Project at CrossWire: http://www.crosswire.org. These mechanisms provide a useful means for looking up the exact original language word in a lexicon that is keyed to Strong's numbers. \
: \
:Special thanks to the volunteers at Bible Foundation for keying the Hebrew/English data and of Project KJV2003 for working toward the completion of synchronizing the English phrases to the Stephanas Textus Receptus, and to Dr. Maurice Robinson for providing the base Greek text with Strong's and Morphology. We are also appreciative of formatting markup that was provided by Michael Paul Johnson at http://www.ebible.org. Their time and generosity to contribute such for the free use of the Body of Christ is a great blessing and this derivative work could not have been possible without these efforts of so many individuals. It is in this spirit that we in turn offer the KJV2003 Project text freely for any purpose. Any copyright that might be obtained for this effort is held by CrossWire Bible Society (c) 2003 and CrossWire Bible Society hereby grants a general public license to use this text for any purpose. \
: Inquiries and comments may be directed to: \
: \
:CrossWire Bible Society \
:kjv2003@crosswire.org \
:http://www.crosswire.org

=== Common mistakes ===
Using Latin-1 or CP1252 when:
: Encoding=UTF-8

Having a [http://en.wikipedia.org/wiki/Byte_order_mark Byte Order Mark (BOM)] at the beginning of the file<ref>Windows Notepad and Wordpad may silently add these to the file</ref><ref>This can even cause some front-ends to crash!</ref>
: U+FEFF
: [KJV]

Repeating the same element with the same value:
: Lang=en
: ...
: Lang=en

Repeating the same element with different values, when the element doesn't allow repeats:
: Lang=en
: Lang=de

Not supplying a value:
: About=
Only the field CipherKey allows this.

Having a continuation marker on the last line, causing the next key=value to be appended to the prior field:
: this is text that continues from the prior line \
: Lang=en

Omitting the space after an otherwise valid RTF tag:
: About=Module name\parModule details...

'''Notes:'''
<references/>

=== 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 . 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 below for details.

For example, to give a French description, you can have a field:
: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.

'''Notes''':
# 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 front-end support for it.
# See also [[Localized Language Names]].

== See also ==
* The main reference [[DevTools:conf Files|page for .conf files]]

== External links ==

* [https://github.com/DavidHaslam/CONF CONF] – User Defined Language file to be used with [https://notepad-plus-plus.org/ Notepad++] for syntax highlighting SWORD module CONF text files.

[[Category:Development tools|Conf files]]
[[Category:Localization|Conf files]]
[[Category:Copyright|Conf files]]
[[Category:Tutorials|Conf files]]

Tutorial:Writing Conf files

2020-02-14T06:43:20Z

Scribe: /* Overview by Example */

==Creating a .conf File==

=== module.conf File Layout===
SWORD uses a plain text [[DevTools:conf Files|configuration file]] to store information about modules, one for each module. This file is used by the SWORD engine to process modules, by installers to help users install modules and by front-ends to render the module appropriately.

Different [http://en.wikipedia.org/wiki/Newline End-of-Line] styles should be not be mixed in the same file.

=== Overview by Example ===
The module.conf file starts with an INI section, giving the ModName.
:[KJV]

This is then followed by key=value pairs.
: # A line that starts with a # is a comment
: DataPath=./modules/texts/ztext/kjv/
: ModDrv=Text
: Encoding=UTF-8
: BlockType=BOOK
: CompressType=ZIP
: SourceType=OSIS
: Lang=en

Some keys can be repeated with different values:
:GlobalOptionFilter=OSISStrongs
:GlobalOptionFilter=OSISMorph
:GlobalOptionFilter=OSISFootnotes
:GlobalOptionFilter=OSISHeadings
:GlobalOptionFilter=OSISRedLetterWords

Some keys support [[DevTools:conf Files#Localization|localization]]:
Abbreviation=和合本
Abbreviation_en=ChiUn
Description=和合本 (繁體字)
Description_en=Chinese Union Version (Traditional)

Some fields can have [[DevTools:conf Files#RTF|RTF]] in a single line:
:About=This is the King James Version of the Holy Bible (also known as the Authorized Version) with embedded Strong's Numbers. The rights to the base text are held by the Crown of England. The Strong's numbers in the OT were obtained from The Bible Foundation: http://www.bf.org. The NT Strong's data was obtained from The KJV2003 Project at CrossWire: http://www.crosswire.org. These mechanisms provide a useful means for looking up the exact original language word in a lexicon that is keyed to Strong's numbers.\par\par Special thanks to the volunteers at Bible Foundation for keying the Hebrew/English data and of Project KJV2003 for working toward the completion of synchronizing the English phrases to the Stephanas Textus Receptus, and to Dr. Maurice Robinson for providing the base Greek text with Strong's and Morphology. We are also appreciative of formatting markup that was provided by Michael Paul Johnson at http://www.ebible.org. Their time and generosity to contribute such for the free use of the Body of Christ is a great blessing and this derivative work could not have been possible without these efforts of so many individuals. It is in this spirit that we in turn offer the KJV2003 Project text freely for any purpose. Any copyright that might be obtained for this effort is held by CrossWire Bible Society (c) 2003 and CrossWire Bible Society hereby grants a general public license to use this text for any purpose.\par Inquiries and comments may be directed to:\par\par CrossWire Bible Society\par kjv2003@crosswire.org\par http://www.crosswire.org
Some fields allow multiple lines using \ to escape the newline:
:About=This is the King James Version of the Holy Bible (also known as the Authorized Version) with embedded Strong's Numbers. The rights to the base text are held by the Crown of England. The Strong's numbers in the OT were obtained from The Bible Foundation: http://www.bf.org. The NT Strong's data was obtained from The KJV2003 Project at CrossWire: http://www.crosswire.org. These mechanisms provide a useful means for looking up the exact original language word in a lexicon that is keyed to Strong's numbers. \
: \
:Special thanks to the volunteers at Bible Foundation for keying the Hebrew/English data and of Project KJV2003 for working toward the completion of synchronizing the English phrases to the Stephanas Textus Receptus, and to Dr. Maurice Robinson for providing the base Greek text with Strong's and Morphology. We are also appreciative of formatting markup that was provided by Michael Paul Johnson at http://www.ebible.org. Their time and generosity to contribute such for the free use of the Body of Christ is a great blessing and this derivative work could not have been possible without these efforts of so many individuals. It is in this spirit that we in turn offer the KJV2003 Project text freely for any purpose. Any copyright that might be obtained for this effort is held by CrossWire Bible Society (c) 2003 and CrossWire Bible Society hereby grants a general public license to use this text for any purpose. \
: Inquiries and comments may be directed to: \
: \
:CrossWire Bible Society \
:kjv2003@crosswire.org \
:http://www.crosswire.org

=== Common mistakes ===
Using Latin-1 or CP1252 when:
: Encoding=UTF-8

Having a [http://en.wikipedia.org/wiki/Byte_order_mark Byte Order Mark (BOM)] at the beginning of the file<ref>Windows Notepad and Wordpad may silently add these to the file</ref><ref>This can even cause some front-ends to crash!</ref>
: U+FEFF
: [KJV]

Repeating the same element with the same value:
: Lang=en
: ...
: Lang=en

Repeating the same element with different values, when the element doesn't allow repeats:
: Lang=en
: Lang=de

Not supplying a value:
: About=
Only the field CipherKey allows this.

Having a continuation marker on the last line, causing the next key=value to be appended to the prior field:
: this is text that continues from the prior line \
: Lang=en

Omitting the space after an otherwise valid RTF tag:
: About=Module name\parModule details...

'''Notes:'''
<references/>

=== 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 . 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 below for details.

For example, to give a French description, you can have a field:
: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.

'''Notes''':
# 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 front-end support for it.
# See also [[Localized Language Names]].

== See also ==
* The main reference [[DevTools:conf Files|page for .conf files]]

== External links ==

* [https://github.com/DavidHaslam/CONF CONF] – User Defined Language file to be used with [https://notepad-plus-plus.org/ Notepad++] for syntax highlighting SWORD module CONF text files.

[[Category:Development tools|Conf files]]
[[Category:Localization|Conf files]]
[[Category:Copyright|Conf files]]
[[Category:Tutorials|Conf files]]

DevTools:conf Files

2020-02-14T06:39:34Z

Scribe: /* Required Elements */

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

Please look also at our detailed and commented [[Tutorial:Writing Conf files|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===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|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 [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> 
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<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>
|
'''<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]
| [[DevTools:conf Files#Localization|Localization]]
|-
| Description
|
'''<string>''' 
This is a short (1 line) title of the module.
|  
| [[DevTools:conf Files#Localization|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<ref>Daily devotionals & glossaries go in subdirectories under lexdict. A glossary is between two languages.</ref>, 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)<ref name="text4">e.g. If the Bible contains large introduction sections</ref> 
'''zText''' (for compressed Bibles) 
'''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> 
'''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)<ref name="sv">zText4 & zCom4 modules require SwordVersion=1.8 or later.</ref> 
'''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)
|  
|  
|}

<references />

===Required Elements with defaults ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| SourceType<ref>Omitting this for a non-plaintext module has unpredictable effects.</ref>
|
'''Plaintext''' 
'''OSIS''' ([http://www.bibletechnologies.net Open Scriptural Information Standard]) 
'''TEI''' ([http://www.tei-c.org 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''' ([http://www.ebible.org/bible/gbf.htm General Bible Format]) 
'''ThML''' ([http://www.ccel.org/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''' ([http://en.wikipedia.org/wiki/Standard_Compression_Scheme_for_Unicode 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 [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
|  
|-
| CompressType
|
'''ZIP''' 
'''LZSS''' ([http://en.wikipedia.org/wiki/Lempel%E2%80%93Ziv%E2%80%93Storer%E2%80%93Szymanski 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. 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
|  
|}

<references />

=== Elements required for proper rendering ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| GlobalOptionFilter
|
'''UTF8Cantillation''' (For Hebrew texts having cantillation marks)<ref>See https://en.wikipedia.org/wiki/Cantillation</ref> 
'''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> 
'''UTF8HebrewPoints''' (For Hebrew texts having vowel points)<ref>See https://en.wikipedia.org/wiki/Niqqud</ref> 
'''UTF8ArabicPoints''' (For Arabic texts having vowel points)<ref>See https://en.wikipedia.org/wiki/Arabic_diacritics</ref> 
'''OSISLemma''' (For OSIS texts having lemmas)<ref>Must precede OSISStrongs.</ref> 
'''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> 
'''OSISStrongs''' (For OSIS texts having Strong's Numbers)<ref name="strongs">See https://en.wikipedia.org/wiki/Strong%27s_Concordance#Strong.27s_numbers</ref> 
'''OSISFootnotes''' (For OSIS texts having informational notes) 
'''OSISScripref''' (For OSIS texts having [[OSIS Bibles#Marking_cross-references_note|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)<ref name="red">See https://en.wikipedia.org/wiki/Red_letter_edition</ref> 
'''OSISGlosses''' (For OSIS texts with glosses)<ref>Minimum SWORD version of 1.7.0 in the module .conf is required for OSISGlosses.</ref> 
'''OSISXlit''' (For OSIS texts that include transliterated forms)<ref>The Samaritan Pentateuch module SP is an example of using xlit.</ref> 
'''OSISEnum''' (For OSIS texts with enumerated words)<ref>The Samaritan Pentateuch module SP is an example of using enum.</ref> 
'''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> 
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> 
'''GBFStrongs''' (For GBF texts having Strong's Numbers)<ref name="strongs">See https://en.wikipedia.org/wiki/Strong%27s_Concordance#Strong.27s_numbers</ref> 
'''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)<ref name="red">See https://en.wikipedia.org/wiki/Red_letter_edition</ref> 
'''ThMLStrongs''' (For THML texts having Strong's Numbers)<ref name="strongs">See https://en.wikipedia.org/wiki/Strong%27s_Concordance#Strong.27s_numbers</ref> 
'''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.<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
|  
|-
| 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 [[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.
|  
|  
|-
| <del>OSISqToTick</del> (deprecated)<ref>For further details, refer to [http://www.crosswire.org/bugs/browse/MOD-188 MOD-188] in CrossWire bugs.</ref>
| This attribute is deprecated in favor of the marker attribute on the q element. E.g.: <pre><q who="Jesus" marker="">....</q></pre> 
<del>true/false</del> 
<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
|  
|-
| 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<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>)
|  
| 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.
|  
|  
|}
<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. 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''' – 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 ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| About
|
'''<string>''' 
A lengthier description and may include copyright, source, etc. information, possibly duplicating information in other elements.
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#RTF|RTF]] [[DevTools:conf Files#Localization|Localization]]
|-
| SwordVersionDate
|
'''<yyyy-mm-dd>''' ([http://en.wikipedia.org/wiki/ISO_8601#Calendar_dates 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>''' 
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 [[DevTools:conf Files#Localization|Localization]]
|-
| MinimumVersion<ref>See http://tracker.crosswire.org/browse/API-201</ref>
|
'''<version string>''' 
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
|  
|-
| Category
|valign="top"|
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)<ref>'''Essays''' is handled as a subset of '''Generic Books'''.</ref>
|
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 [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.
|  
|  
|-
| Lang
|
'''<Language[-Script]?[-Region]?>''' 
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}/)'': 
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: 
: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}/)'': 
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}/)'' 
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})?/)'': 
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<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>
|
'''<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:'''
<references/>

=== Copyright & Licensing related elements ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| Copyright
|
'''<string>''' 
Contains the copyright notice for the work, including the year of copyright and the owner of the copyright.
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightHolder
|
'''<string>''' 
Contains the name of the copyright holder.
|  
| [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightDate
|
'''<yyyy>''' ([http://en.wikipedia.org/wiki/ISO_8601#Years ISO 8601 Year])
|  
| [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightNotes
|
'''<string>'''
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightContactName
|
'''<string>''' 
Contains the name of the copyright holder.
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightContactNotes
|
'''<string>'''
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightContactAddress
|
'''<string>''' 
Contains the mailing address of the copyright holder.
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightContactEmail
|
'''<string>''' 
Contains the email address of the copyright holder, preferably in the form: name at xyz dot com
|  
| [[DevTools:conf Files#Localization|Localization]]
|-
| ShortPromo
|
'''<string>''' 
A link to the home page for the module, perhaps with an encouragement to visit the site.
|  
| HTML Link [[DevTools:conf Files#Localization|Localization]]
|-
| ShortCopyright
|
'''<string>'''
|  
| [[DevTools:conf Files#Localization|Localization]]
|- id="distlic"
| DistributionLicense
|
'''Copyrighted''' 
'''Copyrighted; Permission to distribute granted to CrossWire'''<ref>Modules in other repositories may have a different organization name instead of CrossWire.</ref> 
'''Copyrighted; Permission granted to distribute non-commercially in SWORD format''' 
'''Copyrighted; Free non-commercial distribution''' 
'''Copyrighted; Freely distributable''' 
'''[http://www.gnu.org/copyleft/fdl.html GFDL]''' 
'''[http://www.gnu.org/copyleft/gpl.html GPL]''' 
'''Creative Commons: [http://creativecommons.org/licenses/by-nc-nd by-nc-nd]''' 
'''Creative Commons: [http://creativecommons.org/licenses/by-nc-sa by-nc-sa]''' 
'''Creative Commons: [http://creativecommons.org/licenses/by-nc by-nc]''' 
'''Creative Commons: [http://creativecommons.org/licenses/by-nd by-nd]''' 
'''Creative Commons: [http://creativecommons.org/licenses/by-sa by-sa]''' 
'''Creative Commons: [http://creativecommons.org/licenses/by by]''' 
'''Creative Commons: [http://creativecommons.org/publicdomain/zero/1.0/ CC0]''' 
'''Public Domain''' 

Use one of these strings '''verbatim'''. The actual copyright and/or license information is held in other elements. The last seven<ref>Each link goes to a page that no longer exists!</ref> licenses are [http://creativecommons.org/ Creative Commons] licenses.
|  
|  
|-
| DistributionNotes
|
'''<string>''' 
Indicates any additional notes about distribution of the module.
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| TextSource
|
'''<string>''' 
Indicates, either in prose (such as "CCEL") or as a URL of the source of the text
|  
| [[DevTools:conf Files#Continuation|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.
|  
| [[DevTools:conf Files#RTF|RTF]] [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]] HTML Link
|}
'''Note:'''
<references/>

== 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 ==
* [[User:Dmsmith|DMSmith]] has created a script 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].

== Automated generation ==
* For new module submissions to CrossWire, [[User:Refdoc|Refdoc]] now maintains a script called '''confmaker''' that includes the ''automated generation'' of module conf files, given the minimum ''non-automatable'' requirements by the module submitter.

== See also ==
* [[BibTeX entries]]

[[Category:Development tools|Conf files]]
[[Category:Localization|Conf files]]
[[Category:Versification|Conf files]]
[[Category:Copyright|Conf files]]

DevTools:conf Files

2020-02-14T05:57:18Z

Scribe: /* Copyright & Licensing related elements */

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

Please look also at our detailed and commented [[Tutorial:Writing Conf files|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===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| [ModName]
| Each conf file begins with [ModName], replacing "ModName" with a short well known abbreviation for the module (e.g., [KJV]). 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! An invalid ModName can cause some front-ends to crash.</ref> 
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, [MyModule] would be mymodule.conf.
|  
|  
|-
| Abbreviation<ref>We strongly advise to avoid using an Abbreviation that's identical to the ModName or Abbreviation of any other module. It only leads to confusion, and may have unexpected consequences for some front-ends.</ref>
|
'''<string>''' 
This field allows for the localization of the ModName. It is meant to be short just like the ModName.

''Actually, this element is not required, but it makes the most sense to describe it here.''
| [ModName]
| [[DevTools:conf Files#Localization|Localization]]
|-
| Description
|
'''<string>''' 
This is a short (1 line) title of the module.
|  
| [[DevTools:conf Files#Localization|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<ref>Daily devotionals & glossaries go in subdirectories under lexdict. A glossary is between two languages.</ref>, 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)<ref name="text4">e.g. If the Bible contains large introduction sections</ref> 
'''zText''' (for compressed Bibles) 
'''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> 
'''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)<ref name="sv">zText4 & zCom4 modules require SwordVersion=1.8 or later.</ref> 
'''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)
|  
|  
|}

<references />

===Required Elements with defaults ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| SourceType<ref>Omitting this for a non-plaintext module has unpredictable effects.</ref>
|
'''Plaintext''' 
'''OSIS''' ([http://www.bibletechnologies.net Open Scriptural Information Standard]) 
'''TEI''' ([http://www.tei-c.org 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''' ([http://www.ebible.org/bible/gbf.htm General Bible Format]) 
'''ThML''' ([http://www.ccel.org/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''' ([http://en.wikipedia.org/wiki/Standard_Compression_Scheme_for_Unicode 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 [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
|  
|-
| CompressType
|
'''ZIP''' 
'''LZSS''' ([http://en.wikipedia.org/wiki/Lempel%E2%80%93Ziv%E2%80%93Storer%E2%80%93Szymanski 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. 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
|  
|}

<references />

=== Elements required for proper rendering ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| GlobalOptionFilter
|
'''UTF8Cantillation''' (For Hebrew texts having cantillation marks)<ref>See https://en.wikipedia.org/wiki/Cantillation</ref> 
'''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> 
'''UTF8HebrewPoints''' (For Hebrew texts having vowel points)<ref>See https://en.wikipedia.org/wiki/Niqqud</ref> 
'''UTF8ArabicPoints''' (For Arabic texts having vowel points)<ref>See https://en.wikipedia.org/wiki/Arabic_diacritics</ref> 
'''OSISLemma''' (For OSIS texts having lemmas)<ref>Must precede OSISStrongs.</ref> 
'''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> 
'''OSISStrongs''' (For OSIS texts having Strong's Numbers)<ref name="strongs">See https://en.wikipedia.org/wiki/Strong%27s_Concordance#Strong.27s_numbers</ref> 
'''OSISFootnotes''' (For OSIS texts having informational notes) 
'''OSISScripref''' (For OSIS texts having [[OSIS Bibles#Marking_cross-references_note|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)<ref name="red">See https://en.wikipedia.org/wiki/Red_letter_edition</ref> 
'''OSISGlosses''' (For OSIS texts with glosses)<ref>Minimum SWORD version of 1.7.0 in the module .conf is required for OSISGlosses.</ref> 
'''OSISXlit''' (For OSIS texts that include transliterated forms)<ref>The Samaritan Pentateuch module SP is an example of using xlit.</ref> 
'''OSISEnum''' (For OSIS texts with enumerated words)<ref>The Samaritan Pentateuch module SP is an example of using enum.</ref> 
'''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> 
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> 
'''GBFStrongs''' (For GBF texts having Strong's Numbers)<ref name="strongs">See https://en.wikipedia.org/wiki/Strong%27s_Concordance#Strong.27s_numbers</ref> 
'''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)<ref name="red">See https://en.wikipedia.org/wiki/Red_letter_edition</ref> 
'''ThMLStrongs''' (For THML texts having Strong's Numbers)<ref name="strongs">See https://en.wikipedia.org/wiki/Strong%27s_Concordance#Strong.27s_numbers</ref> 
'''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.<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
|  
|-
| 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 [[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.
|  
|  
|-
| <del>OSISqToTick</del> (deprecated)<ref>For further details, refer to [http://www.crosswire.org/bugs/browse/MOD-188 MOD-188] in CrossWire bugs.</ref>
| This attribute is deprecated in favor of the marker attribute on the q element. E.g.: <pre><q who="Jesus" marker="">....</q></pre> 
<del>true/false</del> 
<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
|  
|-
| 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<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>)
|  
| 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.
|  
|  
|}
<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. 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''' – 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 ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| About
|
'''<string>''' 
A lengthier description and may include copyright, source, etc. information, possibly duplicating information in other elements.
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#RTF|RTF]] [[DevTools:conf Files#Localization|Localization]]
|-
| SwordVersionDate
|
'''<yyyy-mm-dd>''' ([http://en.wikipedia.org/wiki/ISO_8601#Calendar_dates 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>''' 
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 [[DevTools:conf Files#Localization|Localization]]
|-
| MinimumVersion<ref>See http://tracker.crosswire.org/browse/API-201</ref>
|
'''<version string>''' 
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
|  
|-
| Category
|valign="top"|
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)<ref>'''Essays''' is handled as a subset of '''Generic Books'''.</ref>
|
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 [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.
|  
|  
|-
| Lang
|
'''<Language[-Script]?[-Region]?>''' 
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}/)'': 
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: 
: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}/)'': 
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}/)'' 
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})?/)'': 
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<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>
|
'''<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:'''
<references/>

=== Copyright & Licensing related elements ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| Copyright
|
'''<string>''' 
Contains the copyright notice for the work, including the year of copyright and the owner of the copyright.
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightHolder
|
'''<string>''' 
Contains the name of the copyright holder.
|  
| [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightDate
|
'''<yyyy>''' ([http://en.wikipedia.org/wiki/ISO_8601#Years ISO 8601 Year])
|  
| [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightNotes
|
'''<string>'''
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightContactName
|
'''<string>''' 
Contains the name of the copyright holder.
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightContactNotes
|
'''<string>'''
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightContactAddress
|
'''<string>''' 
Contains the mailing address of the copyright holder.
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightContactEmail
|
'''<string>''' 
Contains the email address of the copyright holder, preferably in the form: name at xyz dot com
|  
| [[DevTools:conf Files#Localization|Localization]]
|-
| ShortPromo
|
'''<string>''' 
A link to the home page for the module, perhaps with an encouragement to visit the site.
|  
| HTML Link [[DevTools:conf Files#Localization|Localization]]
|-
| ShortCopyright
|
'''<string>'''
|  
| [[DevTools:conf Files#Localization|Localization]]
|- id="distlic"
| DistributionLicense
|
'''Copyrighted''' 
'''Copyrighted; Permission to distribute granted to CrossWire'''<ref>Modules in other repositories may have a different organization name instead of CrossWire.</ref> 
'''Copyrighted; Permission granted to distribute non-commercially in SWORD format''' 
'''Copyrighted; Free non-commercial distribution''' 
'''Copyrighted; Freely distributable''' 
'''[http://www.gnu.org/copyleft/fdl.html GFDL]''' 
'''[http://www.gnu.org/copyleft/gpl.html GPL]''' 
'''Creative Commons: [http://creativecommons.org/licenses/by-nc-nd by-nc-nd]''' 
'''Creative Commons: [http://creativecommons.org/licenses/by-nc-sa by-nc-sa]''' 
'''Creative Commons: [http://creativecommons.org/licenses/by-nc by-nc]''' 
'''Creative Commons: [http://creativecommons.org/licenses/by-nd by-nd]''' 
'''Creative Commons: [http://creativecommons.org/licenses/by-sa by-sa]''' 
'''Creative Commons: [http://creativecommons.org/licenses/by by]''' 
'''Creative Commons: [http://creativecommons.org/publicdomain/zero/1.0/ CC0]''' 
'''Public Domain''' 

Use one of these strings '''verbatim'''. The actual copyright and/or license information is held in other elements. The last seven<ref>Each link goes to a page that no longer exists!</ref> licenses are [http://creativecommons.org/ Creative Commons] licenses.
|  
|  
|-
| DistributionNotes
|
'''<string>''' 
Indicates any additional notes about distribution of the module.
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| TextSource
|
'''<string>''' 
Indicates, either in prose (such as "CCEL") or as a URL of the source of the text
|  
| [[DevTools:conf Files#Continuation|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.
|  
| [[DevTools:conf Files#RTF|RTF]] [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]] HTML Link
|}
'''Note:'''
<references/>

== 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 ==
* [[User:Dmsmith|DMSmith]] has created a script 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].

== Automated generation ==
* For new module submissions to CrossWire, [[User:Refdoc|Refdoc]] now maintains a script called '''confmaker''' that includes the ''automated generation'' of module conf files, given the minimum ''non-automatable'' requirements by the module submitter.

== See also ==
* [[BibTeX entries]]

[[Category:Development tools|Conf files]]
[[Category:Localization|Conf files]]
[[Category:Versification|Conf files]]
[[Category:Copyright|Conf files]]

DevTools:conf Files

2020-01-05T23:11:49Z

Scribe: /* Copyright & Licensing related elements */

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

Please look also at our detailed and commented [[Tutorial:Writing Conf files|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===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| [ModName]
| Each conf file begins with [ModName], replacing "ModName" with a short well known abbreviation for the module (e.g., [KJV]). 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! An invalid ModName can cause some front-ends to crash.</ref> 
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, [MyModule] would be mymodule.conf.
|  
|  
|-
| Abbreviation<ref>We strongly advise to avoid using an Abbreviation that's identical to the ModName or Abbreviation of any other module. It only leads to confusion, and may have unexpected consequences for some front-ends.</ref>
|
'''<string>''' 
This field allows for the localization of the ModName. It is meant to be short just like the ModName.

''Actually, this element is not required, but it makes the most sense to describe it here.''
| [ModName]
| [[DevTools:conf Files#Localization|Localization]]
|-
| Description
|
'''<string>''' 
This is a short (1 line) title of the module.
|  
| [[DevTools:conf Files#Localization|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<ref>Daily devotionals & glossaries go in subdirectories under lexdict. A glossary is between two languages.</ref>, 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)<ref name="text4">e.g. If the Bible contains large introduction sections</ref> 
'''zText''' (for compressed Bibles) 
'''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> 
'''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)<ref name="sv">zText4 & zCom4 modules require SwordVersion=1.8 or later.</ref> 
'''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)
|  
|  
|}

<references />

===Required Elements with defaults ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| SourceType<ref>Omitting this for a non-plaintext module has unpredictable effects.</ref>
|
'''Plaintext''' 
'''OSIS''' ([http://www.bibletechnologies.net Open Scriptural Information Standard]) 
'''TEI''' ([http://www.tei-c.org 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''' ([http://www.ebible.org/bible/gbf.htm General Bible Format]) 
'''ThML''' ([http://www.ccel.org/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''' ([http://en.wikipedia.org/wiki/Standard_Compression_Scheme_for_Unicode 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 [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
|  
|-
| CompressType
|
'''ZIP''' 
'''LZSS''' ([http://en.wikipedia.org/wiki/Lempel%E2%80%93Ziv%E2%80%93Storer%E2%80%93Szymanski 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. 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
|  
|}

<references />

=== Elements required for proper rendering ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| GlobalOptionFilter
|
'''UTF8Cantillation''' (For Hebrew texts having cantillation marks)<ref>See https://en.wikipedia.org/wiki/Cantillation</ref> 
'''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> 
'''UTF8HebrewPoints''' (For Hebrew texts having vowel points)<ref>See https://en.wikipedia.org/wiki/Niqqud</ref> 
'''UTF8ArabicPoints''' (For Arabic texts having vowel points)<ref>See https://en.wikipedia.org/wiki/Arabic_diacritics</ref> 
'''OSISLemma''' (For OSIS texts having lemmas)<ref>Must precede OSISStrongs.</ref> 
'''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> 
'''OSISStrongs''' (For OSIS texts having Strong's Numbers)<ref name="strongs">See https://en.wikipedia.org/wiki/Strong%27s_Concordance#Strong.27s_numbers</ref> 
'''OSISFootnotes''' (For OSIS texts having informational notes) 
'''OSISScripref''' (For OSIS texts having [[OSIS Bibles#Marking_cross-references_note|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)<ref name="red">See https://en.wikipedia.org/wiki/Red_letter_edition</ref> 
'''OSISGlosses''' (For OSIS texts with glosses)<ref>Minimum SWORD version of 1.7.0 in the module .conf is required for OSISGlosses.</ref> 
'''OSISXlit''' (For OSIS texts that include transliterated forms)<ref>The Samaritan Pentateuch module SP is an example of using xlit.</ref> 
'''OSISEnum''' (For OSIS texts with enumerated words)<ref>The Samaritan Pentateuch module SP is an example of using enum.</ref> 
'''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> 
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> 
'''GBFStrongs''' (For GBF texts having Strong's Numbers)<ref name="strongs">See https://en.wikipedia.org/wiki/Strong%27s_Concordance#Strong.27s_numbers</ref> 
'''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)<ref name="red">See https://en.wikipedia.org/wiki/Red_letter_edition</ref> 
'''ThMLStrongs''' (For THML texts having Strong's Numbers)<ref name="strongs">See https://en.wikipedia.org/wiki/Strong%27s_Concordance#Strong.27s_numbers</ref> 
'''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.<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
|  
|-
| 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 [[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.
|  
|  
|-
| <del>OSISqToTick</del> (deprecated)<ref>For further details, refer to [http://www.crosswire.org/bugs/browse/MOD-188 MOD-188] in CrossWire bugs.</ref>
| This attribute is deprecated in favor of the marker attribute on the q element. E.g.: <pre><q who="Jesus" marker="">....</q></pre> 
<del>true/false</del> 
<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
|  
|-
| 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<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>)
|  
| 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.
|  
|  
|}
<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. 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''' – 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 ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| About
|
'''<string>''' 
A lengthier description and may include copyright, source, etc. information, possibly duplicating information in other elements.
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#RTF|RTF]] [[DevTools:conf Files#Localization|Localization]]
|-
| SwordVersionDate
|
'''<yyyy-mm-dd>''' ([http://en.wikipedia.org/wiki/ISO_8601#Calendar_dates 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>''' 
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 [[DevTools:conf Files#Localization|Localization]]
|-
| MinimumVersion<ref>See http://tracker.crosswire.org/browse/API-201</ref>
|
'''<version string>''' 
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
|  
|-
| Category
|valign="top"|
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)<ref>'''Essays''' is handled as a subset of '''Generic Books'''.</ref>
|
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 [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.
|  
|  
|-
| Lang
|
'''<Language[-Script]?[-Region]?>''' 
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}/)'': 
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: 
: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}/)'': 
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}/)'' 
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})?/)'': 
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<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>
|
'''<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:'''
<references/>

=== Copyright & Licensing related elements ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| Copyright
|
'''<string>''' 
Contains the copyright notice for the work, including the year of copyright and the owner of the copyright.
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightHolder
|
'''<string>''' 
Contains the name of the copyright holder.
|  
| [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightDate
|
'''<yyyy>''' ([http://en.wikipedia.org/wiki/ISO_8601#Years ISO 8601 Year])
|  
| [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightNotes
|
'''<string>'''
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightContactName
|
'''<string>''' 
Contains the name of the copyright holder.
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightContactNotes
|
'''<string>'''
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightContactAddress
|
'''<string>''' 
Contains the mailing address of the copyright holder.
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightContactEmail
|
'''<string>''' 
Contains the email address of the copyright holder, preferably in the form: name at xyz dot com
|  
| [[DevTools:conf Files#Localization|Localization]]
|-
| ShortPromo
|
'''<string>''' 
A link to the home page for the module, perhaps with an encouragement to visit the site.
|  
| HTML Link [[DevTools:conf Files#Localization|Localization]]
|-
| ShortCopyright
|
'''<string>'''
|  
| [[DevTools:conf Files#Localization|Localization]]
|- id="distlic"
| DistributionLicense
|
'''Public Domain''' 
'''Copyrighted''' 
'''Copyrighted; Permission to distribute granted to CrossWire'''<ref>Modules in other repositories may have a different organization name instead of CrossWire.</ref> 
'''Copyrighted; Free non-commercial distribution''' 
'''Copyrighted; Freely distributable''' 
'''Copyrighted; Permission granted to distribute non-commercially in SWORD format''' 
'''[http://www.gnu.org/copyleft/fdl.html GFDL]''' 
'''[http://www.gnu.org/copyleft/gpl.html GPL]''' 
'''Creative Commons: [http://creativecommons.org/licenses/by-nc-nd by-nc-nd]''' 
'''Creative Commons: [http://creativecommons.org/licenses/by-nc-sa by-nc-sa]''' 
'''Creative Commons: [http://creativecommons.org/licenses/by-nc by-nc]''' 
'''Creative Commons: [http://creativecommons.org/licenses/by-nd by-nd]''' 
'''Creative Commons: [http://creativecommons.org/licenses/by-sa by-sa]''' 
'''Creative Commons: [http://creativecommons.org/licenses/by by]''' 
'''Creative Commons: [http://creativecommons.org/publicdomain/zero/1.0/ CC0]''' 

Use one of these strings '''verbatim'''. The actual copyright and/or license information is held in other elements. The last seven<ref>Each link goes to a page that no longer exists!</ref> licenses are [http://creativecommons.org/ Creative Commons] licenses.
|  
|  
|-
| DistributionNotes
|
'''<string>''' 
Indicates any additional notes about distribution of the module.
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| TextSource
|
'''<string>''' 
Indicates, either in prose (such as "CCEL") or as a URL of the source of the text
|  
| [[DevTools:conf Files#Continuation|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.
|  
| [[DevTools:conf Files#RTF|RTF]] [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]] HTML Link
|}
'''Note:'''
<references/>

== 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 ==
* [[User:Dmsmith|DMSmith]] has created a script 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].

== Automated generation ==
* For new module submissions to CrossWire, [[User:Refdoc|Refdoc]] now maintains a script called '''confmaker''' that includes the ''automated generation'' of module conf files, given the minimum ''non-automatable'' requirements by the module submitter.

== See also ==
* [[BibTeX entries]]

[[Category:Development tools|Conf files]]
[[Category:Localization|Conf files]]
[[Category:Versification|Conf files]]
[[Category:Copyright|Conf files]]

DevTools:conf Files

2020-01-05T23:06:44Z

Scribe: /* Copyright & Licensing related elements */

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

Please look also at our detailed and commented [[Tutorial:Writing Conf files|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===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| [ModName]
| Each conf file begins with [ModName], replacing "ModName" with a short well known abbreviation for the module (e.g., [KJV]). 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! An invalid ModName can cause some front-ends to crash.</ref> 
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, [MyModule] would be mymodule.conf.
|  
|  
|-
| Abbreviation<ref>We strongly advise to avoid using an Abbreviation that's identical to the ModName or Abbreviation of any other module. It only leads to confusion, and may have unexpected consequences for some front-ends.</ref>
|
'''<string>''' 
This field allows for the localization of the ModName. It is meant to be short just like the ModName.

''Actually, this element is not required, but it makes the most sense to describe it here.''
| [ModName]
| [[DevTools:conf Files#Localization|Localization]]
|-
| Description
|
'''<string>''' 
This is a short (1 line) title of the module.
|  
| [[DevTools:conf Files#Localization|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<ref>Daily devotionals & glossaries go in subdirectories under lexdict. A glossary is between two languages.</ref>, 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)<ref name="text4">e.g. If the Bible contains large introduction sections</ref> 
'''zText''' (for compressed Bibles) 
'''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> 
'''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)<ref name="sv">zText4 & zCom4 modules require SwordVersion=1.8 or later.</ref> 
'''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)
|  
|  
|}

<references />

===Required Elements with defaults ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| SourceType<ref>Omitting this for a non-plaintext module has unpredictable effects.</ref>
|
'''Plaintext''' 
'''OSIS''' ([http://www.bibletechnologies.net Open Scriptural Information Standard]) 
'''TEI''' ([http://www.tei-c.org 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''' ([http://www.ebible.org/bible/gbf.htm General Bible Format]) 
'''ThML''' ([http://www.ccel.org/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''' ([http://en.wikipedia.org/wiki/Standard_Compression_Scheme_for_Unicode 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 [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
|  
|-
| CompressType
|
'''ZIP''' 
'''LZSS''' ([http://en.wikipedia.org/wiki/Lempel%E2%80%93Ziv%E2%80%93Storer%E2%80%93Szymanski 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. 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
|  
|}

<references />

=== Elements required for proper rendering ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| GlobalOptionFilter
|
'''UTF8Cantillation''' (For Hebrew texts having cantillation marks)<ref>See https://en.wikipedia.org/wiki/Cantillation</ref> 
'''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> 
'''UTF8HebrewPoints''' (For Hebrew texts having vowel points)<ref>See https://en.wikipedia.org/wiki/Niqqud</ref> 
'''UTF8ArabicPoints''' (For Arabic texts having vowel points)<ref>See https://en.wikipedia.org/wiki/Arabic_diacritics</ref> 
'''OSISLemma''' (For OSIS texts having lemmas)<ref>Must precede OSISStrongs.</ref> 
'''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> 
'''OSISStrongs''' (For OSIS texts having Strong's Numbers)<ref name="strongs">See https://en.wikipedia.org/wiki/Strong%27s_Concordance#Strong.27s_numbers</ref> 
'''OSISFootnotes''' (For OSIS texts having informational notes) 
'''OSISScripref''' (For OSIS texts having [[OSIS Bibles#Marking_cross-references_note|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)<ref name="red">See https://en.wikipedia.org/wiki/Red_letter_edition</ref> 
'''OSISGlosses''' (For OSIS texts with glosses)<ref>Minimum SWORD version of 1.7.0 in the module .conf is required for OSISGlosses.</ref> 
'''OSISXlit''' (For OSIS texts that include transliterated forms)<ref>The Samaritan Pentateuch module SP is an example of using xlit.</ref> 
'''OSISEnum''' (For OSIS texts with enumerated words)<ref>The Samaritan Pentateuch module SP is an example of using enum.</ref> 
'''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> 
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> 
'''GBFStrongs''' (For GBF texts having Strong's Numbers)<ref name="strongs">See https://en.wikipedia.org/wiki/Strong%27s_Concordance#Strong.27s_numbers</ref> 
'''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)<ref name="red">See https://en.wikipedia.org/wiki/Red_letter_edition</ref> 
'''ThMLStrongs''' (For THML texts having Strong's Numbers)<ref name="strongs">See https://en.wikipedia.org/wiki/Strong%27s_Concordance#Strong.27s_numbers</ref> 
'''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.<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
|  
|-
| 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 [[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.
|  
|  
|-
| <del>OSISqToTick</del> (deprecated)<ref>For further details, refer to [http://www.crosswire.org/bugs/browse/MOD-188 MOD-188] in CrossWire bugs.</ref>
| This attribute is deprecated in favor of the marker attribute on the q element. E.g.: <pre><q who="Jesus" marker="">....</q></pre> 
<del>true/false</del> 
<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
|  
|-
| 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<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>)
|  
| 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.
|  
|  
|}
<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. 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''' – 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 ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| About
|
'''<string>''' 
A lengthier description and may include copyright, source, etc. information, possibly duplicating information in other elements.
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#RTF|RTF]] [[DevTools:conf Files#Localization|Localization]]
|-
| SwordVersionDate
|
'''<yyyy-mm-dd>''' ([http://en.wikipedia.org/wiki/ISO_8601#Calendar_dates 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>''' 
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 [[DevTools:conf Files#Localization|Localization]]
|-
| MinimumVersion<ref>See http://tracker.crosswire.org/browse/API-201</ref>
|
'''<version string>''' 
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
|  
|-
| Category
|valign="top"|
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)<ref>'''Essays''' is handled as a subset of '''Generic Books'''.</ref>
|
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 [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.
|  
|  
|-
| Lang
|
'''<Language[-Script]?[-Region]?>''' 
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}/)'': 
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: 
: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}/)'': 
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}/)'' 
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})?/)'': 
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<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>
|
'''<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:'''
<references/>

=== Copyright & Licensing related elements ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| Copyright
|
'''<string>''' 
Contains the copyright notice for the work, including the year of copyright and the owner of the copyright.
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightHolder
|
'''<string>''' 
Contains the name of the copyright holder.
|  
| [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightDate
|
'''<yyyy>''' ([http://en.wikipedia.org/wiki/ISO_8601#Years ISO 8601 Year])
|  
| [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightNotes
|
'''<string>'''
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightContactName
|
'''<string>''' 
Contains the name of the copyright holder.
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightContactNotes
|
'''<string>'''
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightContactAddress
|
'''<string>''' 
Contains the mailing address of the copyright holder.
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightContactEmail
|
'''<string>''' 
Contains the email address of the copyright holder, preferably in the form: name at xyz dot com
|  
| [[DevTools:conf Files#Localization|Localization]]
|-
| ShortPromo
|
'''<string>''' 
A link to the home page for the module, perhaps with an encouragement to visit the site.
|  
| HTML Link [[DevTools:conf Files#Localization|Localization]]
|-
| ShortCopyright
|
'''<string>'''
|  
| [[DevTools:conf Files#Localization|Localization]]
|- id="distlic"
| DistributionLicense
|
'''Public Domain''' 
'''Copyrighted''' 
'''Copyrighted; Permission to distribute granted to CrossWire'''<ref>Modules in other repositories may have a different organization name instead of CrossWire.</ref> 
'''Copyrighted; Free non-commercial distribution''' 
'''Copyrighted; Freely distributable''' 
'''Copyrighted; Permission granted to distribute non-commercially in SWORD format''' 
'''[http://www.gnu.org/copyleft/fdl.html GFDL]''' 
'''[http://www.gnu.org/copyleft/gpl.html GPL]''' 
'''Creative Commons: [http://creativecommons.org/licenses/by-nc-nd by-nc-nd]''' 
'''Creative Commons: [http://creativecommons.org/licenses/by-nc-sa by-nc-sa]''' 
'''Creative Commons: [http://creativecommons.org/licenses/by-nc by-nc]''' 
'''Creative Commons: [http://creativecommons.org/licenses/by-nd by-nd]''' 
'''Creative Commons: [http://creativecommons.org/licenses/by-sa by-sa]''' 
'''Creative Commons: [http://creativecommons.org/licenses/by by]''' 
'''Creative Commons: [http://creativecommons.org/publicdomain/zero/1.0/ CC0]''' 

Use one of these strings '''verbatim'''. The actual copyright and/or license information is held in other elements. The last seven<ref>Each link goes to a page that no longer exists!</ref> licenses are [http://creativecommons.org/ Creative Commons] licenses.
|  
|  
|-
| DistributionNotes
|
'''<string>''' 
Indicates any additional notes about distribution of the module.
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| TextSource
|
'''<string>''' 
Indicates, either in prose (such as "CCEL") or as a URL of the source of the text
|  
| [[DevTools:conf Files#Continuation|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.
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]] HTML Link
|}
'''Note:'''
<references/>

== 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 ==
* [[User:Dmsmith|DMSmith]] has created a script 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].

== Automated generation ==
* For new module submissions to CrossWire, [[User:Refdoc|Refdoc]] now maintains a script called '''confmaker''' that includes the ''automated generation'' of module conf files, given the minimum ''non-automatable'' requirements by the module submitter.

== See also ==
* [[BibTeX entries]]

[[Category:Development tools|Conf files]]
[[Category:Localization|Conf files]]
[[Category:Versification|Conf files]]
[[Category:Copyright|Conf files]]

DevTools:Locale Files

2019-08-19T20:59:50Z

Scribe: /* Book Abbrevs */

A locale file is stored in the '''locales.d''' folder under the Sword path. 
The file name is generally the language code with extension .conf 
As Unicode text files, locale files should be encoded UTF-8 (without BOM) and the file name should include "-utf8" after the language code. 
Other encodings are deprecated.

== Example ==

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

excerpts from /sword/locales.d/de.conf:

=== Meta ===

[Meta]
Name=de
Description=German
Encoding=UTF-8

The above information is used to define the locale. They should be
fairly obvious. Name should be, in preferred order, an ISO 639-1 alpha 2 language code, an ISO 639-2+ alpha 3 lanugage code, or an Ethnologue 3 letter language code. SWORD includes a fairly comprehensive list of these available at: sword/locales.d/locales.conf.
This, and all entries are case sensitive.

=== Text ===
This section requires a "one-to-one" mapping for each string to be translated.

The following entries are translation strings for anything you might want. REQUIRED are the book names of the Bible, including deuterocanonical books if used. Other things might be option name, value, tip, translations, or any text returned from the engine.

If you find any errors or omissions, please post a message that you found a constant string in the engine not being (properly) translated.

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

# <snipped rest of book names>

Observe that a full-stop is a permitted character in a book name.

=== Book Abbrevs ===
This section specifies all possible alternative book names and abbreviations for each Bible book. These are required for the locale to work correctly within the SWORD engine. This section teaches the verse reference parser all possible ways to represent a book name. The verse parser will allow partial matches and will sort entries in this section alphabetically by their codepoint values and give preference to partial matches with lower alphabetical order, e.g, "1 C" is a partial match for 1 CORINTHIANS=1Cor and 1 CHRONICLES=1Chr, but 1 CHRONICLES will be preferred because it is alphabetically first. If the desire is to have "1 C" prefer 1Cor, instead, then a 3rd entry is required: 1 C=1Cor. This preference for disambiguation is important to consider for partial matches, as they are prolific throughout Biblical literature, e.g., Jud=Jude (instead of Judges), Jo=John (instead of Job, Jonah, or Joshua)

The format is:
uppercase alternative book name or abbreviation=osisID
SWORD will sort this list, but it is preferred and standard to keep this list in alphabetical order to assist the authors in defining and tuning these preferences, .e.g.,

[Book Abbrevs]
1 C=1Cor
1 CHRONICLES=1Chr
1 CORINTHIANS=1Cor
1 JN=1Jn
1C=1Cor
1CHRONICLES=1Chr
1CORINTHIANS=1Cor
I C=1Cor
I CHRONICLES=1Chr
I CORINTHIANS=1Cor
IC=1Cor
ICHRONICLES=1Chr
ICORINTHIANS=1Cor

As expressed earlier, notice that 1 Chronicles would come, alphabetically
before 1 Corinthians. The above entries say: 1Cor (which is the OSIS book id for 1 Corinthians)
has precedence up through "1 C", any character beyond that will disambiguate the entry anyway, so the default 1 CHRONICLES or 1
CORINTHIANS entries would correctly resolve partial matches with more characters starting with "1 C".

'''IMPORTANT''':

All verse references output by SWORD must be legal, parsable reference as input to SWORD. This means that there MUST be at least 1 abbreviation entry for each book name
which is comprised of a toupper (uppercase function) of the entire string EXACTLY as you have translated it in the [Text] section.

For example, the following are the REQUIRED entries for our book names from the excerpt [Text] section example above.
1. MOSE=Gen
2. MOSE=Ex
3. MOSE=Lev

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

=== Pref Abbrevs ===
This section designates the preferred abbreviation for each book. These are typically used when SWORD is asked to display a very short verse reference or a short Bible book name. The format for these entries is: osisID=Preferred Abbreviation, e.g.,

[Pref Abbrevs]
Gen=1Mo
Exod=2Mo
Lev=3Mo
Num=4Mo
Deut=5Mo
Josh=Jos
Judg=Rich

Each preferred abbreviation must necessarily be parsable by the exhaustive list of abbreviations in the [Book Abbrevs] section.

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

A full-stop is a permitted character in a localized book abbreviation. Other punctuation characters commonly used in verse references are not allowed in localized book names. These include the hyphen '-' (used for verse ranges), the colon ':' (used to separate chapter and verse numbers), and the comma ',' (used for verse lists). Additionally, numerals in non-initial position are not permitted in book names (i.e. '3John' is valid but 'Psalm151' is not).

== Submissions ==
If you create a new locale file as part of the process towards making a module, please submit it to CrossWire.

Submissions should be sent to sword-support@crosswire.org

== Maintained locale files ==

On the CrossWire server, the locale files are stored in <tt>/space/home/ftp/pub/sword/raw/locales.d</tt> 
Users with FTP or SCP access are able to download them from that folder.

Corrections to errors in locale files should be sent to sword-support@crosswire.org

[[Category:Localization|Locale Files]]
[[Category:SWORD]]

DevTools:Locale Files

2019-08-19T20:25:10Z

Scribe: /* Pref Abbrevs */

A locale file is stored in the '''locales.d''' folder under the Sword path. 
The file name is generally the language code with extension .conf 
As Unicode text files, locale files should be encoded UTF-8 (without BOM) and the file name should include "-utf8" after the language code. 
Other encodings are deprecated.

== Example ==

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

excerpts from /sword/locales.d/de.conf:

=== Meta ===

[Meta]
Name=de
Description=German
Encoding=UTF-8

The above information is used to define the locale. They should be
fairly obvious. Name should be, in preferred order, an ISO 639-1 alpha 2 language code, an ISO 639-2+ alpha 3 lanugage code, or an Ethnologue 3 letter language code. SWORD includes a fairly comprehensive list of these available at: sword/locales.d/locales.conf.
This, and all entries are case sensitive.

=== Text ===
This section requires a "one-to-one" mapping for each string to be translated.

The following entries are translation strings for anything you might want. REQUIRED are the book names of the Bible, including deuterocanonical books if used. Other things might be option name, value, tip, translations, or any text returned from the engine.

If you find any errors or omissions, please post a message that you found a constant string in the engine not being (properly) translated.

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

# <snipped rest of book names>

Observe that a full-stop is a permitted character in a book name.

=== Book Abbrevs ===
This section permits a "many-to-one" mapping for each book, as required by the references used in the Bible translation or commentary, etc.

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

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

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

'''IMPORTANT''':

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

Following are the REQUIRED entries from our excerpt book names above.
1. MOSE=Gen
2. MOSE=Ex
3. MOSE=Lev

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

=== Pref Abbrevs ===
This section designates the preferred abbreviation for each book. These are typically used when SWORD is asked to display a very short verse reference or a short Bible book name. The format for these entries is: osisID=Preferred Abbreviation, e.g.,

[Pref Abbrevs]
Gen=1Mo
Exod=2Mo
Lev=3Mo
Num=4Mo
Deut=5Mo
Josh=Jos
Judg=Rich

Each preferred abbreviation must necessarily be parsable by the exhaustive list of abbreviations in the [Book Abbrevs] section.

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

A full-stop is a permitted character in a localized book abbreviation. Other punctuation characters commonly used in verse references are not allowed in localized book names. These include the hyphen '-' (used for verse ranges), the colon ':' (used to separate chapter and verse numbers), and the comma ',' (used for verse lists). Additionally, numerals in non-initial position are not permitted in book names (i.e. '3John' is valid but 'Psalm151' is not).

== Submissions ==
If you create a new locale file as part of the process towards making a module, please submit it to CrossWire.

Submissions should be sent to sword-support@crosswire.org

== Maintained locale files ==

On the CrossWire server, the locale files are stored in <tt>/space/home/ftp/pub/sword/raw/locales.d</tt> 
Users with FTP or SCP access are able to download them from that folder.

Corrections to errors in locale files should be sent to sword-support@crosswire.org

[[Category:Localization|Locale Files]]
[[Category:SWORD]]

DevTools:Locale Files

2019-08-19T18:46:02Z

Scribe: /* Pref Abbrevs */

A locale file is stored in the '''locales.d''' folder under the Sword path. 
The file name is generally the language code with extension .conf 
As Unicode text files, locale files should be encoded UTF-8 (without BOM) and the file name should include "-utf8" after the language code. 
Other encodings are deprecated.

== Example ==

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

excerpts from /sword/locales.d/de.conf:

=== Meta ===

[Meta]
Name=de
Description=German
Encoding=UTF-8

The above information is used to define the locale. They should be
fairly obvious. Name should be, in preferred order, an ISO 639-1 alpha 2 language code, an ISO 639-2+ alpha 3 lanugage code, or an Ethnologue 3 letter language code. SWORD includes a fairly comprehensive list of these available at: sword/locales.d/locales.conf.
This, and all entries are case sensitive.

=== Text ===
This section requires a "one-to-one" mapping for each string to be translated.

The following entries are translation strings for anything you might want. REQUIRED are the book names of the Bible, including deuterocanonical books if used. Other things might be option name, value, tip, translations, or any text returned from the engine.

If you find any errors or omissions, please post a message that you found a constant string in the engine not being (properly) translated.

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

# <snipped rest of book names>

Observe that a full-stop is a permitted character in a book name.

=== Book Abbrevs ===
This section permits a "many-to-one" mapping for each book, as required by the references used in the Bible translation or commentary, etc.

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

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

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

'''IMPORTANT''':

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

Following are the REQUIRED entries from our excerpt book names above.
1. MOSE=Gen
2. MOSE=Ex
3. MOSE=Lev

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

=== Pref Abbrevs ===
This section define a preferred abbreviation for each book. These are typically used when SWORD is asked to display a very short verse reference or a short Bible book name. The format for these entries is: osisID=Preferred Abbreviation, e.g.,

[Pref Abbrevs]
Gen=1Mo
Exod=2Mo
Lev=3Mo
Num=4Mo
Deut=5Mo
Josh=Jos
Judg=Rich

Each preferred abbreviation must necessarily be parsable by the exhaustive list of abbreviations in the [Book Abbrevs] section.

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

A full-stop is a permitted character in a localized book abbreviation. Other punctuation characters commonly used in verse references are not allowed in localized book names. These include the hyphen '-' (used for verse ranges), the colon ':' (used to separate chapter and verse numbers), and the comma ',' (used for verse lists). Additionally, numerals in non-initial position are not permitted in book names (i.e. '3John' is valid but 'Psalm151' is not).

== Submissions ==
If you create a new locale file as part of the process towards making a module, please submit it to CrossWire.

Submissions should be sent to sword-support@crosswire.org

== Maintained locale files ==

On the CrossWire server, the locale files are stored in <tt>/space/home/ftp/pub/sword/raw/locales.d</tt> 
Users with FTP or SCP access are able to download them from that folder.

Corrections to errors in locale files should be sent to sword-support@crosswire.org

[[Category:Localization|Locale Files]]
[[Category:SWORD]]

DevTools:Locale Files

2019-08-19T18:45:31Z

Scribe: /* Pref Abbrevs */

A locale file is stored in the '''locales.d''' folder under the Sword path. 
The file name is generally the language code with extension .conf 
As Unicode text files, locale files should be encoded UTF-8 (without BOM) and the file name should include "-utf8" after the language code. 
Other encodings are deprecated.

== Example ==

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

excerpts from /sword/locales.d/de.conf:

=== Meta ===

[Meta]
Name=de
Description=German
Encoding=UTF-8

The above information is used to define the locale. They should be
fairly obvious. Name should be, in preferred order, an ISO 639-1 alpha 2 language code, an ISO 639-2+ alpha 3 lanugage code, or an Ethnologue 3 letter language code. SWORD includes a fairly comprehensive list of these available at: sword/locales.d/locales.conf.
This, and all entries are case sensitive.

=== Text ===
This section requires a "one-to-one" mapping for each string to be translated.

The following entries are translation strings for anything you might want. REQUIRED are the book names of the Bible, including deuterocanonical books if used. Other things might be option name, value, tip, translations, or any text returned from the engine.

If you find any errors or omissions, please post a message that you found a constant string in the engine not being (properly) translated.

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

# <snipped rest of book names>

Observe that a full-stop is a permitted character in a book name.

=== Book Abbrevs ===
This section permits a "many-to-one" mapping for each book, as required by the references used in the Bible translation or commentary, etc.

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

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

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

'''IMPORTANT''':

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

Following are the REQUIRED entries from our excerpt book names above.
1. MOSE=Gen
2. MOSE=Ex
3. MOSE=Lev

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

=== Pref Abbrevs ===
This section define a preferred abbreviation for each book. These are typically used when SWORD is asked to display a very short verse reference or a short Bible book name. The format for these entries is: osisID=Preferred Abbreviation, e.g.,

[Pref Abbrevs]
Gen=1Mo
Exod=2Mo
Lev=3Mo
Num=4Mo
Deut=5Mo
Josh=Jos
Judg=Rich

Each preferred abbreviation must necessarily be parsable by the exhaustive list of abbreviations in the [Book Abbrevs] section.

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

A full-stop is a permitted character in a localized book abbreviation. Other punctuation characters commonly used in verse references are not allowed in localized book names. These include the hyphen '-' (used for verse ranges), the colon ':' (used to separate chapter and verse numbers), and the comma ',' (used for verse lists). Additionally, numerals in non-initial position are not permitted in book names (i.e. '3John' is valid but 'Psalm151' is not).

== Submissions ==
If you create a new locale file as part of the process towards making a module, please submit it to CrossWire.

Submissions should be sent to sword-support@crosswire.org

== Maintained locale files ==

On the CrossWire server, the locale files are stored in <tt>/space/home/ftp/pub/sword/raw/locales.d</tt> 
Users with FTP or SCP access are able to download them from that folder.

Corrections to errors in locale files should be sent to sword-support@crosswire.org

[[Category:Localization|Locale Files]]
[[Category:SWORD]]

DevTools:Locale Files

2019-08-19T18:42:34Z

Scribe:

A locale file is stored in the '''locales.d''' folder under the Sword path. 
The file name is generally the language code with extension .conf 
As Unicode text files, locale files should be encoded UTF-8 (without BOM) and the file name should include "-utf8" after the language code. 
Other encodings are deprecated.

== Example ==

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

excerpts from /sword/locales.d/de.conf:

=== Meta ===

[Meta]
Name=de
Description=German
Encoding=UTF-8

The above information is used to define the locale. They should be
fairly obvious. Name should be, in preferred order, an ISO 639-1 alpha 2 language code, an ISO 639-2+ alpha 3 lanugage code, or an Ethnologue 3 letter language code. SWORD includes a fairly comprehensive list of these available at: sword/locales.d/locales.conf.
This, and all entries are case sensitive.

=== Text ===
This section requires a "one-to-one" mapping for each string to be translated.

The following entries are translation strings for anything you might want. REQUIRED are the book names of the Bible, including deuterocanonical books if used. Other things might be option name, value, tip, translations, or any text returned from the engine.

If you find any errors or omissions, please post a message that you found a constant string in the engine not being (properly) translated.

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

# <snipped rest of book names>

Observe that a full-stop is a permitted character in a book name.

=== Book Abbrevs ===
This section permits a "many-to-one" mapping for each book, as required by the references used in the Bible translation or commentary, etc.

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

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

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

'''IMPORTANT''':

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

Following are the REQUIRED entries from our excerpt book names above.
1. MOSE=Gen
2. MOSE=Ex
3. MOSE=Lev

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

=== Pref Abbrevs ===
This section define a preferred abbreviation for each book. These are typically used when SWORD is asked to display a very short verse reference or a short Bible book name. The format for these entries is: osisID=Preferred Abbreviation, e.g.,

[Pref Abbrevs]
Gen=1Mo
Exod=2Mo
Lev=3Mo
Num=4Mo
Deut=5Mo
Josh=Jos
Judg=Rich

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

A full-stop is a permitted character in a localized book abbreviation. Other punctuation characters commonly used in verse references are not allowed in localized book names. These include the hyphen '-' (used for verse ranges), the colon ':' (used to separate chapter and verse numbers), and the comma ',' (used for verse lists). Additionally, numerals in non-initial position are not permitted in book names (i.e. '3John' is valid but 'Psalm151' is not).

== Submissions ==
If you create a new locale file as part of the process towards making a module, please submit it to CrossWire.

Submissions should be sent to sword-support@crosswire.org

== Maintained locale files ==

On the CrossWire server, the locale files are stored in <tt>/space/home/ftp/pub/sword/raw/locales.d</tt> 
Users with FTP or SCP access are able to download them from that folder.

Corrections to errors in locale files should be sent to sword-support@crosswire.org

[[Category:Localization|Locale Files]]
[[Category:SWORD]]

DevTools:Locale Files

2019-08-19T18:36:22Z

Scribe: /* Meta */

A locale file is stored in the '''locales.d''' folder under the Sword path. 
The file name is generally the language code with extension .conf 
As Unicode text files, locale files should be encoded UTF-8 (without BOM) and the file name should include "-utf8" after the language code. 
Other encodings are deprecated.

== Example ==

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

excerpts from /sword/locales.d/de.conf:

=== Meta ===

[Meta]
Name=de
Description=German
Encoding=UTF-8

The above information is used to define the locale. They should be
fairly obvious. Name should be, in preferred order, an ISO 639-1 alpha 2 language code, an ISO 639-2+ alpha 3 lanugage code, or an Ethnologue 3 letter language code. SWORD includes a fairly comprehensive list of these available at: sword/locales.d/locales.conf.
This, and all entries are case sensitive.

=== Text ===
This section requires a "one-to-one" mapping for each string to be translated.

The following entries are translation strings for anything you might want. REQUIRED are the book names of the Bible, including deuterocanonical books if used. Other things might be option name, value, tip, translations, or any text returned from the engine.

If you find any errors or omissions, please post a message that you found a constant string in the engine not being (properly) translated.

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

# <snipped rest of book names>

Observe that a full-stop is a permitted character in a book name.

=== Book Abbrevs ===
This section permits a "many-to-one" mapping for each book, as required by the references used in the Bible translation or commentary, etc.

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

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

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

'''IMPORTANT''':

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

Following are the REQUIRED entries from our excerpt book names above.
1. MOSE=Gen
2. MOSE=Ex
3. MOSE=Lev

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

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

A full-stop is a permitted character in a localized book abbreviation. Other punctuation characters commonly used in verse references are not allowed in localized book names. These include the hyphen '-' (used for verse ranges), the colon ':' (used to separate chapter and verse numbers), and the comma ',' (used for verse lists). Additionally, numerals in non-initial position are not permitted in book names (i.e. '3John' is valid but 'Psalm151' is not).

== Submissions ==
If you create a new locale file as part of the process towards making a module, please submit it to CrossWire.

Submissions should be sent to sword-support@crosswire.org

== Maintained locale files ==

On the CrossWire server, the locale files are stored in <tt>/space/home/ftp/pub/sword/raw/locales.d</tt> 
Users with FTP or SCP access are able to download them from that folder.

Corrections to errors in locale files should be sent to sword-support@crosswire.org

[[Category:Localization|Locale Files]]
[[Category:SWORD]]

Tutorials:SWORD 102

2018-03-03T00:00:35Z

Scribe:

== XML Basics ==

XMLTag is a wonderful class for working with.... XML Tags!

For example. If you have the tag:

<verse osisID="John.1.1" type='test type' yeah = "stuff" />

You can do handy things like:

<pre>cout << tag.getAttribute("type");
$ test type

tag.setAttribute("type", "changedType");
tag.setAttribute("subtype", "newSubtype");

cout << tag.getName();
$ verse

cout << tag.isEmpty();
$ true

cout << tag.isEndTag();
$ false

cout << XMLTag("</verse>").isEndTag();
$ true

cout << tag.toString();
$ <verse osisID="John.1.1" subtype="newSubtype" type="changedType"
yeah="stuff"/>
</pre>
<hr/>

XMLTag even helps you parse list attributes like:

<reference osisRef="John.3.16 John.3.22-25 Act.4.12">

<pre>int count = tag.getAttributePartCount("osisRef", ' ');
for (int i = 0; i < count; ++i) {
cout << tag.getAttribute("osisRef", i, ' ');
}
$ John.3.16
$ John.3.22-25
$ Acts.4.12
</pre>
<hr>

And it mostly figures things out for you, even when the XML isn't
exactly valid (which we quite often find in imported modules)

For a wild and crazy show see the link below:

http://crosswire.org/svn/sword/trunk/tests/xmltest.cpp

[[Category:Tutorials]]

Frontends:Bishop

2018-03-02T23:36:52Z

Scribe:

'''Bishop''' - Very small, very fast, very powerful programme for Android Mobile phones.

Google Play Store: [https://play.google.com/store/apps/details?id=org.crosswire.bishop]
Direct Download: [http://crosswire.org/bishop.apk]

Official and Affiliated Module Repositories

2017-10-24T14:30:17Z

Scribe:

The Repository directory has to be specified for the Install Manager in [[Frontends:BibleCS|the SWORD Project for Windows]], which uses FTP access. Likewise for the other front-ends based on the SWORD API.

The Catalog & ZIP directories have to be specified for the [[DevTools:JSword|JSword]] based installer (e.g. as used for [[Frontends:BibleDesktop|Bible Desktop]]), which uses HTTP access.

The 'Site Name' field is just a convenient name for managing/selecting repositories. Users may edit these without any loss of functionality, as long as they ensure that each is uniquely and appropriately named.

== CrossWire Bible Society ==
CrossWire maintains a '''Master Repositories List''' (filename: <tt>masterRepoList.conf</tt>) which is accessed by most front-end applications. Some front-ends require a refresh operation to ensure that the latest edition of the '''MRL''' is installed.

=== Released modules ===
Official module repository from CrossWire Bible Society. This repository now also hosts modules with [[Alternate Versification]]s.
Site Name: CrossWire Bible Society (main)
Site Machine Name: ftp.crosswire.org
Repository Directory: /pub/sword/raw/

Catalog Directory: /ftpmirror/pub/sword/raw
ZIP Directory: /ftpmirror/pub/sword/packages/rawzip

These modules can be downloaded directly via the link below, but using the module manager built into most front-end applications is vastly preferable

* http://www.crosswire.org/sword/modules

=== Module attic ===
Official module repository from CrossWire Bible Society for the previous version of released modules. Look here if you have updated to a new version of a module, discover that there are bugs or errors, and want to downgrade. This repository is not shown in PocketSword. It is not included in the Master Repositories List.
Site Name: CrossWire Bible Society Attic
Site Machine Name: ftp.crosswire.org
Repository Directory: /pub/sword/atticraw/

=== Modules for beta testing ===
This is included in the Master Repositories List. Please test these modules and report your findings on [[Modules in the beta repository]]. Beta modules should be validated before being transferred to the main CrossWire repository.
Site Name: CrossWire beta
Site Machine Name: ftp.crosswire.org
Repository Directory: /pub/sword/betaraw

Catalog Directory: /ftpmirror/pub/sword/betaraw
ZIP Directory: /ftpmirror/pub/sword/betapackages/rawzip

These modules can be downloaded directly via the link below, but using the module manager built into most front-end applications is vastly preferable

* http://www.crosswire.org/sword/modules/betaindex.jsp

=== CrossWire Wycliffe ===
The 43 [[Modules:WBTI & BL Bibles|modules from WBTI & BL]] that were formerly kept in CrossWire Beta have been moved to a separate repository. This is included in the Master Repositories List.
Site Name: CrossWire Wycliffe
Site Machine Name: ftp.crosswire.org
Repository Directory: /pub/sword/wyclifferaw
'''Note:'''
# Many of these translations are now available online at [http://bibles.org/ Bible Search] hosted by the American Bible Society.

=== Experimental modules ===
These [[Modules in the experimental repository|experimental modules]] are primarily intended for front-end developers. They require new features not supported by some front-end applications. This repository is not included in the Master Repositories List, neither is it displayed by PocketSword.
Site Name: CrossWire experimental
Site Machine Name: ftp.crosswire.org
Repository Directory: /pub/sword/experimentalraw

== Other Repositories ==
=== Other Bible agencies ===
Any ''bona fide'' Bible agency may set up and maintain their own modules repository. Providing the agency adheres to orthodox Christian doctrine (i.e. not a cult!), a request for such a repository to be added to the Master Repostories List will be seriously considered by CrossWire.

=== NET Bible ===
Home of the New English Translation. This is included in the Master Repositories List.
Site Name: NET
Site Machine Name: ftp.bible.org
Repository Directory: /sword

Catalog Directory: /sword/raw
ZIP Directory: /sword/packages/rawzip

=== Xiphos ===
A number of random creations, including a fair number of dictionary, map and image modules:
Tischendorf8 Greek NT, Hodge's Systematic Theology, and others. Daily Devotionals include BibleCompanion, MCheyne, OneYearRead. This is included in the Master Repositories List.
Site Name: Xiphos
Site Machine Name: ftp.xiphos.org
Repository Directory: .

Catalog Directory: /sword
ZIP Directory: /sword/zip

=== Institute for Bible Translation ===
The [http://ibt.org.ru/en/pc.htm Institute for Bible Translation] has a SWORD repository. This is included in the Master Repositories List.

Site Name: IBT
Site Machine Name: ftp.ibt.org.ru
Repository Directory: /pub/modsword/raw

Catalog Directory: /ftpmirror/pub/modsword/raw
ZIP Directory: /ftpmirror/pub/modsword/rawzip

The '''Institute for Bible Translation''' provides a number of Bible translations in various languages of Central Asia and the CIS. Currently these include Adygei, Aghul, Avar, Buryat, Chuvash, Crimean Tatar, Gagauz (Latin & Cyrillic), Georgian, Karakalpak, Kazakh, Khakas, Kumyk, Kyrgyz (Arabic & Cyrillic), Ossetic, Tabasaran, Tajik (Gospels), Tatar, Turkmen (Latin & Cyrillic), Uzbek (Latin & Cyrillic). Alongside these translations are modules for English, Russian, Ukrainian and the original Bible languages (Hebrew & Greek). Further modules are in preparation. Several of the translations have linked dictionary modules.

'''Notes:'''
# The programmer has made his source code available under the name [https://github.com/JohnAustinDev/xulsword xulsword].
# With the advent of [[Alternate Versification]] in SWORD, the MK program is fully [https://github.com/JohnAustinDev/osis-converters/ compatible] with the SWORD API. All modules in the IBT repository are fully SWORD compatible, although their .conf files have some extra entries which apply only to xulsword, and their OSIS tags may have some subtype attributes which other SWORD front ends will ignore.
# The Original languages module combines the Hebrew OT and Greek NT into a single module.
# The Russian Synodal (1876) module has cross references and Strong's tags.

=== eBible.org ===
This repository maintained by Michael Paul Johnson provides access to Bible modules in more than 600 languages. It has been added to the Master Repository List.

FTP access:
Site Name: eBible.org
Site Machine Name: ftp.ebible.org
Repository Directory: /pub/sword
Catalog Directory: /pub/sword
ZIP Directory: /pub/sword/zip

HTTP access:
Site Name: eBible.org
Site Machine Name: ebible.org
Repository Directory: /sword
Catalog Directory: /sword
ZIP Directory: /sword/zip

=== Tyndale STEP ===
I put the following questions to our partners at STEP Development:
# Does STEP have its own modules repository?
# If so, can it be accessed by the module manager from other JSword or SWORD front-ends?
Here is their reply:
:Yes. When you "Install more Bibles" in "Help" of the Download version, you have access to two STEP repositories - '''Public''' and '''Licensed'''. Modules from the '''Public''' repository can be used in any '''JSword''' software. Unfortunately, not all publishers allow us to put their works in the '''Public''' one. There are not yet many modules in either.
::''I have begun to seek further details.'' [[User:David Haslam|David Haslam]] ([[User talk:David Haslam|talk]]) 09:04, 23 January 2017 (MST)

==Other module sources==

=== Bible Vietnam ===
[http://www.biblevietnam.org The UBS Vietnam page] has several Vietnamese-language modules, including the UBS version of the Viet module, which incorporates minor corrections to the 1926 text made in 1998 by the UBS along with headings and cross-references.

=== Slovak ===
[http://www.kristus.sk/biblia/ kristus.sk] has the SSV translation available to download as a SWORD module called SvkPS. The published Catholic SSV translation contains deuterocanonical books, but this first module edition does not. One with [[Alternate Versification]] is in the pipeline.

The same web-page also has Slovak & Czech Bibles for download in other electronic editions, including Go Bible.

=== Gilak Media ===
[http://gilakmedia.com/en/software Windows Software for Gilaki Scripture] – this is a Farsi and Gilaki edition of the IBT MK Holy Bible software, with a xulsword module for the Gilaki Scriptures, currently the Gospel of John only, but with full audio. The Farsi Bible module is FarsiOPV version 1.0, adapted to suit xulsword. The Gilaki language is a Caspian language, and a member of the northwestern Iranian language branch, spoken in Iran's Gīlān Province.

=== Paite e-Holy Bible ===
[http://en.wikipedia.org/wiki/Paite Paite] is spoken in parts of North East India, Burma & Bangladesh. The complete Paite e-Holy Bible version 3 (2009-10-15) is available from [http://zogam.com/documents/cat_view/954-bible-for-computer/915-paite-e-holy-bible Paite E-Holy Bible]. It is possible to display the Paite module in other SWORD front-end applications for Windows by copying the installed files to the SWORD path.<ref>Alternatively, without actually running the install setup, the EXE file may opened as an archive using (e.g.) [http://www.7-zip.org/ 7-Zip], and the PEH module may be extracted along with the file <tt>peh.conf</tt>.</ref><ref>Take care, as the setup file also included a copy of our KJV module (Version=2.3).</ref><ref>In Xiphos, the localized language name is displayed as '''Paite Chin'''.</ref>

'''News update:''' 2014-01-19 – Yesterday I had a message from Hlunboi Guite asking if & how CrossWire might distribute the Paite Bible module. [[User:David Haslam|David Haslam]] 03:28, 19 January 2014 (MST)

'''Note:'''
<references />

=== Tedim e-Holy Bible ===
There is a similar Bible application for the [http://en.wikipedia.org/wiki/Tedim Tedim Lai Siangtho] dialect, available from [http://zogam.com/documents/cat_view/954-bible-for-computer/955-tedim-e-holy-bible Tedim e-Holy Bible]. The same observations apply.

=== German ===
==== Volxbibel ====
[http://www.volxbibel.com/ Volxbibel] – A new German Bible translation in the language of the young generation. The translation is under the [http://creativecommons.org/licenses/by-nc-sa/2.0/de/deed.en_GB Creative Commons] license, so non-commercial use and distribution is allowed. A SWORD module called VLX3 has been created by [http://www.heidoc.net/ Jan Krohn], who has also built Go Bible applications for Java mobile phones. ''Contact Jan Krohn for further details''.

==== Offene Bibel ====
[http://www.offene-bibel.de/ Offene Bibel] is an independent new ecumenical CC German translation in two parts: a philological "study version" and a dynamic-equivalence "reading version" (see the [http://www.offene-bibel.de/wiki/index.php5?title=About_Offene_Bibel English About]). The translation is far from finished, but test SWORD modules with sample chapters have been created for both versions. They can be downloaded [http://www.offene-bibel.de/forum/sword_module here]. The creators will be happy to receive your feedback. Official modules are planned.

=== Word Of God team (India) ===
The following modules are being made available by the [http://www.wordofgod.in/ Word of God] team in India, under the leadership of Yesudas Solomon.
* Hindi Bible
* Hmar Bible
* Kannada (KJV) Bible
* Kannada (BSI) NT
* Koya NT
* Malayalam Bible
* Tamil (Common) Bible
* Tamil (OV) Bible
* Telugu Bible
Registration and login is required to download these modules. Some of those listed here are still underway. Other languages expected to follow.

Currently there are "easy to install" downloads for these Windows front-ends:
* [http://wordofgod.in/Downloads/FreeBibleSoftwares/SwordBibleSoftware.aspx SwordBible]
* [http://www.wordofgod.in/Downloads/FreeBibleSoftwares/BPBibleSoftware.aspx BPBible]
* [http://www.wordofgod.in/Downloads/FreeBibleSoftwares/TheSwordProject.aspx The Sword Project for Windows]
The latter also has the raw module format downloads.

There are also Go Bible (mobile phone) versions, and modules for some non-CrossWire free Bible study applications.

=== Nepal Bible Society ===

[http://www.nepalbiblesociety.org.np/ NBS] has made both its translations available for use with a Nepali interfaced edition of [http://bpbible.com/ BPBible].

* Nepali New Revised Version
* Simple Nepali Holy Bible

Their e-Bible modules are serial numbered and licensed for individual use. Request by email on [http://www.nepalbiblesociety.org.np/index.php?option=com_content&view=article&id=5&Itemid=2 this page].

Both versions are also available as free [http://www.nepalbiblesociety.org.np/go-bible.html Go Bible] applications, with either English or Nepali UI.

=== Thailand Bible Society ===
The Thailand Bible Society has ported The SWORD Project for Windows to make a localized Thai edition complete with several Thai Bible modules.

Visit http://www.thaibible.or.th/crosswire/ (largely in Thai) for more information.

It seems that you may have had to register and be signed in to download their software, but there is a module update in the form of a self-extracting EXE file, which contains some module files suitable for improved searching. There is an illustrated manual available in PDF format (also in Thai). A friend of a friend wrote, "Now I can't actually find the Thai version of The SWORD Project for Windows ANYWHERE. I've seen people using it (several years ago now)."

Latest news (2012-02-09): It would appear that Thailand Bible Society had ceased distributing their localized version of The SWORD Project for Windows, and have switched to promoting The Word instead. See [http://www.thaibible.or.th/]. They have other Bible software available too.

=== An Bíobla Naofa ===

[http://www.anbioblanaofa.org/en/crosswire ABN] module. The Gaeilge (Irish Gaelic) translation (1981) by Monsignor Pádraig Ó Fiannachta. Requires front-end support for [[Alternate Versification]] to display the Deuterocanonical books. This electronic version of the ABN has been adapted to follow the KJVA versification scheme, yet also displays the alternate ABN verse numbers in {braces}.

=== Terjemahan Sederhana Indonesia ===
As described in [http://albata.info/?page_id=43 Yayasan Alkitab BahasaKita] the TSI Sword module (Terjemahan Sederhana Indonesia) can be downloaded as a compressed zip file from [https://sites.google.com/a/bahasakita.net/albatadotinfo/tsi-terjemahan-sederhana/program-lain-untuk-membaca-tsi/TSISwordModule.zip?attredirects=0&d=1 TSI Sword module]. This Plain Indonesian New Testament translation project was pioneered by Phil Fields. tsi.conf currently has Lang=UNKNOWN.

=== Portuguese Almeida Corrigida Fiel 2007 ===
[http://www.biblias.com.br Sociedade Bíblica Trinitariana do Brasil (SBTB)] – Esta obra é distribuída gratuitamente através do [http://siriarah.wordpress.com/ blog]
:The '''ACF2007''' module is available on https://app.box.com/v/siriarah as biblias/ACF2007/ACF2007-sword.zip

== See also ==

* [[Creating and Maintaining a Module Repository]]

[[Category:Modules]]
[[Category:Repositories]]

DevTools:conf Files

2017-06-14T19:36:52Z

Scribe: /* Copyright & Licensing related elements */

=Creating a .conf File=
== module.conf File Layout==
SWORD uses a Windows INI file for configuration information. Each module's configuration is held in a module.conf file. This file is used by the SWORD engine to process modules, by installers to help users install modules and by front-ends to render the module appropriately.

Different [http://en.wikipedia.org/wiki/Newline End-of-Line] styles should be not be mixed in the same file.

== Overview by Example ==
The module.conf file starts with an INI section, giving the ModName.
:[KJV]

This is then followed by key=value pairs. While a Windows INI file allows : in addition to =, SWORD does not.
: # A line that starts with a # is a comment
: ; A line that begins with a ; is also a comment
:     # whitespace at the beginning of the line or end of the line is trimmed. This also is a comment.
:     DataPath=./modules/texts/ztext/kjv/
: # whitespace can be around the = as well.
: ModDrv   =     zText
: Encoding=UTF-8
: BlockType=BOOK
: CompressType=ZIP
: SourceType=OSIS
: Lang=en

Some keys can be repeated with different values:
:GlobalOptionFilter=OSISStrongs
:GlobalOptionFilter=OSISMorph
:GlobalOptionFilter=OSISFootnotes
:GlobalOptionFilter=OSISHeadings
:GlobalOptionFilter=OSISRedLetterWords

Some keys support [[DevTools:conf Files#Localization|localization]]:
Abbreviation=和合本
Abbreviation_en=ChiUn
Description=和合本 (繁體字)
Description_en=Chinese Union Version (Traditional)

Some fields can have [[DevTools:conf Files#RTF|RTF]] in a single line:
:About=This is the King James Version of the Holy Bible (also known as the Authorized Version) with embedded Strong's Numbers. The rights to the base text are held by the Crown of England. The Strong's numbers in the OT were obtained from The Bible Foundation: http://www.bf.org. The NT Strong's data was obtained from The KJV2003 Project at CrossWire: http://www.crosswire.org. These mechanisms provide a useful means for looking up the exact original language word in a lexicon that is keyed to Strong's numbers.\par\par Special thanks to the volunteers at Bible Foundation for keying the Hebrew/English data and of Project KJV2003 for working toward the completion of synchronizing the English phrases to the Stephanas Textus Receptus, and to Dr. Maurice Robinson for providing the base Greek text with Strong's and Morphology. We are also appreciative of formatting markup that was provided by Michael Paul Johnson at http://www.ebible.org. Their time and generosity to contribute such for the free use of the Body of Christ is a great blessing and this derivative work could not have been possible without these efforts of so many individuals. It is in this spirit that we in turn offer the KJV2003 Project text freely for any purpose. Any copyright that might be obtained for this effort is held by CrossWire Bible Society (c) 2003 and CrossWire Bible Society hereby grants a general public license to use this text for any purpose.\par Inquiries and comments may be directed to:\par\par CrossWire Bible Society\par kjv2003@crosswire.org\par http://www.crosswire.org
Some fields allow multiple lines using \ to escape the newline:
:About=This is the King James Version of the Holy Bible (also known as the Authorized Version) with embedded Strong's Numbers. The rights to the base text are held by the Crown of England. The Strong's numbers in the OT were obtained from The Bible Foundation: http://www.bf.org. The NT Strong's data was obtained from The KJV2003 Project at CrossWire: http://www.crosswire.org. These mechanisms provide a useful means for looking up the exact original language word in a lexicon that is keyed to Strong's numbers. \
: \
:Special thanks to the volunteers at Bible Foundation for keying the Hebrew/English data and of Project KJV2003 for working toward the completion of synchronizing the English phrases to the Stephanas Textus Receptus, and to Dr. Maurice Robinson for providing the base Greek text with Strong's and Morphology. We are also appreciative of formatting markup that was provided by Michael Paul Johnson at http://www.ebible.org. Their time and generosity to contribute such for the free use of the Body of Christ is a great blessing and this derivative work could not have been possible without these efforts of so many individuals. It is in this spirit that we in turn offer the KJV2003 Project text freely for any purpose. Any copyright that might be obtained for this effort is held by CrossWire Bible Society (c) 2003 and CrossWire Bible Society hereby grants a general public license to use this text for any purpose. \
: Inquiries and comments may be directed to: \
: \
:CrossWire Bible Society \
:kjv2003@crosswire.org \
:http://www.crosswire.org

=== Common mistakes ===
Using Latin-1 or CP1252 when:
: Encoding=UTF-8

Having a [http://en.wikipedia.org/wiki/Byte_order_mark Byte Order Mark (BOM)] at the beginning of the file<ref>Windows Notepad and Wordpad may silently add these to the file</ref>
: U+FEFF
: [KJV]

Repeating the same element with the same value:
: Lang=en
: ...
: Lang=en

Repeating the same element with different values, when the element doesn't allow repeats:
: Lang=en
: Lang=de

Not supplying a value:
: About=
Only the field CipherKey allows this.

Having a continuation marker on the last line, causing the next key=value to be appended to the prior field.:
: this is text that continues from the prior line \
: Lang=en

'''Notes:'''
<references/>

=== 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 . 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 below for details.

For example, to give a French description, you can have a field:
: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.

'''Notes''':
# 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 front-end support for it.
# See also [[Localized Language Names]].

== Key elements of a SWORD module.conf ==
Below is a listing of the possible directives in that file.

Some keys can be repeated. Don't repeat ones that can't. One or more of them will be ignored.

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. Don't use it otherwise. It will produce different results in different front ends.

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.

Configuration elements not defined in this page are assumed to be ignored by most front-end applications.

===Required Elements===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| [ModName]
| Each conf file begins with [ModName], replacing "ModName" with a short well known abbreviation for the module (e.g., [KJV]). 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! An invalid ModName can cause some front-ends to crash.</ref> 
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, [MyModule] would be mymodule.conf.
|  
|  
|-
| Abbreviation<ref>We strongly advise to avoid using an Abbreviation that's identical to the ModName or Abbreviation of any other module. It only leads to confusion, and may have unexpected consequences for some front-ends.</ref>
|
'''<string>''' 
This field allows for the localization of the ModName. It is meant to be short just like the ModName.

''Actually, this element is not required, but it makes the most sense to describe it here.''
| [ModName]
| [[DevTools:conf Files#Localization|Localization]]
|-
| Description
|
'''<string>''' 
This is a short (1 line) title of the module.
|  
| [[DevTools:conf Files#Localization|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<ref>Daily devotionals & glossaries go in subdirectories under lexdict. A glossary is between two languages.</ref>, 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)<ref name="text4">e.g. If the Bible contains large introduction sections</ref> 
'''zText''' (for compressed Bibles) 
'''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> 
'''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)<ref name="sv">zText4 & zCom4 modules require SwordVersion=1.8 or later.</ref> 
'''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)
|  
|  
|}

<references />

===Required Elements with defaults ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| SourceType<ref>Omitting this for a non-plaintext module has unpredictable effects.</ref>
|
'''Plaintext''' 
'''GBF''' ([http://www.ebible.org/bible/gbf.htm General Bible Format]) 
'''ThML''' ([http://www.ccel.org/ThML Theological Markup Language]) 
'''OSIS''' ([http://www.bibletechnologies.net Open Scriptural Information Standard]) 
'''TEI''' ([http://www.tei-c.org 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. 
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
|
'''Latin-1'''&dagger; ([http://en.wikipedia.org/wiki/Windows-1252 Windows Codepage 1252 (cp1252)]) 
'''UTF-8''' 
'''UTF-16''' 
'''SCSU''' ([http://en.wikipedia.org/wiki/Standard_Compression_Scheme_for_Unicode 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 [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.

&dagger;'''Warning: ''' ''"Latin-1" is an ambiguously used term. Latin-1 is regularly used as a synonym for [http://en.wikipedia.org/wiki/ISO_8859-1 ISO-8859-1]. Here it means Windows Codepage 1252, a superset of ISO-8859-1. Front-end implementors should use "cp1252" or "windows1252" explicitly, not "Latin-1" provided by some programming language libraries.''
| Latin-1
|  
|-
| CompressType
|
'''ZIP''' 
'''LZSS''' ([http://en.wikipedia.org/wiki/Lempel%E2%80%93Ziv%E2%80%93Storer%E2%80%93Szymanski 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
|
'''Catholic''' 
'''Catholic2''' 
'''German''' 
'''KJV''' 
'''KJVA''' 
'''LXX''' 
'''Leningrad''' 
'''Luther''' 
'''MT''' 
'''NRSV''' 
'''NRSVA''' 
'''Orthodox''' 
'''Synodal''' 
'''SynodalProt''' 
'''Vulg''' 
Used to specify the versification employed by a Bible module. 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
|  
|}

<references />

=== Elements required for proper rendering ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| GlobalOptionFilter
|
'''GBFStrongs''' (For GBF texts having Strong's Numbers)<ref name="strongs">See https://en.wikipedia.org/wiki/Strong%27s_Concordance#Strong.27s_numbers</ref> 
'''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)<ref name="red">See https://en.wikipedia.org/wiki/Red_letter_edition</ref> 
'''ThMLStrongs''' (For THML texts having Strong's Numbers)<ref name="strongs">See https://en.wikipedia.org/wiki/Strong%27s_Concordance#Strong.27s_numbers</ref> 
'''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) 
'''UTF8Cantillation''' (For Hebrew texts having cantillation marks)<ref>See https://en.wikipedia.org/wiki/Cantillation</ref> 
'''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> 
'''UTF8HebrewPoints''' (For Hebrew texts having vowel points)<ref>See https://en.wikipedia.org/wiki/Niqqud</ref> 
'''UTF8ArabicPoints''' (For Arabic texts having vowel points)<ref>See https://en.wikipedia.org/wiki/Arabic_diacritics</ref> 
'''OSISLemma''' (For OSIS texts having lemmas)<ref>Must precede OSISStrongs.</ref> 
'''OSISMorphSegmentation''' (For OSIS texts having morphological segmentation elements) 
'''OSISStrongs''' (For OSIS texts having Strong's Numbers)<ref name="strongs">See https://en.wikipedia.org/wiki/Strong%27s_Concordance#Strong.27s_numbers</ref> 
'''OSISFootnotes''' (For OSIS texts having informational notes) 
'''OSISScripref''' (For OSIS texts having [[OSIS Bibles#Marking_cross-references_note|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)<ref name="red">See https://en.wikipedia.org/wiki/Red_letter_edition</ref> 
'''OSISGlosses''' (For OSIS texts with glosses)<ref>Minimum SWORD version of 1.7.0 in the module .conf is required for OSISGlosses.</ref> <s>'''OSISRuby''' (For OSIS texts with glosses)</s><ref>Deprecated in 1.7.0. Use OSISGlosses instead.</ref> 
'''OSISXlit''' (For OSIS texts that include transliterated forms)<ref>The Samaritan Pentateuch module SP is an example of using xlit.</ref> 
'''OSISEnum''' (For OSIS texts with enumerated words)<ref>The Samaritan Pentateuch module SP is an example of using enum.</ref> 
'''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> 
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. crossreferences in notes require both the OSISFootnotes and the OSISScriprefs filters enabled.
|  
| 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.<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
|  
|-
| 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 [[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.
|  
|  
|-
| <del>OSISqToTick</del> (deprecated)<ref>For further details, refer to [http://www.crosswire.org/bugs/browse/MOD-188 MOD-188] in CrossWire bugs.</ref>
| This attribute is deprecated in favor of the marker attribute on the q element. E.g.: <pre><q who="Jesus" marker="">....</q></pre> 
<del>true/false</del> 
<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
|  
|-
| 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 modules with Greek morphology expansions) 
'''HebrewParse''' (for 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<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>)
|  
| 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.
|  
|  
|}
<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. 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''' – 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 ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| About
|
'''<string>''' 
A lengthier description and may include copyright, source, etc. information, possibly duplicating information in other elements.
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#RTF|RTF]] [[DevTools:conf Files#Localization|Localization]]
|-
| SwordVersionDate
|
'''<yyyy-mm-dd>''' ([http://en.wikipedia.org/wiki/ISO_8601#Calendar_dates 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>''' 
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 [[DevTools:conf Files#Localization|Localization]]
|-
| MinimumVersion<ref>See http://tracker.crosswire.org/browse/API-201</ref>
|
'''<version string>''' 
Identifies the [[Sword library versions | minimum version]] of the SWORD library required for this module.
| 1.5.1a
|  
|-
| Category
|valign="top"|
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)<ref>'''Essays''' is handled as a subset of '''Generic Books'''.</ref>
|
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 [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.
|  
|  
|-
| Lang
|
'''<Language[-Script]?[-Region]?>''' 
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}/)'': 
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: 
: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}/)'': 
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}/)'' 
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})?/)'': 
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<ref>Many (xulsword compatible) modules in the [[Module Repositories#Institute_for_Bible_Translation|IBT Repository]] make use of this field. See also https://github.com/johnaustindev/osis-converters</ref>
|
'''<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:'''
<references/>

=== Copyright & Licensing related elements ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| Copyright
|
'''<string>''' 
Contains the copyright notice for the work, including the year of copyright and the owner of the copyright.
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightHolder
|
'''<string>''' 
Contains the name of the copyright holder.
|  
| [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightDate
|
'''<yyyy>''' ([http://en.wikipedia.org/wiki/ISO_8601#Years ISO 8601 Year])
|  
| [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightNotes
|
'''<string>'''
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightContactName
|
'''<string>''' 
Contains the name of the copyright holder.
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightContactNotes
|
'''<string>'''
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightContactAddress
|
'''<string>''' 
Contains the mailing address of the copyright holder.
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightContactEmail
|
'''<string>''' 
Contains the email address of the copyright holder, preferably in the form: name at xyz dot com
|  
| [[DevTools:conf Files#Localization|Localization]]
|-
| ShortPromo
|
'''<string>''' 
A link to the home page for the module, perhaps with an encouragement to visit the site.
|  
| HTML Link [[DevTools:conf Files#Localization|Localization]]
|-
| ShortCopyright
|
'''<string>'''
|  
| [[DevTools:conf Files#Localization|Localization]]
|- id="distlic"
| DistributionLicense
|
'''Public Domain''' 
'''Copyrighted''' 
'''Copyrighted; Permission to distribute granted to CrossWire'''<ref>Modules in other repositories may have a different organization name instead of CrossWire.</ref> 
'''Copyrighted; Free non-commercial distribution''' 
'''Copyrighted; Freely distributable''' 
'''Copyrighted; Permission granted to distribute non-commercially in SWORD format''' 
'''[http://www.gnu.org/copyleft/fdl.html GFDL]''' 
'''[http://www.gnu.org/copyleft/gpl.html GPL]''' 
'''Creative Commons: [http://creativecommons.org/licenses/by-nc-nd by-nc-nd]''' 
'''Creative Commons: [http://creativecommons.org/licenses/by-nc-sa by-nc-sa]''' 
'''Creative Commons: [http://creativecommons.org/licenses/by-nc by-nc]''' 
'''Creative Commons: [http://creativecommons.org/licenses/by-nd by-nd]''' 
'''Creative Commons: [http://creativecommons.org/licenses/by-sa by-sa]''' 
'''Creative Commons: [http://creativecommons.org/licenses/by by]''' 
'''Creative Commons: [http://creativecommons.org/publicdomain/zero/1.0/ CC0]''' 

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.
|  
|  
|-
| DistributionNotes
|
'''<string>''' 
Indicates any additional notes about distribution of the module.
|  
| [[DevTools:conf Files#Continuation|Continuation]] [[DevTools:conf Files#Localization|Localization]]
|-
| TextSource
|
'''<string>''' 
Indicates, either in prose (such as "CCEL") or as a URL of the source of the text
|  
| [[DevTools:conf Files#Continuation|Continuation]]
|-
| UnlockURL
|
'''<string>''' 
Contains the URL (a bare URL, not a HTML <a> link) of a web page for unlocking instructions/payment
|  
| URL
|}
'''Note:'''
<references/>

== 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 ==
* [[User:Dmsmith|DMSmith]] has created a script 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].

== Automated generation ==
* For new module submissions to CrossWire, [[User:Refdoc|Refdoc]] now maintains a script that includes the ''automated generation'' of module conf files, given the minimum ''non-automatable'' requirements by the module submitter.

[[Category:Development tools|Conf files]]
[[Category:Localization|Conf files]]
[[Category:Versification|Conf files]]
[[Category:Copyright|Conf files]]

DevTools:conf Files

2013-01-06T16:14:10Z

Scribe:

=Creating a .conf File=
==.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.

Note on RTF, 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.

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.

Configuration elements not defined in this page are assumed to be ignored by most front-end applications.

''Any line that starts with a semicolon should be ignored by front-end applications, and treated as a remark or comment line''.

===Required Elements===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| [name]
| Each conf file begins with [name], replacing "name" with a short well known abbreviation for the module (e.g., [KJV]). This must be first in the file. Valid characters for this abbreviation are limited to A-Z, a-z, 0-9 and _. 
The .conf file should be named the lowercase of this abbreviation followed by .conf. For example, [MyModule] would be mymodule.conf.
|  
|  
|-
| 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 for a module named [mymodule], depending on the type of module (Bible text, commentary, lexcon or dictionary, general book) and the data driver used are:

:./modules/texts/rawtext/mymodule/

:./modules/texts/ztext/mymodule/

:./modules/comments/zcom/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

|  
|  
|-
| Description
| <string> 
This is a short (1 line) title of the module.<ref>If a continuation line is really needed, some front-ends may support the HTML break element </ref>
|  
|  
|-
| ModDrv
| RawText (for uncompressed Bibles) zText (for compressed Bibles) RawCom (for uncompressed Commentaries) RawCom4 (for uncompressed Commentaries having entries greater than 32K bytes) zCom (for compressed Commentaries) 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 32K bytes) zLD (for compressed Dictionaries) RawGenBook (for uncompressed tree keyed modules)
|  
|  
|}

<references />
===Elements to indicate features ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| CompressType
| ZIP [http://en.wikipedia.org/wiki/Lempel%E2%80%93Ziv%E2%80%93Storer%E2%80%93Szymanski LZSS]
Used to indicate how a compressed module (zText, zCom, zLD) is compressed.
ZIP is the preferred format.
| LZSS
|  
|-
| BlockType
| BOOK CHAPTER VERSE 
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.
| CHAPTER
|  
|-
| BlockCount
| <integer> 
Used for zLD to indicate the number of entries in a compressed block. Higher values will make the module slower, but smaller.
| 200
|  
|-
| 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. See below.
| TreeKey
|  
|-
| CipherKey
| <string> 
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.)
|  
|  
|-
| Versification<ref> Used to specify the versification employed by a Bible module. Refer to [[Alternate Versification]].</ref>
|Catholic Catholic2 German KJV KJVA Leningrad Luther MT NRSV NRSVA Synodal SynodalP Vulg
| KJV
|  
|-
| <del>Scope</del> (proposed)
| <osisRef><ref>Use OSIS Book names. Book, chapter and verse are separated by '.', dot. Ranges are with respect to the order of books in the v11n. Both ends of a range must be fully specified. Ranges are separated by spaces. While order in an osisRef is undefined, they should be ordered here.</ref> Indicates that the versification is limited to subset of its books, chapters and/or verses.

When there are only a few verses different within a chapter, it may be permissible to include them. But where there are many, do so.

Examples: To leave out deuterocanonical material from Synodal use the following: Gen-Josh.4.33 Judg-2Chr Ezra Neh Esth-Ps.150 Prov.0<ref>When used in a verse range, the start of a book is chapter 0, the introduction. If the book has no introduction then Prov.1 is fine.</ref>-Prov.4.27 Prov.5-Prov.13.25 Prov.14-Prov.18.24 Prov.19-Song Isa-Lam Ezek-Dan.3.33 Dan.4-Dan.12 Hos-Mal Matt-Rev

To note that a module only contains the NT, the following would be appropriate for many v11n: Matt-Rev<ref>At the moment, there is no way to specify the inclusion of module or testament introductions. JSword (in development) is using Intro.Bible, Intro.OT and Intro.NT.</ref>
|  
|  
|}
<references />

=== Elements required for proper rendering ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| GlobalOptionFilter
| GBFStrongs (For GBF texts having Strong's Numbers) 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) ThMLStrongs (For THML texts having Strong's Numbers) 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) UTF8Cantillation (For Hebrew texts having cantillation marks) UTF8GreekAccents (For Greek texts having accents) UTF8HebrewPoints (For Hebrew texts having vowel points) OSISStrongs (For OSIS texts having Strong's Numbers) 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) OSISLemma (For OSIS texts having lemmas) OSISRuby (For OSIS texts with glosses) OSISXlit (For OSIS texts that include transliterated forms) OSISEnum (For OSIS texts with enumerated words)
Each of these filters removes/hides the text's feature, when activated by the application.
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. crossreferences in notes require both the OSISFootnotes and the OSISScriprefs filters enabled.
|  
| Repeats
|-
| Direction
| LtoR (Left to Right) RtoL (Right to Left) 
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
|  
|-
| SourceType
| Plaintext GBF General Bible Format: http://www.ebible.org/bible/gbf.htm ThML Theological Markup Language: http://www.ccel.org/ThML OSIS Open Scriptural Information Standard: http://www.bibletechnologies.net TEI Text Encoding Initiative: http://www.tei-c.org/ 
Specifies the markup used in the module. The preferred markup is OSIS. TEI is preferred for dictionaries until OSIS supports dictionaries. 
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 Latin-1 (cp1252; see the warning) 
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.
Warning: "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. Front-end implementors should use "cp1252" or "windows1252" explicitly, not "Latin-1" provided by some programming language libraries.
| Latin-1
|  
|-
| 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. 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.
|  
|  
|-
| <del>OSISqToTick</del> (deprecated)<ref>For further details, refer to [http://www.crosswire.org/bugs/browse/MOD-188 MOD-188] in CrossWire bugs.</ref>
| This attribute is deprecated in favor of the marker attribute on the q element. E.g.: <pre><q who="Jesus" marker="">....</q></pre> 
<del>true/false</del> 
<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
|  
|-
| Feature
| StrongsNumbers (for modules that include Strong's numbers) GreekDef (for modules with Strong's number encoded Greek definitions) HebrewDef (for modules with Strong's number encoded Hebrew definitions) GreekParse (for modules with Greek morphology expansions) HebrewParse (for 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)
|  
| Repeats
|-
| GlossaryFrom
| <xml: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
| <xml: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.
|  
|  
|}
<references />

=== Optional elements to support particular features ===
==== 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.

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".<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 ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| Abbreviation
| <string> 
A shorter abbreviation which can be displayed instead of the full name. For example, KJV for the King James Version.
| The module name.
|  
|-
| About
| <string> 
A lengthier description and may include copyright, source, etc. information, possibly duplicating information in other elements.
|  
| Continuation RTF
|-
| 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 or 1.1.3.
| 1.0
|  
|-
| History_x.x
| <string> 
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.
|  
| Repeats
|-
| MinimumVersion
| <version string> 
Identifies the minimum version of the SWORD library required for this module.
| 1.5.1a
|  
|-
| Category
| Daily Devotional (for modules with Feature=DailyDevotion) Glossaries (for modules with Feature=Glossary) Cults / Unorthodox / Questionable Material Essays (for essays) Maps (for modules that primarily consist of maps) Images (for modules that primarily consist of images) Biblical Texts (for Bibles) Commentaries Lexicons / Dictionaries Generic Books (for anything else....) 
This is used by installers to further categorize the modules beyond what can be figured out by the ModDrv and Feature.
| Biblical Texts (for /(Raw|z)Text4?/) 
Commentaries (for /(Raw|z|HREF)Com4?/) 
Lexicons / Dictionaries (for /(Raw|z)LD4?/ 
Generic Books (for RawGenBook)
|  
|-
| LCSH
| <tree/string> 
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.
|  
|  
|-
| Lang
| <xml:lang identifier> 
This is the primary language code of the module and should include a value according to BCP 47 (i.e. [http://tools.ietf.org/html/rfc4646 RFC 4646] & [http://tools.ietf.org/html/rfc4647 RFC 4647]). When available use a 2-letter code from [http://en.wikipedia.org/wiki/ISO_639-1 ISO 639-1 codes] ([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] (e.g. ceb for Cebuano) ([http://www.loc.gov/standards/iso639-2/php/code_list.php registrar]). Failing that, use [http://en.wikipedia.org/wiki/ISO_639-3 ISO 639-3] ([http://www.sil.org/iso639-3/codes.asp registrar]), which covers over 7000 languages, or [http://en.wikipedia.org/wiki/ISO_639-5 ISO 639-5] ([http://www.loc.gov/standards/iso639-5/id.php registrar]) for macrolanguages. The regex for this subtag will be /[a-z]{2,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 [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). The regex for this subtag will be /[A-Z][a-z]{3}/.

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). The regex for this subtag will be /[A-Z]{2}/

Individual subtags (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. Private use extensions defined by BCP 47 (e.g. x-, qaa, and Qaaa) should be avoided wherever possible.
| en
|  
|-
| InstallSize<ref>This item in generated automatically within CrossWire by the script used to prepare modules for hosting in our repositories.</ref>
| <integer (indicating bytes)><ref>Excludes the size of any Lucene index.</ref>
|  
|  
|-
| SwordVersionDate
| <ISO date string (yyyy-mm-dd)>
Indicates the date that the module was changed.
|  
|  
|-
| Obsoletes
| <name of module> 
Each instance of this element names a module that is made obsolete by this module, usually indicated by the former name of the module.
|  
| Repeats
|-
| OSISVersion
| <version string><ref>e.g. OSISVersion=2.1.1</ref> 
Identifies the OSIS schema version employed in the OSIS source document.
|  
|
|}
<references />

=== Copyright & Licensing related elements ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| Copyright
| <string> 
Contains the copyright notice for the work, including the year of copyright and the owner of the copyright.
|  
| Continuation
|-
| CopyrightHolder
| <string> 
Contains the name of the copyright holder.
|  
|  
|-
| CopyrightDate
| <integer (indicating year)>
|  
|  
|-
| CopyrightNotes
| <string>
|  
| Continuation
|-
| CopyrightContactName
| <string> 
Contains the name of the copyright holder.
|  
| Continuation
|-
| CopyrightContactNotes
| <string>
|  
| Continuation
|-
| CopyrightContactAddress
| <string> 
Contains the mailing address of the copyright holder.
|  
| Continuation
|-
| CopyrightContactEmail
| <string> 
Contains the email address of the copyright holder, preferably in the form: name at xyz dot com.
|  
|  
|-
| ShortPromo
| <string> 
A link to the home page for the module, perhaps with an encouragement to visit the site.
|  
| HTML Link
|-
| ShortCopyright
| <string>
|  
|  
|-
| DistributionLicense
| Public Domain Copyrighted Copyrighted; Permission to distribute granted to CrossWire Copyrighted; Free non-commercial distribution Copyrighted; Freely distributable Copyrighted; Permission granted to distribute non-commercially in SWORD format [http://www.gnu.org/copyleft/fdl.html GFDL] [http://www.gnu.org/copyleft/gpl.html GPL] Creative Commons: [http://creativecommons.org/licenses/by-nc-nd by-nc-nd] Creative Commons: [http://creativecommons.org/licenses/by-nc-sa by-nc-sa] Creative Commons: [http://creativecommons.org/licenses/by-nc by-nc] Creative Commons: [http://creativecommons.org/licenses/by-nd by-nd] Creative Commons: [http://creativecommons.org/licenses/by-sa by-sa] Creative Commons: [http://creativecommons.org/licenses/by by] Creative Commons: [http://creativecommons.org/publicdomain/zero/1.0/ CC0] 
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.
|  
|  
|-
| DistributionNotes
| <string> 
Indicates any additional notes about distribution of the module.
|  
| Continuation
|-
| TextSource
| <string, probably a URL> 
Indicates, either in prose (such as "CCEL") or as a URL of the source of the text
|  
| Continuation
|-
| UnlockURL
| <string> 
Contains the URL (a bare URL, not an HTML <a> link) of a web page for unlocking instructions/payment
|  
| URL
|}

== Uniqueness ==
For comparing two versions of a module during module development, the module names and locations must be unique. For Bible Desktop, there is a further requirement, the Description items must be different.

== 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 above for details.

For example, to give a French description, you can have a field:
: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.

'''Notes''':
# 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.
# See also [[Localized Language Names]].

[[Category:Development tools|Conf files]]
[[Category:Localization|Conf files]]
[[Category:Versification|Conf files]]
[[Category:Copyright|Conf files]]

DevTools:conf Files

2013-01-06T16:12:32Z

Scribe:

=Creating a .conf File=
==.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.

Note on RTF, 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.

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.

Configuration elements not defined in this page are assumed to be ignored by most front-end applications.

''Any line that starts with a semicolon should be ignored by front-end applications, and treated as a remark or comment line''.

===Required Elements===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| [name]
| Each conf file begins with [name], replacing "name" with a short well known abbreviation for the module (e.g., [KJV]). This must be first in the file. Valid characters for this abbreviation are limited to A-Z, a-z, 0-9 and _. 
The .conf file should be named the lowercase of this abbreviation followed by .conf. For example, [MyModule] would be mymodule.conf.
|  
|  
|-
| 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 for a module named [mymodule], depending on the type of module (Bible text, commentary, lexcon or dictionary, general book) and the data driver used are:

:./modules/texts/rawtext/mymodule/

:./modules/texts/ztext/mymodule/

:./modules/comments/zcom/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

|  
|  
|-
| Description
| <string> 
This is a short (1 line) title of the module.<ref>If a continuation line is really needed, some front-ends may support the HTML break element </ref>
|  
|  
|-
| ModDrv
| RawText (for uncompressed Bibles) zText (for compressed Bibles) RawCom (for uncompressed Commentaries) RawCom4 (for uncompressed Commentaries having entries greater than 32K bytes) zCom (for compressed Commentaries) 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 32K bytes) zLD (for compressed Dictionaries) RawGenBook (for uncompressed tree keyed modules)
|  
|  
|}

<references />
===Elements to indicate features ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| CompressType
| ZIP [http://en.wikipedia.org/wiki/Lempel%E2%80%93Ziv%E2%80%93Storer%E2%80%93Szymanski LZSS]
Used to indicate how a compressed module (zText, zCom, zLD) is compressed.
ZIP is the preferred format.
| LZSS
|  
|-
| BlockType
| BOOK CHAPTER VERSE 
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.
| CHAPTER
|  
|-
| BlockCount
| <integer> 
Used for zLD to indicate the number of entries in a compressed block. Higher values will make the module slower, but smaller.
| 200
|  
|-
| 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. See below.
| TreeKey
|  
|-
| CipherKey
| <string> 
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.)
|  
|  
|-
| Versification<ref> Used to specify the versification employed by a Bible module. Refer to [[Alternate Versification]].</ref>
|Catholic Catholic2 German KJV KJVA Leningrad Luther MT NRSV NRSVA Synodal SynodalP Vulg
| KJV
|  
|-
| <del>Scope</del> (proposed)
| <osisRef><ref>Use OSIS Book names. Book, chapter and verse are separated by '.', dot. Ranges are with respect to the order of books in the v11n. Both ends of a range must be fully specified. Ranges are separated by spaces. While order in an osisRef is undefined, they should be ordered here.</ref> Indicates that the versification is limited to subset of its books, chapters and/or verses.

When there are only a few verses different within a chapter, it may be permissible to include them. But where there are many, do so.

Examples: To leave out deuterocanonical material from Synodal use the following: Gen-Josh.4.33 Judg-2Chr Ezra Neh Esth-Ps.150 Prov.0<ref>When used in a verse range, the start of a book is chapter 0, the introduction. If the book has no introduction then Prov.1 is fine.</ref>-Prov.4.27 Prov.5-Prov.13.25 Prov.14-Prov.18.24 Prov.19-Song Isa-Lam Ezek-Dan.3.33 Dan.4-Dan.12 Hos-Mal Matt-Rev

To note that a module only contains the NT, the following would be appropriate for many v11n: Matt-Rev<ref>At the moment, there is no way to specify the inclusion of module or testament introductions. JSword (in development) is using Intro.Bible, Intro.OT and Intro.NT.</ref>
|  
|  
|}
<references />

=== Elements required for proper rendering ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| GlobalOptionFilter
| GBFStrongs (For GBF texts having Strong's Numbers) 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) ThMLStrongs (For THML texts having Strong's Numbers) 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) UTF8Cantillation (For Hebrew texts having cantillation marks) UTF8GreekAccents (For Greek texts having accents) UTF8HebrewPoints (For Hebrew texts having vowel points) OSISStrongs (For OSIS texts having Strong's Numbers) 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) OSISLemma (For OSIS texts having lemmas) OSISRuby (For OSIS texts with glosses) OSISXlit (For OSIS texts that include transliterated forms) OSISEnum (For OSIS texts with enumerated words)
Each of these filters removes/hides the text's feature, when activated by the application.
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. crossreferences in notes require both the OSISFootnotes and the OSISScriprefs filters enabled.
|  
| Repeats
|-
| Direction
| LtoR (Left to Right) RtoL (Right to Left) 
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
|  
|-
| SourceType
| Plaintext GBF General Bible Format: http://www.ebible.org/bible/gbf.htm ThML Theological Markup Language: http://www.ccel.org/ThML OSIS Open Scriptural Information Standard: http://www.bibletechnologies.net TEI Text Encoding Initiative: http://www.tei-c.org/ 
Specifies the markup used in the module. The preferred markup is OSIS. TEI is preferred for dictionaries until OSIS supports dictionaries. 
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 Latin-1 (cp1252; see the warning) 
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.
Warning: "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. Front-end implementors should use "cp1252" or "windows1252" explicitly, not "Latin-1" provided by some programming language libraries.
| Latin-1
|  
|-
| 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. 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.
|  
|  
|-
| <del>OSISqToTick</del> (deprecated)<ref>For further details, refer to [http://www.crosswire.org/bugs/browse/MOD-188 MOD-188] in CrossWire bugs.</ref>
| This attribute is deprecated in favor of the marker attribute on the q element. E.g.: <pre><q who="Jesus" marker="">....</q></pre> 
<del>true/false</del> 
<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
|  
|-
| Feature
| StrongsNumbers (for modules that include Strong's numbers) GreekDef (for modules with Strong's number encoded Greek definitions) HebrewDef (for modules with Strong's number encoded Hebrew definitions) GreekParse (for modules with Greek morphology expansions) HebrewParse (for 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)
|  
| Repeats
|-
| GlossaryFrom
| <xml: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
| <xml: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.
|  
|  
|}
<references />

=== Optional elements to support particular features ===
==== 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.

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".<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 ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| Abbreviation
| <string> 
A shorter abbreviation which can be displayed instead of the full name. For example, KJV for the King James Version.
| The module name.
|  
|-
| About
| <string> 
A lengthier description and may include copyright, source, etc. information, possibly duplicating information in other elements.
|  
| Continuation RTF
|-
| 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 or 1.1.3.
| 1.0
|  
|-
| History_x.x
| <string> 
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.
|  
| Repeats
|-
| MinimumVersion
| <version string> 
Identifies the minimum version of the SWORD library required for this module.
| 1.5.1a
|  
|-
| Category
| Daily Devotional (for modules with Feature=DailyDevotion) Glossaries (for modules with Feature=Glossary) Cults / Unorthodox / Questionable Material Essays (for essays) Maps (for modules that primarily consist of maps) Images (for modules that primarily consist of images) Biblical Texts (for Bibles) Commentaries Lexicons / Dictionaries Generic Books (for anything else....) 
This is used by installers to further categorize the modules beyond what can be figured out by the ModDrv and Feature.
| Biblical Texts (for /(Raw|z)Text4?/) 
Commentaries (for /(Raw|z|HREF)Com4?/) 
Lexicons / Dictionaries (for /(Raw|z)LD4?/ 
Generic Books (for RawGenBook)
|  
|-
| LCSH
| <tree/string> 
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.
|  
|  
|-
| Lang
| <xml:lang identifier> 
This is the primary language code of the module and should include a value according to BCP 47 (i.e. [http://tools.ietf.org/html/rfc4646 RFC 4646] & [http://tools.ietf.org/html/rfc4647 RFC 4647]). When available use a 2-letter code from [http://en.wikipedia.org/wiki/ISO_639-1 ISO 639-1 codes] ([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] (e.g. ceb for Cebuano) ([http://www.loc.gov/standards/iso639-2/php/code_list.php registrar]). Failing that, use [http://en.wikipedia.org/wiki/ISO_639-3 ISO 639-3] ([http://www.sil.org/iso639-3/codes.asp registrar]), which covers over 7000 languages, or [http://en.wikipedia.org/wiki/ISO_639-5 ISO 639-5] ([http://www.loc.gov/standards/iso639-5/id.php registrar]) for macrolanguages. The regex for this subtag will be /[a-z]{2,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 [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). The regex for this subtag will be /[A-Z][a-z]{3}/.

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). The regex for this subtag will be /[A-Z]{2}/

Individual subtags (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. Private use extensions defined by BCP 47 (e.g. x-, qaa, and Qaaa) should be avoided wherever possible.
| en
|  
|-
| InstallSize<ref>This item in generated automatically within CrossWire by the script used to prepare modules for hosting in our repositories.</ref>
| <integer (indicating bytes)><ref>Excludes the size of any Lucene index.</ref>
|  
|  
|-
| SwordVersionDate
| <ISO date string (yyyy-mm-dd)>
Indicates the date that the module was changed.
|  
|  
|-
| Obsoletes
| <name of module> 
Each instance of this element names a module that is made obsolete by this module, usually indicated by the former name of the module.
|  
| Repeats
|-
| OSISVersion
| <version string><ref>e.g. OSISVersion=2.1.1</ref> 
Identifies the OSIS schema version employed in the OSIS source document.
|  
|
|}
<references />

=== Copyright & Licensing related elements ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| Copyright
| <string> 
Contains the copyright notice for the work, including the year of copyright and the owner of the copyright.
|  
| Continuation
|-
| CopyrightHolder
| <string> 
Contains the name of the copyright holder.
|  
|  
|-
| CopyrightDate
| <integer (indicating year)>
|  
|  
|-
| CopyrightNotes
| <string>
|  
| Continuation
|-
| CopyrightContactName
| <string> 
Contains the name of the copyright holder.
|  
| Continuation
|-
| CopyrightContactNotes
| <string>
|  
| Continuation
|-
| CopyrightContactAddress
| <string> 
Contains the mailing address of the copyright holder.
|  
| Continuation
|-
| CopyrightContactEmail
| <string> 
Contains the email address of the copyright holder, preferably in the form: name at xyz dot com.
|  
|  
|-
| ShortPromo
| <string> 
A link to the home page for the module, perhaps with an encouragement to visit the site.
|  
| HTML Link
|-
| ShortCopyright
| <string>
|  
|  
|-
| DistributionLicense
| Public Domain Copyrighted Copyrighted; Permission to distribute granted to CrossWire Copyrighted; Free non-commercial distribution Copyrighted; Freely distributable Copyrighted; Permission granted to distribute non-commercially in SWORD format [http://www.gnu.org/copyleft/fdl.html GFDL] [http://www.gnu.org/copyleft/gpl.html GPL] Creative Commons: [http://creativecommons.org/licenses/by-nc-nd by-nc-nd] Creative Commons: [http://creativecommons.org/licenses/by-nc-sa by-nc-sa] Creative Commons: [http://creativecommons.org/licenses/by-nc by-nc] Creative Commons: [http://creativecommons.org/licenses/by-nd by-nd] Creative Commons: [http://creativecommons.org/licenses/by-sa by-sa] Creative Commons: [http://creativecommons.org/licenses/by by] Creative Commons: [http://creativecommons.org/publicdomain/zero/1.0/ CC0] 
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.
|  
|  
|-
| DistributionNotes
| <string> 
Indicates any additional notes about distribution of the module.
|  
| Continuation
|-
| TextSource
| <string, probably a URL> 
Indicates, either in prose (such as "CCEL") or as a URL of the source of the text
|  
| Continuation
|-
| UnlockURL
| <string> 
Contains the URL (a bare URL, not an HTML <a> link) of a web page for unlocking instructions/payment
|  
| URL
|}

== Uniqueness ==
For comparing two versions of a module during module development, the module names and locations must be unique. For Bible Desktop, there is a further requirement, the Description items must be different.

== 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 above for details.

For example, to give a French description, you can have a field:
: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.

'''Notes''':
# 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.
# See also [[Localized Language Names]].

[[Category:Development tools|Conf files]]
[[Category:Localization|Conf files]]
[[Category:Versification|Conf files]]
[[Category:Copyright|Conf files]]

DevTools:Code Examples

2012-02-21T08:37:09Z

Scribe:

[[Category:Development tools]]

This page was started to provoke developers who know how the SWORD API works to post simple, everyday code examples that anyone can use.

Be sure to first see the age old, always up to date, ever growing, and very helpful [http://crosswire.org/svn/sword/trunk/examples/ examples/ folder] in the source code distribution.
The [http://crosswire.org/svn/sword/trunk/utilities/ /utilities/] and [http://crosswire.org/svn/sword/trunk/tests /tests/] folders are also very informative and provide concise code examples.

== Examples ==

=== C++ ===

Be sure to first see the age old, always up to date, ever growing, and very helpful [http://crosswire.org/svn/sword/trunk/examples/ examples/ folder] in the source code distribution.
The [http://crosswire.org/svn/sword/trunk/utilities/ /utilities/] and [http://crosswire.org/svn/sword/trunk/tests /tests/] folders are also very informative and provide concise code examples.

==== Get Modules Example(s) ====
The following example is for obtaining modules that are installed in the user's SWORD repository. The following function takes one parameter, the type of the modules you want to retrieve. It is defaulted to retrieve only Bibles.

===== Code =====
<pre>
#include <string>
#include <vector>
#include <swmgr.h>
#include <swmodule.h>

using namespace sword;
using namespace std;

vector<string> getModuleNames(const char *modType = SWMgr::MODTYPE_BIBLES) {
vector <string> modules;
SWMgr library;
ModMap::iterator it;
for (it = library.Modules.begin(); it != library.Modules.end(); ++it) {
SWModule *module = (*it).second;
if (!strcmp(module->getType(), modType)) {
modules.push_back(module->getName());
}
}
return modules;
}
</pre>
====== Example Usage ======
<pre>
list<string> bibles = getModuleNames(SWMgr::MODTYPE_COMMENTARIES);
</pre>
Modules contain features. If looking for a feature of a module, one can query with:
<pre>
if (module->getConfig().has("Feature", "Images")
// do something ...
</pre>
----

==== Get Biblical Book Names Example(s) ====
This example isn't completely accurate nor is it desireable to point users to internal implementations which may change. The [Text] section of a locales.d/ file is meant to include any i18n string, not just Bible book names-- though that's likely all we have in most (all?) localization files at the moment. Other internal strings in the engine are meant to be localized there. Better example to get Biblical Names using SWORD (as stated later):

VerseKey vk;
while (!vk.Error()) {
cout << vk.getBookName();
vk.setBook(vk.getBook()+1);
}

Obtaining a list of the canonical books of the Bible doesn't necessarily require any SWORD classes (though in the following example we'll be using [http://www.crosswire.org/~ghellings/svnclassdocs/classSWConfig.html SWConfig]). A default SWORD installation installs the file <tt>abbr.conf</tt> at <tt>/usr/share/sword/locales.d</tt> on a Unix-like system (on Windows it may be located at <tt>C:\Program Files\CrossWire\The SWORD Project\locales.d</tt>). The syntax of the file is the same as any INI file. Therefore we just need to parse the file for the canonical books; so technically any configuration file parser that can parse INI files will do. The section we want to obtain from <tt>abbr.conf</tt> is called <tt>Text</tt>. (Again, the example uses a Qt4 class, [http://doc.trolltech.com/4.5/qstringlist.html QStringList].)

===== Code #1 =====
<pre>
#include <QStringList>
#include <swconfig.h>

QStringList getBiblicalBooks()
{
QStringList books;
SWConfig config("/usr/share/sword/locales.d/abbr.conf");
ConfigEntMap::iterator it;
for (it = config["Text"].begin(); it != config["Text"].end(); it++)
{
books << (*it).first.c_str();
}

return books;
}
</pre>

After obtaining all the Bible book names, you can obtain their abbreviations with [http://www.crosswire.org/~ghellings/svnclassdocs/classSWConfig.html SWConfig], again:
<pre>
SWConfig config("/usr/share/sword/locales.d/abbr.conf");
const char *GenAbbr = config["Text"]["Genesis"];
</pre>

But, of course, since it's not necessarily safe to assume that you would have an abbr.conf file lying around, the above example isn't necessarily practical. Nevertheless, hopefully, its existence provided some insight on [http://www.crosswire.org/~ghellings/svnclassdocs/classSWConfig.html SWConfig]. The more proper way to obtain a list of Biblical, canonical book names is through the use of [http://www.crosswire.org/~ghellings/svnclassdocs/classVerseKey.html VerseKey]. VerseKey has a public member that stores the number of books for each testament—BMAX. BMAX[0] has the number of Old Testament books, and BMAX[1] has the number of New Testament books, which will be useful for use in a <tt>for</tt> loop.

===== Code #2 =====
<pre>
QStringList getBiblicalBooks()
{
QStringList books;
VerseKey vk;
for (int b = 0; b < 2; b++)
{
// Set the Testament number to retrieve book names from that Testament.
// Add 1 to b since the Testament numbers don't start at 0.
vk.setTestament(b+1);
for (int i = 0; i < vk.BMAX[b]; i++)
{
// Add 1 to i since the book numbers don't start at 0.
vk.setBook(i+1);
books << vk.getBookName();
}
}
return books;
}
</pre>
----

==== Getting Generic Book Table of Contents ====

[http://www.crosswire.org/~ghellings/svnclassdocs/classTreeKey.html TreeKey] is necessary for traversing the generic book's tree. I am going to let the comments and function names speak for themselves here. Assume that <tt>module</tt> points to a [http://www.crosswire.org/~ghellings/svnclassdocs/classSWModule.html SWModule] object.
<pre>
#include <swmodule.h>
#include <treekey.h>

void getGenBookTOC(sword::TreeKey *tk, Class *parent)
{
// if no TreeKey, then obtain one from the module
if (!tk)
tk = dynamic_cast<sword::TreeKey*>(module->getKey());

// Move onto the first child if any
if (tk->firstChild())
{
// Get the first child's information before moving onto the next
do
{
// Retrieve the name so we can use it to get
// the GenBook's content later
QString text = tk->getText();
// Keep track of the information for custom implementation
Class *item = storeItemInfoForLaterUse(parent, text);

// If it has children, dive into it
if (tk->hasChildren())
getGenBookTOC(tk, item);
}
// Move onto the next child if any
while (tk->nextSibling());
// Move up one level in case one of the children had children
tk->parent();
}
}
</pre>
How you go about in implementing this is up to you.

[[Category:Genbook]]

==== Install Manager ====

The [http://www.crosswire.org/~ghellings/svnclassdocs/classInstallMgr.html InstallMgr] class is pretty easy to work with and will manage most of the install sources itself. When instantiated, it will generate the list of sources (which can later be accessed from its public attribute, <tt>sources</tt>) from the InstallMgr.conf located at the path provided in the constructor's first paramater, <tt>privatePath</tt>, if any. If no InstallMgr.conf exists, you can use the method <tt>refreshRemoteSourceConfiguration()</tt> to retrieve a list of sources remotely. <tt>refreshRemoteSourceConfiguration()</tt> will return 0 upon success. If -1 is returned, you should check to see if <tt>isUserDisclaimerConfirmed()</tt> returns false; <tt>isUserDisclaimerConfirmed()</tt> must return true to get passed the first process when refreshing the remote source.

When working with the InstallMgr class, it will be useful to have a SWMgr object lying around before installing any new modules and refreshing any remote sources. This is so you can provide some additional module information to the user with the help of <tt>InstallMgr::getModuleStatus()</tt>. You rely on the return value of <tt>InstallMgr::getModuleStatus()</tt> to display the list of modules and whether they are new (not installed) (<tt>InstallMgr::MODSTAT_NEW</tt>), already installed (<tt>InstallMgr::MODSTAT_SAMEVERSION</tt>), an update is available (<tt>InstallMgr::MODSTAT_UPDATED</tt>), et cetera.

To install modules you would of course use the method <tt>installModule()</tt>. Local installs make use of only the first three parameters; remote installs make use of the first and last two while passing 0 to the second parameter. Note, the name of the module you want to install is obtained through <tt>SWModule::Name()</tt>. <tt>installModule()</tt> will return 0 on success.

=== Python ===

=== Java ===

DevTools:Code Examples

2012-02-21T08:36:42Z

Scribe:

[[Category:Development tools]]

This page was started to provoke developers who know how the SWORD API works to post simple, everyday code examples that anyone can use.

Be sure to first see the age old, always up to date, ever growing, and very helpful [http://crosswire.org/svn/sword/trunk/examples/ examples/ folder] in the source code distribution.
The [http://crosswire.org/svn/sword/trunk/utilities/ /utilities/] and [http://crosswire.org/svn/sword/trunk/tests /tests/] folders are also very informative and provide concise code examples.

== Examples ==

=== C++ ===

==== Get Modules Example(s) ====
The following example is for obtaining modules that are installed in the user's SWORD repository. The following function takes one parameter, the type of the modules you want to retrieve. It is defaulted to retrieve only Bibles.

===== Code =====
<pre>
#include <string>
#include <vector>
#include <swmgr.h>
#include <swmodule.h>

using namespace sword;
using namespace std;

vector<string> getModuleNames(const char *modType = SWMgr::MODTYPE_BIBLES) {
vector <string> modules;
SWMgr library;
ModMap::iterator it;
for (it = library.Modules.begin(); it != library.Modules.end(); ++it) {
SWModule *module = (*it).second;
if (!strcmp(module->getType(), modType)) {
modules.push_back(module->getName());
}
}
return modules;
}
</pre>
====== Example Usage ======
<pre>
list<string> bibles = getModuleNames(SWMgr::MODTYPE_COMMENTARIES);
</pre>
Modules contain features. If looking for a feature of a module, one can query with:
<pre>
if (module->getConfig().has("Feature", "Images")
// do something ...
</pre>
----

==== Get Biblical Book Names Example(s) ====
This example isn't completely accurate nor is it desireable to point users to internal implementations which may change. The [Text] section of a locales.d/ file is meant to include any i18n string, not just Bible book names-- though that's likely all we have in most (all?) localization files at the moment. Other internal strings in the engine are meant to be localized there. Better example to get Biblical Names using SWORD (as stated later):

VerseKey vk;
while (!vk.Error()) {
cout << vk.getBookName();
vk.setBook(vk.getBook()+1);
}

Obtaining a list of the canonical books of the Bible doesn't necessarily require any SWORD classes (though in the following example we'll be using [http://www.crosswire.org/~ghellings/svnclassdocs/classSWConfig.html SWConfig]). A default SWORD installation installs the file <tt>abbr.conf</tt> at <tt>/usr/share/sword/locales.d</tt> on a Unix-like system (on Windows it may be located at <tt>C:\Program Files\CrossWire\The SWORD Project\locales.d</tt>). The syntax of the file is the same as any INI file. Therefore we just need to parse the file for the canonical books; so technically any configuration file parser that can parse INI files will do. The section we want to obtain from <tt>abbr.conf</tt> is called <tt>Text</tt>. (Again, the example uses a Qt4 class, [http://doc.trolltech.com/4.5/qstringlist.html QStringList].)

===== Code #1 =====
<pre>
#include <QStringList>
#include <swconfig.h>

QStringList getBiblicalBooks()
{
QStringList books;
SWConfig config("/usr/share/sword/locales.d/abbr.conf");
ConfigEntMap::iterator it;
for (it = config["Text"].begin(); it != config["Text"].end(); it++)
{
books << (*it).first.c_str();
}

return books;
}
</pre>

After obtaining all the Bible book names, you can obtain their abbreviations with [http://www.crosswire.org/~ghellings/svnclassdocs/classSWConfig.html SWConfig], again:
<pre>
SWConfig config("/usr/share/sword/locales.d/abbr.conf");
const char *GenAbbr = config["Text"]["Genesis"];
</pre>

But, of course, since it's not necessarily safe to assume that you would have an abbr.conf file lying around, the above example isn't necessarily practical. Nevertheless, hopefully, its existence provided some insight on [http://www.crosswire.org/~ghellings/svnclassdocs/classSWConfig.html SWConfig]. The more proper way to obtain a list of Biblical, canonical book names is through the use of [http://www.crosswire.org/~ghellings/svnclassdocs/classVerseKey.html VerseKey]. VerseKey has a public member that stores the number of books for each testament—BMAX. BMAX[0] has the number of Old Testament books, and BMAX[1] has the number of New Testament books, which will be useful for use in a <tt>for</tt> loop.

===== Code #2 =====
<pre>
QStringList getBiblicalBooks()
{
QStringList books;
VerseKey vk;
for (int b = 0; b < 2; b++)
{
// Set the Testament number to retrieve book names from that Testament.
// Add 1 to b since the Testament numbers don't start at 0.
vk.setTestament(b+1);
for (int i = 0; i < vk.BMAX[b]; i++)
{
// Add 1 to i since the book numbers don't start at 0.
vk.setBook(i+1);
books << vk.getBookName();
}
}
return books;
}
</pre>
----

==== Getting Generic Book Table of Contents ====

[http://www.crosswire.org/~ghellings/svnclassdocs/classTreeKey.html TreeKey] is necessary for traversing the generic book's tree. I am going to let the comments and function names speak for themselves here. Assume that <tt>module</tt> points to a [http://www.crosswire.org/~ghellings/svnclassdocs/classSWModule.html SWModule] object.
<pre>
#include <swmodule.h>
#include <treekey.h>

void getGenBookTOC(sword::TreeKey *tk, Class *parent)
{
// if no TreeKey, then obtain one from the module
if (!tk)
tk = dynamic_cast<sword::TreeKey*>(module->getKey());

// Move onto the first child if any
if (tk->firstChild())
{
// Get the first child's information before moving onto the next
do
{
// Retrieve the name so we can use it to get
// the GenBook's content later
QString text = tk->getText();
// Keep track of the information for custom implementation
Class *item = storeItemInfoForLaterUse(parent, text);

// If it has children, dive into it
if (tk->hasChildren())
getGenBookTOC(tk, item);
}
// Move onto the next child if any
while (tk->nextSibling());
// Move up one level in case one of the children had children
tk->parent();
}
}
</pre>
How you go about in implementing this is up to you.

[[Category:Genbook]]

==== Install Manager ====

The [http://www.crosswire.org/~ghellings/svnclassdocs/classInstallMgr.html InstallMgr] class is pretty easy to work with and will manage most of the install sources itself. When instantiated, it will generate the list of sources (which can later be accessed from its public attribute, <tt>sources</tt>) from the InstallMgr.conf located at the path provided in the constructor's first paramater, <tt>privatePath</tt>, if any. If no InstallMgr.conf exists, you can use the method <tt>refreshRemoteSourceConfiguration()</tt> to retrieve a list of sources remotely. <tt>refreshRemoteSourceConfiguration()</tt> will return 0 upon success. If -1 is returned, you should check to see if <tt>isUserDisclaimerConfirmed()</tt> returns false; <tt>isUserDisclaimerConfirmed()</tt> must return true to get passed the first process when refreshing the remote source.

When working with the InstallMgr class, it will be useful to have a SWMgr object lying around before installing any new modules and refreshing any remote sources. This is so you can provide some additional module information to the user with the help of <tt>InstallMgr::getModuleStatus()</tt>. You rely on the return value of <tt>InstallMgr::getModuleStatus()</tt> to display the list of modules and whether they are new (not installed) (<tt>InstallMgr::MODSTAT_NEW</tt>), already installed (<tt>InstallMgr::MODSTAT_SAMEVERSION</tt>), an update is available (<tt>InstallMgr::MODSTAT_UPDATED</tt>), et cetera.

To install modules you would of course use the method <tt>installModule()</tt>. Local installs make use of only the first three parameters; remote installs make use of the first and last two while passing 0 to the second parameter. Note, the name of the module you want to install is obtained through <tt>SWModule::Name()</tt>. <tt>installModule()</tt> will return 0 on success.

=== Python ===

=== Java ===

DevTools:Code Examples

2012-02-21T08:32:10Z

Scribe: /* Get Modules Example(s) */

[[Category:Development tools]]
This page was started to provoke developers who know how the SWORD API works to post simple, everyday code examples that anyone can use. By "simple", I mean something that can work within a static function if possible.

== Examples ==

=== C++ ===

Be sure to first see the [http://crosswire.org/svn/sword/trunk/examples/ examples/ folder] in the source code distribution.
The [http://crosswire.org/svn/sword/trunk/utilities/ /utilities/] and [http://crosswire.org/svn/sword/trunk/tests /tests/] folders are also very informative and provide concise code examples.

==== Get Modules Example(s) ====
The following example is for obtaining modules that are installed in the user's SWORD repository. The following function takes one parameter, the type of the modules you want to retrieve. It is defaulted to retrieve only Bibles.

===== Code =====
<pre>
#include <string>
#include <vector>
#include <swmgr.h>
#include <swmodule.h>

using namespace sword;
using namespace std;

vector<string> getModuleNames(const char *modType = SWMgr::MODTYPE_BIBLES) {
vector <string> modules;
SWMgr library;
ModMap::iterator it;
for (it = library.Modules.begin(); it != library.Modules.end(); ++it) {
SWModule *module = (*it).second;
if (!strcmp(module->getType(), modType)) {
modules.push_back(module->getName());
}
}
return modules;
}
</pre>
====== Example Usage ======
<pre>
list<string> bibles = getModuleNames(SWMgr::MODTYPE_COMMENTARIES);
</pre>
Modules contain features. If looking for a feature of a module, one can query with:
<pre>
if (module->getConfig().has("Feature", "Images")
// do something ...
</pre>
----

==== Get Biblical Book Names Example(s) ====
This example isn't completely accurate nor is it desireable to point users to internal implementations which may change. The [Text] section of a locales.d/ file is meant to include any i18n string, not just Bible book names-- though that's likely all we have in most (all?) localization files at the moment. Other internal strings in the engine are meant to be localized there. Better example to get Biblical Names using SWORD (as stated later):

VerseKey vk;
while (!vk.Error()) {
cout << vk.getBookName();
vk.setBook(vk.getBook()+1);
}

Obtaining a list of the canonical books of the Bible doesn't necessarily require any SWORD classes (though in the following example we'll be using [http://www.crosswire.org/~ghellings/svnclassdocs/classSWConfig.html SWConfig]). A default SWORD installation installs the file <tt>abbr.conf</tt> at <tt>/usr/share/sword/locales.d</tt> on a Unix-like system (on Windows it may be located at <tt>C:\Program Files\CrossWire\The SWORD Project\locales.d</tt>). The syntax of the file is the same as any INI file. Therefore we just need to parse the file for the canonical books; so technically any configuration file parser that can parse INI files will do. The section we want to obtain from <tt>abbr.conf</tt> is called <tt>Text</tt>. (Again, the example uses a Qt4 class, [http://doc.trolltech.com/4.5/qstringlist.html QStringList].)

===== Code #1 =====
<pre>
#include <QStringList>
#include <swconfig.h>

QStringList getBiblicalBooks()
{
QStringList books;
SWConfig config("/usr/share/sword/locales.d/abbr.conf");
ConfigEntMap::iterator it;
for (it = config["Text"].begin(); it != config["Text"].end(); it++)
{
books << (*it).first.c_str();
}

return books;
}
</pre>

After obtaining all the Bible book names, you can obtain their abbreviations with [http://www.crosswire.org/~ghellings/svnclassdocs/classSWConfig.html SWConfig], again:
<pre>
SWConfig config("/usr/share/sword/locales.d/abbr.conf");
const char *GenAbbr = config["Text"]["Genesis"];
</pre>

But, of course, since it's not necessarily safe to assume that you would have an abbr.conf file lying around, the above example isn't necessarily practical. Nevertheless, hopefully, its existence provided some insight on [http://www.crosswire.org/~ghellings/svnclassdocs/classSWConfig.html SWConfig]. The more proper way to obtain a list of Biblical, canonical book names is through the use of [http://www.crosswire.org/~ghellings/svnclassdocs/classVerseKey.html VerseKey]. VerseKey has a public member that stores the number of books for each testament—BMAX. BMAX[0] has the number of Old Testament books, and BMAX[1] has the number of New Testament books, which will be useful for use in a <tt>for</tt> loop.

===== Code #2 =====
<pre>
QStringList getBiblicalBooks()
{
QStringList books;
VerseKey vk;
for (int b = 0; b < 2; b++)
{
// Set the Testament number to retrieve book names from that Testament.
// Add 1 to b since the Testament numbers don't start at 0.
vk.setTestament(b+1);
for (int i = 0; i < vk.BMAX[b]; i++)
{
// Add 1 to i since the book numbers don't start at 0.
vk.setBook(i+1);
books << vk.getBookName();
}
}
return books;
}
</pre>
----

==== Getting Generic Book Table of Contents ====

[http://www.crosswire.org/~ghellings/svnclassdocs/classTreeKey.html TreeKey] is necessary for traversing the generic book's tree. I am going to let the comments and function names speak for themselves here. Assume that <tt>module</tt> points to a [http://www.crosswire.org/~ghellings/svnclassdocs/classSWModule.html SWModule] object.
<pre>
#include <swmodule.h>
#include <treekey.h>

void getGenBookTOC(sword::TreeKey *tk, Class *parent)
{
// if no TreeKey, then obtain one from the module
if (!tk)
tk = dynamic_cast<sword::TreeKey*>(module->getKey());

// Move onto the first child if any
if (tk->firstChild())
{
// Get the first child's information before moving onto the next
do
{
// Retrieve the name so we can use it to get
// the GenBook's content later
QString text = tk->getText();
// Keep track of the information for custom implementation
Class *item = storeItemInfoForLaterUse(parent, text);

// If it has children, dive into it
if (tk->hasChildren())
getGenBookTOC(tk, item);
}
// Move onto the next child if any
while (tk->nextSibling());
// Move up one level in case one of the children had children
tk->parent();
}
}
</pre>
How you go about in implementing this is up to you.

[[Category:Genbook]]

==== Install Manager ====

The [http://www.crosswire.org/~ghellings/svnclassdocs/classInstallMgr.html InstallMgr] class is pretty easy to work with and will manage most of the install sources itself. When instantiated, it will generate the list of sources (which can later be accessed from its public attribute, <tt>sources</tt>) from the InstallMgr.conf located at the path provided in the constructor's first paramater, <tt>privatePath</tt>, if any. If no InstallMgr.conf exists, you can use the method <tt>refreshRemoteSourceConfiguration()</tt> to retrieve a list of sources remotely. <tt>refreshRemoteSourceConfiguration()</tt> will return 0 upon success. If -1 is returned, you should check to see if <tt>isUserDisclaimerConfirmed()</tt> returns false; <tt>isUserDisclaimerConfirmed()</tt> must return true to get passed the first process when refreshing the remote source.

When working with the InstallMgr class, it will be useful to have a SWMgr object lying around before installing any new modules and refreshing any remote sources. This is so you can provide some additional module information to the user with the help of <tt>InstallMgr::getModuleStatus()</tt>. You rely on the return value of <tt>InstallMgr::getModuleStatus()</tt> to display the list of modules and whether they are new (not installed) (<tt>InstallMgr::MODSTAT_NEW</tt>), already installed (<tt>InstallMgr::MODSTAT_SAMEVERSION</tt>), an update is available (<tt>InstallMgr::MODSTAT_UPDATED</tt>), et cetera.

To install modules you would of course use the method <tt>installModule()</tt>. Local installs make use of only the first three parameters; remote installs make use of the first and last two while passing 0 to the second parameter. Note, the name of the module you want to install is obtained through <tt>SWModule::Name()</tt>. <tt>installModule()</tt> will return 0 on success.

=== Python ===

=== Java ===

DevTools:Code Examples

2012-02-21T08:30:32Z

Scribe: /* C++ */

[[Category:Development tools]]
This page was started to provoke developers who know how the SWORD API works to post simple, everyday code examples that anyone can use. By "simple", I mean something that can work within a static function if possible.

== Examples ==

=== C++ ===

Be sure to first see the [http://crosswire.org/svn/sword/trunk/examples/ examples/ folder] in the source code distribution.
The [http://crosswire.org/svn/sword/trunk/utilities/ /utilities/] and [http://crosswire.org/svn/sword/trunk/tests /tests/] folders are also very informative and provide concise code examples.

==== Get Modules Example(s) ====
The following example is for obtaining modules that are installed in the user's SWORD repository. This example also makes slight use of the Qt4 GUI library. The following function takes one parameter, the type of the modules you want to retrieve. Unless stated otherwise, there are up to 4 different types to choose from:
* "Biblical Texts"
* "Commentaries"
* "Lexicons / Dictionaries"
* "Generic Books"
===== Code =====
<pre>
#include <string>
#include <vector>
#include <swmgr.h>
#include <swmodule.h>

using namespace sword;
using namespace std;

vector<string> getModuleNames(const char *modType = SWMgr::MODTYPE_BIBLES) {
vector <string> modules;
SWMgr library;
ModMap::iterator it;
for (it = library.Modules.begin(); it != library.Modules.end(); ++it) {
SWModule *module = (*it).second;
if (!strcmp(module->getType(), modType)) {
modules.push_back(module->getName());
}
}
return modules;
}
</pre>
====== Example Usage ======
<pre>
list<string> bibles = getModuleNames(SWMgr::MODTYPE_COMMENTARIES);
</pre>
Modules contain features. If looking for a feature of a module, one can query with:
<pre>
if (module->getConfig().has("Feature", "Images")
// do something ...
</pre>
----

==== Get Biblical Book Names Example(s) ====
This example isn't completely accurate nor is it desireable to point users to internal implementations which may change. The [Text] section of a locales.d/ file is meant to include any i18n string, not just Bible book names-- though that's likely all we have in most (all?) localization files at the moment. Other internal strings in the engine are meant to be localized there. Better example to get Biblical Names using SWORD (as stated later):

VerseKey vk;
while (!vk.Error()) {
cout << vk.getBookName();
vk.setBook(vk.getBook()+1);
}

Obtaining a list of the canonical books of the Bible doesn't necessarily require any SWORD classes (though in the following example we'll be using [http://www.crosswire.org/~ghellings/svnclassdocs/classSWConfig.html SWConfig]). A default SWORD installation installs the file <tt>abbr.conf</tt> at <tt>/usr/share/sword/locales.d</tt> on a Unix-like system (on Windows it may be located at <tt>C:\Program Files\CrossWire\The SWORD Project\locales.d</tt>). The syntax of the file is the same as any INI file. Therefore we just need to parse the file for the canonical books; so technically any configuration file parser that can parse INI files will do. The section we want to obtain from <tt>abbr.conf</tt> is called <tt>Text</tt>. (Again, the example uses a Qt4 class, [http://doc.trolltech.com/4.5/qstringlist.html QStringList].)

===== Code #1 =====
<pre>
#include <QStringList>
#include <swconfig.h>

QStringList getBiblicalBooks()
{
QStringList books;
SWConfig config("/usr/share/sword/locales.d/abbr.conf");
ConfigEntMap::iterator it;
for (it = config["Text"].begin(); it != config["Text"].end(); it++)
{
books << (*it).first.c_str();
}

return books;
}
</pre>

After obtaining all the Bible book names, you can obtain their abbreviations with [http://www.crosswire.org/~ghellings/svnclassdocs/classSWConfig.html SWConfig], again:
<pre>
SWConfig config("/usr/share/sword/locales.d/abbr.conf");
const char *GenAbbr = config["Text"]["Genesis"];
</pre>

But, of course, since it's not necessarily safe to assume that you would have an abbr.conf file lying around, the above example isn't necessarily practical. Nevertheless, hopefully, its existence provided some insight on [http://www.crosswire.org/~ghellings/svnclassdocs/classSWConfig.html SWConfig]. The more proper way to obtain a list of Biblical, canonical book names is through the use of [http://www.crosswire.org/~ghellings/svnclassdocs/classVerseKey.html VerseKey]. VerseKey has a public member that stores the number of books for each testament—BMAX. BMAX[0] has the number of Old Testament books, and BMAX[1] has the number of New Testament books, which will be useful for use in a <tt>for</tt> loop.

===== Code #2 =====
<pre>
QStringList getBiblicalBooks()
{
QStringList books;
VerseKey vk;
for (int b = 0; b < 2; b++)
{
// Set the Testament number to retrieve book names from that Testament.
// Add 1 to b since the Testament numbers don't start at 0.
vk.setTestament(b+1);
for (int i = 0; i < vk.BMAX[b]; i++)
{
// Add 1 to i since the book numbers don't start at 0.
vk.setBook(i+1);
books << vk.getBookName();
}
}
return books;
}
</pre>
----

==== Getting Generic Book Table of Contents ====

[http://www.crosswire.org/~ghellings/svnclassdocs/classTreeKey.html TreeKey] is necessary for traversing the generic book's tree. I am going to let the comments and function names speak for themselves here. Assume that <tt>module</tt> points to a [http://www.crosswire.org/~ghellings/svnclassdocs/classSWModule.html SWModule] object.
<pre>
#include <swmodule.h>
#include <treekey.h>

void getGenBookTOC(sword::TreeKey *tk, Class *parent)
{
// if no TreeKey, then obtain one from the module
if (!tk)
tk = dynamic_cast<sword::TreeKey*>(module->getKey());

// Move onto the first child if any
if (tk->firstChild())
{
// Get the first child's information before moving onto the next
do
{
// Retrieve the name so we can use it to get
// the GenBook's content later
QString text = tk->getText();
// Keep track of the information for custom implementation
Class *item = storeItemInfoForLaterUse(parent, text);

// If it has children, dive into it
if (tk->hasChildren())
getGenBookTOC(tk, item);
}
// Move onto the next child if any
while (tk->nextSibling());
// Move up one level in case one of the children had children
tk->parent();
}
}
</pre>
How you go about in implementing this is up to you.

[[Category:Genbook]]

==== Install Manager ====

The [http://www.crosswire.org/~ghellings/svnclassdocs/classInstallMgr.html InstallMgr] class is pretty easy to work with and will manage most of the install sources itself. When instantiated, it will generate the list of sources (which can later be accessed from its public attribute, <tt>sources</tt>) from the InstallMgr.conf located at the path provided in the constructor's first paramater, <tt>privatePath</tt>, if any. If no InstallMgr.conf exists, you can use the method <tt>refreshRemoteSourceConfiguration()</tt> to retrieve a list of sources remotely. <tt>refreshRemoteSourceConfiguration()</tt> will return 0 upon success. If -1 is returned, you should check to see if <tt>isUserDisclaimerConfirmed()</tt> returns false; <tt>isUserDisclaimerConfirmed()</tt> must return true to get passed the first process when refreshing the remote source.

When working with the InstallMgr class, it will be useful to have a SWMgr object lying around before installing any new modules and refreshing any remote sources. This is so you can provide some additional module information to the user with the help of <tt>InstallMgr::getModuleStatus()</tt>. You rely on the return value of <tt>InstallMgr::getModuleStatus()</tt> to display the list of modules and whether they are new (not installed) (<tt>InstallMgr::MODSTAT_NEW</tt>), already installed (<tt>InstallMgr::MODSTAT_SAMEVERSION</tt>), an update is available (<tt>InstallMgr::MODSTAT_UPDATED</tt>), et cetera.

To install modules you would of course use the method <tt>installModule()</tt>. Local installs make use of only the first three parameters; remote installs make use of the first and last two while passing 0 to the second parameter. Note, the name of the module you want to install is obtained through <tt>SWModule::Name()</tt>. <tt>installModule()</tt> will return 0 on success.

=== Python ===

=== Java ===

DevTools:Code Examples

2012-02-21T08:29:32Z

Scribe: /* Examples */

[[Category:Development tools]]
This page was started to provoke developers who know how the SWORD API works to post simple, everyday code examples that anyone can use. By "simple", I mean something that can work within a static function if possible.

== Examples ==

=== C++ ===

Be sure to see the [http://crosswire.org/svn/sword/trunk/examples/ examples/ folder] in the source code distribution.
The [http://crosswire.org/svn/sword/trunk/utilities/ /utilities/] and [http://crosswire.org/svn/sword/trunk/tests /tests/] folders are also very informative and provide concise code examples.

==== Get Modules Example(s) ====
The following example is for obtaining modules that are installed in the user's SWORD repository. This example also makes slight use of the Qt4 GUI library. The following function takes one parameter, the type of the modules you want to retrieve. Unless stated otherwise, there are up to 4 different types to choose from:
* "Biblical Texts"
* "Commentaries"
* "Lexicons / Dictionaries"
* "Generic Books"
===== Code =====
<pre>
#include <string>
#include <vector>
#include <swmgr.h>
#include <swmodule.h>

using namespace sword;
using namespace std;

vector<string> getModuleNames(const char *modType = SWMgr::MODTYPE_BIBLES) {
vector <string> modules;
SWMgr library;
ModMap::iterator it;
for (it = library.Modules.begin(); it != library.Modules.end(); ++it) {
SWModule *module = (*it).second;
if (!strcmp(module->getType(), modType)) {
modules.push_back(module->getName());
}
}
return modules;
}
</pre>
====== Example Usage ======
<pre>
list<string> bibles = getModuleNames(SWMgr::MODTYPE_COMMENTARIES);
</pre>
Modules contain features. If looking for a feature of a module, one can query with:
<pre>
if (module->getConfig().has("Feature", "Images")
// do something ...
</pre>
----

==== Get Biblical Book Names Example(s) ====
This example isn't completely accurate nor is it desireable to point users to internal implementations which may change. The [Text] section of a locales.d/ file is meant to include any i18n string, not just Bible book names-- though that's likely all we have in most (all?) localization files at the moment. Other internal strings in the engine are meant to be localized there. Better example to get Biblical Names using SWORD (as stated later):

VerseKey vk;
while (!vk.Error()) {
cout << vk.getBookName();
vk.setBook(vk.getBook()+1);
}

Obtaining a list of the canonical books of the Bible doesn't necessarily require any SWORD classes (though in the following example we'll be using [http://www.crosswire.org/~ghellings/svnclassdocs/classSWConfig.html SWConfig]). A default SWORD installation installs the file <tt>abbr.conf</tt> at <tt>/usr/share/sword/locales.d</tt> on a Unix-like system (on Windows it may be located at <tt>C:\Program Files\CrossWire\The SWORD Project\locales.d</tt>). The syntax of the file is the same as any INI file. Therefore we just need to parse the file for the canonical books; so technically any configuration file parser that can parse INI files will do. The section we want to obtain from <tt>abbr.conf</tt> is called <tt>Text</tt>. (Again, the example uses a Qt4 class, [http://doc.trolltech.com/4.5/qstringlist.html QStringList].)

===== Code #1 =====
<pre>
#include <QStringList>
#include <swconfig.h>

QStringList getBiblicalBooks()
{
QStringList books;
SWConfig config("/usr/share/sword/locales.d/abbr.conf");
ConfigEntMap::iterator it;
for (it = config["Text"].begin(); it != config["Text"].end(); it++)
{
books << (*it).first.c_str();
}

return books;
}
</pre>

After obtaining all the Bible book names, you can obtain their abbreviations with [http://www.crosswire.org/~ghellings/svnclassdocs/classSWConfig.html SWConfig], again:
<pre>
SWConfig config("/usr/share/sword/locales.d/abbr.conf");
const char *GenAbbr = config["Text"]["Genesis"];
</pre>

But, of course, since it's not necessarily safe to assume that you would have an abbr.conf file lying around, the above example isn't necessarily practical. Nevertheless, hopefully, its existence provided some insight on [http://www.crosswire.org/~ghellings/svnclassdocs/classSWConfig.html SWConfig]. The more proper way to obtain a list of Biblical, canonical book names is through the use of [http://www.crosswire.org/~ghellings/svnclassdocs/classVerseKey.html VerseKey]. VerseKey has a public member that stores the number of books for each testament—BMAX. BMAX[0] has the number of Old Testament books, and BMAX[1] has the number of New Testament books, which will be useful for use in a <tt>for</tt> loop.

===== Code #2 =====
<pre>
QStringList getBiblicalBooks()
{
QStringList books;
VerseKey vk;
for (int b = 0; b < 2; b++)
{
// Set the Testament number to retrieve book names from that Testament.
// Add 1 to b since the Testament numbers don't start at 0.
vk.setTestament(b+1);
for (int i = 0; i < vk.BMAX[b]; i++)
{
// Add 1 to i since the book numbers don't start at 0.
vk.setBook(i+1);
books << vk.getBookName();
}
}
return books;
}
</pre>
----

==== Getting Generic Book Table of Contents ====

[http://www.crosswire.org/~ghellings/svnclassdocs/classTreeKey.html TreeKey] is necessary for traversing the generic book's tree. I am going to let the comments and function names speak for themselves here. Assume that <tt>module</tt> points to a [http://www.crosswire.org/~ghellings/svnclassdocs/classSWModule.html SWModule] object.
<pre>
#include <swmodule.h>
#include <treekey.h>

void getGenBookTOC(sword::TreeKey *tk, Class *parent)
{
// if no TreeKey, then obtain one from the module
if (!tk)
tk = dynamic_cast<sword::TreeKey*>(module->getKey());

// Move onto the first child if any
if (tk->firstChild())
{
// Get the first child's information before moving onto the next
do
{
// Retrieve the name so we can use it to get
// the GenBook's content later
QString text = tk->getText();
// Keep track of the information for custom implementation
Class *item = storeItemInfoForLaterUse(parent, text);

// If it has children, dive into it
if (tk->hasChildren())
getGenBookTOC(tk, item);
}
// Move onto the next child if any
while (tk->nextSibling());
// Move up one level in case one of the children had children
tk->parent();
}
}
</pre>
How you go about in implementing this is up to you.

[[Category:Genbook]]

==== Install Manager ====

The [http://www.crosswire.org/~ghellings/svnclassdocs/classInstallMgr.html InstallMgr] class is pretty easy to work with and will manage most of the install sources itself. When instantiated, it will generate the list of sources (which can later be accessed from its public attribute, <tt>sources</tt>) from the InstallMgr.conf located at the path provided in the constructor's first paramater, <tt>privatePath</tt>, if any. If no InstallMgr.conf exists, you can use the method <tt>refreshRemoteSourceConfiguration()</tt> to retrieve a list of sources remotely. <tt>refreshRemoteSourceConfiguration()</tt> will return 0 upon success. If -1 is returned, you should check to see if <tt>isUserDisclaimerConfirmed()</tt> returns false; <tt>isUserDisclaimerConfirmed()</tt> must return true to get passed the first process when refreshing the remote source.

When working with the InstallMgr class, it will be useful to have a SWMgr object lying around before installing any new modules and refreshing any remote sources. This is so you can provide some additional module information to the user with the help of <tt>InstallMgr::getModuleStatus()</tt>. You rely on the return value of <tt>InstallMgr::getModuleStatus()</tt> to display the list of modules and whether they are new (not installed) (<tt>InstallMgr::MODSTAT_NEW</tt>), already installed (<tt>InstallMgr::MODSTAT_SAMEVERSION</tt>), an update is available (<tt>InstallMgr::MODSTAT_UPDATED</tt>), et cetera.

To install modules you would of course use the method <tt>installModule()</tt>. Local installs make use of only the first three parameters; remote installs make use of the first and last two while passing 0 to the second parameter. Note, the name of the module you want to install is obtained through <tt>SWModule::Name()</tt>. <tt>installModule()</tt> will return 0 on success.

=== Python ===

=== Java ===

Tutorial:How SWORD works

2012-02-21T07:51:08Z

Scribe:

Be sure to read [http://crosswire.org/sword/develop/swordapi/apiprimer.jsp The SWORD API Primer]

This is the index page for a series of tutorials on how SWORD works.

These lessons are written by Troy A. Griffitts. They first appeared as emails sent to SWORD Devel.

== Why you should love SWORD ==

* [[Tutorials:SWORD 101|SWORD 101 – Text Processing Flow]]
* [[Tutorials:SWORD 102|SWORD 102 – XML Basics ]]
* [[Tutorials:SWORD 103|SWORD 103 – What is a filter?]]

[[Category:Tutorials]]

Tutorial:How SWORD works

2012-02-21T07:50:47Z

Scribe:

Be sure to read [http://crosswire.org/sword/develop/swordapi/apiprimer.jsp | The SWORD API Primer]

This is the index page for a series of tutorials on how SWORD works.

These lessons are written by Troy A. Griffitts. They first appeared as emails sent to SWORD Devel.

== Why you should love SWORD ==

* [[Tutorials:SWORD 101|SWORD 101 – Text Processing Flow]]
* [[Tutorials:SWORD 102|SWORD 102 – XML Basics ]]
* [[Tutorials:SWORD 103|SWORD 103 – What is a filter?]]

[[Category:Tutorials]]

Tutorial:How SWORD works

2012-02-21T07:50:28Z

Scribe:

Be sure to read the SWORD API Primer [http://crosswire.org/sword/develop/swordapi/apiprimer.jsp | The SWORD API Primer]

This is the index page for a series of tutorials on how SWORD works.

These lessons are written by Troy A. Griffitts. They first appeared as emails sent to SWORD Devel.

== Why you should love SWORD ==

* [[Tutorials:SWORD 101|SWORD 101 – Text Processing Flow]]
* [[Tutorials:SWORD 102|SWORD 102 – XML Basics ]]
* [[Tutorials:SWORD 103|SWORD 103 – What is a filter?]]

[[Category:Tutorials]]

Tutorial:How SWORD works

2012-02-21T07:49:21Z

Scribe:

Be sure to read the SWORD API Primer [http://crosswire.org/sword/develop/swordapi/apiprimer.jsp]

This is the index page for a series of tutorials on how SWORD works.

These lessons are written by Troy A. Griffitts. They first appeared as emails sent to SWORD Devel.

== Why you should love SWORD ==

* [[Tutorials:SWORD 101|SWORD 101 – Text Processing Flow]]
* [[Tutorials:SWORD 102|SWORD 102 – XML Basics ]]
* [[Tutorials:SWORD 103|SWORD 103 – What is a filter?]]

[[Category:Tutorials]]

Current Projects

2012-02-21T07:36:06Z

Scribe:

Use this page to provide information about current projects and proposals for new software applications.

==New front-end applications==
Use this section to announce work begun for developing new SWORD or JSword based front-ends. They should be mentioned here even if they are only at the proof of concept stage, so that may prevent duplication of effort.

=== Tyndale STEP ===

* [[Frontends:TyndaleStep|Tyndale STEP - Scripture Tools for Every Pastor]] – in collaboration with Tyndale House, Cambridge.

=== Android platform ===

* Troy has begun work on developing an [http://en.wikipedia.org/wiki/Android_%28operating_system%29 Android] front-end called '''Bishop'''. A preliminary APK file is now available for early testing. ''Visit the CrossWire mobile-devel mailing list if you would like to help''.

* It is feasible to convert any J2ME application to an Android APK using the '''J2ME Bridge''' service available at [http://www.netmite.com/ netmite.com]. Several '''Go Bible''' applications have been converted as an experiment. The conversion process works OK, but leaves the MIDlet icon unchanged in size, which does not conform to Android guidelines. NB. Some languages did not have font support by default.

=== Java ME application framework ===

* [[Projects:Go Bible|Go Bible]] is not a SWORD front-end ''per se''. Nevertheless it is CrossWire's first project for the [http://en.wikipedia.org/wiki/Java_Platform,_Micro_Edition Java ME] application framework. Project leader is [[User:David Haslam|David Haslam]].

=== Blackberry smart phones ===

* '''Go Bible''' source code has been adapted and successfully ported to the Blackberry platform. It includes full support for touch-screen controls. Download '''The Bible''' via a link in http://www.mobileappfarm.com/

=== Qt Framework ===

* [http://sourceforge.net/projects/bibletimemini/ BibleTime Mini] project based on [http://bibletime.info/ BibleTime] source code and optimized for use on mobile devices. It runs now on Windows and Windows Mobile platforms, but it is easy to port it on other mobile platforms supported by Qt (Symbian, MeeGo, Maemo, Android).

=== HP/Palm webOS ===
* [http://zefanjas.de/biblez BibleZ HD] is a SWORD based bible reader app for the HP TouchPad and the HP Pre3.

== Ideas for new projects ==

* See [[Ideas for new projects]].

==Developer To Do Lists==

* Scribe: http://www.crosswire.org/~scribe/todo/

* Osk: [[User:Osk/Todo]]

* Go Bible: [[User:David Haslam]]

[[Category:Projects]]
[[Category:Versification]]
[[Category:SWORD Frontends]]

Encoding

2011-08-31T22:01:28Z

Scribe: /* Searching in modules */

As many people are making mistakes with encoding, here is a small text where I try to explain what does exist.

== Introduction ==
Computers are working on words of bits, usually 8, 16, 32 or 64 today. Those words are meanless for the computer, they can be interpreted in many ways, as numbers, as instructions, as characters, as true/false values...

An encoding is a set of rules defining how to translate a sequence of words into a sequence of characters.

== Single byte encoding ==
As computer can easily work with groups of bit called bytes, one of the first solution was to use a different byte value for every character. It's easy to understand and to program: every byte encode a single character; it's space efficient (memory was really expensive), you can size a string by counting bytes... You can have up to 256 characters as a byte can have 256 different values.

When computers was mostly an occidental story, [http://en.wikipedia.org/wiki/ASCII ASCII] was one of the first and most successful encoding. It define 128 characters, including upper case and lower case of the Latin alphabet, digits, punctuation and control. Values above 127 are not defined (allowing extensions or controls values). It is a good set of characters to write in English.

[http://en.wikipedia.org/wiki/EBCDIC EBCDIC] is another byte encoding defined by IBM at the same time which include mostly the sames characters but values above 127 are not free.

As many languages are using characters not included in the original ASCII set; many country, or group of country defined new encoding based on the ASCII encoding. Missing characters are filled in the unused 128 values (above 127). As 128 values is not enough for every earth alphabet, we have many of theses encodings. One of the most successful are [http://en.wikipedia.org/wiki/ISO/IEC_8859 ISO-8859] and in particular [http://en.wikipedia.org/wiki/ISO/IEC_8859-1 ISO-8859-1] which include characters for 29 western European and African languages.

== Unicode ==
Theses encoding where 1 byte correspond to 1 character are really great for English, it's working well for languages based on the Latin alphabet, but is really bad for other alphabets. Some of them use more than 256 signs.

You can not write a text with characters from different encoding; and when sending a text, you always have to agree on a common encoding.

Here is Unicode. But first, learn this: '''Unicode is not an encoding'''

[http://en.wikipedia.org/wiki/Unicode Unicode] is an industry standard where every character in any real language, past or present (now over 100,000 characters), is having a different numeric value called a code-point. This code-point can be recorded in many ways. The first 128 code-points are the same values used in the ASCII encoding.

Did you remember, Unicode is not an encoding? Ok, in fact, Unicode also define many different encodings to store code-point.

== Multi-bytes encoding ==
One word = One character was a great rule, let's keep it. When Unicode was young, Code-point were all under 65536. So we can represent every character with a 2 bytes word, (a 16 bits word). This is called [http://en.wikipedia.org/wiki/UTF-16/UCS-2 UCS2]. UCS2 is deprecated.

Now, Code-point are under 2^32, so we can represent every character with a 4 bytes word, (a 32 bit word). This is called [http://en.wikipedia.org/wiki/UTF-32/UCS-4 UCS4], or UTF-32.

For an English text, because every character is encoded with 4 bytes, the size if 4 time bigger than the same text in ASCII encoding.

== Variable byte length encoding ==
UCS2 and UCS4 are great, but it takes too much space, and if your old program does work with 1 byte = 1 character, it will not work. We need an encoding where ASCII characters are the same, but with the ability to encode any Unicode character.

So [http://en.wikipedia.org/wiki/UTF-8 UTF-8] was created. It's a variable-byte length encoding. ASCII character are the same as in an ASCII encoded text; and other characters are encoded using 2, 3 or 4 characters. You should use this for all your SWORD files now.

For programs written to use UCS2, there is also an extension, [http://en.wikipedia.org/wiki/UTF-16/UCS-2 UTF-16] is designed to use a single 2 bytes word for characters under 65536, and a pair of words above.

== Common mistakes ==
If you use a wrong encoding, some characters will not be displayed correctly as the computer decoded it using incorrect rules.

The two most common encoding are ISO-8859-1 and UTF-8

=== 1. An UTF-8 text decoded as ISO-8859-1 (or ISO-8859-*) ===

You will see two or three characters for non-ASCII ones, usually Ã and ©.
Et Dieu vit la lumière, qu'elle était bonne; et Dieu sépara la lumière d'avec les ténèbres.
will show as
Et Dieu vit la lumiÃ¨re, qu'elle Ã©tait bonne; et Dieu sÃ©para la lumiÃ¨re d'avec les tÃ©nÃ¨bres.

=== 2. An ISO-8859-1 text decoded as UTF-8 ===

The UTF-8 decoder will find an invalid multi-byte character, it can report an error, or put question marks or squares instead:

Et Dieu vit la lumière, qu'elle était bonne; et Dieu sépara la lumière d'avec les ténèbres.
will show as
Et Dieu vit la lumi?re, qu'elle ?tait bonne; et Dieu s?para la lumi?re d'avec les t?n?bres.

Warning: If you see squares, it can also be a font problem! This happen if you're using a font which does not define some characters you are using.

=== 3. Using a font that does not include the characters you want ===

If you use accented greek characters, for example, but do not use a unicode font that supports precomposed greek characters (like @Arial Unicode MS) accented characters will appear as empty rectangles in your text. In BibleCS you can change the font in Options/Preferences/Display.

== Normalization ==
For module making, it is strongly recommended that Unicode source files encoded as UTF-8 are [http://unicode.org/faq/normalization.html normalized] to NFC. [http://en.wikipedia.org/wiki/Combining_character Combining characters] are permitted in source text, e.g. for diacriticals where there is no precomposed character in the Unicode Standard.<ref>Be aware, however, that many fonts in many operating systems lack such ability, and that many of our front-ends use rendering widgets which could easily barf on such functionality. Xiphos and BibleTime ought to be OK from a renderer's perspective, provided a good system font can be found, but it may be that BibleDesktop would suffer. BibleCS probably has access to good fonts, but it uses very different technologies, so check that one carefully. BPBible, especially older versions, might have a tough time with advanced character sets. Eloquent is probably fine!</ref>

=== Searching in modules ===
The simple rule is that if a search request and the indexed text are not normalized the same, there will not be a hit.

Modules are prepared for search using StripFilter mechanisms. Frontends should be sure to call SWModule::StripText() on the user input before passing to the search method to make sure both are normalized the same.

Regarding rendering, each front-end should not assume that the module is encoded in a way that works for it. When we did experiments, NFC was the best across the widest variety of front-ends. But no one way was best for every script, font or display engine. It would be best for each front-end to normalize the text before display. This could be different than the normalization used for search.

'''Note:'''
<references />

== See also ==

* [[Fonts]]

== External links ==
* [http://en.wikipedia.org/wiki/Unicode_equivalence Unicode equivalence]

* [http://scripts.sil.org/TECkitIntro TECkit] – a Text Encoding Conversion toolkit.

:As well as being able to convert between encodings, it can also be used to convert text from one script to another, for any language that can be represented by more than one script. Example: Some languages in Central Asia can be represented in either Latin or Cyrillic script.

* [http://www.alanwood.net/unicode/ Alan Wood’s Unicode Resources] – Unicode and Multilingual Support in HTML, Fonts, Web Browsers and Other Applications (including text editors)

* [http://www.ewellic.org/compression.html A survey of Unicode compression] – by Doug Ewell.

* [http://babelstone.blogspot.com/2011/06/whats-new-in-unicode-61.html What's new in Unicode 6.1 ?] – by Andrew West.

[[Category:Unicode]]

DevTools:conf Files

2011-05-03T02:04:02Z

Scribe:

=Creating a .conf File=
==.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.

Note on RTF, 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.

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

===Required Elements===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| [name]
| Each conf file begins with [name], replacing "name" with a short well known abbreviation for the module (e.g., [KJV]). This must be first in the file. Valid characters for this abbreviation are limited to A-Z, a-z, 0-9 and _. 
The .conf file should be named the lowercase of this abbreviation followed by .conf. For example, [MyModule] would be mymodule.conf.
|  
|  
|-
| 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 for a module named [mymodule], depending on the type of module (Bible text, commentary, lexcon or dictionary, general book) and the data driver used are:

:./modules/texts/rawtext/mymodule/

:./modules/texts/ztext/mymodule/

:./modules/comments/zcom/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

|  
|  
|-
| Description
| <string> 
This is a short (1 line) title of the module.
|  
|  
|-
| ModDrv
| RawText (for uncompressed Bibles) zText (for compressed Bibles) RawCom (for uncompressed Commentaries) RawCom4 (for uncompressed Commentaries having entries greater than 32K bytes) zCom (for compressed Commentaries) 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 32K bytes) zLD (for compressed Dictionaries) RawGenBook (for uncompressed tree keyed modules)
|  
|  
|}

===Elements to indicate features ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| CompressType
| ZIP [http://en.wikipedia.org/wiki/Lempel%E2%80%93Ziv%E2%80%93Storer%E2%80%93Szymanski LZSS]
Used to indicate how a compressed module (zText, zCom, zLD) is compressed.
ZIP is the preferred format.
| LZSS
|  
|-
| BlockType
| BOOK CHAPTER VERSE 
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.
| CHAPTER
|  
|-
| BlockCount
| <integer> 
Used for zLD to indicate the number of entries in a compressed block. Higher values will make the module slower, but smaller.
| 200
|  
|-
| 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 Bible's which do not conform to any supported versification system in SWORD. See [[Alternate_Versification|alternate versification]].
| TreeKey
|  
|-
| CipherKey
| <string> 
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.)
|  
|  
|-
| Versification
|Catholic Catholic2 German KJV KJVA Leningrad Luther MT NRSV NRSVA Synodal SynodalP Vulg

Used to specify the versification employed by a Bible module.
| KJV
|  
|}

=== Elements required for proper rendering ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| GlobalOptionFilter
| GBFStrongs (For GBF texts having Strong's Numbers) 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) ThMLStrongs (For THML texts having Strong's Numbers) 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) UTF8Cantillation (For Hebrew texts having cantillation marks) UTF8GreekAccents (For Greek texts having accents) UTF8HebrewPoints (For Hebrew texts having vowel points) OSISStrongs (For OSIS texts having Strong's Numbers) 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) OSISLemma (For OSIS texts having lemmas) OSISRuby (For Japanese OSIS texts with [http://www.w3.org/TR/ruby/ ruby]: Kana glosses of Han characters) 
Each of these filters removes/hides the text's feature, when activated by the application.
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. crossreferences in notes require both the OSISFootnotes and the OSISScriprefs filters enabled.
|  
| Repeats
|-
| Direction
| LtoR (Left to Right) RtoL (Right to Left) 
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
|  
|-
| SourceType
| Plaintext GBF General Bible Format: http://www.ebible.org/bible/gbf.htm ThML Theological Markup Language: http://www.ccel.org/ThML OSIS Open Scriptural Information Standard: http://www.bibletechnologies.net TEI Text Encoding Initiative: http://www.tei-c.org/P4X/DI.html 
Specifies the markup used in the module. The preferred markup is OSIS. TEI is preferred for dictionaries until OSIS supports dictionaries. 
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 Latin-1 (cp1252; see the warning) 
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.
Warning: "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. Front-end implementors should use "cp1252" or "windows1252" explicitly, not "Latin-1" provided by some programming language libraries.
| Latin-1
|  
|-
| 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. 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
| 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 modules with Strong's number encoded Greek definitions) HebrewDef (for modules with Strong's number encoded Hebrew definitions) GreekParse (for modules with Greek morphology expansions) HebrewParse (for 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)
|  
| Repeats
|-
| GlossaryFrom
| <xml: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
| <xml: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.
|  
|  
|}

=== General informatic and installer elements ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| Abbreviation
| <string> 
A shorter abbreviation which can be displayed instead of the full name. For example, KJV for the King James Version.
| The module name.
|  
|-
| About
| <string> 
A lengthier description and may include copyright, source, etc. information, possibly duplicating information in other elements.
|  
| Continuation RTF
|-
| 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 or 1.1.3.
| 1.0
|  
|-
| History_x.x
| <string> 
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.
|  
| Repeats
|-
| MinimumVersion
| <version string> 
Identifies the minimum version of the SWORD library required for this module.
| 1.5.1a
|  
|-
| Category
| Daily Devotional (for modules with Feature=DailyDevotion) Glossaries (for modules with Feature=Glossary) Cults / Unorthodox / Questionable Material Essays (for essays) Maps (for modules that primarily consist of maps) Images (for modules that primarily consist of images) Biblical Texts (for Bibles) Commentaries Lexicons / Dictionaries Generic Books (for anything else....) 
This is used by installers to further categorize the modules beyond what can be figured out by the ModDrv and Feature.
| Biblical Texts (for /(Raw|z)Text4?/) 
Commentaries (for /(Raw|z|HREF)Com4?/) 
Lexicons / Dictionaries (for /(Raw|z)LD4?/ 
Generic Books (for RawGenBook)
|  
|-
| LCSH
| <tree/string> 
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.
|  
|  
|-
| Lang
| <xml:lang identifier> 
This is the primary language code of the module and should include a value according to BCP 47 (i.e. [http://tools.ietf.org/html/rfc4646 RFC 4646] & [http://tools.ietf.org/html/rfc4647 RFC 4647]). When available use a 2-letter code from [http://en.wikipedia.org/wiki/ISO_639-1 ISO 639-1 codes] ([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] (e.g. ceb for Cebuano) ([http://www.loc.gov/standards/iso639-2/php/code_list.php registrar]). Failing that, use [http://en.wikipedia.org/wiki/ISO_639-3 ISO 639-3] ([http://www.sil.org/iso639-3/codes.asp registrar]), which covers over 7000 languages, or [http://en.wikipedia.org/wiki/ISO_639-5 ISO 639-5] ([http://www.loc.gov/standards/iso639-5/id.php registrar]) for macrolanguages. The regex for this subtag will be /[a-z]{2,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 [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). The regex for this subtag will be /[A-Z][a-z]{3}/.

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). The regex for this subtag will be /[A-Z]{2}/

Individual subtags (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. Private use extensions defined by BCP 47 (e.g. x-, qaa, and Qaaa) should be avoided wherever possible.
| en
|  
|-
| InstallSize
| <integer (indicating bytes)>
|  
|  
|-
| SwordVersionDate
| <ISO date string (yyyy-mm-dd)>
Indicates the date that the module was changed.
|  
|  
|-
| Obsoletes
| <name of module> 
Each instance of this element names a module that is made obsolete by this module, usually indicated by the former name of the module.
|  
| Repeats
|}

=== Copyright & Licensing related elements ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| Copyright
| <string> 
Contains the copyright notice for the work, including the year of copyright and the owner of the copyright.
|  
| Continuation
|-
| CopyrightHolder
| <string> 
Contains the name of the copyright holder.
|  
|  
|-
| CopyrightDate
| <integer (indicating year)>
|  
|  
|-
| CopyrightNotes
| <string>
|  
| Continuation
|-
| CopyrightContactName
| <string> 
Contains the name of the copyright holder.
|  
| Continuation
|-
| CopyrightContactNotes
| <string>
|  
| Continuation
|-
| CopyrightContactAddress
| <string> 
Contains the mailing address of the copyright holder.
|  
| Continuation
|-
| CopyrightContactEmail
| <string> 
Contains the email address of the copyright holder, preferably in the form: name at xyz dot com.
|  
|  
|-
| ShortPromo
| <string> 
A link to the home page for the module, perhaps with an encouragement to visit the site.
|  
| HTML Link
|-
| ShortCopyright
| <string>
|  
|  
|-
| DistributionLicense
| Public Domain Copyrighted Copyrighted; Permission to distribute granted to CrossWire Copyrighted; Free non-commercial distribution Copyrighted; Freely distributable Copyrighted; Permission granted to distribute non-commercially in SWORD format [http://www.gnu.org/copyleft/fdl.html GFDL] [http://www.gnu.org/copyleft/gpl.html GPL] Creative Commons: [http://creativecommons.org/licenses/by-nc-nd by-nc-nd] Creative Commons: [http://creativecommons.org/licenses/by-nc-sa by-nc-sa] Creative Commons: [http://creativecommons.org/licenses/by-nc by-nc] Creative Commons: [http://creativecommons.org/licenses/by-nd by-nd] Creative Commons: [http://creativecommons.org/licenses/by-sa by-sa] Creative Commons: [http://creativecommons.org/licenses/by by] 
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.
|  
|  
|-
| DistributionNotes
| <string> 
Indicates any additional notes about distribution of the module.
|  
| Continuation
|-
| TextSource
| <string, probably a URL> 
Indicates, either in prose (such as "CCEL") or as a URL of the source of the text
|  
| Continuation
|-
| UnlockURL
| <string> 
Contains the URL (a bare URL, not an HTML <a> link) of a web page for unlocking instructions/payment
|  
| URL
|}

== Localization ==

Where it makes sense, the values in the .conf file may be internationalized by appending _lang where lang is replaced by an appropriate code, according to [http://www.rfc-editor.org/rfc/bcp/bcp47.txt BCP 47]. See Lang above for details.

For example, to give a French description, you can have a field:
: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, then 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 ....

The language for .conf entries without the locale modifier is the default and must be the language of the module itself (as specified in Lang=) or English.

'''Notes''':
*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.
*See also [[Localized Language Names]].

[[Category:Development tools|Conf files]]
[[Category:Localization|Conf files]]

Osis2mod

2011-04-21T16:42:38Z

Scribe: /* Transformations */

==Introduction==
osis2mod transforms an OSIS encoded [[OSIS Bibles|Bible]] or [[OSIS_Commentaries|commentary]] into a SWORD module.

== Current status ==

:''Please describe current status of osis2mod, including a list of any outstanding issues or unsolved difficulties''.

==History of Changes==
The following outlines in reverse, chronological order the major changes to osis2mod. When several changes were made over the span of a few days, they are lumped into the most recent date. Bug fixes are not mentioned.

{|width="100%" border="0" class="sortable"
!width="10%"|Date
!Feature
|-valign="top"
|
'''2009-06-06'''
|
* Improved handling of chapter introductions.
|-valign="top"
|
'''2009-05-23'''
|
* '''-d flags''' now always available.
|-valign="top"
|
'''2009-05-10'''
|
*Added '''-d flags''' as a compile time option.
*Improved exit codes and documented them here.
*Labeled all diagnostic and debug output.
*Can now read from standard input.

|-valign="top"
|
'''2009-04-28'''
|
*Predictable handling of inter-verse material.

|-valign="top"
|
'''2009-04-24'''
|
*'''-v v11n''' added to support [[Alternate Versification]].
*'''-s <2|4>''' added to support uncompressed commentaries with large entries (exceeding 64K bytes).
*Replace paragraph hack with milestoned paragraphs: <div type="paragraph" sID="xxx"/> ... <div type="paragraph" eID="xxx"/>

|-valign="top"
|
'''2008-09-11'''
|
*Words of Christ (WoC) can be marked up naturally. osis2mod does the right thing.
*Container elements converted to their milestoned form.

|-valign="top"
|
'''2008-02-29'''
|
*Now supports commentaries in addition to Bibles.
*Added utf-8 detection and automatic conversion from cp1252 and iso8859-1 to utf-8, making that the default behavior
*Added NFC normalization, making it the default
*Now handles the full definition of an osisID and an osisRef, including workID and grain.

|-valign="top"
|
'''2007-09-27'''
|
*Changed command-line parsing from positional parameters to flags.

|-valign="top"
|
'''2007-05-13'''
|
*All whitespace tokens are converted into blanks and adjacent spaces are merged into one. Leading whitespace on each verse is still removed.

|-valign="top"
|
'''2007-05-01'''
|
*Added version identification to the running of osis2mod.

|-valign="top"
|
'''2007-04-24'''
|
*Added ignoring of unknown books

|-valign="top"
|
'''2006-07-15'''
|
*Optimized writing to module.
*Added simple transformations of <q> and into milestones.
*Now allow empty attributes, such as marker=""

|-valign="top"
|
'''2006-07-04'''
|
*Updated to support OSIS 2.1
*Added validation that verses in isolation are well formed

|-valign="top"
|
'''2005-12-22'''
|
*Added command-line options for compress and encipher.

|-valign="top"
|
'''2005-04-29'''
|
*Removed <verse> and </verse>

|-valign="top"
|
'''2005-01-23'''
|
*Reverted pre-verse title handling

|-valign="top"
|
'''2004-06-12'''
|
*Removed pre-verse title handling
*Added <verse> and </verse>
*Added support for milestoned version of some OSIS elements
*Added support for verses that are not in the KJV versification by appending them to the closest prior verse.
*Added support for osisIDs with sub-verse references (i.e. osisID grains)

|-valign="top"
|
'''2004-05-19'''
|
*Added support for linked verses

|-valign="top"
|
'''2003-11-20'''
|
*Added recognition for <chapter> element

|-valign="top"
|
'''2003-05-26'''
|
*Initial version
|}

==Transformations==
Osis2mod performs the following transformations:
* '''Whitespace''' -- Allows for human-readable OSIS files.
**Leading whitespace on books, chapters and verses is removed
**Whitespace is normalized into blanks
**Multiple adjacent whitespace is reduced to a single space
* '''Unicode handling''' - All modules should be UTF-8, NFC.
**Latin-1 (cp1252 and iso8859-1) are converted into UTF-8
**UTF-8 is normalized into NFC
* '''Milestone conversion''' - necessary for frontends to show a verse at a time. (note: genX is unique for an sID/eID pair, where X is a number.)
** <q ...>...</q> is converted into <q sID="genX" .../>...<q eID="genX" .../>. Note: Quotes with who="Jesus" are not transformed at this time.
** ... becomes <div type="paragraph" sID="genX" .../>... <div type="paragraph" eID="genX" ...>.
** <chapter ...>...</chapter> becomes <chapter sID="genX" .../>...<chapter eID="genX" .../>
** <closer ...>...</closer> becomes <closer sID="genX" .../>...<closer eID="genX" .../>
** <div ...>...</div> becomes <div sID="genX" .../>...<div eID="genX" .../>
** <l ...>...</l> becomes <l sID="genX" .../>...<l eID="genX" .../>
** <lg ...>...</lg> becomes <lg sID="genX" .../>...<lg eID="genX" .../>
** <salute ...>...</salute> becomes <salute sID="genX" .../>...<salute eID="genX" .../>
** <signed ...>...</signed> becomes <signed sID="genX" .../>...<signed eID="genX" .../>
** <speech ...>...</speech> becomes <speech sID="genX" .../>...<speech eID="genX" .../>
** <verse ...>...</verse> becomes (when using -d 2 for debugging.) <milestone resp="v" sID="genX" ... />...<milestone resp="v" eID="genX" ... />
* '''Words of Christ''' - necessary for front-ends to appropriately highlight the WOC, a verse at a time.
** <q sID="XXX" who="Jesus" .../>...<eID="XXX" who="Jesus" .../> becomes <q who="Jesus" marker=""><q sID="XXX" .../>...<q eID="XXX" .../></q>
** <q who="Jesus" ...>...</q> becomes <q who="Jesus" marker=""><q sID="genX" .../>...<q eID="genX" .../></q>
** Within the following construct, <q who="Jesus" marker="">...</q> will surround verse text.
* '''Pre-Verse Titles''' (obsolete with SVN revision 2358 for the SWORD 1.6.0 release)
** Titles immediately preceeding a verse are converted into <title type="section" subType="x-preverse>...</title>
** Interverse tags not in titles are appended to prior verse.
** (In 1.6.0) <div sID="pvX" type="x-milestone" subType="x-preverse"/>...<div eID="pvX" type="x-milestone" subType="x-preverse"/> will replace preverse titles.

Note: With 1.6.0, these transformations can be reversed to produce the original elements.

==Handling of Introductions, Titles and Inter-Verse Material==
SWORD for module, testament, book and chapter introductory material. Those introductions can have appropriate titles as well. At this time, osis2mod does not handle module and testament introductions.

In SWORD 1.6.0 the handling of this material has changed.

Please Note: In the following, the effects of the above transformations are not shown.

===Book Introductions and Titles===
Book introductions and titles are straight forward. It includes the start of the book and everything following it up to, but not including the start of the chapter. See [[OSIS Bibles]] for best practices in marking up titles and introductions.

For example:
<div type="book" ...>
... introductory material ...
<chapter"...>
will put the following into the book introduction:
<div type="book" ...>
... introductory material ...

===Chapter Introductions===
Chapter introductions and titles are a bit problematic. Between the start of a chapter and its first verse, we could have a chapter title, a chapter introduction and/or a start of a section of verses or a titled verse. Osis2mod now handles this in a predictable fashion. From the start of the chapter up to and not including a section div or a title that has a type that is not ''main'', ''chapter'' or ''sub'', the content is chapter introduction. After that, it is part of the verse.

Specifically, the following list gives the possible first elements following the chapter introduction.:
*<div type="section" ...>
*<title type="yyy" ...> where yyy is not ''main'', ''chapter'' or ''sub''.

For example,
<chapter ...>
<title>Chapter Title</title> (or <title type="chapter">Chapter Title</title>
or <title type="main">Chapter Title</title>)
<title type="sub">Chapter Subtitle</title>
<div type="introduction">... intro ...</div>

<lg>
<div type="section"> or <title type="yyy">
will put the following into the chapter introduction:
<chapter ...>
<title>Chapter Title</title>
<title type="sub">Chapter Subtitle</title>

<lg>
<div type="introduction">... intro ...</div>
Note: Prior to 1.6.0, osis2mod would change the order of some these elements.

The material starting with:
<div type="section"> or <title type="yyy">
and including everything up to the <verse ...> will be put into the following construct and prepended to the verse content.
<div type="x-milestone" subType="x-preverse" sID="pvXXX"/>
<div type="section"> or <title type="yyy">
<div type="x-milestone" subType="x-preverse" eID="pvXXX"/>
... verse content ...

===Between Verses===
Between verses we may have closing tags to finish off what was started earlier, structural opening tags (e.g. line groups, divisions, paragraphs, ...), titles and/or introductory material.

Upon finding the close of a verse, osis2mod will append all adjacent closing tags to it. Once it finds a start tag, it will attach that to the following verse, marking it up in the same fashion.

For example, the following would be prepended to the verse content:
<div type="x-milestone" subType="x-preverse" sID="pvXXX"/>
<div type="section">
<title>Section title</title>

<lg>
<div type="x-milestone" subType="x-preverse" eID="pvXXX"/>
... verse content ...

===Last Verse===
The material following the last verse of a chapter is appended to that verse. You might find:
... verse content ...
</chapter>
<div type="colophon">... colophon text ...</div>
</div>
</div>

==Exclusions==
Only content starting the first <div> to the last </div> is retained. All other is excluded. From a practical perspective, this excludes the OSIS header information.

==Usage==
It is always best to use the most recent version of osis2mod and compiling it from SVN is best.

After the SWORD 1.5.9 release, osis2mod was changed to take flags rather than positional arguments.
<pre>
You are running osis2mod: $Rev: 2421 $
OSIS Bible/commentary module creation tool for The SWORD Project

usage: ./osis2mod <output/path> <osisDoc> [OPTIONS]
<output/path> an existing folder that the module will be written
<osisDoc> path to the validated OSIS document, or '-' to
read from standard input
-a augment module if exists (default is to create new)
-z use ZIP compression (default no compression)
-Z use LZSS compression (default no compression)
-b <2|3|4> compression block size (default 4):
2 - verse; 3 - chapter; 4 - book
-c <cipher_key> encipher module using supplied key
(default no enciphering)
-N do not convert UTF-8 or normalize UTF-8 to NFC
(default is to convert to UTF-8, if needed,
and then normalize to NFC)
Note: UTF-8 texts should be normalized to NFC.
-s <2|4> bytes used to store entry size (default is 2).
Note: useful for commentaries with very large
entries in uncompressed modules
(2 bytes to store size equal 65535 characters)
-v <v11n> specify a versification scheme to use (default is KJV)
Note: The following are valid values for v11n:
KJV
KJVA
Leningrad
MT
NRSV
NRSVA
-d <flags> turn on debugging (default is 0)
Note: This flag may change in the future.
Flags: The following are valid values:
0 - no debugging
1 - writes to module, very verbose
2 - verse start and end
4 - quotes, esp. Words of Christ
8 - titles
16 - inter-verse material
32 - BSP to BCV transformations
64 - v11n exceptions
128 - parsing of osisID and osisRef
256 - internal stack
512 - miscellaneous
This argument can be used more than once. (Or
the flags may be added together.)

See http://www.crosswire.org/wiki/osis2mod for more details.
</pre>
'''<output/path>''' 
This a path to any existing directory. It is best for it to be empty.

'''<osisDoc>''' 
This is a single, well-formed, valid OSIS document.

If '''-''' is used instead of a file name, the document will be read from standard input. This allows for two constructs:
* Redirection
osis2mod ./modules/texts/ztext/KJV - < kjv.xml
* Piping
cat kjv.xml | osis2mod ./modules/texts/ztext/KJV -

'''-a''' 
Osis2mod can create a Bible all at once or incrementally, depending on the presence of the -a flag. This
provides for two abilities,
<ol>
<li>Assembling a Bible from book files: 
<pre>
mkdir /tmp/mymodule
osis2mod /tmp/mymodule matt.xml
osis2mod /tmp/mymodule -a mark.xml
...
osis2mod /tmp/mymodule -a rev.xml
</pre>
'''Note:''' The book files can be in any order. SWORD will order them correctly in the index.
<li>Adding corrections to a Bible: 
<pre>
osis2mod /tmp/mymodule -a fixes.xml
</pre>
'''Note:''' When fixes are put into the module they are appended to the data file and do not actually replace the verses. The index file is adjusted to point to the new place in the data file.
</ol>

'''-z|-Z''' 
A SWORD Bible can be compressed with Zip (-z) '''or''' LZSS (-Z). All of SWORD's Bible modules are compressed with Zip. This saves significant space over an uncompressed module. Uncompressed modules are useful for debugging.

'''-b 2|3|4''' 
This setting is only useful for a compressed module. The choice as to whether to use Verse (2), Chapter (3) or Book (4, the default) level compression depends upon the amount of data in the block. A typical Bible is best compressed book by book. A commentary, chapter by chapter. If the commentary is very robust and the amount of text per verse is really huge, then verse compression might make sense.

All of SWORD's compressed Bible modules are compressed by book. Basically, all of the verses in a block are compressed and appended to the data file. For this reason, the datafile cannot be uncompressed by anything other than the SWORD and JSword libraries.

When creating the module by appending it is important to do so by whole compression block. That is, if blockType is Chapter, then the osisDoc needs to contain one or more whole chapters.

'''-c cipherKey''' 
This is typically 16 characters in length, having no leading or trailing spaces, consisting of alternating sets of 4 alpha and 4 numeric characters, such as Aduf0274PjNq0328.

'''-N''' 
All OSIS modules should be UTF-8 and all that are UTF-8 are also to be NFC. The default is to automatically detect the presense of Latin-1 (either cp1252 or iso8859-1) and convert it to UTF-8 and to normalize UTF-8 to NFC. This flag will turn off this behavior and is useful for creating Latin-1 modules or for modules that are already UTF-1 and NFC.

Note: this was added late Feb 2008 and requires ICU support when compiling.

'''-s 2|4''' 
A value of 2, the default, restricts raw, uncompressed modules to 64K bytes per entry. A value of 4, breaks this barrier. This is needed for Bibles, having large introductory materials, and for commentaries with large entries. All compressed OSIS modules can handle large entries.

Note: this was added late Apr 2009 and will be part of the SWORD 1.6.0 release (formerly known as 1.5.11).

'''-v v11n''' 
By default, osis2mod uses the KJV versification. The practical implication of this is that only books in the KJV canon are allowed and any text in an allowed book are retained. However, if the verse reference of a supported book falls outside of the versification it is appended to the prior verse in the canon. This flag allows for an alternate versification.

Note: this was added late Apr 2009 and will be part of the SWORD 1.6.0 release (formerly known as 1.5.11). With that release, only the Leningrad Codex will be supported, with '''-v Leningrad'''.

'''-d flags''' 
By default, osis2mod is compiled without debug support. You may uncomment #define DEBUG and recompile to enable the -d flag. The flag can be used more than once or the flags can be added together. For example,
-d 2 -d 4
is the same as
-d 6

To do verbose debugging use:
-d -1

For the most part these flags are not intended for debugging modules, but rather for debugging problems in osis2mod.

The -d 2 flag produces no output but puts milestones into the module where verses start and end. The form of the milestone is:
<milestone resp="v" [attributes from verse] />
The milestone will contain the osisID from the verse and also a valid sID or eID. The sID/eID indicates the start of end of the verse.

Note: the -d 2 flag change at any time, or may be removed.

==Messages==
Osis2mod has robust, mind-boggling messages. These are provided here in hopes that it will help problem diagnosis.

===Exit Status===
When an error occurs that causes osis2mod to exit without processing the entire input file, a non-zero exit status is supplied to the caller. Here are the codes that osis2mod uses:
const int EXIT_BAD_ARG = 1; // Bad parameter given for program
const int EXIT_NO_WRITE = 2; // Could not open the module for writing
const int EXIT_NO_CREATE = 3; // Could not create the module
const int EXIT_NO_READ = 4; // Could not open the input file for reading.
const int EXIT_BAD_NESTING = 5; // BSP or BCV nesting is bad

===Diagnostic Messages===
In the following, example values are given in '''[...]'''. The brackets do not actually appear in the message. Also, the messages are a bit prettier here than in reality.
WARNING(UTF8): '''[ osisID ]''': Should be converted to UTF-8 ('''[ text ]''')
The program will always check for text that is not UTF-8.

INFO(UTF8): '''[ osisID ]''': Converting to UTF-8 ('''[ text before conversion ]''')
Text that is converted to UTF-8 is noted.

ERROR(UTF8): '''[ osisID ]''': Converting to UTF-8 ('''[ text after first conversion ]''')
It is an error if after a conversion it still is not UTF-8.

WARNING(UTF8): osis2mod is not compiled with support for ICU. Ignoring -n flag.
Normalization was requested, but since osis2mod was not compiled for it, it cannot honor the default request.

INFO(V11N): '''[ osisID ]''' is not in the '''[ v11n ]''' versification.
Indicates that a verse is not in the versification.

INFO(V11N): '''[ osisID ]''' is not in the '''[ v11n ]''' versification. Appending content to '''[ osisID ]'''
This like the other indicates a versification problem, but shows where the text will be found. Osis2mod preserves all module content for supported books.

WARNING(V11N): New book is '''[ name ]''' and is not in '''[ v11n ]''' versification, ignoring
The name of the book was not recognized as belonging to the chosen versification, it and all of it's content is ignored.

INFO(WRITE): Appending entry: '''[ osisID ]''': '''[ text so far ]'''
If osis2mod encounters text that needs to be appended to a verse that is already in the module. This could indicate that
* the reference is in the input twice. This typically indicates a problem.
* more text was found that needs to be added to the prior verse.
* osis2mod is being run in append mode to fix a verse in the module.

INFO(LINK): Linking '''[ osisID ]''' to '''[ osisID ]'''
An osisID such as "Gen.1.1 Gen.1.2 Gen.1.3" was used and the latter are linked to the first.

ERROR(REF): Invalid osisID/annotateRef: '''[ invalid attribute value ]'''
This indicates that the SWORD library was unable to parse the osisID or annotateRef.

FATAL(NESTING): '''[ currentOsisID ]''': tag expected
This indicates that the specified verse is not balanced with regard to its tags. Building a raw text module, looking in the module for the verse and pairing begin/end tags will help find the problem. Typically, this indicates an end tag that did not have a matching begin tag and all tags before it were properly paired.

FATAL(NESTING): '''[ currentOsisID ]''': Expected '''[ topToken.getName() ]''' found '''[ tokenName ]'''
This also indicates that the specified verse is not balanced with regard to its tags. Building a raw text module, looking in the module for the verse and pairing begin/end tags will help find the problem. It could be either a begin or an end tag problem.

WARNING(NESTING): verse '''[ currentOsisID ]''' is not well formed:('''[ verseDepth ]''','''[ tagDepth ]''')
This indicates that the verse probably will not show properly in some front-ends in some circumstances. Typically, it shows the problem if the verse is shown in isolation.

ERROR(NESTING): improper nesting '''[ currentOsisID ]''': matching (sID,eID) not found. Looking at ('''[ sID ]''','''[ eID ]''')
OSIS specifies that every sID has a matching eID. Osis2mod is checking that BSP elements are properly nested.

===Debug Messages===
The following are shown in the same form as the diagnostic messages above. These only show when osis2mod is compiled with DEBUG defined. They are given without comment.

'''-d 1''' 
Output of what is being written to the module. The two osisIDs should always be the same.
DEBUG(WRITE): '''[ osisID ]''':'''[ osisID ]''': '''[ text so far ]'''

'''-d 4''' 
A stack is maintained to represent the Words of Christ on a per verse basis. This is internal diagnostic of that stack
DEBUG(QUOTE): '''[ currentOsisID ]''': quote top('''[ quote stack size ]''') '''[ token ]'''
DEBUG(QUOTE): '''[ currentOsisID ]''': quote pop('''[ quote stack size ]''') '''[ topToken ]''' -- '''[ token ]'''
DEBUG(QUOTE): '''[ currentOsisID ]''': ('''[ quote stack size ]''') '''[ topToken ]''' -- '''[ token ]'''

'''-d 8''' 
Identifies when book and chapter introductions are being determined.
DEBUG(TITLE): '''[ currentOsisID ]''': OOPS INTRO
inChapterIntro = '''[ inChapterIntro ]'''
inBookIntro = '''[ inBookIntro ]'''
DEBUG(TITLE): '''[ currentOsisID ]''': Looking for book introduction
DEBUG(TITLE): '''[ currentOsisID ]''': Done looking for book introduction
DEBUG(TITLE): '''[ currentOsisID ]''': BOOK INTRO '''[ beading ]'''
DEBUG(TITLE): '''[ currentOsisID ]''': Looking for chapter introduction
DEBUG(TITLE): '''[ currentOsisID ]''': Done looking for chapter introduction
DEBUG(TITLE): '''[ currentOsisID ]''': CHAPTER INTRO '''[ heading ]'''

'''-d 16''' 
Inter-verse material either goes with the prior "verse" or the next. This help diagnose problems related to that split.
DEBUG(INTERVERSE): '''[ currentOsisID ]''': interverse start token '''[ token ]''':'''[ text ]'''
DEBUG(INTERVERSE): '''[ currentOsisID ]''': interverse end tag: '''[ tokenName ]'''('''[ tagDepth ]''','''[ chapterDepth ]''','''[ bookDepth ]''')
DEBUG(INTERVERSE): '''[ currentOsisID ]''': appending interverse end tag: '''[tokenName ]'''('''[ tagDepth ]''','''[ chapterDepth ]''','''[ bookDepth ]''')

'''-d 32''' 
The following messages relate to the transformations of containers to milestones.
DEBUG(XFORM): '''[ currentOsisID ]''': xform empty '''[ token ]'''
DEBUG(XFORM): '''[ currentOsisID ]''': xform push ('''[ bspTagStack.size() ]''') '''[ token ]''' (tagname='''[ tagName ]''')
DEBUG(XFORM): '''[ currentOsisID ]''': xform top('''[ bsp stack size ]''') '''[ topToken ]'''
DEBUG(XFORM): '''[ currentOsisID ]''': xform pop('''[ bsp stack size ]''') '''[ topToken ]'''

'''-d 64''' 
Occasionally a verse reference is outside of the chosen versification. These messages help to understand difficulties that osis2mod has in storing extra-canonical material in the module.
DEBUG(V11N): '''[ currentOsisID ]''' normalizes to '''[ after ]'''
DEBUG(V11N): Chapter max:'''[ chapterMax ]''', Verse Max:'''[ verseMax ]'''

'''-d 128''' 
OSIS ids and references can be of a form that SWORD cannot parse. Osis2mod contains a routine that munges these into a form that SWORD can understand.
DEBUG(REF): Copy range marker: '''[ marker ]'''
DEBUG(REF): Found a work prefix '''[ workPrefix ]'''
DEBUG(REF): Copy osisID:'''[ osisID ]'''
DEBUG(REF): Found a grain suffix '''[ grain ]'''
DEBUG(REF): Found a range
DEBUG(REF): replacing space with ;. Remaining: '''[ text ]'''
DEBUG(REF): shortended keyVal to`'''[ text ]'''`

'''-d 256''' 
Osis2mod contains two stacks to validate proper nesting of BSP and BCV, respectively. This is an internal representation of the BCV stacks. It provides additional information to understand the diagnostic nesting messages.
DEBUG(STACK): '''[ currentOsisID ]''': push ('''[ stack size]''') '''[ tokenName ]'''
DEBUG(STACK): '''[ currentOsisID ]''': pop('''[ tagDepth ]''') '''[ topToken.getName() ]'''

'''-d 512''' 
These are general debug messages.
DEBUG(FOUND): Found first div and pitching prior material: '''[ text ]'''
DEBUG(FOUND): New book is '''[ currentOsisID ]'''
DEBUG(FOUND): Current chapter is '''[ currentOsisID ]''' ('''[ osisID attribute value ]''')
DEBUG(FOUND): Entering verse
DEBUG(FOUND): New current verse is '''[ currentOsisID ]'''
DEBUG(FOUND): osisID/annotateRef is adjusted to: '''[ simpler osisID or osisRef ]'''

'''-d 512''' 
The following gives the input arguments.
DEBUG(ARGS):
path: '''[ path ]'''
osisDoc: '''[ osisDoc ]'''
create: '''[ append ]'''
compressType: '''[ compType ]'''
blockType: '''[ iType ]'''
cipherKey: '''[ cipherKey ]'''
normalize: '''[ normalize ]'''

== See also ==
* [[Osis2mod testcases]]
* [[Mod2osis]]

[[Category:OSIS]]
[[Category:Utilities]]

Zipped modules

2011-02-01T04:19:45Z

Scribe:

Some of the smaller devices running a sword front-end might not not have a network enabled module manager or network use might be slow and expensive. Users of these devices need to download their modules as zipped files and unzip them in the right place - e.g. a SD card.

JSword front-ends also require (for the moment at least) having zipped modules available.

It is also helpful for people who have no direct access to the Internet or who live in countries with monitored access to the Internet to be able to download (and possibly distribute) zipped modules. This is a zipped archive of a module in the file and directory layout used in the local module directory.

E.g. to create from your own module directory a zipped module of a uncompressed GenBook do this:

cd ~ftp/pub/sword
zip -r zip/mybook.zip mods.d/mybook.conf modules/genbook/rawgenbooks/mybook

[[Category:Modules|Zipped modules]]

DevTools:conf Files

2011-01-24T22:52:36Z

Scribe: /* Elements required for proper rendering */

=Creating a .conf File=
==.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.

Note on RTF, 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.

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

===Required Elements===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| [name]
| Each conf file begins with [name], replacing "name" with a short well known abbreviation for the module (e.g., [KJV]). This must be first in the file. Valid characters for this abbreviation are limited to A-Z, a-z, 0-9 and _. 
The .conf file should be named the lowercase of this abbreviation followed by .conf. For example, [MyModule] would be mymodule.conf.
|  
|  
|-
| 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 for a module named [mymodule], depending on the type of module (Bible text, commentary, lexcon or dictionary, general book) and the data driver used are:

:./modules/texts/rawtext/mymodule/

:./modules/texts/ztext/mymodule/

:./modules/comments/zcom/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

|  
|  
|-
| Description
| <string> 
This is a short (1 line) title of the module.
|  
|  
|-
| ModDrv
| RawText (for uncompressed Bibles) zText (for compressed Bibles) RawCom (for uncompressed Commentaries) RawCom4 (for uncompressed Commentaries having entries greater than 32K bytes) zCom (for compressed Commentaries) 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 32K bytes) zLD (for compressed Dictionaries) RawGenBook (for uncompressed tree keyed modules)
|  
|  
|}

===Elements to indicate features ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| CompressType
| ZIP [http://en.wikipedia.org/wiki/Lempel%E2%80%93Ziv%E2%80%93Storer%E2%80%93Szymanski LZSS]
Used to indicate how a compressed module (zText, zCom, zLD) is compressed.
ZIP is the preferred format.
| LZSS
|  
|-
| BlockType
| BOOK CHAPTER VERSE 
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.
| CHAPTER
|  
|-
| BlockCount
| <integer> 
Used for zLD to indicate the number of entries in a compressed block. Higher values will make the module slower, but smaller.
| 200
|  
|-
| 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 Bible's which do not conform to any supported versification system in SWORd. See [[Alternate_Versification|alternate versification]].
| TreeKey
|  
|-
| CipherKey
| <string> 
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.)
|  
|  
|-
| Versification
|Catholic Catholic2 German KJV KJVA Leningrad Luther MT NRSV NRSVA Synodal SynodalP Vulg

Used to specify the versification employed by a Bible module.
| KJV
|  
|}

=== Elements required for proper rendering ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| GlobalOptionFilter
| GBFStrongs (For GBF texts having Strong's Numbers) 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) ThMLStrongs (For THML texts having Strong's Numbers) 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) UTF8Cantillation (For Hebrew texts having cantillation marks) UTF8GreekAccents (For Greek texts having accents) UTF8HebrewPoints (For Hebrew texts having vowel points) OSISStrongs (For OSIS texts having Strong's Numbers) 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) OSISLemma (For OSIS texts having lemmas) OSISRuby (For Japanese OSIS texts with [http://www.w3.org/TR/ruby/ ruby]: Kana glosses of Han characters) 
Each of these filters removes/hides the text's feature, when activated by the application.
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. crossreferences in notes require both the OSISFootnotes and the OSISScriprefs filters enabled.
|  
| Repeats
|-
| Direction
| LtoR (Left to Right) RtoL (Right to Left) 
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
|  
|-
| SourceType
| Plaintext GBF General Bible Format: http://www.ebible.org/bible/gbf.htm ThML Theological Markup Language: http://www.ccel.org/ThML OSIS Open Scriptural Information Standard: http://www.bibletechnologies.net TEI Text Encoding Initiative: http://www.tei-c.org/P4X/DI.html 
Specifies the markup used in the module. The preferred markup is OSIS. TEI is preferred for dictionaries until OSIS supports dictionaries. 
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 Latin-1 (cp1252; see the warning) 
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.
Warning: "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. Front-end implementors should use "cp1252" or "windows1252" explicitly, not "Latin-1" provided by some programming language libraries.
| Latin-1
|  
|-
| 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. 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
| 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 modules with Strong's number encoded Greek definitions) HebrewDef (for modules with Strong's number encoded Hebrew definitions) GreekParse (for modules with Greek morphology expansions) HebrewParse (for 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)
|  
| Repeats
|-
| GlossaryFrom
| <xml: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
| <xml: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.
|  
|  
|}

=== General informatic and installer elements ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| Abbreviation
| <string> 
A shorter abbreviation which can be displayed instead of the full name. For example, KJV for the King James Version.
| The module name.
|  
|-
| About
| <string> 
A lengthier description and may include copyright, source, etc. information, possibly duplicating information in other elements.
|  
| Continuation RTF
|-
| 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 or 1.1.3.
| 1.0
|  
|-
| History_x.x
| <string> 
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.
|  
| Repeats
|-
| MinimumVersion
| <version string> 
Identifies the minimum version of the Sword library required for this module.
| 1.5.1a
|  
|-
| Category
| Daily Devotional (for modules with Feature=DailyDevotion) Glossaries (for modules with Feature=Glossary) Cults / Unorthodox / Questionable Material Essays (for essays) Maps (for modules that primarily consist of maps) Images (for modules that primarily consist of images) Biblical Texts (for Bibles) Commentaries Lexicons / Dictionaries Generic Books (for anything else....) 
This is used by installers to further categorize the modules beyond what can be figured out by the ModDrv and Feature.
| Biblical Texts (for /(Raw|z)Text4?/) 
Commentaries (for /(Raw|z|HREF)Com4?/) 
Lexicons / Dictionaries (for /(Raw|z)LD4?/ 
Generic Books (for RawGenBook)
|  
|-
| LCSH
| <tree/string> 
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.
|  
|  
|-
| Lang
| <xml:lang identifier> 
This is the primary language code of the module and should include a value according to BCP 47 (i.e. [http://tools.ietf.org/html/rfc4646 RFC 4646] & [http://tools.ietf.org/html/rfc4647 RFC 4647]). When available use a 2-letter code from [http://en.wikipedia.org/wiki/ISO_639-1 ISO 639-1 codes] ([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] (e.g. ceb for Cebuano) ([http://www.loc.gov/standards/iso639-2/php/code_list.php registrar]). Failing that, use [http://en.wikipedia.org/wiki/ISO_639-3 ISO 639-3] ([http://www.sil.org/iso639-3/codes.asp registrar]), which covers over 7000 languages, or [http://en.wikipedia.org/wiki/ISO_639-5 ISO 639-5] ([http://www.loc.gov/standards/iso639-5/id.php registrar]) for macrolanguages. The regex for this subtag will be /[a-z]{2,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 [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). The regex for this subtag will be /[A-Z][a-z]{3}/.

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). The regex for this subtag will be /[A-Z]{2}/

Individual subtags (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. Private use extensions defined by BCP 47 (e.g. x-, qaa, and Qaaa) should be avoided wherever possible.
| en
|  
|-
| InstallSize
| <integer (indicating bytes)>
|  
|  
|-
| SwordVersionDate
| <ISO date string (yyyy-mm-dd)>
Indicates the date that the module was changed.
|  
|  
|-
| Obsoletes
| <name of module> 
Each instance of this element names a module that is made obsolete by this module, usually indicated by the former name of the module.
|  
| Repeats
|}

=== Copyright & Licensing related elements ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| Copyright
| <string> 
Contains the copyright notice for the work, including the year of copyright and the owner of the copyright.
|  
| Continuation
|-
| CopyrightHolder
| <string> 
Contains the name of the copyright holder.
|  
|  
|-
| CopyrightDate
| <integer (indicating year)>
|  
|  
|-
| CopyrightNotes
| <string>
|  
| Continuation
|-
| CopyrightContactName
| <string> 
Contains the name of the copyright holder.
|  
| Continuation
|-
| CopyrightContactNotes
| <string>
|  
| Continuation
|-
| CopyrightContactAddress
| <string> 
Contains the mailing address of the copyright holder.
|  
| Continuation
|-
| CopyrightContactEmail
| <string> 
Contains the email address of the copyright holder, preferably in the form: name at xyz dot com.
|  
|  
|-
| ShortPromo
| <string> 
A link to the home page for the module, perhaps with an encouragement to visit the site.
|  
| HTML Link
|-
| ShortCopyright
| <string>
|  
|  
|-
| DistributionLicense
| Public Domain Copyrighted Copyrighted; Permission to distribute granted to CrossWire Copyrighted; Free non-commercial distribution Copyrighted; Freely distributable Copyrighted; Permission granted to distribute non-commercially in Sword format [http://www.gnu.org/copyleft/fdl.html GFDL] [http://www.gnu.org/copyleft/gpl.html GPL] Creative Commons: [http://creativecommons.org/licenses/by-nc-nd by-nc-nd] Creative Commons: [http://creativecommons.org/licenses/by-nc-sa by-nc-sa] Creative Commons: [http://creativecommons.org/licenses/by-nc by-nc] Creative Commons: [http://creativecommons.org/licenses/by-nd by-nd] Creative Commons: [http://creativecommons.org/licenses/by-sa by-sa] Creative Commons: [http://creativecommons.org/licenses/by by] 
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.
|  
|  
|-
| DistributionNotes
| <string> 
Indicates any additional notes about distribution of the module.
|  
| Continuation
|-
| TextSource
| <string, probably a URL> 
Indicates, either in prose (such as "CCEL") or as a URL of the source of the text
|  
| Continuation
|-
| UnlockURL
| <string> 
Contains the URL (a bare URL, not an HTML <a> link) of a web page for unlocking instructions/payment
|  
| URL
|}

== Localization ==

Where it makes sense, the values in the .conf file may be internationalized by appending _lang where lang is replaced by an appropriate code, according to [http://www.rfc-editor.org/rfc/bcp/bcp47.txt BCP 47]. See Lang above for details.

For example, to give a French description, you can have a field:
: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, then 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 ....

The language for .conf entries without the locale modifier is the default and must be the language of the module itself (as specified in Lang=) or English.

'''Notes''':
*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.
*See also [[Localized Language Names]].

[[Category:Development tools|Conf files]]
[[Category:Localization|Conf files]]

DevTools:conf Files

2011-01-24T22:44:33Z

Scribe: /* Elements required for proper rendering */

=Creating a .conf File=
==.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.

Note on RTF, 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.

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

===Required Elements===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| [name]
| Each conf file begins with [name], replacing "name" with a short well known abbreviation for the module (e.g., [KJV]). This must be first in the file. Valid characters for this abbreviation are limited to A-Z, a-z, 0-9 and _. 
The .conf file should be named the lowercase of this abbreviation followed by .conf. For example, [MyModule] would be mymodule.conf.
|  
|  
|-
| 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 for a module named [mymodule], depending on the type of module (Bible text, commentary, lexcon or dictionary, general book) and the data driver used are:

:./modules/texts/rawtext/mymodule/

:./modules/texts/ztext/mymodule/

:./modules/comments/zcom/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

|  
|  
|-
| Description
| <string> 
This is a short (1 line) title of the module.
|  
|  
|-
| ModDrv
| RawText (for uncompressed Bibles) zText (for compressed Bibles) RawCom (for uncompressed Commentaries) RawCom4 (for uncompressed Commentaries having entries greater than 32K bytes) zCom (for compressed Commentaries) 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 32K bytes) zLD (for compressed Dictionaries) RawGenBook (for uncompressed tree keyed modules)
|  
|  
|}

===Elements to indicate features ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| CompressType
| ZIP [http://en.wikipedia.org/wiki/Lempel%E2%80%93Ziv%E2%80%93Storer%E2%80%93Szymanski LZSS]
Used to indicate how a compressed module (zText, zCom, zLD) is compressed.
ZIP is the preferred format.
| LZSS
|  
|-
| BlockType
| BOOK CHAPTER VERSE 
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.
| CHAPTER
|  
|-
| BlockCount
| <integer> 
Used for zLD to indicate the number of entries in a compressed block. Higher values will make the module slower, but smaller.
| 200
|  
|-
| 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 Bible's which do not conform to any supported versification system in SWORd. See [[Alternate_Versification|alternate versification]].
| TreeKey
|  
|-
| CipherKey
| <string> 
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.)
|  
|  
|-
| Versification
|Catholic Catholic2 German KJV KJVA Leningrad Luther MT NRSV NRSVA Synodal SynodalP Vulg

Used to specify the versification employed by a Bible module.
| KJV
|  
|}

=== Elements required for proper rendering ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| GlobalOptionFilter
| GBFStrongs (For GBF texts having Strong's Numbers) 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) ThMLStrongs (For THML texts having Strong's Numbers) 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) UTF8Cantillation (For Hebrew texts having cantillation marks) UTF8GreekAccents (For Greek texts having accents) UTF8HebrewPoints (For Hebrew texts having vowel points) OSISStrongs (For OSIS texts having Strong's Numbers) 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) OSISLemma (For OSIS texts having lemmas) OSISRuby (For Japanese OSIS texts with [http://www.w3.org/TR/ruby/ ruby]: Kana glosses of Han characters) 
Each of these filters removes/hides the text's feature, when activated by the application.
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. crossreferences in notes require both the OSISFootnotes and the OSISScriprefs filters enabled.
|  
| Repeats
|-
| Direction
| LtoR (Left to Right) RtoL (Right to Left) 
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
|  
|-
| SourceType
| Plaintext GBF General Bible Format: http://www.ebible.org/bible/gbf.htm ThML Theological Markup Language: http://www.ccel.org/ThML OSIS Open Scriptural Information Standard: http://www.bibletechnologies.net TEI Text Encoding Initiative: http://www.tei-c.org/P4X/DI.html 
Specifies the markup used in the module. The preferred markup is OSIS. TEI is preferred for dictionaries until OSIS supports dictionaries. 
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 Latin-1 (cp1252; see the warning) 
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.
Warning: "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. Front-end implementors should use "cp1252" or "windows1252" explicitly, not "Latin-1" provided by some programming language libraries.
| Latin-1
|  
|-
| DisplayLevel
| <integer>
| 1
|  
|-
| Font
| <string> 
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.
|  
|  
|-
| OSISqToTick
| 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 modules with Strong's number encoded Greek definitions) HebrewDef (for modules with Strong's number encoded Hebrew definitions) GreekParse (for modules with Greek morphology expansions) HebrewParse (for 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)
|  
| Repeats
|-
| GlossaryFrom
| <xml: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
| <xml: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.
|  
|  
|}

=== General informatic and installer elements ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| Abbreviation
| <string> 
A shorter abbreviation which can be displayed instead of the full name. For example, KJV for the King James Version.
| The module name.
|  
|-
| About
| <string> 
A lengthier description and may include copyright, source, etc. information, possibly duplicating information in other elements.
|  
| Continuation RTF
|-
| 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 or 1.1.3.
| 1.0
|  
|-
| History_x.x
| <string> 
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.
|  
| Repeats
|-
| MinimumVersion
| <version string> 
Identifies the minimum version of the Sword library required for this module.
| 1.5.1a
|  
|-
| Category
| Daily Devotional (for modules with Feature=DailyDevotion) Glossaries (for modules with Feature=Glossary) Cults / Unorthodox / Questionable Material Essays (for essays) Maps (for modules that primarily consist of maps) Images (for modules that primarily consist of images) Biblical Texts (for Bibles) Commentaries Lexicons / Dictionaries Generic Books (for anything else....) 
This is used by installers to further categorize the modules beyond what can be figured out by the ModDrv and Feature.
| Biblical Texts (for /(Raw|z)Text4?/) 
Commentaries (for /(Raw|z|HREF)Com4?/) 
Lexicons / Dictionaries (for /(Raw|z)LD4?/ 
Generic Books (for RawGenBook)
|  
|-
| LCSH
| <tree/string> 
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.
|  
|  
|-
| Lang
| <xml:lang identifier> 
This is the primary language code of the module and should include a value according to BCP 47 (i.e. [http://tools.ietf.org/html/rfc4646 RFC 4646] & [http://tools.ietf.org/html/rfc4647 RFC 4647]). When available use a 2-letter code from [http://en.wikipedia.org/wiki/ISO_639-1 ISO 639-1 codes] ([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] (e.g. ceb for Cebuano) ([http://www.loc.gov/standards/iso639-2/php/code_list.php registrar]). Failing that, use [http://en.wikipedia.org/wiki/ISO_639-3 ISO 639-3] ([http://www.sil.org/iso639-3/codes.asp registrar]), which covers over 7000 languages, or [http://en.wikipedia.org/wiki/ISO_639-5 ISO 639-5] ([http://www.loc.gov/standards/iso639-5/id.php registrar]) for macrolanguages. The regex for this subtag will be /[a-z]{2,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 [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). The regex for this subtag will be /[A-Z][a-z]{3}/.

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). The regex for this subtag will be /[A-Z]{2}/

Individual subtags (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. Private use extensions defined by BCP 47 (e.g. x-, qaa, and Qaaa) should be avoided wherever possible.
| en
|  
|-
| InstallSize
| <integer (indicating bytes)>
|  
|  
|-
| SwordVersionDate
| <ISO date string (yyyy-mm-dd)>
Indicates the date that the module was changed.
|  
|  
|-
| Obsoletes
| <name of module> 
Each instance of this element names a module that is made obsolete by this module, usually indicated by the former name of the module.
|  
| Repeats
|}

=== Copyright & Licensing related elements ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| Copyright
| <string> 
Contains the copyright notice for the work, including the year of copyright and the owner of the copyright.
|  
| Continuation
|-
| CopyrightHolder
| <string> 
Contains the name of the copyright holder.
|  
|  
|-
| CopyrightDate
| <integer (indicating year)>
|  
|  
|-
| CopyrightNotes
| <string>
|  
| Continuation
|-
| CopyrightContactName
| <string> 
Contains the name of the copyright holder.
|  
| Continuation
|-
| CopyrightContactNotes
| <string>
|  
| Continuation
|-
| CopyrightContactAddress
| <string> 
Contains the mailing address of the copyright holder.
|  
| Continuation
|-
| CopyrightContactEmail
| <string> 
Contains the email address of the copyright holder, preferably in the form: name at xyz dot com.
|  
|  
|-
| ShortPromo
| <string> 
A link to the home page for the module, perhaps with an encouragement to visit the site.
|  
| HTML Link
|-
| ShortCopyright
| <string>
|  
|  
|-
| DistributionLicense
| Public Domain Copyrighted Copyrighted; Permission to distribute granted to CrossWire Copyrighted; Free non-commercial distribution Copyrighted; Freely distributable Copyrighted; Permission granted to distribute non-commercially in Sword format [http://www.gnu.org/copyleft/fdl.html GFDL] [http://www.gnu.org/copyleft/gpl.html GPL] Creative Commons: [http://creativecommons.org/licenses/by-nc-nd by-nc-nd] Creative Commons: [http://creativecommons.org/licenses/by-nc-sa by-nc-sa] Creative Commons: [http://creativecommons.org/licenses/by-nc by-nc] Creative Commons: [http://creativecommons.org/licenses/by-nd by-nd] Creative Commons: [http://creativecommons.org/licenses/by-sa by-sa] Creative Commons: [http://creativecommons.org/licenses/by by] 
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.
|  
|  
|-
| DistributionNotes
| <string> 
Indicates any additional notes about distribution of the module.
|  
| Continuation
|-
| TextSource
| <string, probably a URL> 
Indicates, either in prose (such as "CCEL") or as a URL of the source of the text
|  
| Continuation
|-
| UnlockURL
| <string> 
Contains the URL (a bare URL, not an HTML <a> link) of a web page for unlocking instructions/payment
|  
| URL
|}

== Localization ==

Where it makes sense, the values in the .conf file may be internationalized by appending _lang where lang is replaced by an appropriate code, according to [http://www.rfc-editor.org/rfc/bcp/bcp47.txt BCP 47]. See Lang above for details.

For example, to give a French description, you can have a field:
: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, then 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 ....

The language for .conf entries without the locale modifier is the default and must be the language of the module itself (as specified in Lang=) or English.

'''Notes''':
*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.
*See also [[Localized Language Names]].

[[Category:Development tools|Conf files]]
[[Category:Localization|Conf files]]

DevTools:conf Files

2011-01-24T22:43:27Z

Scribe: /* Elements required for proper rendering */

=Creating a .conf File=
==.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.

Note on RTF, 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.

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

===Required Elements===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| [name]
| Each conf file begins with [name], replacing "name" with a short well known abbreviation for the module (e.g., [KJV]). This must be first in the file. Valid characters for this abbreviation are limited to A-Z, a-z, 0-9 and _. 
The .conf file should be named the lowercase of this abbreviation followed by .conf. For example, [MyModule] would be mymodule.conf.
|  
|  
|-
| 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 for a module named [mymodule], depending on the type of module (Bible text, commentary, lexcon or dictionary, general book) and the data driver used are:

:./modules/texts/rawtext/mymodule/

:./modules/texts/ztext/mymodule/

:./modules/comments/zcom/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

|  
|  
|-
| Description
| <string> 
This is a short (1 line) title of the module.
|  
|  
|-
| ModDrv
| RawText (for uncompressed Bibles) zText (for compressed Bibles) RawCom (for uncompressed Commentaries) RawCom4 (for uncompressed Commentaries having entries greater than 32K bytes) zCom (for compressed Commentaries) 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 32K bytes) zLD (for compressed Dictionaries) RawGenBook (for uncompressed tree keyed modules)
|  
|  
|}

===Elements to indicate features ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| CompressType
| ZIP [http://en.wikipedia.org/wiki/Lempel%E2%80%93Ziv%E2%80%93Storer%E2%80%93Szymanski LZSS]
Used to indicate how a compressed module (zText, zCom, zLD) is compressed.
ZIP is the preferred format.
| LZSS
|  
|-
| BlockType
| BOOK CHAPTER VERSE 
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.
| CHAPTER
|  
|-
| BlockCount
| <integer> 
Used for zLD to indicate the number of entries in a compressed block. Higher values will make the module slower, but smaller.
| 200
|  
|-
| 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 Bible's which do not conform to any supported versification system in SWORd. See [[Alternate_Versification|alternate versification]].
| TreeKey
|  
|-
| CipherKey
| <string> 
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.)
|  
|  
|-
| Versification
|Catholic Catholic2 German KJV KJVA Leningrad Luther MT NRSV NRSVA Synodal SynodalP Vulg

Used to specify the versification employed by a Bible module.
| KJV
|  
|}

=== Elements required for proper rendering ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| GlobalOptionFilter
| GBFStrongs (For GBF texts having Strong's Numbers) 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) ThMLStrongs (For THML texts having Strong's Numbers) 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) UTF8Cantillation (For Hebrew texts having cantillation marks) UTF8GreekAccents (For Greek texts having accents) UTF8HebrewPoints (For Hebrew texts having vowel points) OSISStrongs (For OSIS texts having Strong's Numbers) 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) OSISLemma (For OSIS texts having lemmas) OSISRuby (For Japanese OSIS texts with [http://www.w3.org/TR/ruby/ ruby]: Kana glosses of Han characters) 
Each of these filters removes/hides the text's feature, when activated by the application.
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. crossreferences in notes require both the OSISFootnotes and the OSISScriprefs filters enabled.
|  
| Repeats
|-
| Direction
| LtoR (Left to Right) RtoL (Right to Left) 
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
|  
|-
| SourceType
| Plaintext GBF General Bible Format: http://www.ebible.org/bible/gbf.htm ThML Theological Markup Language: http://www.ccel.org/ThML OSIS Open Scriptural Information Standard: http://www.bibletechnologies.net TEI Text Encoding Initiative: http://www.tei-c.org/P4X/DI.html 
This specifies the *markup* used in the module. The preferred markup is OSIS. TEI is preferred for dictionaries until OSIS supports dictionaries. 
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 Latin-1 (cp1252; see the warning) 
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.
Warning: "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. Front-end implementors should use "cp1252" or "windows1252" explicitly, not "Latin-1" provided by some programming language libraries.
| Latin-1
|  
|-
| DisplayLevel
| <integer>
| 1
|  
|-
| Font
| <string> 
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.
|  
|  
|-
| OSISqToTick
| 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 modules with Strong's number encoded Greek definitions) HebrewDef (for modules with Strong's number encoded Hebrew definitions) GreekParse (for modules with Greek morphology expansions) HebrewParse (for 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)
|  
| Repeats
|-
| GlossaryFrom
| <xml: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
| <xml: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.
|  
|  
|}

=== General informatic and installer elements ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| Abbreviation
| <string> 
A shorter abbreviation which can be displayed instead of the full name. For example, KJV for the King James Version.
| The module name.
|  
|-
| About
| <string> 
A lengthier description and may include copyright, source, etc. information, possibly duplicating information in other elements.
|  
| Continuation RTF
|-
| 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 or 1.1.3.
| 1.0
|  
|-
| History_x.x
| <string> 
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.
|  
| Repeats
|-
| MinimumVersion
| <version string> 
Identifies the minimum version of the Sword library required for this module.
| 1.5.1a
|  
|-
| Category
| Daily Devotional (for modules with Feature=DailyDevotion) Glossaries (for modules with Feature=Glossary) Cults / Unorthodox / Questionable Material Essays (for essays) Maps (for modules that primarily consist of maps) Images (for modules that primarily consist of images) Biblical Texts (for Bibles) Commentaries Lexicons / Dictionaries Generic Books (for anything else....) 
This is used by installers to further categorize the modules beyond what can be figured out by the ModDrv and Feature.
| Biblical Texts (for /(Raw|z)Text4?/) 
Commentaries (for /(Raw|z|HREF)Com4?/) 
Lexicons / Dictionaries (for /(Raw|z)LD4?/ 
Generic Books (for RawGenBook)
|  
|-
| LCSH
| <tree/string> 
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.
|  
|  
|-
| Lang
| <xml:lang identifier> 
This is the primary language code of the module and should include a value according to BCP 47 (i.e. [http://tools.ietf.org/html/rfc4646 RFC 4646] & [http://tools.ietf.org/html/rfc4647 RFC 4647]). When available use a 2-letter code from [http://en.wikipedia.org/wiki/ISO_639-1 ISO 639-1 codes] ([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] (e.g. ceb for Cebuano) ([http://www.loc.gov/standards/iso639-2/php/code_list.php registrar]). Failing that, use [http://en.wikipedia.org/wiki/ISO_639-3 ISO 639-3] ([http://www.sil.org/iso639-3/codes.asp registrar]), which covers over 7000 languages, or [http://en.wikipedia.org/wiki/ISO_639-5 ISO 639-5] ([http://www.loc.gov/standards/iso639-5/id.php registrar]) for macrolanguages. The regex for this subtag will be /[a-z]{2,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 [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). The regex for this subtag will be /[A-Z][a-z]{3}/.

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). The regex for this subtag will be /[A-Z]{2}/

Individual subtags (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. Private use extensions defined by BCP 47 (e.g. x-, qaa, and Qaaa) should be avoided wherever possible.
| en
|  
|-
| InstallSize
| <integer (indicating bytes)>
|  
|  
|-
| SwordVersionDate
| <ISO date string (yyyy-mm-dd)>
Indicates the date that the module was changed.
|  
|  
|-
| Obsoletes
| <name of module> 
Each instance of this element names a module that is made obsolete by this module, usually indicated by the former name of the module.
|  
| Repeats
|}

=== Copyright & Licensing related elements ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| Copyright
| <string> 
Contains the copyright notice for the work, including the year of copyright and the owner of the copyright.
|  
| Continuation
|-
| CopyrightHolder
| <string> 
Contains the name of the copyright holder.
|  
|  
|-
| CopyrightDate
| <integer (indicating year)>
|  
|  
|-
| CopyrightNotes
| <string>
|  
| Continuation
|-
| CopyrightContactName
| <string> 
Contains the name of the copyright holder.
|  
| Continuation
|-
| CopyrightContactNotes
| <string>
|  
| Continuation
|-
| CopyrightContactAddress
| <string> 
Contains the mailing address of the copyright holder.
|  
| Continuation
|-
| CopyrightContactEmail
| <string> 
Contains the email address of the copyright holder, preferably in the form: name at xyz dot com.
|  
|  
|-
| ShortPromo
| <string> 
A link to the home page for the module, perhaps with an encouragement to visit the site.
|  
| HTML Link
|-
| ShortCopyright
| <string>
|  
|  
|-
| DistributionLicense
| Public Domain Copyrighted Copyrighted; Permission to distribute granted to CrossWire Copyrighted; Free non-commercial distribution Copyrighted; Freely distributable Copyrighted; Permission granted to distribute non-commercially in Sword format [http://www.gnu.org/copyleft/fdl.html GFDL] [http://www.gnu.org/copyleft/gpl.html GPL] Creative Commons: [http://creativecommons.org/licenses/by-nc-nd by-nc-nd] Creative Commons: [http://creativecommons.org/licenses/by-nc-sa by-nc-sa] Creative Commons: [http://creativecommons.org/licenses/by-nc by-nc] Creative Commons: [http://creativecommons.org/licenses/by-nd by-nd] Creative Commons: [http://creativecommons.org/licenses/by-sa by-sa] Creative Commons: [http://creativecommons.org/licenses/by by] 
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.
|  
|  
|-
| DistributionNotes
| <string> 
Indicates any additional notes about distribution of the module.
|  
| Continuation
|-
| TextSource
| <string, probably a URL> 
Indicates, either in prose (such as "CCEL") or as a URL of the source of the text
|  
| Continuation
|-
| UnlockURL
| <string> 
Contains the URL (a bare URL, not an HTML <a> link) of a web page for unlocking instructions/payment
|  
| URL
|}

== Localization ==

Where it makes sense, the values in the .conf file may be internationalized by appending _lang where lang is replaced by an appropriate code, according to [http://www.rfc-editor.org/rfc/bcp/bcp47.txt BCP 47]. See Lang above for details.

For example, to give a French description, you can have a field:
: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, then 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 ....

The language for .conf entries without the locale modifier is the default and must be the language of the module itself (as specified in Lang=) or English.

'''Notes''':
*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.
*See also [[Localized Language Names]].

[[Category:Development tools|Conf files]]
[[Category:Localization|Conf files]]

DevTools:conf Files

2011-01-24T22:35:54Z

Scribe: /* Elements to indicate features */

=Creating a .conf File=
==.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.

Note on RTF, 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.

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

===Required Elements===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| [name]
| Each conf file begins with [name], replacing "name" with a short well known abbreviation for the module (e.g., [KJV]). This must be first in the file. Valid characters for this abbreviation are limited to A-Z, a-z, 0-9 and _. 
The .conf file should be named the lowercase of this abbreviation followed by .conf. For example, [MyModule] would be mymodule.conf.
|  
|  
|-
| 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 for a module named [mymodule], depending on the type of module (Bible text, commentary, lexcon or dictionary, general book) and the data driver used are:

:./modules/texts/rawtext/mymodule/

:./modules/texts/ztext/mymodule/

:./modules/comments/zcom/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

|  
|  
|-
| Description
| <string> 
This is a short (1 line) title of the module.
|  
|  
|-
| ModDrv
| RawText (for uncompressed Bibles) zText (for compressed Bibles) RawCom (for uncompressed Commentaries) RawCom4 (for uncompressed Commentaries having entries greater than 32K bytes) zCom (for compressed Commentaries) 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 32K bytes) zLD (for compressed Dictionaries) RawGenBook (for uncompressed tree keyed modules)
|  
|  
|}

===Elements to indicate features ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| CompressType
| ZIP [http://en.wikipedia.org/wiki/Lempel%E2%80%93Ziv%E2%80%93Storer%E2%80%93Szymanski LZSS]
Used to indicate how a compressed module (zText, zCom, zLD) is compressed.
ZIP is the preferred format.
| LZSS
|  
|-
| BlockType
| BOOK CHAPTER VERSE 
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.
| CHAPTER
|  
|-
| BlockCount
| <integer> 
Used for zLD to indicate the number of entries in a compressed block. Higher values will make the module slower, but smaller.
| 200
|  
|-
| 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 Bible's which do not conform to any supported versification system in SWORd. See [[Alternate_Versification|alternate versification]].
| TreeKey
|  
|-
| CipherKey
| <string> 
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.)
|  
|  
|-
| Versification
|Catholic Catholic2 German KJV KJVA Leningrad Luther MT NRSV NRSVA Synodal SynodalP Vulg

Used to specify the versification employed by a Bible module.
| KJV
|  
|}

=== Elements required for proper rendering ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| GlobalOptionFilter
| GBFStrongs (For GBF texts having Strong's Numbers) 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) ThMLStrongs (For THML texts having Strong's Numbers) 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) UTF8Cantillation (For Hebrew texts having cantillation marks) UTF8GreekAccents (For Greek texts having accents) UTF8HebrewPoints (For Hebrew texts having vowel points) OSISStrongs (For OSIS texts having Strong's Numbers) 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) OSISLemma (For OSIS texts having lemmas) OSISRuby (For Japanese OSIS texts with [http://www.w3.org/TR/ruby/ ruby]: Kana glosses of Han characters) 
Each of these filters removes/hides the text's feature, when activated by the application.
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. crossreferences in notes require both the OSISFootnotes and the OSISScriprefs filters enabled.
|  
| Repeats
|-
| Direction
| LtoR (Left to Right) RtoL (Right to Left) 
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
|  
|-
| SourceType
| Plaintext GBF General Bible Format: http://www.ebible.org/bible/gbf.htm ThML Theological Markup Language: http://www.ccel.org/ThML OSIS Open Scriptural Information Standard: http://www.bibletechnologies.net TEI Text Encoding Initiative: http://www.tei-c.org/P4X/DI.html 
These are various ways that the text can be encoded. The preferred encoding is OSIS. TEI is preferred for dictionaries until OSIS supports dictionaries. 
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 Latin-1 (cp1252; see the warning) 
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.
Warning: "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. Front-end implementors should use "cp1252" or "windows1252" explicitly, not "Latin-1" provided by some programming language libraries.
| Latin-1
|  
|-
| DisplayLevel
| <integer>
| 1
|  
|-
| Font
| <string> 
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.
|  
|  
|-
| OSISqToTick
| 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 modules with Strong's number encoded Greek definitions) HebrewDef (for modules with Strong's number encoded Hebrew definitions) GreekParse (for modules with Greek morphology expansions) HebrewParse (for 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)
|  
| Repeats
|-
| GlossaryFrom
| <xml: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
| <xml: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.
|  
|  
|}

=== General informatic and installer elements ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| Abbreviation
| <string> 
A shorter abbreviation which can be displayed instead of the full name. For example, KJV for the King James Version.
| The module name.
|  
|-
| About
| <string> 
A lengthier description and may include copyright, source, etc. information, possibly duplicating information in other elements.
|  
| Continuation RTF
|-
| 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 or 1.1.3.
| 1.0
|  
|-
| History_x.x
| <string> 
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.
|  
| Repeats
|-
| MinimumVersion
| <version string> 
Identifies the minimum version of the Sword library required for this module.
| 1.5.1a
|  
|-
| Category
| Daily Devotional (for modules with Feature=DailyDevotion) Glossaries (for modules with Feature=Glossary) Cults / Unorthodox / Questionable Material Essays (for essays) Maps (for modules that primarily consist of maps) Images (for modules that primarily consist of images) Biblical Texts (for Bibles) Commentaries Lexicons / Dictionaries Generic Books (for anything else....) 
This is used by installers to further categorize the modules beyond what can be figured out by the ModDrv and Feature.
| Biblical Texts (for /(Raw|z)Text4?/) 
Commentaries (for /(Raw|z|HREF)Com4?/) 
Lexicons / Dictionaries (for /(Raw|z)LD4?/ 
Generic Books (for RawGenBook)
|  
|-
| LCSH
| <tree/string> 
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.
|  
|  
|-
| Lang
| <xml:lang identifier> 
This is the primary language code of the module and should include a value according to BCP 47 (i.e. [http://tools.ietf.org/html/rfc4646 RFC 4646] & [http://tools.ietf.org/html/rfc4647 RFC 4647]). When available use a 2-letter code from [http://en.wikipedia.org/wiki/ISO_639-1 ISO 639-1 codes] ([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] (e.g. ceb for Cebuano) ([http://www.loc.gov/standards/iso639-2/php/code_list.php registrar]). Failing that, use [http://en.wikipedia.org/wiki/ISO_639-3 ISO 639-3] ([http://www.sil.org/iso639-3/codes.asp registrar]), which covers over 7000 languages, or [http://en.wikipedia.org/wiki/ISO_639-5 ISO 639-5] ([http://www.loc.gov/standards/iso639-5/id.php registrar]) for macrolanguages. The regex for this subtag will be /[a-z]{2,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 [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). The regex for this subtag will be /[A-Z][a-z]{3}/.

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). The regex for this subtag will be /[A-Z]{2}/

Individual subtags (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. Private use extensions defined by BCP 47 (e.g. x-, qaa, and Qaaa) should be avoided wherever possible.
| en
|  
|-
| InstallSize
| <integer (indicating bytes)>
|  
|  
|-
| SwordVersionDate
| <ISO date string (yyyy-mm-dd)>
Indicates the date that the module was changed.
|  
|  
|-
| Obsoletes
| <name of module> 
Each instance of this element names a module that is made obsolete by this module, usually indicated by the former name of the module.
|  
| Repeats
|}

=== Copyright & Licensing related elements ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| Copyright
| <string> 
Contains the copyright notice for the work, including the year of copyright and the owner of the copyright.
|  
| Continuation
|-
| CopyrightHolder
| <string> 
Contains the name of the copyright holder.
|  
|  
|-
| CopyrightDate
| <integer (indicating year)>
|  
|  
|-
| CopyrightNotes
| <string>
|  
| Continuation
|-
| CopyrightContactName
| <string> 
Contains the name of the copyright holder.
|  
| Continuation
|-
| CopyrightContactNotes
| <string>
|  
| Continuation
|-
| CopyrightContactAddress
| <string> 
Contains the mailing address of the copyright holder.
|  
| Continuation
|-
| CopyrightContactEmail
| <string> 
Contains the email address of the copyright holder, preferably in the form: name at xyz dot com.
|  
|  
|-
| ShortPromo
| <string> 
A link to the home page for the module, perhaps with an encouragement to visit the site.
|  
| HTML Link
|-
| ShortCopyright
| <string>
|  
|  
|-
| DistributionLicense
| Public Domain Copyrighted Copyrighted; Permission to distribute granted to CrossWire Copyrighted; Free non-commercial distribution Copyrighted; Freely distributable Copyrighted; Permission granted to distribute non-commercially in Sword format [http://www.gnu.org/copyleft/fdl.html GFDL] [http://www.gnu.org/copyleft/gpl.html GPL] Creative Commons: [http://creativecommons.org/licenses/by-nc-nd by-nc-nd] Creative Commons: [http://creativecommons.org/licenses/by-nc-sa by-nc-sa] Creative Commons: [http://creativecommons.org/licenses/by-nc by-nc] Creative Commons: [http://creativecommons.org/licenses/by-nd by-nd] Creative Commons: [http://creativecommons.org/licenses/by-sa by-sa] Creative Commons: [http://creativecommons.org/licenses/by by] 
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.
|  
|  
|-
| DistributionNotes
| <string> 
Indicates any additional notes about distribution of the module.
|  
| Continuation
|-
| TextSource
| <string, probably a URL> 
Indicates, either in prose (such as "CCEL") or as a URL of the source of the text
|  
| Continuation
|-
| UnlockURL
| <string> 
Contains the URL (a bare URL, not an HTML <a> link) of a web page for unlocking instructions/payment
|  
| URL
|}

== Localization ==

Where it makes sense, the values in the .conf file may be internationalized by appending _lang where lang is replaced by an appropriate code, according to [http://www.rfc-editor.org/rfc/bcp/bcp47.txt BCP 47]. See Lang above for details.

For example, to give a French description, you can have a field:
: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, then 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 ....

The language for .conf entries without the locale modifier is the default and must be the language of the module itself (as specified in Lang=) or English.

'''Notes''':
*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.
*See also [[Localized Language Names]].

[[Category:Development tools|Conf files]]
[[Category:Localization|Conf files]]

DevTools:conf Files

2011-01-24T22:32:29Z

Scribe: /* Elements to indicate features */

=Creating a .conf File=
==.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.

Note on RTF, 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.

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

===Required Elements===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| [name]
| Each conf file begins with [name], replacing "name" with a short well known abbreviation for the module (e.g., [KJV]). This must be first in the file. Valid characters for this abbreviation are limited to A-Z, a-z, 0-9 and _. 
The .conf file should be named the lowercase of this abbreviation followed by .conf. For example, [MyModule] would be mymodule.conf.
|  
|  
|-
| 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 for a module named [mymodule], depending on the type of module (Bible text, commentary, lexcon or dictionary, general book) and the data driver used are:

:./modules/texts/rawtext/mymodule/

:./modules/texts/ztext/mymodule/

:./modules/comments/zcom/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

|  
|  
|-
| Description
| <string> 
This is a short (1 line) title of the module.
|  
|  
|-
| ModDrv
| RawText (for uncompressed Bibles) zText (for compressed Bibles) RawCom (for uncompressed Commentaries) RawCom4 (for uncompressed Commentaries having entries greater than 32K bytes) zCom (for compressed Commentaries) 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 32K bytes) zLD (for compressed Dictionaries) RawGenBook (for uncompressed tree keyed modules)
|  
|  
|}

===Elements to indicate features ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| CompressType
| ZIP [http://en.wikipedia.org/wiki/Lempel%E2%80%93Ziv%E2%80%93Storer%E2%80%93Szymanski LZSS]
Used to indicate how a compressed module (zText, zCom, zLD) is compressed.
ZIP is the preferred format.
| LZSS
|  
|-
| BlockType
| BOOK CHAPTER VERSE 
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.
| CHAPTER
|  
|-
| BlockCount
| <integer> 
Used for zLD to indicate the number of entries in a compressed block. Higher values will make the module slower, but smaller.
| 200
|  
|-
| KeyType
| TreeKey VerseKey 
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|alternate versification]].
| TreeKey
|  
|-
| CipherKey
| <string> 
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.)
|  
|  
|-
| Versification
|Catholic Catholic2 German KJV KJVA Leningrad Luther MT NRSV NRSVA Synodal SynodalP Vulg

Used to specify the versification employed by a Bible module.
| KJV
|  
|}

=== Elements required for proper rendering ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| GlobalOptionFilter
| GBFStrongs (For GBF texts having Strong's Numbers) 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) ThMLStrongs (For THML texts having Strong's Numbers) 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) UTF8Cantillation (For Hebrew texts having cantillation marks) UTF8GreekAccents (For Greek texts having accents) UTF8HebrewPoints (For Hebrew texts having vowel points) OSISStrongs (For OSIS texts having Strong's Numbers) 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) OSISLemma (For OSIS texts having lemmas) OSISRuby (For Japanese OSIS texts with [http://www.w3.org/TR/ruby/ ruby]: Kana glosses of Han characters) 
Each of these filters removes/hides the text's feature, when activated by the application.
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. crossreferences in notes require both the OSISFootnotes and the OSISScriprefs filters enabled.
|  
| Repeats
|-
| Direction
| LtoR (Left to Right) RtoL (Right to Left) 
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
|  
|-
| SourceType
| Plaintext GBF General Bible Format: http://www.ebible.org/bible/gbf.htm ThML Theological Markup Language: http://www.ccel.org/ThML OSIS Open Scriptural Information Standard: http://www.bibletechnologies.net TEI Text Encoding Initiative: http://www.tei-c.org/P4X/DI.html 
These are various ways that the text can be encoded. The preferred encoding is OSIS. TEI is preferred for dictionaries until OSIS supports dictionaries. 
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 Latin-1 (cp1252; see the warning) 
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.
Warning: "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. Front-end implementors should use "cp1252" or "windows1252" explicitly, not "Latin-1" provided by some programming language libraries.
| Latin-1
|  
|-
| DisplayLevel
| <integer>
| 1
|  
|-
| Font
| <string> 
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.
|  
|  
|-
| OSISqToTick
| 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 modules with Strong's number encoded Greek definitions) HebrewDef (for modules with Strong's number encoded Hebrew definitions) GreekParse (for modules with Greek morphology expansions) HebrewParse (for 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)
|  
| Repeats
|-
| GlossaryFrom
| <xml: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
| <xml: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.
|  
|  
|}

=== General informatic and installer elements ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| Abbreviation
| <string> 
A shorter abbreviation which can be displayed instead of the full name. For example, KJV for the King James Version.
| The module name.
|  
|-
| About
| <string> 
A lengthier description and may include copyright, source, etc. information, possibly duplicating information in other elements.
|  
| Continuation RTF
|-
| 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 or 1.1.3.
| 1.0
|  
|-
| History_x.x
| <string> 
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.
|  
| Repeats
|-
| MinimumVersion
| <version string> 
Identifies the minimum version of the Sword library required for this module.
| 1.5.1a
|  
|-
| Category
| Daily Devotional (for modules with Feature=DailyDevotion) Glossaries (for modules with Feature=Glossary) Cults / Unorthodox / Questionable Material Essays (for essays) Maps (for modules that primarily consist of maps) Images (for modules that primarily consist of images) Biblical Texts (for Bibles) Commentaries Lexicons / Dictionaries Generic Books (for anything else....) 
This is used by installers to further categorize the modules beyond what can be figured out by the ModDrv and Feature.
| Biblical Texts (for /(Raw|z)Text4?/) 
Commentaries (for /(Raw|z|HREF)Com4?/) 
Lexicons / Dictionaries (for /(Raw|z)LD4?/ 
Generic Books (for RawGenBook)
|  
|-
| LCSH
| <tree/string> 
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.
|  
|  
|-
| Lang
| <xml:lang identifier> 
This is the primary language code of the module and should include a value according to BCP 47 (i.e. [http://tools.ietf.org/html/rfc4646 RFC 4646] & [http://tools.ietf.org/html/rfc4647 RFC 4647]). When available use a 2-letter code from [http://en.wikipedia.org/wiki/ISO_639-1 ISO 639-1 codes] ([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] (e.g. ceb for Cebuano) ([http://www.loc.gov/standards/iso639-2/php/code_list.php registrar]). Failing that, use [http://en.wikipedia.org/wiki/ISO_639-3 ISO 639-3] ([http://www.sil.org/iso639-3/codes.asp registrar]), which covers over 7000 languages, or [http://en.wikipedia.org/wiki/ISO_639-5 ISO 639-5] ([http://www.loc.gov/standards/iso639-5/id.php registrar]) for macrolanguages. The regex for this subtag will be /[a-z]{2,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 [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). The regex for this subtag will be /[A-Z][a-z]{3}/.

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). The regex for this subtag will be /[A-Z]{2}/

Individual subtags (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. Private use extensions defined by BCP 47 (e.g. x-, qaa, and Qaaa) should be avoided wherever possible.
| en
|  
|-
| InstallSize
| <integer (indicating bytes)>
|  
|  
|-
| SwordVersionDate
| <ISO date string (yyyy-mm-dd)>
Indicates the date that the module was changed.
|  
|  
|-
| Obsoletes
| <name of module> 
Each instance of this element names a module that is made obsolete by this module, usually indicated by the former name of the module.
|  
| Repeats
|}

=== Copyright & Licensing related elements ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| Copyright
| <string> 
Contains the copyright notice for the work, including the year of copyright and the owner of the copyright.
|  
| Continuation
|-
| CopyrightHolder
| <string> 
Contains the name of the copyright holder.
|  
|  
|-
| CopyrightDate
| <integer (indicating year)>
|  
|  
|-
| CopyrightNotes
| <string>
|  
| Continuation
|-
| CopyrightContactName
| <string> 
Contains the name of the copyright holder.
|  
| Continuation
|-
| CopyrightContactNotes
| <string>
|  
| Continuation
|-
| CopyrightContactAddress
| <string> 
Contains the mailing address of the copyright holder.
|  
| Continuation
|-
| CopyrightContactEmail
| <string> 
Contains the email address of the copyright holder, preferably in the form: name at xyz dot com.
|  
|  
|-
| ShortPromo
| <string> 
A link to the home page for the module, perhaps with an encouragement to visit the site.
|  
| HTML Link
|-
| ShortCopyright
| <string>
|  
|  
|-
| DistributionLicense
| Public Domain Copyrighted Copyrighted; Permission to distribute granted to CrossWire Copyrighted; Free non-commercial distribution Copyrighted; Freely distributable Copyrighted; Permission granted to distribute non-commercially in Sword format [http://www.gnu.org/copyleft/fdl.html GFDL] [http://www.gnu.org/copyleft/gpl.html GPL] Creative Commons: [http://creativecommons.org/licenses/by-nc-nd by-nc-nd] Creative Commons: [http://creativecommons.org/licenses/by-nc-sa by-nc-sa] Creative Commons: [http://creativecommons.org/licenses/by-nc by-nc] Creative Commons: [http://creativecommons.org/licenses/by-nd by-nd] Creative Commons: [http://creativecommons.org/licenses/by-sa by-sa] Creative Commons: [http://creativecommons.org/licenses/by by] 
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.
|  
|  
|-
| DistributionNotes
| <string> 
Indicates any additional notes about distribution of the module.
|  
| Continuation
|-
| TextSource
| <string, probably a URL> 
Indicates, either in prose (such as "CCEL") or as a URL of the source of the text
|  
| Continuation
|-
| UnlockURL
| <string> 
Contains the URL (a bare URL, not an HTML <a> link) of a web page for unlocking instructions/payment
|  
| URL
|}

== Localization ==

Where it makes sense, the values in the .conf file may be internationalized by appending _lang where lang is replaced by an appropriate code, according to [http://www.rfc-editor.org/rfc/bcp/bcp47.txt BCP 47]. See Lang above for details.

For example, to give a French description, you can have a field:
: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, then 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 ....

The language for .conf entries without the locale modifier is the default and must be the language of the module itself (as specified in Lang=) or English.

'''Notes''':
*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.
*See also [[Localized Language Names]].

[[Category:Development tools|Conf files]]
[[Category:Localization|Conf files]]