Difference between revisions of "DevTools:conf Files"

From CrossWire Bible Society
Jump to: navigation, search
(Elements required for proper rendering)
(Elements to indicate features)
Line 125: Line 125:
| Scope<ref>Proposed. Name and definition may change.</ref>
| <del>Scope</del> (proposed)
| &lt;osisRef&gt;<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><br/>Indicates that the versification is limited to subset of its books, chapters and/or verses.
| &lt;osisRef&gt;<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><br/>Indicates that the versification is limited to subset of its books, chapters and/or verses.

Revision as of 06:07, 18 October 2012

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

Element Values (type or enumerated) Default Value 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:

Description <string>

This is a short (1 line) title of the module.[1]

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)
  1. If a continuation line is really needed, some front-ends may support the HTML break element <BR>

Elements to indicate features

Element Values (type or enumerated) Default Value Allows
CompressType ZIP

Used to indicate how a compressed module (zText, zCom, zLD) is compressed. ZIP is the preferred format.

BlockType BOOK

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.

BlockCount <integer>

Used for zLD to indicate the number of entries in a compressed block. Higher values will make the module slower, but smaller.

KeyType TreeKey

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.

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[1] Catholic
Scope (proposed) <osisRef>[2]
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.

To leave out deuterocanonical material from Synodal use the following:
Gen-Josh.4.33 Judg-2Chr Ezra Neh Esth-Ps.150 Prov.0[3]-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:

  1. Used to specify the versification employed by a Bible module. Refer to Alternate Versification.
  2. 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.
  3. 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.
  4. 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.

Elements required for proper rendering

Element Values (type or enumerated) Default Value 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.

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 bi-directional). If the RtoL script is transliterated into a LtoR script, set the value to 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.

Encoding UTF-8
Latin-1 (cp1252; see the warning)

The preferred encoding of texts is UTF-8. UTF-8 modules must be encoded with Normalization Form C (NFC). Latin-1 is defined by 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 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.

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.

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 (deprecated)[1] This attribute is deprecated in favor of the marker attribute on the q element. E.g.:
<q who="Jesus" marker="">....</q>

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.

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

  1. For further details, refer to MOD-188 in CrossWire bugs.

General informatic and installer elements

Element Values (type or enumerated) Default Value 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.

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.

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.

MinimumVersion <version string>

Identifies the minimum version of the SWORD library required for this module.

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)
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 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. RFC 4646 & RFC 4647). When available use a 2-letter code from ISO 639-1 codes (registrar), (e.g. en for English). If there is none for the given language, use an ISO 639-2/T code (e.g. ceb for Cebuano) (registrar). Failing that, use ISO 639-3 (registrar), which covers over 7000 languages, or ISO 639-5 (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 ISO 15924 script code (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 ISO 3166-1 region code (registrar) after the script code (or language code if no country code is present) (e.g. en-GB for UK English). 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.

InstallSize[1] <integer (indicating bytes)>[2]    
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.

OSISVersion <version string>[3]

Identifies the OSIS schema version employed in the OSIS source document.

  1. This item in generated automatically within CrossWire by the script used to prepare modules for hosting in our repositories.
  2. Excludes the size of any Lucene index.
  3. e.g. OSISVersion=2.1.1

Copyright & Licensing related elements

Element Values (type or enumerated) Default Value Allows
Copyright <string>

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

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.

CopyrightContactNotes <string>   Continuation
CopyrightContactAddress <string>

Contains the mailing address of the copyright holder.

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; Permission to distribute granted to CrossWire
Copyrighted; Free non-commercial distribution
Copyrighted; Freely distributable
Copyrighted; Permission granted to distribute non-commercially in SWORD format
Creative Commons: by-nc-nd
Creative Commons: by-nc-sa
Creative Commons: by-nc
Creative Commons: by-nd
Creative Commons: by-sa
Creative Commons: by
Creative Commons: CC0

Use one of these strings verbatim. The actual copyright and/or license information is held in other elements. The last six licenses are Creative Commons licenses.

DistributionNotes <string>

Indicates any additional notes about distribution of the module.

TextSource <string, probably a URL>

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

UnlockURL <string>

Contains the URL (a bare URL, not an HTML <a> link) of a web page for unlocking instructions/payment



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.


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

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


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:


Script variants can be given as in:

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

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


  1. 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.
  2. See also Localized Language Names.