Difference between revisions of "DevTools:conf Files"

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.

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

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

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

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

./modules/texts/rawtext/mymodule/

./modules/texts/rawtext4/mymodule/

./modules/texts/ztext/mymodule/

./modules/texts/ztext4/mymodule/

./modules/comments/zcom/mymodule/

./modules/comments/zcom4/mymodule/

./modules/comments/hrefcom/mymodule/

./modules/comments/rawcom/mymodule/

./modules/comments/rawcom4/mymodule/

./modules/comments/rawfiles/mymodule/

./modules/lexdict/zld/mymodule/mymodule

./modules/lexdict/rawld/mymodule/mymodule

./modules/lexdict/rawld/devotionals/mymodule/mymodule

./modules/lexdict/rawld/glossaries/mymodule/mymodule

./modules/lexdict/rawld4/mymodule/mymodule

./modules/genbook/rawgenbook/mymodule/mymodule

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

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

Legacy modules may have a key here stating:

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

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

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

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

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

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

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.

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

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.

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

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.

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

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

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

Legacy modules may also have following keys:

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

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

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.

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

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

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

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^[21])

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

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

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.

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

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

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

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.

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

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)^[3]

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

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.

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

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

When available use a 2-letter ISO 639-1 code (registrar), (e.g. en for English).

If there is none for the given language, use an ISO 639-2/T code (registrar) (e.g. ceb for Cebuano).

Failing that, use a ISO 639-3 code (registrar), which covers over 7000 languages.

Finally, use a ISO 639-5 code (registrar) for macro languages.

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

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

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

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

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

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

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

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

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

<string>
Contains the name of the copyright holder.

<yyyy> (ISO 8601 Year)

<string>

<string>
Contains the name of the copyright holder.

<string>

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

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

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

<string>

Public Domain
Copyrighted
Copyrighted; Permission to distribute granted to CrossWire^[1]
Copyrighted; Free non-commercial distribution
Copyrighted; Freely distributable
Copyrighted; Permission granted to distribute non-commercially in SWORD format
GFDL
GPL
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 seven^[2] licenses are Creative Commons licenses.

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

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

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