Difference between revisions of "DevTools:Modules"

From CrossWire Bible Society
Jump to: navigation, search
(Much fuller description of entries in the conf. (more to do))
m (Related Pages: deleted *GenBook and OpenOffice)
 
(171 intermediate revisions by 15 users not shown)
Line 1: Line 1:
= Module Repositories =
+
= Module Development Overview=
List of known [[Module Repositories]]
+
If you want to learn how to create a SWORD module, this is the place to start. Here is a brief overview of the process:
 +
#Collect and install the necessary software tools.
 +
#Obtain the source text and permission from the copyright holder if you wish to distribute a copyrighted module.
 +
#Prepare the source text for import.
 +
#Use an XML validator to check that your source file is properly constructed.
 +
#Import the source text using the appropriate tool.
 +
#Create a .conf file.
 +
#Install and test that the module displays correctly in several of the SWORD front-end applications.
 +
#Submit your module to CrossWire for distribution.
  
= Module Development=
+
=Creating a module=
 +
==Collect and Install Software Tools==
 +
*Install SWORD and collect SWORD module creation tools. For Linux (and Mac?) many of the module creation tools come installed with SWORD, so if you aren't comfortable installing from source simply install from your distribution's repositories. For Windows, you will need to download the module creation utilities from [http://www.crosswire.org/ftpmirror/pub/sword/utils/win32/ http://www.crosswire.org/ftpmirror/pub/sword/utils/win32/].<ref>Unofficial builds that may be from more recent SVN revisions may be found [http://dl.thehellings.com/sword-utils/ here].</ref> Be sure to download the most recent icudt dll and unzip it in the folder where you place the utilities.
  
== OSIS Book Name Abbreviations ==
+
*[[Frontends:Xiphos|Xiphos]] (for Windows) users should find a complete set of Sword tools in the Xiphos directory.
  
See [[DevTools:OSISBookNames]].
+
*The latest build of the Sword utilities for Windows requires the [http://www.microsoft.com/download/en/details.aspx?id=5555 Visual C++ 2010 Redistributable x86] version. If you have a 64-bit version of Windows, and you have installed only the [http://www.microsoft.com/download/en/details.aspx?id=14632 Visual C++ 2010 Redistributable x64] version, you will also need to install the x86 version.
  
== Introduction ==
+
*Obtain a good programmer's text editor, preferentially one which does syntax and validation checks. See [[DevTools:Text Editors]] for examples
  
A SWORD module consists of a set of binary files in any of an increasing number of formats created for SWORD plus a .conf file that specifies the location and attributes of the module.
+
<references />
  
The .conf file is located in a standard location, such as the mods.d directory of the SWORD install directory, that may be specified to The SWORD Engine in a number of ways that are outside the scope of this document. This file should be created with a standard text editor like notepad, emacs, vi, or pico. Its contents are described below in section II.
+
==Obtain Source Text and Permission to Distribute==
 +
*The easiest texts to work with, especially for learning how to make a module, are texts in the [http://en.wikipedia.org/wiki/Public_domain public domain]. For example, you might try downloading a text from [http://www.ccel.org/ CCEL] first to get you started on the process of moving from a prepared text to a compiled module. Be sure to verify that the source text you obtain is indeed in the public domain.  
 +
*Some people provide texts that are freely distributable under some sort of license (GNU GPL, Creative Commons, etc.) or no formal license. Be sure to document where the source provides that permission and check to see that they have the right to grant such permission so you can produce it if you want to distribute it with CrossWire.
 +
*For copyrighted material, you will need to contact the publisher or author to obtain permission. First check to see that someone else in CrossWire hasn't already pursued permission for that work. A list of requests and attempts to obtain rights on behalf of CrossWire can be found at [http://www.crosswire.org/wiki/index.php/Module_Requests Module Requests].
  
The module files themselves usually require an amount of pre-processing before they are ready to be imported to SWORD. How you go about this pre-processing is something you will need to decide for yourself. You may be able to do all of your pre-processing with simple search & replace operations in notepad or more complex regular expression search & replace operations in emacs, but the majority of modules will probably require even more complex editing using a scripting language such as Perl plus a fair amount of manual correction. On the other hand, some modules may come in a standard format such as ThML or OSIS encoded files, which does not require any modification, assuming they are valid documents. Document pre-processing is outside the scope of this document, but we will explain how you need to format documents to prepare them for import to SWORD, both in terms of encoding and markup.
+
==Prepare the Source Text for Import==
  
Once you have a document ready for import, you will need to run it through an importer to create the SWORD module files, which will then be placed in the module directory you specify in your .conf file.
+
===Versification===
 +
For Bible modules, SWORD supports a growing number of [[Alternate Versification|Versifications]]. A prerequisite for submission of a module that would not match the default versification for the KJV Bible is to decide which of the several versifications is most suitable for the new module.
  
After this, you may test your work and consider submitting it to The SWORD Project for public distribution from our website.
+
===Encoding===
 +
Note that the SWORD Project requires all submitted texts to be Unicode (UTF-8) encoded documents.  
  
 +
Legacy texts might need [[DevTools:Conversion to Unicode|conversion to Unicode]].
  
== .conf File Layout ==
+
===Character sets===
 +
A common problem in texts created by people less aware of Unicode principles is presence of characters which fit graphically but are out of set for this particular language. E.g. a Cyrillic a and a Latin a look identical but use different code points. It is important to clean this up prior to import as our module search depends on clean texts with consistent use of letters. Below a short shell script which will produce a list of all characters employed in a text.
  
The conf file tell the Sword engine how to treat installed module files, etc. which kind of markup they contain, and so forth.
+
<pre>
 +
cat *txt |\
 +
uni2ascii -paU |\
 +
sed  -e "s/u/\nu/g" -e '/\./d' |\
 +
sort |\
 +
uniq -c -w5 |\
 +
sed -e 's/\\//' -e 's/\W+/\t/g' -e 's/\s*\([0-9][0-9]*\).*u\([0-9A-F]*\)/Character \\x\2 (u\2) was used \1 times/' |\
 +
ascii2uni -aB |\
 +
grep 'used' > charactercount.txt
 +
</pre>
  
 +
===Images===
 +
Images can be included in any type of module. The specifics of how to do this is dependent upon markup.
  
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 &lt;a href="xxx"&gt;label&lt/a&gt;hypertext links. HTML is not allowed otherwise.
+
Some SWORD applications are able to use virtually any image format, but SWORD only offically supports JPEG and PNG image files.
  
 +
===Markup===
  
Enumerated values are shown in bold. These should be used exactly as given and no other values should be used.
+
(''see also [[DevTools:Misc]]'')
  
<table width="100%" border="1">
+
We will accept only plain texts or texts marked up in OSIS or TEI, with the sole exception texts based on CCEL documents that are marked up in ThML.  
  <tr>
 
<th>Element</th>
 
<th>Values (type or enumerated)</th>
 
<th>Default Value</th>
 
<th>Allows</th>
 
  </tr>
 
  <tr>
 
<th colspan="4">Required Elements</th>
 
  </tr>
 
  <tr>
 
<td>[name]</td>
 
<td>Each conf file begins with [name], replacing "name" with be a short well known abbreviation. This must be on the first line, and start the first line. It can only contain A-Z, a-z and 0-9.</td>
 
<td>&nbsp;</td>
 
<td>&nbsp;</td>
 
  </tr>
 
  <tr>
 
<td>DataPath</td>
 
<td>&lt;relative system path&gt;
 
  
DataPath is the path to the module relative to the SWORD module 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.
+
Internally, SWORD can process text in OSIS, TEI and 2 legacy formats(ThML, and GBF). From these formats, it can convert to other formats, including RTF and HTML, for display. OSIS 2.1 is now the preferred format for Bibles and commentaries. At the moment OSIS does not have thorough support for complex dictionaries. For that reason we support TEI for dictionaries.
  
Typical paths are for a module named [mymodule] are:<br/>
+
You may find documentation for each of these standards at their respective websites:<br/>
./modules/texts/rawtext/mymodule/<br/>
+
*Open Scriptural Information Standard (OSIS) : http://www.bibletechnologies.net/<br/>
./modules/texts/ztext/mymodule/<br/>
+
*Text Encoding Initiative (TEI) : http://www.tei-c.org/P4X/DI.html<br/>
./modules/comments/zcom/mymodule/<br/>
 
./modules/comments/hrefcom/mymodule/<br/>
 
./modules/comments/rawcom/mymodule/<br/>
 
./modules/comments/rawcom4/mymodule/<br/>
 
./modules/comments/rawfiles/mymodule/<br/>
 
./modules/lexdict/zld/mymodule/mymodule<br/>
 
./modules/lexdict/rawld/mymodule/mymodule<br/>
 
./modules/lexdict/rawld/devotionals/mymodule/mymodule<br/>
 
./modules/lexdict/rawld/glossaries/mymodule/mymodule<br/>
 
./modules/lexdict/rawld4/mymodule/mymodule<br/>
 
./modules/genbook/rawgenbook/mymodule/mymodule<br/>
 
  
But when it really comes down to it, a valid path could be:<br/>
+
In SWORD, for modules encoded  in OSIS, each verse, dictionary entry, and book division needs to be well-formed XML or it will result in display problems in some front-ends.
./xxx/ or ./xxx/mymodule
 
</td>
 
<td>&nbsp;</td>
 
<td>&nbsp;</td>
 
  </tr>
 
  <tr>
 
<td>Description</td>
 
<td>&lt;string&gt;<br/>
 
  
This is a short (1 line) title of the module.</td>
+
===Import formats===
<td>&nbsp;</td>
 
<td>&nbsp;</td>
 
  </tr>
 
  <tr>
 
<td>ModDrv</td>
 
<td>
 
<b>RawText</b> (for uncompressed Bibles)<br/>
 
<b>zText</b> (for compressed Bibles)<br/>
 
<b>RawCom</b> (for uncompressed Commentaries)<br/>
 
<b>RawCom4</b> (for uncompressed Commentaries having entries greater than 32K bytes)<br/>
 
<b>zCom</b> (for compressed Commentaries)<br/>
 
<b>HREFCom</b> (currently no module uses this type)<br/>
 
<b>RawFiles</b> (for Personal Commentary)<br/>
 
<b>RawLD</b> (for uncompressed Dictionaries)<br/>
 
<b>RawLD4</b> (for uncompressed Dictionaries having entries greater than 32K bytes)<br/>
 
<b>zLD</b> (for compressed Dictionaries)<br/>
 
<b>RawGenBook</b> (for uncompressed tree keyed modules)
 
</td>
 
<td>&nbsp;</td>
 
<td>&nbsp;</td>
 
  </tr>
 
  <tr>
 
<th colspan="4">Elements required for proper module access</th>
 
  </tr>
 
  <tr>
 
<td>CompressType</td>
 
<td><b>ZIP</b><br/>
 
<b>LZSS</b>
 
  
Used to indicate how a compressed modules (zText, zCom, & zLD) is compressed.
+
====OSIS Formatted General Books====
ZIP is the preferred format. And as of today, no compressed modules use LZSS.
+
With OSIS formatted general books, provided your document is well-formed and valid XML according to the OSIS 2.1 Schema, you should not need to do any further processing. You can use your XML file with xml2gbs. For OSIS encoded Bibles use [[osis2mod]].
</td>
 
<td>LZSS</td>
 
<td>&nbsp;</td>
 
  </tr>
 
  <tr>
 
<td>BlockType</td>
 
<td>
 
<b>BOOK</b><br/>
 
<b>CHAPTER</b><br/>
 
<b>VERSE</b><br/>
 
  
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.
+
====VPL Format====
</td>
+
[[File Formats#VPL|VPL]] or verse-per-line format may only be used in creating Bibles. This format requires that each line start with a verse reference that SWORD can understand, such as "Genesis 1:1" or "Jn 3:16". Most English abbreviations are acceptable. Following the verse reference, the verse itself should be written, in any kind of markup. For example:
<td>CHAPTER</td>
 
<td>&nbsp;</td>
 
  </tr>
 
  <tr>
 
<td>BlockCount</td>
 
<td>&lt;integer&gt;<br/>
 
  
Used for zLD to indicate the number of entries in a compressed block. Higher values will make the module slower, but smaller.</td>
+
Genesis 1:1 In the beginning God created the heaven and the earth.
<td>200</td>
+
Genesis 1:2 And the earth was without form, and void; and darkness was upon the face of the deep. And the Spirit of God moved upon the face of the waters.
<td>&nbsp;</td>
 
  </tr>
 
  <tr>
 
<td>CipherKey</td>
 
<td>&lt;string&gt; (typically in a format matching the pattern: /[0-9]{4}[A-Za-z]{4}[0-9]{4}[A-Za-z]{4}/<br/>
 
  
Contains the unlock key for enciphered modules. Leave a blank line ("CipherKey=") to indicate that the module is enciphered but has no unlock key. (Omit for unlocked modules.)</td>
+
This format is used with the utility vpl2mod, discussed below. To import Bibles that have have combined verses, you will need to use imp format, instead of vpl.
<td>&nbsp;</td>
 
<td>&nbsp;</td>
 
  </tr>
 
  <tr>
 
<th colspan="4">Elements required for proper rendering</th>
 
  </tr>
 
  <tr>
 
<td>GlobalOptionFilter</td>
 
<td>
 
<b>GBFStrongs</b> (For GBF texts having Strong's Numbers)<br/>
 
<b>GBFFootnotes</b> (For GBF texts having footnotes)<br/>
 
<b>GBFScripref</b> (For GBF texts having cross references)<br/>
 
<b>GBFMorph</b> (For GBF texts having morphology information)<br/>
 
<b>GBFHeadings</b> (For GBF texts having headings)<br/>
 
<b>GBFRedLetterWords</b> (For GBF texts marking the Words of Christ)
 
<b>ThMLStrongs</b> (For THML texts having Strong's Numbers)<br/>
 
<b>ThMLFootnotes</b> (For THML texts having footnotes)<br/>
 
<b>ThMLScripref</b> (For THML texts having cross references)<br/>
 
<b>ThMLMorph</b> (For THML texts having morphology information)<br/>
 
<b>ThMLHeadings</b> (For THML texts having headings)<br/>
 
<b>ThMLVariants</b> (For THML texts having variant readings)<br/>
 
<b>ThMLLemma</b> (For THML texts having lemmas)<br/>
 
<b>UTF8Cantillation</b> (For Hebrew texts having cantillation marks)<br/>
 
<b>UTF8GreekAccents</b> (For Greek texts having accents)<br/>
 
<b>UTF8HebrewVowels</b> (For Hebrew texts having vowel points)<br/>
 
<b>OSISStrongs</b> (For OSIS texts having Strong's Numbers)<br/>
 
<b>OSISFootnotes</b> (For OSIS texts having informational notes)<br/>
 
<b>OSISScripref</b> (For OSIS texts having cross reference type notes)<br/>
 
<b>OSISMorph</b> (For OSIS texts having morphology information)<br/>
 
<b>OSISHeadings</b> (For OSIS texts having non-canonical headings)<br/>
 
<b>OSISRedLetterWords</b> (For OSIS texts marking the Words of Christ)<br/>
 
  
Each of these filters removes/hides the text's feature, when activated by the application.
+
'''For CrossWire import purposes VPL is acceptable for text only Bibles without any further markup'''
These filters are applied in the order that they are listed in the conf.
 
        </td>
 
<td>&nbsp;</td>
 
<td>Repeats</td>
 
  </tr>
 
  <tr>
 
<td>Direction</td>
 
<td><b>LtoR</b><br/><b>RtoL</b></td>
 
<td>LtoR</td>
 
<td>&nbsp;</td>
 
  </tr>
 
  <tr>
 
<td>SourceType</td>
 
<td>
 
<b>Plaintext</b><br/>
 
<b>GBF</b> General Bible Format: http://www.ebible.org/bible/gbf.htm<br/>
 
<b>ThML</b> Theological Markup Language: http://www.ccel.org/ThML<br/>
 
<b>OSIS</b> Open Scriptural Information Standard: http://www.bibletechnologies.net<br/>
 
<b>TEI</b> Text Encoding Initiative: http://www.tei-c.org/P4X/DI.html<br/>
 
  
These are various ways that the text can be encoded. The preferred encoding is OSIS. TEI is preferred for dictionaries until OSIS supports dictionaries.<br/>
+
===Imp 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 frontends.
+
GenBook and LexDict modules may also be submitted in [[DevTools:Imp Format|Imp Format]].
</td>
 
<td>Plaintext</td>
 
<td>&nbsp;</td>
 
  </tr>
 
  <tr>
 
<td>Encoding</td>
 
<td>
 
<b>UTF-8</b><br/>
 
<b>Latin-1</b>
 
  
The preferred encoding of texts is UTF-8. Latin-1 is defined by cp1252 which is a superset of ISO8859-1.
+
==Validate the Source Text==
  
This encoding indicates how the conf and the module are encoded.
+
If your source text is either OSIS or TEI, you should definitely check it with a suitable XML text editor before proceeding to the next step.
</td>
+
# Check that it has valid XML syntax
<td>Latin-1</td>
+
# Validate the XML contents against the specified XML schema
<td>&nbsp;</td>
 
  </tr>
 
  <tr>
 
<td>DisplayLevel</td>
 
<td>&lt;integer&gt;</td>
 
<td>1</td>
 
<td>&nbsp;</td>
 
  </tr>
 
  <tr>
 
<td>Font</td>
 
<td>&lt;string&gt;<br/>
 
  
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.
+
==Import the Source Text==
</td>
+
Now that your text is ready to be imported, you will need to use one of the command line utilities for converting documents to SWORD format. Depending on the format of your document at this point, you will need to use the appropriate importer.
<td>&nbsp;</td>
+
*If your text is a valid OSIS Bible, use [[osis2mod]].
<td>&nbsp;</td>
+
*If your text is a valid OSIS Commentary, use [[osis2mod]].
  </tr>
+
*If your text is a valid OSIS document of some other type, use xml2gbs.
  <tr>
+
*If your text is a valid TEI P5 dictionary, use [[TEI Dictionaries|tei2mod]].
<td>OSISqToTick</td>
+
*If your text is a vpl format Bible, use vpl2mod.
<td>true/false
+
*If your text is an imp format Bible or commentary, use imp2vs.
 +
*If your text is an imp format dictionary, lexicon, glossary, or daily devotional, use imp2ld.
 +
*If your text is an imp format general book, use imp2gbs.
  
When set to false indicates that 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.
+
You may find these files in the SWORD Project source distribution or compiled for Win32 at http://crosswire.org/ftpmirror/pub/sword/utils/win32/. Each utility has brief usage information that can be viewed by running it once without any arguments.
</td>
 
<td>true</td>
 
<td>&nbsp;</td>
 
  </tr>
 
  <tr>
 
<th colspan="4">Elements to indicate features</th>
 
  </tr>
 
  <tr>
 
<td>Feature</td>
 
<td>
 
<b>StrongsNumbers</b> (for modules that include Strong's numbers)<br/>
 
<b>GreekDef</b> (for modules with Strong's number encoded Greek definitions)<br/>
 
<b>HebrewDef</b> (for modules with Strong's number encoded Hebrew definitions)<br/>
 
<b>GreekParse</b> (for modules with Greek morphology expansions)<br/>
 
<b>HebrewParse</b> (for modules with Hebrew morphology expansions)<br/>
 
<b>DailyDevotion</b> (for daily devotionals using one of the LD drivers and keyed with MM.DD)<br/>
 
<b>Glossary</b> (for collections of glosses using one of the LD drivers)
 
</td>
 
<td>&nbsp;</td>
 
<td>Repeats</td>
 
  </tr>
 
  <tr>
 
<td>GlossaryFrom</td>
 
<td>&lt;OSIS:Lang identifier&gt;</td>
 
<td>&nbsp;</td>
 
<td>&nbsp;</td>
 
  </tr>
 
  <tr>
 
<td>GlossaryTo</td>
 
<td>&lt;OSIS:Lang identifier&gt;</td>
 
<td>&nbsp;</td>
 
<td>&nbsp;</td>
 
  </tr>
 
  <tr>
 
<th colspan="4">General informatic and installer elements</th>
 
  </tr>
 
  <tr>
 
<td>About</td>
 
<td>&lt;string&gt;</td>
 
<td>&nbsp;</td>
 
<td>Continuation<br/>RTF</td>
 
  </tr>
 
  <tr>
 
<td>Version</td>
 
<td>&lt;version string&gt;
 
  
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.</td>
+
===Compressing Modules===
<td>1.0</td>
+
To compress a Bible, commentary, or LD module, use the mod2zmod utility. First you will need to install the module so that it can be accessed using the SWORD engine. Next, run:
<td>&nbsp;</td>
+
mod2zmod &lt;modname&gt; &lt;datapath&gt; [blockType [compressType]]
  </tr>
+
blockType can be 4 = book (default), 3 = chapter, or 1 = verse and indicates the granularity of the compression blocks. The larger the block is, the longer it will take to access a piece of the text, but the smaller the resulting module will be. compressType can be either 1 = LZSS (default) or 2 = Zip.
  <tr>
 
<td>History_x.x</td>
 
<td>&lt;string&gt;
 
  
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.</td>
+
You may wish to try different compression settings to find out which is best for your module. Typically, we use chapter compression for large commentaries, book compression for Bibles, and the Zip compression algorithm.
<td>&nbsp;</td>
+
<td>Repeats</td>
+
===[[Copyright#Locked_Modules|Locking Modules]]===
  </tr>
+
To lock a rawText Bible or rawCom commentary module, use the cipherraw utility. Just run:
  <tr>
+
cipherraw &lt;/path/to/module&gt; '&lt;key&gt;'
<td>MinimumVersion</td>
 
<td>&lt;version string&gt;</td>
 
<td>1.5.1a</td>
 
<td>&nbsp;</td>
 
  </tr>
 
  <tr>
 
<td>Category</td>
 
<td>
 
<b>Daily Devotional</b> (for modules with Feature=DailyDevotion)<br/>
 
<b>Glossaries</b> (for modules with Feature=Glossary)<br/>
 
<b>Cults / Unorthodox / Questionable Material</b><br/>
 
<b>Essays</b> (for essays)<br/>
 
  
This is used by installers to further categorize the modules beyond what can be figured out by the ModDrv and Feature.
+
===Miscellaneous tools===
</td>
+
Further miscellaneous tools that are 'not ready for public consumption' but may be useful to modules authors are found in [[DevTools:Misc]].  These includes scripts and programs that are used for the preparation and conversion of various specific modules.
<td>&nbsp;</td>
 
<td>&nbsp;</td>
 
  </tr>
 
  <tr>
 
<td>LCSH</td>
 
<td>&lt;tree/string&gt;</td>
 
<td>&nbsp;</td>
 
<td>&nbsp;</td>
 
  </tr>
 
  <tr>
 
<td>Lang</td>
 
<td>&lt;OSIS:Lang identifier&gt;<br/>
 
  
This is the primary language code of the module and should include a value according to RFC 2066. ISO 639-1 codes are the preferred code (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). See http://lcweb.loc.gov/standards/iso639-2/englangn.html for ISO 639-1 and 639-2/T codes. Otherwise use ISO 639-3, see: http://www.sil.org/iso639-3. In cases where no ISO 639 code is available, use "x-E-" followed by the SIL Ethnologue code for the language (e.g. x-E-KEK for Kekchi). If a text is country specific, such as the Anglicized NIV, include the ISO 3166-1 country code after the language code and an underscore (e.g. en_GB for UK English). See http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html for ISO 3166-1 codes.</td>
+
===Debugging modules===
<td>en</td>
 
<td>&nbsp;</td>
 
  </tr>
 
  <tr>
 
<td>InstallSize</td>
 
<td>&lt;integer (indicating bytes)&gt;</td>
 
<td>&nbsp;</td>
 
<td>&nbsp;</td>
 
  </tr>
 
  <tr>
 
<td>SwordVersionDate</td>
 
<td>&lt;ISO date string (yyyy-mm-dd)&gt;
 
  
Indicates the date that the module was changed.
+
If you are not the module creator and thus do not have a copy of the source text file, some of the SWORD utilities can be used for help in debugging a module. It is especially useful to note that mod2imp followed by [imp2vs | imp2ld | imp2gbs] (depending on module type) often produces a lossless round-trip, no matter what the markup variety was used to make the original module. Editing the IMP file in between these two steps can therefore be used as a method to evaluate sensible conjectures regarding the apparent cause of a bug in a particular module.
</td>
 
<td>&nbsp;</td>
 
<td>&nbsp;</td>
 
  </tr>
 
  <tr>
 
<td>Obsoletes</td>
 
<td>&lt;name of module&gt;<br/>
 
  
Each instance of this element names a module that is made obsolete by this module, usually indicated by the former name of the module.
+
:'''N.B.''' mod2imp followed by imp2(vs|ld|gbs) is not guaranteed to round-trip losslessly. mod2imp will give an accurate record of the contents of each content entry in the module, but skips past link entries. So for investigating entry contents in order to track down bugs, this process is fine, but CrossWire would never release content that had gone through this process.
</td>
 
<td>&nbsp;</td>
 
<td>Repeats</td>
 
  </tr>
 
  <tr>
 
<th colspan="4">Copyright &amp; Licensing related elements</th>
 
  </tr>
 
  <tr>
 
<td>Copyright</td>
 
<td>&lt;string&gt;</td>
 
<td>&nbsp;</td>
 
<td>Continuation</td>
 
  </tr>
 
  <tr>
 
<td>CopyrightHolder</td>
 
<td>&lt;string&gt;</td>
 
<td>&nbsp;</td>
 
<td>&nbsp;</td>
 
  </tr>
 
  <tr>
 
<td>CopyrightDate</td>
 
<td>&lt;integer (indicating year)&gt;</td>
 
<td>&nbsp;</td>
 
<td>&nbsp;</td>
 
  </tr>
 
  <tr>
 
<td>CopyrightNotes</td>
 
<td>&lt;string&gt;</td>
 
<td>&nbsp;</td>
 
<td>Continuation<br/>RTF</td>
 
  </tr>
 
  <tr>
 
<td>CopyrightContactName</td>
 
<td>&lt;string&gt;</td>
 
<td>&nbsp;</td>
 
<td>Continuation<br/>RTF</td>
 
  </tr>
 
  <tr>
 
<td>CopyrightContactNotes</td>
 
<td>&lt;string&gt;</td>
 
<td>&nbsp;</td>
 
<td>Continuation<br/>RTF</td>
 
  </tr>
 
  <tr>
 
<td>CopyrightContactAddress</td>
 
<td>&lt;string&gt;</td>
 
<td>&nbsp;</td>
 
<td>Continuation<br/>RTF</td>
 
  </tr>
 
  <tr>
 
<td>CopyrightContactEmail</td>
 
<td>&lt;string&gt;</td>
 
<td>&nbsp;</td>
 
<td>&nbsp;</td>
 
  </tr>
 
  <tr>
 
<td>ShortPromo</td>
 
<td>&lt;string&gt;</td>
 
<td>&nbsp;</td>
 
<td>&nbsp;</td>
 
  </tr>
 
  <tr>
 
<td>ShortCopyright</td>
 
<td>&lt;string&gt;</td>
 
<td>&nbsp;</td>
 
<td>&nbsp;</td>
 
  </tr>
 
  <tr>
 
<td>DistributionLicense</td>
 
<td><b>Public Domain</b><br/><b>Copyrighted</b><br/><b>Copyrighted; Permission to distribute granted to CrossWire</b><br/><b>Copyrighted; Free non-commercial distribution</b></td>
 
<td>&nbsp;</td>
 
<td>&nbsp;</td>
 
  </tr>
 
  <tr>
 
<td>DistributionSource</td>
 
<td>&lt;string&gt;</td>
 
<td>&nbsp;</td>
 
<td>Continuation</td>
 
  </tr>
 
  <tr>
 
<td>DistributionNotes</td>
 
<td>&lt;string&gt;</td>
 
<td>&nbsp;</td>
 
<td>Continuation</td>
 
  </tr>
 
  <tr>
 
<td>TextSource</td>
 
<td>&lt;string, probably a URL&gt;</td>
 
<td>&nbsp;</td>
 
<td>Continuation</td>
 
  </tr>
 
</table>
 
  
=Things that should move elsewhere=
+
If you have created a 'plain text' Bible module using either imp2vs or vpl2mod, it can be worthwhile to see what the module outputs with mod2osis. If the resulting osis file fails to pass the XML syntax check when viewed with a suitable XML editor, this may point to unexpected residual items in the source text. The proper solution then would be to raise the matter with the provider of the source text.
  
== Module Requests ==
+
If you have created a devotional, imp2ld appears to have a bug that prevents it from creating the module correctly unless you use the trailing argument 2. 
 +
For example:
 +
imp2ld MyLD.txt MyLD 2
  
Here is a place to request modules you would like to be made. If the Copyright holder has been contacted, the permissions granted or not can be put here.  
+
==Create the .conf File==
 +
In order to test and before submitting a new module, you need to create a .conf file, which tells Sword how to recognize and what to do with your module. Instructions for creating a .conf file are on the [[DevTools:conf Files]] page.
  
====Bible Versions====
+
==Install and Test the Module==
*Nederlands Bijbelgenootschap [http://www.biblija.net/biblija.cgi?lang=nl], [http://80.252.86.246/]
+
===Install the Module===
*Turkish Kutsal Kitap [http://www.kitabimukaddes.com/] [http://www.translation-trust.org/html/home.html]
+
Once you have imported the source document as a binary, several files will result. The number of files depends on the type of module, but you should make sure all of them are in the same folder. That folder will go in the modules folder, and the .conf file should go in the mods.d folder wherever your SWORD modules are installed. Open a front-end and see that it is recognizing the presence of the module. If it appears then you have installed it in the right place. Check to make sure that the content appears, and you are ready to start testing.
Permission has been granted and the module is available as "TurNTB" in beta [[User:Refdoc|Refdoc]] 18:04, 29 August 2007 (MDT)
 
  
*Cherokee New Testament [http://cherokeenewtestament.com/] '''Public Domain'''
+
===Checking for Missing Verses===
*German revidierte Luther Bible 1984 [http://www.dbg.de]
+
You can use the utility emptyvss to find verses in a module that contain no text, since this may indicate errors in the module. Just run:
 +
emptyvss &lt;module name&gt;
 +
on an installed module to generate a list.
  
====Books====
+
==Submit the Module to CrossWire for Distribution==
==== English ====
 
<ul>
 
<li>[[Foxe's Book of Martyrs by John Foxe]] ([http://books.google.com/books?id=gCUeSAoqOSEC&dq=&pg=PP1&ots=EwFbQI-cOy&sig=Ciue6KwFnRP_7jDxSRSw1nDEpcw&prev=http://www.google.com/search%3Faq%3Do%26hl%3Den%26client%3Dfirefox-a%26rls%3Dcom.ubuntu%253Aen-US%253Aofficial%26q%3DFoxes%2BBook%2Bof%2BMartyrs%26btnG%3DSearch&sa=X&oi=print&ct=title#PPR9,M1 1] and [http://www.ccel.org/f/foxe/martyrs/home.html 2])</li>
 
</ul>
 
  
====Devotionals====
+
First ensure that your module complies with our stated [[copyright]] policy.
  
====Lexicons====
+
If your module is to be sold rather than distributed for free, CrossWire has a tool to encrypt a module. However, we do not handle any payments, so we always suggest that it's for the owner (or an authorised agent) to host the payment system as well as the delivery of the unlock key.
  
== New Modules ==
+
After you have tested your module, you may wish to submit it to the SWORD Project for public release so that other people can benefit from your work. The submission itself should be of an uncompiled, plain text document in either VPL (verse-per-line), IMP (import), OSIS or TEI [[File Formats|format]], ready to be run through one of the module build tools. '''Do not''' submit built modules that you have imported to Sword format; submit only source documents. You also need to supply the relevant conf file entries. Before any module will be considered for hosting, we require that the following minimum set of module configuration fields be included in its .conf file:  '''Description''', '''About''', '''DistributionLicense''', and '''TextSource'''. For further detail please read [[Module Submission]]  
List of modules that are being developed
 
=== General Book ===
 
==== English ====
 
<ul>
 
  <li>[[Creeds of Christendom by Philip Schaff]] ([http://www.ccel.org/ccel/schaff/creeds1.html 1] and [http://www.ccel.org/ccel/schaff/creeds2.html 2])</li>
 
</ul>
 
  
=== Portuguese ===
+
When you decide that your module is ready to be submitted, you may email it to modules@crosswire.org. If you are unable to email it or would prefer to send the files by some other means, you may contact us at the same email address, and we can discuss other arrangements.
==== Brazilian ====
 
SBB denied permissions, someone from Brasília intends to try again.
 
  
SBT has been contacted, anticipating answer.
+
=Related Pages=
 +
*A Basic [[OSIS Tutorial]]
 +
*Guide to Writing [[OSIS Bibles]]
 +
*[[OSIS Book Abbreviations|OSIS Book Name Abbreviations]]
 +
*Guide to Writing [[OSIS Commentaries]]
 +
*Guide to Writing [[TEI Dictionaries]]
 +
*Guide to [[Converting SFM Bibles to OSIS]]
 +
*[[Encoding| Text Encoding]]
 +
*Related [[File Formats]]
 +
*List of [[Official and Affiliated Module Repositories]]
 +
*[[Zipped modules]]
 +
*[[Module Requests]]
 +
*[[Copyright]]
  
IBB has left the door open to a future favourable answer.  Need to follow up with request for permissions on Versão Revisada and its Almeida Século XXI successor.
+
[[Category:Development tools|Modules]]
 
+
[[Category:Modules]]
[[Corrigida]] low-quality copies are available, we need to evaluate if it is worthwhile to move forward: old translation, not too good, OCR will be troublesome.
 
 
 
[[Tradução Brazileira]] copy obtained, working library contacts to find a book scanner.
 
 
 
For all these, please ask for further information at sword-devel.
 
 
 
==== Iberian ====
 
Permissions were obtained on a number of texts from [[SBP]], as per post at sword-devel.
 

Latest revision as of 20:31, 4 June 2020

Module Development Overview

If you want to learn how to create a SWORD module, this is the place to start. Here is a brief overview of the process:

  1. Collect and install the necessary software tools.
  2. Obtain the source text and permission from the copyright holder if you wish to distribute a copyrighted module.
  3. Prepare the source text for import.
  4. Use an XML validator to check that your source file is properly constructed.
  5. Import the source text using the appropriate tool.
  6. Create a .conf file.
  7. Install and test that the module displays correctly in several of the SWORD front-end applications.
  8. Submit your module to CrossWire for distribution.

Creating a module

Collect and Install Software Tools

  • Install SWORD and collect SWORD module creation tools. For Linux (and Mac?) many of the module creation tools come installed with SWORD, so if you aren't comfortable installing from source simply install from your distribution's repositories. For Windows, you will need to download the module creation utilities from http://www.crosswire.org/ftpmirror/pub/sword/utils/win32/.[1] Be sure to download the most recent icudt dll and unzip it in the folder where you place the utilities.
  • Xiphos (for Windows) users should find a complete set of Sword tools in the Xiphos directory.
  • Obtain a good programmer's text editor, preferentially one which does syntax and validation checks. See DevTools:Text Editors for examples
  1. Unofficial builds that may be from more recent SVN revisions may be found here.

Obtain Source Text and Permission to Distribute

  • The easiest texts to work with, especially for learning how to make a module, are texts in the public domain. For example, you might try downloading a text from CCEL first to get you started on the process of moving from a prepared text to a compiled module. Be sure to verify that the source text you obtain is indeed in the public domain.
  • Some people provide texts that are freely distributable under some sort of license (GNU GPL, Creative Commons, etc.) or no formal license. Be sure to document where the source provides that permission and check to see that they have the right to grant such permission so you can produce it if you want to distribute it with CrossWire.
  • For copyrighted material, you will need to contact the publisher or author to obtain permission. First check to see that someone else in CrossWire hasn't already pursued permission for that work. A list of requests and attempts to obtain rights on behalf of CrossWire can be found at Module Requests.

Prepare the Source Text for Import

Versification

For Bible modules, SWORD supports a growing number of Versifications. A prerequisite for submission of a module that would not match the default versification for the KJV Bible is to decide which of the several versifications is most suitable for the new module.

Encoding

Note that the SWORD Project requires all submitted texts to be Unicode (UTF-8) encoded documents.

Legacy texts might need conversion to Unicode.

Character sets

A common problem in texts created by people less aware of Unicode principles is presence of characters which fit graphically but are out of set for this particular language. E.g. a Cyrillic a and a Latin a look identical but use different code points. It is important to clean this up prior to import as our module search depends on clean texts with consistent use of letters. Below a short shell script which will produce a list of all characters employed in a text.

 cat *txt |\
 uni2ascii -paU |\
 sed  -e "s/u/\nu/g" -e '/\./d' |\
 sort |\
 uniq -c -w5 |\
 sed -e 's/\\//' -e 's/\W+/\t/g' -e 's/\s*\([0-9][0-9]*\).*u\([0-9A-F]*\)/Character \\x\2 (u\2) was used \1 times/' |\
 ascii2uni -aB |\
 grep 'used' > charactercount.txt

Images

Images can be included in any type of module. The specifics of how to do this is dependent upon markup.

Some SWORD applications are able to use virtually any image format, but SWORD only offically supports JPEG and PNG image files.

Markup

(see also DevTools:Misc)

We will accept only plain texts or texts marked up in OSIS or TEI, with the sole exception texts based on CCEL documents that are marked up in ThML.

Internally, SWORD can process text in OSIS, TEI and 2 legacy formats(ThML, and GBF). From these formats, it can convert to other formats, including RTF and HTML, for display. OSIS 2.1 is now the preferred format for Bibles and commentaries. At the moment OSIS does not have thorough support for complex dictionaries. For that reason we support TEI for dictionaries.

You may find documentation for each of these standards at their respective websites:

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

Import formats

OSIS Formatted General Books

With OSIS formatted general books, provided your document is well-formed and valid XML according to the OSIS 2.1 Schema, you should not need to do any further processing. You can use your XML file with xml2gbs. For OSIS encoded Bibles use osis2mod.

VPL Format

VPL or verse-per-line format may only be used in creating Bibles. This format requires that each line start with a verse reference that SWORD can understand, such as "Genesis 1:1" or "Jn 3:16". Most English abbreviations are acceptable. Following the verse reference, the verse itself should be written, in any kind of markup. For example:

Genesis 1:1 In the beginning God created the heaven and the earth.
Genesis 1:2 And the earth was without form, and void; and darkness was upon the face of the deep. And the Spirit of God moved upon the face of the waters.

This format is used with the utility vpl2mod, discussed below. To import Bibles that have have combined verses, you will need to use imp format, instead of vpl.

For CrossWire import purposes VPL is acceptable for text only Bibles without any further markup

Imp Format

GenBook and LexDict modules may also be submitted in Imp Format.

Validate the Source Text

If your source text is either OSIS or TEI, you should definitely check it with a suitable XML text editor before proceeding to the next step.

  1. Check that it has valid XML syntax
  2. Validate the XML contents against the specified XML schema

Import the Source Text

Now that your text is ready to be imported, you will need to use one of the command line utilities for converting documents to SWORD format. Depending on the format of your document at this point, you will need to use the appropriate importer.

  • If your text is a valid OSIS Bible, use osis2mod.
  • If your text is a valid OSIS Commentary, use osis2mod.
  • If your text is a valid OSIS document of some other type, use xml2gbs.
  • If your text is a valid TEI P5 dictionary, use tei2mod.
  • If your text is a vpl format Bible, use vpl2mod.
  • If your text is an imp format Bible or commentary, use imp2vs.
  • If your text is an imp format dictionary, lexicon, glossary, or daily devotional, use imp2ld.
  • If your text is an imp format general book, use imp2gbs.

You may find these files in the SWORD Project source distribution or compiled for Win32 at http://crosswire.org/ftpmirror/pub/sword/utils/win32/. Each utility has brief usage information that can be viewed by running it once without any arguments.

Compressing Modules

To compress a Bible, commentary, or LD module, use the mod2zmod utility. First you will need to install the module so that it can be accessed using the SWORD engine. Next, run:

mod2zmod <modname> <datapath> [blockType [compressType]]

blockType can be 4 = book (default), 3 = chapter, or 1 = verse and indicates the granularity of the compression blocks. The larger the block is, the longer it will take to access a piece of the text, but the smaller the resulting module will be. compressType can be either 1 = LZSS (default) or 2 = Zip.

You may wish to try different compression settings to find out which is best for your module. Typically, we use chapter compression for large commentaries, book compression for Bibles, and the Zip compression algorithm.

Locking Modules

To lock a rawText Bible or rawCom commentary module, use the cipherraw utility. Just run:

cipherraw </path/to/module> '<key>'

Miscellaneous tools

Further miscellaneous tools that are 'not ready for public consumption' but may be useful to modules authors are found in DevTools:Misc. These includes scripts and programs that are used for the preparation and conversion of various specific modules.

Debugging modules

If you are not the module creator and thus do not have a copy of the source text file, some of the SWORD utilities can be used for help in debugging a module. It is especially useful to note that mod2imp followed by [imp2vs | imp2ld | imp2gbs] (depending on module type) often produces a lossless round-trip, no matter what the markup variety was used to make the original module. Editing the IMP file in between these two steps can therefore be used as a method to evaluate sensible conjectures regarding the apparent cause of a bug in a particular module.

N.B. mod2imp followed by imp2(vs|ld|gbs) is not guaranteed to round-trip losslessly. mod2imp will give an accurate record of the contents of each content entry in the module, but skips past link entries. So for investigating entry contents in order to track down bugs, this process is fine, but CrossWire would never release content that had gone through this process.

If you have created a 'plain text' Bible module using either imp2vs or vpl2mod, it can be worthwhile to see what the module outputs with mod2osis. If the resulting osis file fails to pass the XML syntax check when viewed with a suitable XML editor, this may point to unexpected residual items in the source text. The proper solution then would be to raise the matter with the provider of the source text.

If you have created a devotional, imp2ld appears to have a bug that prevents it from creating the module correctly unless you use the trailing argument 2. For example:

imp2ld MyLD.txt MyLD 2

Create the .conf File

In order to test and before submitting a new module, you need to create a .conf file, which tells Sword how to recognize and what to do with your module. Instructions for creating a .conf file are on the DevTools:conf Files page.

Install and Test the Module

Install the Module

Once you have imported the source document as a binary, several files will result. The number of files depends on the type of module, but you should make sure all of them are in the same folder. That folder will go in the modules folder, and the .conf file should go in the mods.d folder wherever your SWORD modules are installed. Open a front-end and see that it is recognizing the presence of the module. If it appears then you have installed it in the right place. Check to make sure that the content appears, and you are ready to start testing.

Checking for Missing Verses

You can use the utility emptyvss to find verses in a module that contain no text, since this may indicate errors in the module. Just run:

emptyvss <module name>

on an installed module to generate a list.

Submit the Module to CrossWire for Distribution

First ensure that your module complies with our stated copyright policy.

If your module is to be sold rather than distributed for free, CrossWire has a tool to encrypt a module. However, we do not handle any payments, so we always suggest that it's for the owner (or an authorised agent) to host the payment system as well as the delivery of the unlock key.

After you have tested your module, you may wish to submit it to the SWORD Project for public release so that other people can benefit from your work. The submission itself should be of an uncompiled, plain text document in either VPL (verse-per-line), IMP (import), OSIS or TEI format, ready to be run through one of the module build tools. Do not submit built modules that you have imported to Sword format; submit only source documents. You also need to supply the relevant conf file entries. Before any module will be considered for hosting, we require that the following minimum set of module configuration fields be included in its .conf file: Description, About, DistributionLicense, and TextSource. For further detail please read Module Submission

When you decide that your module is ready to be submitted, you may email it to modules@crosswire.org. If you are unable to email it or would prefer to send the files by some other means, you may contact us at the same email address, and we can discuss other arrangements.

Related Pages