Tutorial:Writing Conf files

Creating a .conf File

module.conf File Layout

SWORD uses a plain text 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 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

 ; 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

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:

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.