Difference between revisions of "DevTools:conf Files"
m (→Elements required for proper rendering) |
m (fixed a <reference/> without a preceding <ref/>) |
||
| Line 494: | Line 494: | ||
| Continuation<br/>[[DevTools:conf Files#Localization|Localization]] | | Continuation<br/>[[DevTools:conf Files#Localization|Localization]] | ||
|- | |- | ||
| − | | CopyrightContactAddress | + | | CopyrightContactAddress |
| <string><br/> | | <string><br/> | ||
Contains the mailing address of the copyright holder. | Contains the mailing address of the copyright holder. | ||
Revision as of 17:34, 15 March 2015
Creating a .conf File
module.conf File Layout
The module.conf[1] 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.[2]
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 or a hash should be ignored by front-end applications, and treated as a remark or comment line.
Notes:
- ↑ Not to be confused with a locale .conf file for a language.
- ↑ UTF-8 encoded .conf files shall omit the Byte Order Marker (BOM).
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. |
||
| Description | <string> This is a short (1 line) title of the module. |
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 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:
|
||
| ModDrv |
RawText (for uncompressed Bibles) |
Required Elements with defaults
| Element | Values (type or enumerated) | Default Value | Allows |
|---|---|---|---|
| SourceType |
Plaintext |
Plaintext | |
| Encoding |
Latin-1† (Windows Codepage 1252 (cp1252)) The preferred encoding of texts is UTF-8. Other than Hebrew, UTF-8 modules must be encoded with Normalization Form C (NFC). Hebrew requires special handling. To date no module use UTF-16 or SCSU. †Warning: "Latin-1" is an ambiguously used term. Latin-1 is regularly used as a synonym for ISO-8859-1. Here it means Windows Codepage 1252, a superset of ISO-8859-1. Front-end implementors 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 |
Catholic |
KJV | |
| CipherKey | <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. |
||
| KeyType |
TreeKey |
TreeKey |
Elements required for proper rendering
| Element | Values (type or enumerated) | Default Value | Allows |
|---|---|---|---|
| GlobalOptionFilter |
GBFStrongs (For GBF texts having Strong's Numbers) |
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. 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 | <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. |
||
| 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
- ↑ Must precede OSISStrongs.
- ↑ Minimum SWORD version of 1.7.0 in the module .conf is required for OSISGlosses.
- ↑ Deprecated in 1.7.0. Use OSISGlosses instead.
- ↑ 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
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.
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 |
|---|---|---|---|
| Abbreviation[1] | <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[1] | <string> A lengthier description and may include copyright, source, etc. information, possibly duplicating information in other elements. |
Continuation RTF | |
| 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. 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[1] | <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.[2] |
Repeats | |
| MinimumVersion | <version string> Identifies the minimum version of the SWORD library required for this module. |
1.5.1a | |
| 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) Commentaries 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?/) |
|
| 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.[3] 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. See also MultiTree: A Digital Library of Language Relationships. |
en | |
| InstallSize[4] | <integer (indicating bytes)>[5] | ||
| 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. |
Repeats | |
| OSISVersion | <version string>[6] Identifies the OSIS schema version employed in the OSIS source document. |
||
| Companion | <module_name> Specifies companion module(s) (comma-separated list) that should be opened together e.g. When Bible and Commentary modules are distributed together. |
- ↑ 1.0 1.1 1.2 Localizable: see Localization
- ↑ It's good practice to mention the release date in the History_x.x property, so that revision history is fully traceable by date.
Ideally, that should be done even for a first release, to minimize the risk that a subsequent update would leave the original date unknown. - ↑ 2013-01-25 JSword does not yet support language code subtags.
- ↑ This item in generated automatically within CrossWire by the script used to prepare modules for hosting in our repositories.
- ↑ Excludes the size of any Lucene index.
- ↑ e.g. OSISVersion=2.1.1
| 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. |
Continuation Localization | |
| CopyrightHolder | <string> Contains the name of the copyright holder. |
Localization | |
| CopyrightDate | <integer (indicating year)> | Localization | |
| CopyrightNotes | <string> | Continuation Localization | |
| CopyrightContactName | <string> Contains the name of the copyright holder. |
Continuation Localization | |
| CopyrightContactNotes | <string> | Continuation Localization | |
| CopyrightContactAddress | <string> Contains the mailing address of the copyright holder. |
Continuation Localization | |
| CopyrightContactEmail | <string> Contains the email address of the copyright holder, preferably in the form: |
Localization | |
| ShortPromo | <string> A link to the home page for the module, perhaps with an encouragement to visit the site. |
HTML Link Localization | |
| ShortCopyright | <string> | Localization | |
| DistributionLicense | Public Domain Copyrighted 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 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 six licenses are Creative Commons licenses. |
||
| DistributionNotes | <string> Indicates any additional notes about distribution of the module. |
Continuation Localization | |
| TextSource | <string, probably a URL> Indicates, either in prose (such as "CCEL") or as a URL of the source of the text |
Continuation | |
| UnlockURL | <string> Contains the URL (a bare URL, not an HTML <a> link) of a web page for unlocking instructions/payment |
URL |
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.
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 above 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:
- 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.
- See also Localized Language Names.
