Revision as of 10:12, 30 December 2017

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 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 localization: Abbreviation=和合本 Abbreviation_en=ChiUn Description=和合本 (繁體字) Description_en=Chinese Union Version (Traditional)

Some fields can have 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 Byte Order Mark (BOM) at the beginning of the file^[1]

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:

1. ↑ Windows Notepad and Wordpad may silently add these to the file

Continuation

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

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

RTF

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

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

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

Localization

Those .conf fields that are essentially text intended for presentation to the end-user may be localized by appending _locale to the field name, where locale is replaced by an appropriate locale code, according to BCP 47. See Lang 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:

1. 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.
2. 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

1. ↑ That excludes the space and hyphen characters! An invalid ModName can cause some front-ends to crash.
2. ↑ 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.
3. ↑ Daily devotionals & glossaries go in subdirectories under lexdict. A glossary is between two languages.
4. ↑ ^{4.0 4.1} e.g. If the Bible contains large introduction sections
5. ↑ ^{5.0 5.1} zText4 & zCom4 modules require MinimumVersion=1.8 or later. Cite error: Invalid <ref> tag; name "sv" defined multiple times with different content

Required Elements with defaults

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

Elements required for proper rendering

<q who="Jesus" marker="">....</q>

1. ↑ ^{1.0 1.1 1.2} See https://en.wikipedia.org/wiki/Strong%27s_Concordance#Strong.27s_numbers
2. ↑ ^{2.0 2.1} See https://en.wikipedia.org/wiki/Red_letter_edition
3. ↑ See https://en.wikipedia.org/wiki/Cantillation
4. ↑ For detailed background, see https://en.wikipedia.org/wiki/Greek_diacritics
5. ↑ This filter can have undesirable side-effects when applied to non-Greek text!
6. ↑ See https://en.wikipedia.org/wiki/Niqqud
7. ↑ See https://en.wikipedia.org/wiki/Arabic_diacritics
8. ↑ Must precede OSISStrongs.
9. ↑ This filter does not seem to work at all.
10. ↑ Minimum SWORD version of 1.7.0 in the module .conf is required for OSISGlosses.
11. ↑ See Ruby character and Furigana
12. ↑ Deprecated in 1.7.0. Use OSISGlosses instead.
13. ↑ The Samaritan Pentateuch module SP is an example of using xlit.
14. ↑ The Samaritan Pentateuch module SP is an example of using enum.
15. ↑ New in SWORD 1.7.0 - This filter requires six vertical bar-delimited fields, of which the following is an example.

    GlobalOptionFilter=OSISReferenceLinks|Reference Material Links|Hide or show links to study helps in the Biblical text.|x-glossary||On
    

    Here are the different field meanings:

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

Optional elements to support particular features

CaseInsensitiveKeys

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

CaseInsensitiveKeys=true|false

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

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

LangSortOrder=AaBbCcDdEe... 

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

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

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

StrongsPadding

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

StrongsPadding=true|false

Notes:

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

Strip Filters

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

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

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

LocalStripFilter=GBFPlain

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

LocalStripFilter=UTF8ArabicPoints

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

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

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

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

LocalStripFilter=PapyriPlain

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

Note:

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

General informatic and installer elements

Note:

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

Copyright & Licensing related elements

Note:

1. ↑ Modules in other repositories may have a different organization name instead of CrossWire.
2. ↑ Each link goes to a page that no longer exists!

Uniqueness

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

Analysis Tools

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

Automated generation

• For new module submissions to CrossWire, 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.