Difference between revisions of "DevTools:conf Files"
David Haslam (talk | contribs) |
(→Copyright & Licensing related elements) |
||
| (6 intermediate revisions by one other user not shown) | |||
| Line 428: | Line 428: | ||
|- | |- | ||
| History_x.x | | History_x.x | ||
| − | | '''<string>'''<br/> | + | | '''<string>'''<ref>Maximum line length is 1024 characters!</ref><br/> |
x.x is taken from the Version value. | x.x is taken from the Version value. | ||
| Line 655: | Line 655: | ||
| | | | ||
| [[DevTools:conf Files#Continuation|Continuation]]<br/>[[DevTools:conf Files#Localization|Localization]] | | [[DevTools:conf Files#Continuation|Continuation]]<br/>[[DevTools:conf Files#Localization|Localization]] | ||
| − | |- | + | |- id="txtsrc" |
| TextSource | | TextSource | ||
| | | | ||
| Line 685: | Line 685: | ||
</pre>Some other module providers and repositories are already moving in the same direction. | </pre>Some other module providers and repositories are already moving in the same direction. | ||
| − | == Uniqueness == | + | == 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 <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 [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. | 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 == | + | === Analysis Tools === |
* [[User:Dmsmith|DMSmith]] and [[User:Domcox|Domcox]] have created scripts to analyse conf files and report anomalies. | * [[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]. | * [[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 == | == Automated generation == | ||
| − | * For new module submissions to CrossWire, [[User: | + | * 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 == | == See also == | ||
Latest revision as of 06:22, 20 February 2024
This page describes important information about module configuration (.conf) files. All SWORD modules require one.
Please look also at our detailed and commented tutorial.
Contents
- 1 Key elements of a SWORD module.conf
- 2 Further details
- 3 Automated generation
- 4 See also
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
| Element | Values (type or enumerated) | Default Value | 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 PCRE class [A-Za-z0-9_].[1] The Abbreviation element is meant to allow for localization of this field. |
||
| Abbreviation[2] |
<string> |
[ModName] | Localization |
| Description |
<string> |
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
|
||
| ModDrv |
RawText (for uncompressed Bibles) |
- ↑ That excludes the space and hyphen characters!
- ↑ We advise against explicitly declaring a redundant Abbreviation identical to the ModName. Abbreviation values should try to be unique to avoid user confusion.
- ↑ Daily devotionals & glossaries go in subdirectories under lexdict. A glossary is between two languages.
- ↑ 4.0 4.1 e.g. If the Bible contains large introduction sections
- ↑ 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
| Element | Values (type or enumerated) | Default Value | Allows |
|---|---|---|---|
| SourceType[1] |
Plaintext Legacy modules may have a key here stating: GBF (General Bible Format) 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 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. |
Latin-1 | |
| CompressType |
ZIP |
LZSS | |
| BlockType |
BOOK |
CHAPTER | |
| BlockCount |
<integer> |
200 | |
| Versification |
Calvin |
KJV | |
| CipherKey |
<string> 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 |
TreeKey | |
| CaseSensitiveKeys |
Used for Dictionaries whose keys are case sensitive. This key is used to suppress normalization to UPPER CASE before comparison. |
false |
- ↑ Omitting this for a non-plaintext module has unpredictable effects.
- ↑ Unicode normalization can easily break Biblical Hebrew text. See on page 9 in the SBL Hebrew Font User Manual.
- ↑ e.g. If they are mentioned in Table 10 in the Corrigendum 5 Sequences.
- ↑ The improper normalization of exceptional codepoints can be prevented by inserting a Combining Grapheme Joiner.
- ↑ i.e. Specify this only for a module that uses VerseKey.
Elements required for proper rendering
| Element | Values (type or enumerated) | Default Value | Allows |
|---|---|---|---|
| GlobalOptionFilter |
UTF8Cantillation (For Hebrew texts having cantillation marks)[1] 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[16] (For OSIS texts with glosses)[17] |
Repeats | |
| Direction |
LtoR (Left to Right) |
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 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. |
||
| |
This attribute is deprecated in favor of the marker attribute on the q element. E.g.: <q who="Jesus" marker="">....</q>
|
true | |
| Feature |
StrongsNumbers (for modules that include Strong's numbers) |
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. |
- ↑ See https://en.wikipedia.org/wiki/Cantillation
- ↑ For detailed background, see https://en.wikipedia.org/wiki/Greek_diacritics
- ↑ This filter can have undesirable side-effects when applied to non-Greek text!
- ↑ See https://en.wikipedia.org/wiki/Niqqud
- ↑ See https://en.wikipedia.org/wiki/Arabic_diacritics
- ↑ Must precede OSISStrongs.
- ↑ 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.
- ↑ 8.0 8.1 8.2 See https://en.wikipedia.org/wiki/Strong%27s_Concordance#Strong.27s_numbers
- ↑ 9.0 9.1 See https://en.wikipedia.org/wiki/Red_letter_edition
- ↑ Minimum SWORD version of 1.7.0 in the module .conf is required for OSISGlosses.
- ↑ The Samaritan Pentateuch module SP is an example of using xlit.
- ↑ The Samaritan Pentateuch module SP is an example of using enum.
- ↑ 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:
- "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")
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:
- 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 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:
- ↑ 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
| Element | Values (type or enumerated) | Default Value | Allows |
|---|---|---|---|
| About |
<string> |
Continuation RTF Localization | |
| SwordVersionDate |
<yyyy-mm-dd> (ISO 8601 Date) |
||
| Version |
<version string> 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>[1] 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 Localization | |
| MinimumVersion[2] |
<version string> |
1.5.1a | |
| Category |
This is used by installers to further categorize the modules beyond what can be figured out by the ModDrv and Feature. |
Biblical Texts |
|
| 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 |
<Language[-Script]?[-Region]?> Language sub-tag (Regex: /[a-z]{2,3}/):
The ISO639-3 registrar page gives up-to-date table on all of the above. Script sub-tag (Regex: /[A-Z][a-z]{3}/): Region sub-tag: (Regex: /[A-Z]{2}/) Combinations(Regex: /[a-z]{2,3}(-[A-Z][a-z]{3})?(-[A-Z]{2})?/): |
en | |
| InstallSize |
<integer> For modules in the CrossWire repositories, this is automatically generated and overwritten if needed. |
||
| Obsoletes |
<ModName> |
Repeats | |
| OSISVersion |
<version string> It is recommended that this be present for every OSIS module. |
||
| Companion[5] |
<ModName[, ModName]*> |
Note:
- ↑ Maximum line length is 1024 characters!
- ↑ See http://tracker.crosswire.org/browse/API-201
- ↑ Required to support a Bible/Commentary module that has an Alternate Versification.
- ↑ Essays is handled as a subset of Generic Books.
- ↑ Many (xulsword compatible) modules in the IBT Repository make use of this field. See also https://github.com/johnaustindev/osis-converters
| Element | Values (type or enumerated) | Default Value | Allows |
|---|---|---|---|
| Copyright |
<string> |
Continuation Localization | |
| CopyrightHolder |
<string> |
Localization | |
| CopyrightDate |
<yyyy> (ISO 8601 Year) |
Localization | |
| CopyrightNotes |
<string> |
Continuation Localization | |
| CopyrightContactName |
<string> |
Continuation Localization | |
| CopyrightContactNotes |
<string> |
Continuation Localization | |
| CopyrightContactAddress |
<string> |
Continuation Localization | |
| CopyrightContactEmail |
<string> |
Localization | |
| ShortPromo |
<string> |
HTML Link Localization | |
| ShortCopyright |
<string> |
Localization | |
| DistributionLicense |
Public Domain |
||
| DistributionNotes |
<string> |
Continuation Localization | |
| TextSource |
<string> |
Continuation | |
| UnlockInfo |
<string> |
RTF Continuation Localization HTML Link |
Note:
- ↑ Modules in other repositories may have a different organization name instead of CrossWire.
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.
## Sword module configuration file ## Required elements # Module Unique Identifier. [GerMenge] ...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 <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 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
- DMSmith and Domcox have created scripts 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, 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.
