CrossWire Bible Society - User contributions [en]

Module Requests

2008-01-15T16:39:12Z

Spookylukey: /* Commentaries */

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.

New modules are made largely on the basis of content availability and distributability. If you have a link to new material in the public domain, adding it here is a good way of notifying us of its availability. However there is no guarantee that anyone will be interested in creating a module from that material. If you want to see a new module, your quickest results will come from encoding it in OSIS yourself and submitting that to us.

If you would like to see the addition of text currently under copyright and have not made any attempt to get permission for distribution, there is no point to adding it here and the addition will likely be removed. If you only have a link to non-text material (images, PDFs, etc.), there is no point to adding it here and it will likely be removed.

====Bible Versions====
*Cherokee New Testament [http://cherokeenewtestament.com/] '''Public Domain''' -- check back occasionally to see whether the text version is completed

*KJV (original 1611 version/orthography). There exist some reprints in paper - has anyone scanned it? Also a few electronic editions exist--check into adapting one for Sword.

*NASB Currently being prepared. This will be sold. See FAQ.

*Complete Tyndale Bible, Not even the whole NT is available with sword, and also he translated the Pentateuch, and Jonah, and other books later published in Matthew's Bible. Text version is not yet available.

*NKJV, Thomas Nelson Inc. Contact attempted by Karl to rights@thomasnelson.com and onlinenotification@thomasnelson.com, December 2007; no response.

*NIV, the perennial request. Contact attempted via feedback web page at ibs.org, November 2006 and March 2007; no response.

*Contemporary English Version, contact attempted to info@americanbible.org, November 2007, no response.

*Third Millennium Bible, contact attempted at TMBible.com, November 2007, no response.

====Books====
* [[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])

====Commentaries====
<ul>
<li>Calvin's Commentaries [http://www.ccel.org/ccel/calvin/commentaries.i.html]
 
Current approach is to combine ThML files from CCEL and convert to OSIS.
This work is mostly done - see: http://crosswire.org/svn/sword-tools/trunk/modules/calvinscommentaries/ 
At the time of writing, it should be available in Crosswire's 'beta' repository.
 
</li>
</ul>

====Devotionals====

====Lexicons====
*Unabridged Brown-Driver-Briggs Hebrew Lexicon -- worth researching; The text exists in electronic format, at least licensed. It's important that this not be the "Abridged BDBG" which is Larry Pierce's altered module.

*What Does the Bible Say About and Nelson's New Illustrated Bible Dictionary, lightweight but potentially interesting and useful resources and (based on testing from text portions obtained from ebible.com) easy to convert to Sword format. Contact attempted, see NKJV above. There are other resources possible here as well, on a more restricted basis at ebible.com, in the "New Illustrated" series (commentary, "topics"), any of which should be convertible.

File Formats

2007-10-05T14:03:23Z

Spookylukey: /* ThML Utilities */

The SWORD Project respects [[copyright]]. As such, conversion of material that is under copyright is not supported by The SWORD Project.

This page merely lists some of the more common file formats relevant to The SWORD Project and associated utilities.

==File Formats==
Bible study programs use a plethora of markup formats. Even more have been suggested for use in creating Bibles and other religious material. This subsection describes some of the most common of those formats.

===GBF===
General Bible Format

This markup format is intended as an aid to preparing Bible texts (specifically the WEB and WEB:ME) for use with various Bible search programs. The complete specification is at http://www.ebible.org/bible/gbf.htm.

This markup format was previously used for some Sword modules but is now deprecated in favor of OSIS. The rudimentary [http://crosswire.org/ftpmirror/pub/sword/utils/perl/gbf2osis.pl gbf2osis.pl] utility may be used to convert GBF to OSIS for import to Sword's native format.

===HTML===
Hyper Text Markup Language

This is the basic markup language of the World Wide Web. Some Sword front-ends, such as [http://www.bibletime.info/ BibleTime], [http://gnomesword.sourceforge.net/ GnomeSword], and [http://www.crosswire.org/bibledesktop/ Bible Desktop], use HTML for presentation.

===IMP===
Import Format

This proprietary file format is used by Sword for import of all types of modules. The three utilities [http://crosswire.org/ftpmirror/pub/sword/utils/win32/imp2vs.exe imp2vs] (for Bibles and verse-indexed commentaries), [http://crosswire.org/ftpmirror/pub/sword/utils/win32/imp2ld.exe imp2ld] (for lexicons, dictionaries, and daily-devotionals), and [http://crosswire.org/ftpmirror/pub/sword/utils/win32/imp2gbs.exe imp2gbs] (for all other types of books) can be used to import IMP files to Sword's native formats.

An IMP file consists of any number of entries. Each entry consists of a key line and any number of content lines. The key line consists of a line beginning with "$$$". For example, "$$$Gen 1:1" would be the key line for the Genesis 1:1 entry of a Bible or commentary module.

The content lines of an entry may consist of any text (provided that the first three characters of the line are not "$$$"). The internal markup of the content may be in any format supported by Sword, namely OSIS for any module type or ThML for freeform books from CCEL.

===LitML===
Liturgical Markup Language

This markup format is a descendant of, and complement to ThML, described at http://hildormen.org/docs/LitML/Guidelines-LitML10-1.0.html.

The markup reflects its orientation towards liturgy and hymns.

===OSIS===
Open Scripture Information Standard

The Open Scripture Information Standard (OSIS) is "a common format for many visions." It is an XML format for marking up scripture and related text, part of an initiative composed of translators, publishers, scholars, software manufacturers, and technical experts, coordinated by the Bible Technologies Group. It is co-sponsored by the American Bible Society and the Society of Biblical Literature.

The most recent XML schema is [http://www.bibletechnologies.net/osisCore.2.1.1.xsd OSIS 2.1.1], and a manual is also [http://www.bibletechnologies.net/20Manual.dsp available].

This markup format is recommended by the CrossWire Bible Society and can be used for creating all types of resources for The SWORD Project. Support for OSIS is actively maintained and support for any unsupported elements or features needed for a module you may be working on may be requested.

===PDF===
Portable Document Format

This is an ISO track file format for platform independent rendering of documents. It is derived from Postscript and is maintained by Adobe. Documents may be text, images, or scanned images of text. Even textual documents cannot reasonably be expected to allow plain-text export. As such, it is designed to be a "read only" format.

===RTF===
Rich Text Format

This is a markup format designed by Microsoft. It is used as the markup language for presentation The SWORD Project for Windows. It is also the internal markup format used within STEP books (see below). The format is of limited use as an archival format and there are no plans for Sword to support it beyond its current use for presentation.

===STEP===
Standard Template for Electronic Publishing

This file format was formerly used by QuickVerse and WordSearch, and is currently used for some e-Sword books.

While not an open standard, the publicly released documentation and specifications for this format can be found mirrored at
http://www.crosswire.org/bsisg/. Some utilities for working with this format are listed below. It is unlikely that the SWORD Project will support this format in the future as it is laregly dead.

===ThML===
Theological Markup Language

This format is a variant of XML based on TEI and ThML, developed by and for the [http://www.ccel.org/ Christian Classics Etherial Library]. The specifications for this markup format are available at http://www.ccel.org/ThML/.

This markup format in some Sword resources, but only the creation of free-form "General book" modules based on existing CCEL resources is currently supported. Other works and new works should be created using the OSIS format.

===Unbound Bible Format===
Unbound Bible Format

The [http://unbound.biola.edu/ BIOLA's Unbound Bible] offers many of their resources for download in a proprietary, but relatively simple plain-text format.

There is no widespread use of this format, but the rudimentary [http://crosswire.org/ftpmirror/pub/sword/utils/perl/unb2osis.pl unb2osis.pl] utility may be used to convert Unbound Bible format to OSIS for import to Sword's native format.

===USFM===
Unified Standard Format Markers

This plain-text format is a common internal-use format within Bible translation agencies and Bible societies. It is the native format of [http://paratext.ubs-translations.org/Register.html Paratext]. The rudimentary [http://crosswire.org/ftpmirror/pub/sword/utils/perl/usfm2osis.pl usfm2osis.pl] utility may be used to convert USFM to OSIS for import to Sword's native format.

===USFX===
Unified Scripture Format XML

This XML file format is designed to provide clean conversions from Scripture to USFM compliant file formats. A more comprehensive description can be found at http://ebt.cx/usfx/. There is no widespread use of this format and there are no plans for Sword to support it in any way.

===VPL===
Verse-Per-Line

This plain-text format is used for by Sword for import of Bibles. It consists of one verse per line, with an optional verse reference at the beginning. The [http://crosswire.org/ftpmirror/pub/sword/utils/win32/vpl2mod.exe vpl2mod] utility may be used for import. VPL is deprecated in favor of the IMP format, which is more widely useful.

===XSEM===
XML Scripture Encoding Model

This XML format was proposed by SIL. A comprehensive description of the markup language can be found at
http://scripts.sil.org/cms/scripts/page.php?site_id=nrsi&item_id=XSEM&_sc=1.

The formal specifications can be found at
http://scripts.sil.org/cms/scripts/render_download.php?site_id=nrsi&format=file&media_id=XSEM_Source&filename=XSEM_Source.zip

The designers of this markup language were instrumental in the writing of the OSIS Specification and it has largely been deprecated in favor of using OSIS. There is no widespread use of this format and there are no plans for Sword to support it in any way.

===XML===
eXtensible Markup Language

This is generic family of markup formats. Links to a number of XML specifications can be found at http://xml.coverpages.org/xmlApplications.html. Each flavor has its own specifications. Sword supports markup in the XML formats OSIS and ThML internally

===Zefania XML===
This is the [http://www.zykloide.de/Zefania_Bible_Markup_Language/documentation/zef2005_files/schemas/zef2005_xsd/elements/XMLBIBLE.html native file format] of Zefania XML-based Bible study tools such as [http://www.mybible.de/ MyBible] and [http://www.bibleworkplace.de/ BibleWorkPlace]. The [http://crosswire.org/ftpmirror/pub/sword/utils/perl/zef2osis.pl zef2osis.pl] utility may be used to convert Zefania XML to OSIS for import to Sword's native format.

==Utility Programs==
Unless otherwise specified, the utility programs listed in this section do not work with file formats used by The SWORD Project.

===The SWORD Project===
* [http://crosswire.org/ftpmirror/pub/sword/utils/win32/cipherraw.exe cipherraw] - used to encipher Sword modules
* [http://crosswire.org/ftpmirror/pub/sword/utils/win32/diatheke.exe diatheke] - a basic CLI Sword frontend
* [http://crosswire.org/ftpmirror/pub/sword/utils/win32/mkfastmod.exe mkfstmod] - creates a search index for a module
* [http://crosswire.org/ftpmirror/pub/sword/utils/win32/mod2zmod.exe mod2zmod] - creates a compressed module from an installed module

====IMP Tools====
* [http://crosswire.org/ftpmirror/pub/sword/utils/win32/imp2gbs.exe imp2gbs] - imports free-form General books in IMP format to Sword format
* [http://crosswire.org/ftpmirror/pub/sword/utils/win32/imp2ld.exe imp2ld] - imports lexicons, dictionaries, and daily devotionals in IMP format to Sword format
* [http://crosswire.org/ftpmirror/pub/sword/utils/win32/imp2vs.exe imp2vs] - imports Bibles and commentaries in IMP format to Sword format
* [http://crosswire.org/ftpmirror/pub/sword/utils/win32/mod2imp.exe mod2imp] - creates an IMP file from an installed module

====VPL Tools====
* [http://crosswire.org/ftpmirror/pub/sword/utils/win32/vpl2mod.exe vpl2mod] - imports Bibles and commentaries in Verse-Per-Line format to Sword format

===GBF Tools===
* [http://crosswire.org/ftpmirror/pub/sword/utils/perl/gbf2osis.pl gbf2osis.pl] - a PERL utility for converting GBF to OSIS

* [http://ebible.org/translation/gbf.html gbfconvertor, including gbf2osis, gbf2xsem, & gbf2sf] - utilities for converting GBF to OSIS, XSEM, and SFM
* [http://ebible.org/translation/gbf.html gbfsrc] - utilities for converting GBF to "HTML, RTF, TeX, plain ASCII text, a format readable by BibleWorks 5 or later, and a couple of less useful formats"

===OSIS Utilities===
* [http://crosswire.org/ftpmirror/pub/sword/utils/win32/mod2osis.exe mod2osis] - creates an OSIS file from an installed module
* [http://crosswire.org/ftpmirror/pub/sword/utils/win32/osis2mod.exe osis2mod] - imports Bibles and commentaries in OSIS format to Sword format
* [http://crosswire.org/ftpmirror/pub/sword/utils/win32/vs2osisref.exe vs2osisref] - returns the osisRef of a given (text form) verse reference
* [http://crosswire.org/ftpmirror/pub/sword/utils/win32/xml2gbs.exe xml2gbs] - imports free-form General books in OSIS or ThML format to Sword format

===STEP Utilities===

* [http://crosswire.org/ftpmirror/pub/sword/utils/win32/step2vpl.exe step2vpl] - export a STEP book in Verse-Per-Line (VPL) format
* [http://crosswire.org/ftpmirror/pub/sword/utils/win32/stepdump.exe stepdump] - dumps the contents of a STEP book

* [http://www.customconsulting.us/step2rtf.zip step2rtf] - extracts the internal RTF text from STEP books
* [http://www.customconsulting.us/stepr-0.3.1.tgz stepr] - a rudimentary STEP reader

===ThML Utilities===
* [http://crosswire.org/ftpmirror/pub/sword/utils/win32/xml2gbs.exe xml2gbs] - imports free-form General books in OSIS or ThML format to Sword format
* [http://ccel-desktop.sourceforge.net/ CCEL Desktop] - a program for viewing and developing CCEL books
* [http://www.crosswire.org/wiki/index.php/DevTools:Misc#thml2osis thml2osis] - converts ThML to OSIS format.

===Zefania Utilities===

* [http://crosswire.org/ftpmirror/pub/sword/utils/perl/zef2osis.pl zef2osis.pl]- a PERL utility for converting Zefania XML to OSIS

* [https://sourceforge.net/project/showfiles.php?group_id=202842&package_id=243464&release_id=536663 Zefania Module Splitter;]
* [http://sourceforge.net/project/showfiles.php?group_id=202842&package_id=243464&release_id=534590 Zefania TextKonvertor];
* [http://wp1066500.wp101.webpack.hosteurope.de/zef/content/view/61/61/ Zefania XML Bible Book Names Changer];

DevTools:Modules

2007-10-05T13:44:36Z

Spookylukey: /* Miscellaneous tools */

= Module Development=
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.

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 can be created with a standard text editor like notepad, emacs, vi, or pico. Its contents are described below in section II.

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.

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.

After this, you may test your work and consider submitting it to The SWORD Project for public distribution from our website.

=Creating a .conf File=
==.conf File Layout==
The conf file tells the Sword engine how to treat installed module files, etc. which kind of markup they contain, and so forth.

Below is a listing of the possible directives in that file. Each of these directives of the form key=value. Some keys can be repeated. Some can have values that span more than 1 line with '\' at the end of a line indicating that the text on the next line continues the value. Some values allow RTF and some allow HTML <a href="xxx">label&lt/a>hypertext links. HTML is not allowed otherwise.

Enumerated values are shown in bold. These should be used exactly as given and no other values should be used.

<table width="100%" border="1">
<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. 

The name of the file should be the lowercase of this name followed by .conf. For example, [MyModule] would be mymodule.conf.</td>
<td> </td>
<td> </td>
</tr>
<tr>
<td>DataPath</td>
<td><relative system path>

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.

Typical paths are for a module named [mymodule] are:
./modules/texts/rawtext/mymodule/
./modules/texts/ztext/mymodule/
./modules/comments/zcom/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

But when it really comes down to it, a valid path could be: 
./xxx/ or ./xxx/mymodule
</td>
<td> </td>
<td> </td>
</tr>
<tr>
<td>Description</td>
<td><string> 

This is a short (1 line) title of the module.</td>
<td> </td>
<td> </td>
</tr>
<tr>
<td>ModDrv</td>
<td>
RawText (for uncompressed Bibles) 
zText (for compressed Bibles) 
RawCom (for uncompressed Commentaries) 
RawCom4 (for uncompressed Commentaries having entries greater than 32K bytes) 
zCom (for compressed Commentaries) 
HREFCom (currently no module uses this type) 
RawFiles (for Personal Commentary) 
RawLD (for uncompressed Dictionaries) 
RawLD4 (for uncompressed Dictionaries having entries greater than 32K bytes) 
zLD (for compressed Dictionaries) 
RawGenBook (for uncompressed tree keyed modules)
</td>
<td> </td>
<td> </td>
</tr>
<tr>
<th colspan="4">Elements required for proper module access</th>
</tr>
<tr>
<td>CompressType</td>
<td>ZIP 
LZSS

Used to indicate how a compressed modules (zText, zCom, & zLD) is compressed.
ZIP is the preferred format. And as of today, no compressed modules use LZSS.
</td>
<td>LZSS</td>
<td> </td>
</tr>
<tr>
<td>BlockType</td>
<td>
BOOK 
CHAPTER 
VERSE 

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.
</td>
<td>CHAPTER</td>
<td> </td>
</tr>
<tr>
<td>BlockCount</td>
<td><integer> 

Used for zLD to indicate the number of entries in a compressed block. Higher values will make the module slower, but smaller.</td>
<td>200</td>
<td> </td>
</tr>
<tr>
<td>KeyType</td>
<td>TreeKey 
VerseKey 

Used for RawGenBook to indicate whether the module contains a book or a Bible. At this time VerseKey is being developed as the solution for alternate versification.</td>
<td>TreeKey</td>
<td> </td>
</tr>
<tr>
<td>CipherKey</td>
<td><string> 
Contains the unlock key for enciphered modules. A good key is something that is hard to guess. Typically in a format matching the pattern: /[0-9]{4}[A-Za-z]{4}[0-9]{4}[A-Za-z]{4}/. Internally the key can be any byte sequence from 1 to 255 bytes in length. But this file needs it to be readable, plain text, without leading or trailing spaces. Leave a blank line ("CipherKey=") to indicate that the module is enciphered but has no unlock key. (Omit for unlocked modules.)</td>
<td> </td>
<td> </td>
</tr>
<tr>
<th colspan="4">Elements required for proper rendering</th>
</tr>
<tr>
<td>GlobalOptionFilter</td>
<td>
GBFStrongs (For GBF texts having Strong's Numbers) 
GBFFootnotes (For GBF texts having footnotes) 
GBFScripref (For GBF texts having cross references) 
GBFMorph (For GBF texts having morphology information) 
GBFHeadings (For GBF texts having headings) 
GBFRedLetterWords (For GBF texts marking the Words of Christ) 
ThMLStrongs (For THML texts having Strong's Numbers) 
ThMLFootnotes (For THML texts having footnotes) 
ThMLScripref (For THML texts having cross references) 
ThMLMorph (For THML texts having morphology information) 
ThMLHeadings (For THML texts having headings) 
ThMLVariants (For THML texts having variant readings) 
ThMLLemma (For THML texts having lemmas) 
UTF8Cantillation (For Hebrew texts having cantillation marks) 
UTF8GreekAccents (For Greek texts having accents) 
UTF8HebrewVowels (For Hebrew texts having vowel points) 
OSISStrongs (For OSIS texts having Strong's Numbers) 
OSISFootnotes (For OSIS texts having informational notes) 
OSISScripref (For OSIS texts having cross reference type notes) 
OSISMorph (For OSIS texts having morphology information) 
OSISHeadings (For OSIS texts having non-canonical headings) 
OSISRedLetterWords (For OSIS texts marking the Words of Christ) 

Each of these filters removes/hides the text's feature, when activated by the application.
These filters are applied in the order that they are listed in the conf.
</td>
<td> </td>
<td>Repeats</td>
</tr>
<tr>
<td>Direction</td>
<td>
LtoR (Left to Right) 
RtoL (Right to Left) 
BiDi (Bi-Directional) 

Indicate whether the language's script is a left to right script or a right to left script. Languages such as Hebrew, Arabic, Urdu, Farsi have a RtoL script. When a module contains more than one direction, such as a Hebrew/English dictionary, set this value to BiDi. If the RtoL script is transliterated into a LtoR script, set the value to LtoR.
</td>
<td>LtoR</td>
<td> </td>
</tr>
<tr>
<td>SourceType</td>
<td>
Plaintext 
GBF General Bible Format: http://www.ebible.org/bible/gbf.htm 
ThML Theological Markup Language: http://www.ccel.org/ThML 
OSIS Open Scriptural Information Standard: http://www.bibletechnologies.net 
TEI Text Encoding Initiative: http://www.tei-c.org/P4X/DI.html 

These are various ways that the text can be encoded. The preferred encoding is OSIS. TEI is preferred for dictionaries until OSIS supports dictionaries. 

In SWORD, for modules encoded with ThML, OSIS or TEI, each verse, dictionary entry, and book division needs to be well-formed XML or it will result in display problems in some frontends.
</td>
<td>Plaintext</td>
<td> </td>
</tr>
<tr>
<td>Encoding</td>
<td>
UTF-8 
Latin-1 

The preferred encoding of texts is UTF-8. Latin-1 is defined by [http://en.wikipedia.org/wiki/Windows-1252 cp1252] which is a superset of ISO8859-1.

This encoding indicates how the conf and the module are encoded.
</td>
<td>Latin-1</td>
<td> </td>
</tr>
<tr>
<td>DisplayLevel</td>
<td><integer></td>
<td>1</td>
<td> </td>
</tr>
<tr>
<td>Font</td>
<td><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.
</td>
<td> </td>
<td> </td>
</tr>
<tr>
<td>OSISqToTick</td>
<td>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.</td>
<td>true</td>
<td> </td>
</tr>
<tr>
<th colspan="4">Elements to indicate features</th>
</tr>
<tr>
<td>Feature</td>
<td>
StrongsNumbers (for modules that include Strong's numbers) 
GreekDef (for modules with Strong's number encoded Greek definitions) 
HebrewDef (for modules with Strong's number encoded Hebrew definitions) 
GreekParse (for modules with Greek morphology expansions) 
HebrewParse (for modules with Hebrew morphology expansions) 
DailyDevotion (for daily devotionals using one of the LD drivers and keyed with MM.DD) 
Glossary (for collections of glosses using one of the LD drivers) 
Images (for modules that contain images of any type)
</td>
<td> </td>
<td>Repeats</td>
</tr>
<tr>
<td>GlossaryFrom</td>
<td><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.</td>
<td> </td>
<td> </td>
</tr>
<tr>
<td>GlossaryTo</td>
<td><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.</td>
<td> </td>
<td> </td>
</tr>
<tr>
<th colspan="4">General informatic and installer elements</th>
</tr>
<tr>
<td>About</td>
<td><string> 
A lengthier description and may include copyright, source, etc. information, possibly duplicating information in other elements.</td>
<td> </td>
<td>Continuation RTF</td>
</tr>
<tr>
<td>Version</td>
<td><version string> 
Gives the module's revision number. Incrementing it when changes are made alerts users of the SWORD Installers to the presence of updated modules. Please start with version 1.0 and increment by 0.1 for minor updates and by larger values for more major updates such as a new text source. Changes to this conf file should also increment the version number. Do not use non-numbers, such as 1.4a or 1.1.3.</td>
<td>1.0</td>
<td> </td>
</tr>
<tr>
<td>History_x.x</td>
<td><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.</td>
<td> </td>
<td>Repeats</td>
</tr>
<tr>
<td>MinimumVersion</td>
<td><version string> 
Identifies the minimum version of the Sword library required for this module.</td>
<td>1.5.1a</td>
<td> </td>
</tr>
<tr>
<td>Category</td>
<td>
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) 
This is used by installers to further categorize the modules beyond what can be figured out by the ModDrv and Feature.
</td>
<td> </td>
<td> </td>
</tr>
<tr>
<td>LCSH</td>
<td><tree/string> 
Library of Congress Subject Heading. You may search the [http://catalog.loc.gov 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.</td>
<td> </td>
<td> </td>
</tr>
<tr>
<td>Lang</td>
<td><xml:lang identifier> 
This is the primary language code of the module and should include a value according to RFC 4646 using ISO639 codes when possible. 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). Failing that, use ISO 639-3, which covers over 7000 languages. See: http://www.sil.org/iso639-3/codes.asp for ISO 639-1, 639-2/T and 639-3 codes. 

If a text is country specific, such as the Anglicized NIV, include the [http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html ISO 3166-1 country code] after the language code and an underscore (e.g. en_GB for UK English).</td>
<td>en</td>
<td> </td>
</tr>
<tr>
<td>InstallSize</td>
<td><integer (indicating bytes)></td>
<td> </td>
<td> </td>
</tr>
<tr>
<td>SwordVersionDate</td>
<td><ISO date string (yyyy-mm-dd)>
Indicates the date that the module was changed.</td>
<td> </td>
<td> </td>
</tr>
<tr>
<td>Obsoletes</td>
<td><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.</td>
<td> </td>
<td>Repeats</td>
</tr>
<tr>
<th colspan="4">Copyright & Licensing related elements</th>
</tr>
<tr>
<td>Copyright</td>
<td><string> 
Contains the copyright notice for the work, including the year of copyright and the owner of the copyright.</td>
<td> </td>
<td>Continuation</td>
</tr>
<tr>
<td>CopyrightHolder</td>
<td><string> 
Contains the name of the copyright holder.</td>
<td> </td>
<td> </td>
</tr>
<tr>
<td>CopyrightDate</td>
<td><integer (indicating year)></td>
<td> </td>
<td> </td>
</tr>
<tr>
<td>CopyrightNotes</td>
<td><string></td>
<td> </td>
<td>Continuation RTF</td>
</tr>
<tr>
<td>CopyrightContactName</td>
<td><string> 
Contains the name of the copyright holder.</td>
<td> </td>
<td>Continuation RTF</td>
</tr>
<tr>
<td>CopyrightContactNotes</td>
<td><string></td>
<td> </td>
<td>Continuation RTF</td>
</tr>
<tr>
<td>CopyrightContactAddress</td>
<td><string> 
Contains the mailing address of the copyright holder.</td>
<td> </td>
<td>Continuation RTF</td>
</tr>
<tr>
<td>CopyrightContactEmail</td>
<td><string> 
Contains the email address of the copyright holder, preferably in the form: name at xyz dot com.</td>
<td> </td>
<td> </td>
</tr>
<tr>
<td>ShortPromo</td>
<td><string> 
A link to the home page for the module, perhaps with an encouragement to visit the site.</td>
<td> </td>
<td>HTML Link</td>
</tr>
<tr>
<td>ShortCopyright</td>
<td><string></td>
<td> </td>
<td> </td>
</tr>
<tr>
<td>DistributionLicense</td>
<td>
Public Domain 
Copyrighted 
Copyrighted; Permission to distribute granted to CrossWire 
Copyrighted; Free non-commercial distribution 
Creative Commons: [http://creativecommons.org/licenses/by-nc-nd by-nc-nd] 
Creative Commons: [http://creativecommons.org/licenses/by-nc-sa by-nc-sa] 
Creative Commons: [http://creativecommons.org/licenses/by-nc by-nc] 
Creative Commons: [http://creativecommons.org/licenses/by-nd by-nd] 
Creative Commons: [http://creativecommons.org/licenses/by-sa by-sa] 
Creative Commons: [http://creativecommons.org/licenses/by by] 
 
Use one of these strings verbatim. The actual copyright and/or license information is held in other elements. The last six licenses are [http://creativecommons.org/ Creative Commons] licenses.</td>
<td> </td>
<td> </td>
</tr>
<tr>
<td>DistributionSource</td>
<td><string> 
Indicates where the text may be found, such as a URL.</td>
<td> </td>
<td>Continuation</td>
</tr>
<tr>
<td>DistributionNotes</td>
<td><string> 
Indicates any additional notes about distribution of the module.</td>
<td> </td>
<td>Continuation</td>
</tr>
<tr>
<td>TextSource</td>
<td><string, probably a URL> 
Indicates, either in prose (such as "CCEL") or as a URL of the source of the text</td>
<td> </td>
<td>Continuation</td>
</tr>
</table>

=Creating a module=
The SWORD Project currently requires that all submitted texts be Unicode (specifically UTF-8) encoded documents. We recommend that texts be marked up in OSIS, but will still accept those marked up in either ThML or GBF. TEI is currently under development for Dictionaries.

==Preparing a Text for Import==

===Encoding===
For English language texts that only make use of ASCII characters, no change to the source encoding will be required. For other European language and most other languages, there probably exist simple encoding converters for ISO and national standards to UTF-8. For more complex source encodings, you may need to create your own converter or adapt an existing one. Some currently available conversion tools that you may find useful, depending on your platform and needs, include:

uconv (part of ICU), available compiled for Win32 at http://crosswire.org/ftpmirror/pub/sword/utils/win32/uconv.zip or in source format from ICU at http://oss.software.ibm.com/icu/.
font2uni from CCEL, available at http://www.ccel.org/info/gkheb/.

uconv is best suited for standard encodings and font2uni is best suited for font-specific encodings. When creating XML texts, the only entities that should be used are &amp; for '&' and &lt; for '<'. All other entities should be encoded as their UTF-8 equivalents.

===Markup===
Internally, SWORD can process text in one of four formats: GBF, ThML, OSIS and TEI. From these formats, it can convert to other formats, including RTF and HTML, for display. GBF has been our preferred format in the past for Bibles and commentaries. ThML became our preferred format for commentaries, dictionaries, and general books. OSIS 2.1 is now the preferred format for Bibles and commentaries. At the moment OSIS does not have good support for dictionaries and will be adopting markup from TEI for dictionaries. For that reason we are adding direct support for TEI for dictionaries and may not be complete.

You may find documentation for each of these standards at their respective websites: 
*General Bible Format (GBF) : http://www.ebible.org/bible/gbf.htm 
*Theological Markup Format (ThML) : http://www.ccel.org/ThML/ 
*Open Scriptural Information Standard (OSIS) : http://www.bibletechnologies.net/ 
*Text Encoding Initiative (TEI) : http://www.tei-c.org/P4X/DI.html 

In SWORD, for modules encoded with ThML and OSIS, each verse, dictionary entry, and book division needs to be well-formed XML or it will result in display problems in some frontends. SWORD only handles a subset of the ThML tags that we have found necessary, but we are willing to supporting additional tags, as the need arises. For OSIS 2.1 support for the whole tagset is nearly complete.

Supported GBF tags include: <WG>, <WH>, <WTG>, <WTH>, <RX>, <RF>, <FI>, <FB>, <FN>, <FR>, <FS>, <FU>, <FO>, <FV>, <CA>, <CL>, <CG>, <CM>, <CT>, <JR>, <JC>, <JL>, <TT>, and <TS> (plus closing tags where appropriate). In addition, SWORD allows full use of UTF-8 rather than merely ASCII as the GBF standard specifies.

Supported ThML tags include: <sync> (with type parameters of Strongs, morph, & lemma), <scripRef>, and <note> (plus closing tags where appropriate). XHTML tags that ThML inherits, which may be used in SWORD modules include <div> (with types of sechead for section headings and title for titles, , , and . Additional XHTML tags may be interpreted by those SWORD frontends that render HTML, but will not be translated to RTF for the Win32 frontend.

===Import formats===
====ThML and OSIS Formatted General Books====
With ThML and OSIS formatted general books, provided your document is well-formed and valid XML according to the ThML DTD or the OSIS 2.1 Schema, you should not need to do any further processing. You can use your XML file with thml2gbs and 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.

====imp Format====
The imp or import format is the most versatile of the import formats and may be used in creating all types of modules (Bibles, commentaries, dictionaries, daily devotionals, glossaries, general books, etc.) in any supported format (GBF, ThML, OSIS or TEI). Each entry in an imp file may take as many lines as are needed. The first line of the entry will have a format such as "$$$<key>" and will be followed by all lines of text that should be included with that entry. So our above example in imp format would be written as:
$$$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.

Commentaries would follow the same format, but would probably include a greater number of lines of text. If your Bible or commentary uses a single entry to handle multiple verses, simply give a list or range of verses as the key (e.g. "$$$Genesis 1:1-5", "$$$Exodus 1", "$$$Leviticus 1:1,5"). Lexicons, dictionaries, glossaries and daily devotionals would take a form such as:
$$$Adam
Adam was the first man created by God.
$$$Eve
Eve was the first woman created by God.

For daily devotionals, you must encode the key as "$$$mm.dd", such as "$$$01.01" for January 1st and "$$$12.31" for December 31st.

General books are encoded with each book division as a separate entry. The entries are then listed as a tree hierarchy with keys similar to a file system directory structure. For example, if you were encoding the Josephus' Works, you might have a structure like this:
$$$/War
The War of the Jews
$$$/War/Book 1
Book 1 of the War of the Jews
$$$/War/Book 1/Chapter 1
Chapter 1 of Book 1 of the War of the Jews
$$$/War/Book 1/Chapter 1/Section 1
Section 1 of Chapter 1 of Book 1 of the War of the Jews
$$$/War/Book 1/Chapter 1/Section 2
Section 2 of Chapter 1 of Book 1 of the War of the Jews

==Importing==
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 ThML document, use thml2gbs.
*If your text is a valid OSIS Bible, use osis2mod.
*If your text is a valid OSIS document, use xml2gbs.
*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.

==Additional Utilities==
There are additional utilities that may be used on SWORD modules:

===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>'

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

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

==Submitting content to the SWORD Project==
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. All modules submitted to the SWORD Project for distribution either on the internet or on CDs should include both the module as a single document and the .conf file.

The module itself should be an uncompiled, plain text document in either vpl (verse-per-line), imp (import), ThML, OSIS or TEI format, ready to be run through one of the import tools.

Before any module will be considered for posting, we expect that the following minimum set of tags be included in its .conf file: DataPath, ModDrv, Lang, Description, About, DistributionLicense, and TextSource. We also strongly prefer that an LCSH line be included with the .conf file, but will look the LCSH up ourselves if you have trouble deciding on a value. (You can look at other .conf files for examples.)

When you feel 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=
===Guide to Writing [[OSIS Bibles]]===

===[[DevTools:OSISBookNames|OSIS Book Name Abbreviations]]===
===List of Known [[Module Repositories]]===
===[[Module Requests]]===
===[[New Modules]]===

DevTools:Modules

2007-10-05T13:43:36Z

Spookylukey: /* Additional Utilities */

= Module Development=
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.

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 can be created with a standard text editor like notepad, emacs, vi, or pico. Its contents are described below in section II.

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.

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.

After this, you may test your work and consider submitting it to The SWORD Project for public distribution from our website.

=Creating a .conf File=
==.conf File Layout==
The conf file tells the Sword engine how to treat installed module files, etc. which kind of markup they contain, and so forth.

Below is a listing of the possible directives in that file. Each of these directives of the form key=value. Some keys can be repeated. Some can have values that span more than 1 line with '\' at the end of a line indicating that the text on the next line continues the value. Some values allow RTF and some allow HTML <a href="xxx">label&lt/a>hypertext links. HTML is not allowed otherwise.

Enumerated values are shown in bold. These should be used exactly as given and no other values should be used.

<table width="100%" border="1">
<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. 

The name of the file should be the lowercase of this name followed by .conf. For example, [MyModule] would be mymodule.conf.</td>
<td> </td>
<td> </td>
</tr>
<tr>
<td>DataPath</td>
<td><relative system path>

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.

Typical paths are for a module named [mymodule] are:
./modules/texts/rawtext/mymodule/
./modules/texts/ztext/mymodule/
./modules/comments/zcom/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

But when it really comes down to it, a valid path could be: 
./xxx/ or ./xxx/mymodule
</td>
<td> </td>
<td> </td>
</tr>
<tr>
<td>Description</td>
<td><string> 

This is a short (1 line) title of the module.</td>
<td> </td>
<td> </td>
</tr>
<tr>
<td>ModDrv</td>
<td>
RawText (for uncompressed Bibles) 
zText (for compressed Bibles) 
RawCom (for uncompressed Commentaries) 
RawCom4 (for uncompressed Commentaries having entries greater than 32K bytes) 
zCom (for compressed Commentaries) 
HREFCom (currently no module uses this type) 
RawFiles (for Personal Commentary) 
RawLD (for uncompressed Dictionaries) 
RawLD4 (for uncompressed Dictionaries having entries greater than 32K bytes) 
zLD (for compressed Dictionaries) 
RawGenBook (for uncompressed tree keyed modules)
</td>
<td> </td>
<td> </td>
</tr>
<tr>
<th colspan="4">Elements required for proper module access</th>
</tr>
<tr>
<td>CompressType</td>
<td>ZIP 
LZSS

Used to indicate how a compressed modules (zText, zCom, & zLD) is compressed.
ZIP is the preferred format. And as of today, no compressed modules use LZSS.
</td>
<td>LZSS</td>
<td> </td>
</tr>
<tr>
<td>BlockType</td>
<td>
BOOK 
CHAPTER 
VERSE 

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.
</td>
<td>CHAPTER</td>
<td> </td>
</tr>
<tr>
<td>BlockCount</td>
<td><integer> 

Used for zLD to indicate the number of entries in a compressed block. Higher values will make the module slower, but smaller.</td>
<td>200</td>
<td> </td>
</tr>
<tr>
<td>KeyType</td>
<td>TreeKey 
VerseKey 

Used for RawGenBook to indicate whether the module contains a book or a Bible. At this time VerseKey is being developed as the solution for alternate versification.</td>
<td>TreeKey</td>
<td> </td>
</tr>
<tr>
<td>CipherKey</td>
<td><string> 
Contains the unlock key for enciphered modules. A good key is something that is hard to guess. Typically in a format matching the pattern: /[0-9]{4}[A-Za-z]{4}[0-9]{4}[A-Za-z]{4}/. Internally the key can be any byte sequence from 1 to 255 bytes in length. But this file needs it to be readable, plain text, without leading or trailing spaces. Leave a blank line ("CipherKey=") to indicate that the module is enciphered but has no unlock key. (Omit for unlocked modules.)</td>
<td> </td>
<td> </td>
</tr>
<tr>
<th colspan="4">Elements required for proper rendering</th>
</tr>
<tr>
<td>GlobalOptionFilter</td>
<td>
GBFStrongs (For GBF texts having Strong's Numbers) 
GBFFootnotes (For GBF texts having footnotes) 
GBFScripref (For GBF texts having cross references) 
GBFMorph (For GBF texts having morphology information) 
GBFHeadings (For GBF texts having headings) 
GBFRedLetterWords (For GBF texts marking the Words of Christ) 
ThMLStrongs (For THML texts having Strong's Numbers) 
ThMLFootnotes (For THML texts having footnotes) 
ThMLScripref (For THML texts having cross references) 
ThMLMorph (For THML texts having morphology information) 
ThMLHeadings (For THML texts having headings) 
ThMLVariants (For THML texts having variant readings) 
ThMLLemma (For THML texts having lemmas) 
UTF8Cantillation (For Hebrew texts having cantillation marks) 
UTF8GreekAccents (For Greek texts having accents) 
UTF8HebrewVowels (For Hebrew texts having vowel points) 
OSISStrongs (For OSIS texts having Strong's Numbers) 
OSISFootnotes (For OSIS texts having informational notes) 
OSISScripref (For OSIS texts having cross reference type notes) 
OSISMorph (For OSIS texts having morphology information) 
OSISHeadings (For OSIS texts having non-canonical headings) 
OSISRedLetterWords (For OSIS texts marking the Words of Christ) 

Each of these filters removes/hides the text's feature, when activated by the application.
These filters are applied in the order that they are listed in the conf.
</td>
<td> </td>
<td>Repeats</td>
</tr>
<tr>
<td>Direction</td>
<td>
LtoR (Left to Right) 
RtoL (Right to Left) 
BiDi (Bi-Directional) 

Indicate whether the language's script is a left to right script or a right to left script. Languages such as Hebrew, Arabic, Urdu, Farsi have a RtoL script. When a module contains more than one direction, such as a Hebrew/English dictionary, set this value to BiDi. If the RtoL script is transliterated into a LtoR script, set the value to LtoR.
</td>
<td>LtoR</td>
<td> </td>
</tr>
<tr>
<td>SourceType</td>
<td>
Plaintext 
GBF General Bible Format: http://www.ebible.org/bible/gbf.htm 
ThML Theological Markup Language: http://www.ccel.org/ThML 
OSIS Open Scriptural Information Standard: http://www.bibletechnologies.net 
TEI Text Encoding Initiative: http://www.tei-c.org/P4X/DI.html 

These are various ways that the text can be encoded. The preferred encoding is OSIS. TEI is preferred for dictionaries until OSIS supports dictionaries. 

In SWORD, for modules encoded with ThML, OSIS or TEI, each verse, dictionary entry, and book division needs to be well-formed XML or it will result in display problems in some frontends.
</td>
<td>Plaintext</td>
<td> </td>
</tr>
<tr>
<td>Encoding</td>
<td>
UTF-8 
Latin-1 

The preferred encoding of texts is UTF-8. Latin-1 is defined by [http://en.wikipedia.org/wiki/Windows-1252 cp1252] which is a superset of ISO8859-1.

This encoding indicates how the conf and the module are encoded.
</td>
<td>Latin-1</td>
<td> </td>
</tr>
<tr>
<td>DisplayLevel</td>
<td><integer></td>
<td>1</td>
<td> </td>
</tr>
<tr>
<td>Font</td>
<td><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.
</td>
<td> </td>
<td> </td>
</tr>
<tr>
<td>OSISqToTick</td>
<td>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.</td>
<td>true</td>
<td> </td>
</tr>
<tr>
<th colspan="4">Elements to indicate features</th>
</tr>
<tr>
<td>Feature</td>
<td>
StrongsNumbers (for modules that include Strong's numbers) 
GreekDef (for modules with Strong's number encoded Greek definitions) 
HebrewDef (for modules with Strong's number encoded Hebrew definitions) 
GreekParse (for modules with Greek morphology expansions) 
HebrewParse (for modules with Hebrew morphology expansions) 
DailyDevotion (for daily devotionals using one of the LD drivers and keyed with MM.DD) 
Glossary (for collections of glosses using one of the LD drivers) 
Images (for modules that contain images of any type)
</td>
<td> </td>
<td>Repeats</td>
</tr>
<tr>
<td>GlossaryFrom</td>
<td><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.</td>
<td> </td>
<td> </td>
</tr>
<tr>
<td>GlossaryTo</td>
<td><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.</td>
<td> </td>
<td> </td>
</tr>
<tr>
<th colspan="4">General informatic and installer elements</th>
</tr>
<tr>
<td>About</td>
<td><string> 
A lengthier description and may include copyright, source, etc. information, possibly duplicating information in other elements.</td>
<td> </td>
<td>Continuation RTF</td>
</tr>
<tr>
<td>Version</td>
<td><version string> 
Gives the module's revision number. Incrementing it when changes are made alerts users of the SWORD Installers to the presence of updated modules. Please start with version 1.0 and increment by 0.1 for minor updates and by larger values for more major updates such as a new text source. Changes to this conf file should also increment the version number. Do not use non-numbers, such as 1.4a or 1.1.3.</td>
<td>1.0</td>
<td> </td>
</tr>
<tr>
<td>History_x.x</td>
<td><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.</td>
<td> </td>
<td>Repeats</td>
</tr>
<tr>
<td>MinimumVersion</td>
<td><version string> 
Identifies the minimum version of the Sword library required for this module.</td>
<td>1.5.1a</td>
<td> </td>
</tr>
<tr>
<td>Category</td>
<td>
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) 
This is used by installers to further categorize the modules beyond what can be figured out by the ModDrv and Feature.
</td>
<td> </td>
<td> </td>
</tr>
<tr>
<td>LCSH</td>
<td><tree/string> 
Library of Congress Subject Heading. You may search the [http://catalog.loc.gov 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.</td>
<td> </td>
<td> </td>
</tr>
<tr>
<td>Lang</td>
<td><xml:lang identifier> 
This is the primary language code of the module and should include a value according to RFC 4646 using ISO639 codes when possible. 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). Failing that, use ISO 639-3, which covers over 7000 languages. See: http://www.sil.org/iso639-3/codes.asp for ISO 639-1, 639-2/T and 639-3 codes. 

If a text is country specific, such as the Anglicized NIV, include the [http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html ISO 3166-1 country code] after the language code and an underscore (e.g. en_GB for UK English).</td>
<td>en</td>
<td> </td>
</tr>
<tr>
<td>InstallSize</td>
<td><integer (indicating bytes)></td>
<td> </td>
<td> </td>
</tr>
<tr>
<td>SwordVersionDate</td>
<td><ISO date string (yyyy-mm-dd)>
Indicates the date that the module was changed.</td>
<td> </td>
<td> </td>
</tr>
<tr>
<td>Obsoletes</td>
<td><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.</td>
<td> </td>
<td>Repeats</td>
</tr>
<tr>
<th colspan="4">Copyright & Licensing related elements</th>
</tr>
<tr>
<td>Copyright</td>
<td><string> 
Contains the copyright notice for the work, including the year of copyright and the owner of the copyright.</td>
<td> </td>
<td>Continuation</td>
</tr>
<tr>
<td>CopyrightHolder</td>
<td><string> 
Contains the name of the copyright holder.</td>
<td> </td>
<td> </td>
</tr>
<tr>
<td>CopyrightDate</td>
<td><integer (indicating year)></td>
<td> </td>
<td> </td>
</tr>
<tr>
<td>CopyrightNotes</td>
<td><string></td>
<td> </td>
<td>Continuation RTF</td>
</tr>
<tr>
<td>CopyrightContactName</td>
<td><string> 
Contains the name of the copyright holder.</td>
<td> </td>
<td>Continuation RTF</td>
</tr>
<tr>
<td>CopyrightContactNotes</td>
<td><string></td>
<td> </td>
<td>Continuation RTF</td>
</tr>
<tr>
<td>CopyrightContactAddress</td>
<td><string> 
Contains the mailing address of the copyright holder.</td>
<td> </td>
<td>Continuation RTF</td>
</tr>
<tr>
<td>CopyrightContactEmail</td>
<td><string> 
Contains the email address of the copyright holder, preferably in the form: name at xyz dot com.</td>
<td> </td>
<td> </td>
</tr>
<tr>
<td>ShortPromo</td>
<td><string> 
A link to the home page for the module, perhaps with an encouragement to visit the site.</td>
<td> </td>
<td>HTML Link</td>
</tr>
<tr>
<td>ShortCopyright</td>
<td><string></td>
<td> </td>
<td> </td>
</tr>
<tr>
<td>DistributionLicense</td>
<td>
Public Domain 
Copyrighted 
Copyrighted; Permission to distribute granted to CrossWire 
Copyrighted; Free non-commercial distribution 
Creative Commons: [http://creativecommons.org/licenses/by-nc-nd by-nc-nd] 
Creative Commons: [http://creativecommons.org/licenses/by-nc-sa by-nc-sa] 
Creative Commons: [http://creativecommons.org/licenses/by-nc by-nc] 
Creative Commons: [http://creativecommons.org/licenses/by-nd by-nd] 
Creative Commons: [http://creativecommons.org/licenses/by-sa by-sa] 
Creative Commons: [http://creativecommons.org/licenses/by by] 
 
Use one of these strings verbatim. The actual copyright and/or license information is held in other elements. The last six licenses are [http://creativecommons.org/ Creative Commons] licenses.</td>
<td> </td>
<td> </td>
</tr>
<tr>
<td>DistributionSource</td>
<td><string> 
Indicates where the text may be found, such as a URL.</td>
<td> </td>
<td>Continuation</td>
</tr>
<tr>
<td>DistributionNotes</td>
<td><string> 
Indicates any additional notes about distribution of the module.</td>
<td> </td>
<td>Continuation</td>
</tr>
<tr>
<td>TextSource</td>
<td><string, probably a URL> 
Indicates, either in prose (such as "CCEL") or as a URL of the source of the text</td>
<td> </td>
<td>Continuation</td>
</tr>
</table>

=Creating a module=
The SWORD Project currently requires that all submitted texts be Unicode (specifically UTF-8) encoded documents. We recommend that texts be marked up in OSIS, but will still accept those marked up in either ThML or GBF. TEI is currently under development for Dictionaries.

==Preparing a Text for Import==

===Encoding===
For English language texts that only make use of ASCII characters, no change to the source encoding will be required. For other European language and most other languages, there probably exist simple encoding converters for ISO and national standards to UTF-8. For more complex source encodings, you may need to create your own converter or adapt an existing one. Some currently available conversion tools that you may find useful, depending on your platform and needs, include:

uconv (part of ICU), available compiled for Win32 at http://crosswire.org/ftpmirror/pub/sword/utils/win32/uconv.zip or in source format from ICU at http://oss.software.ibm.com/icu/.
font2uni from CCEL, available at http://www.ccel.org/info/gkheb/.

uconv is best suited for standard encodings and font2uni is best suited for font-specific encodings. When creating XML texts, the only entities that should be used are &amp; for '&' and &lt; for '<'. All other entities should be encoded as their UTF-8 equivalents.

===Markup===
Internally, SWORD can process text in one of four formats: GBF, ThML, OSIS and TEI. From these formats, it can convert to other formats, including RTF and HTML, for display. GBF has been our preferred format in the past for Bibles and commentaries. ThML became our preferred format for commentaries, dictionaries, and general books. OSIS 2.1 is now the preferred format for Bibles and commentaries. At the moment OSIS does not have good support for dictionaries and will be adopting markup from TEI for dictionaries. For that reason we are adding direct support for TEI for dictionaries and may not be complete.

You may find documentation for each of these standards at their respective websites: 
*General Bible Format (GBF) : http://www.ebible.org/bible/gbf.htm 
*Theological Markup Format (ThML) : http://www.ccel.org/ThML/ 
*Open Scriptural Information Standard (OSIS) : http://www.bibletechnologies.net/ 
*Text Encoding Initiative (TEI) : http://www.tei-c.org/P4X/DI.html 

In SWORD, for modules encoded with ThML and OSIS, each verse, dictionary entry, and book division needs to be well-formed XML or it will result in display problems in some frontends. SWORD only handles a subset of the ThML tags that we have found necessary, but we are willing to supporting additional tags, as the need arises. For OSIS 2.1 support for the whole tagset is nearly complete.

Supported GBF tags include: <WG>, <WH>, <WTG>, <WTH>, <RX>, <RF>, <FI>, <FB>, <FN>, <FR>, <FS>, <FU>, <FO>, <FV>, <CA>, <CL>, <CG>, <CM>, <CT>, <JR>, <JC>, <JL>, <TT>, and <TS> (plus closing tags where appropriate). In addition, SWORD allows full use of UTF-8 rather than merely ASCII as the GBF standard specifies.

Supported ThML tags include: <sync> (with type parameters of Strongs, morph, & lemma), <scripRef>, and <note> (plus closing tags where appropriate). XHTML tags that ThML inherits, which may be used in SWORD modules include <div> (with types of sechead for section headings and title for titles, , , and . Additional XHTML tags may be interpreted by those SWORD frontends that render HTML, but will not be translated to RTF for the Win32 frontend.

===Import formats===
====ThML and OSIS Formatted General Books====
With ThML and OSIS formatted general books, provided your document is well-formed and valid XML according to the ThML DTD or the OSIS 2.1 Schema, you should not need to do any further processing. You can use your XML file with thml2gbs and 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.

====imp Format====
The imp or import format is the most versatile of the import formats and may be used in creating all types of modules (Bibles, commentaries, dictionaries, daily devotionals, glossaries, general books, etc.) in any supported format (GBF, ThML, OSIS or TEI). Each entry in an imp file may take as many lines as are needed. The first line of the entry will have a format such as "$$$<key>" and will be followed by all lines of text that should be included with that entry. So our above example in imp format would be written as:
$$$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.

Commentaries would follow the same format, but would probably include a greater number of lines of text. If your Bible or commentary uses a single entry to handle multiple verses, simply give a list or range of verses as the key (e.g. "$$$Genesis 1:1-5", "$$$Exodus 1", "$$$Leviticus 1:1,5"). Lexicons, dictionaries, glossaries and daily devotionals would take a form such as:
$$$Adam
Adam was the first man created by God.
$$$Eve
Eve was the first woman created by God.

For daily devotionals, you must encode the key as "$$$mm.dd", such as "$$$01.01" for January 1st and "$$$12.31" for December 31st.

General books are encoded with each book division as a separate entry. The entries are then listed as a tree hierarchy with keys similar to a file system directory structure. For example, if you were encoding the Josephus' Works, you might have a structure like this:
$$$/War
The War of the Jews
$$$/War/Book 1
Book 1 of the War of the Jews
$$$/War/Book 1/Chapter 1
Chapter 1 of Book 1 of the War of the Jews
$$$/War/Book 1/Chapter 1/Section 1
Section 1 of Chapter 1 of Book 1 of the War of the Jews
$$$/War/Book 1/Chapter 1/Section 2
Section 2 of Chapter 1 of Book 1 of the War of the Jews

==Importing==
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 ThML document, use thml2gbs.
*If your text is a valid OSIS Bible, use osis2mod.
*If your text is a valid OSIS document, use xml2gbs.
*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.

==Additional Utilities==
There are additional utilities that may be used on SWORD modules:

===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>'

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

===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 module preparation and convertion.

==Submitting content to the SWORD Project==
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. All modules submitted to the SWORD Project for distribution either on the internet or on CDs should include both the module as a single document and the .conf file.

The module itself should be an uncompiled, plain text document in either vpl (verse-per-line), imp (import), ThML, OSIS or TEI format, ready to be run through one of the import tools.

Before any module will be considered for posting, we expect that the following minimum set of tags be included in its .conf file: DataPath, ModDrv, Lang, Description, About, DistributionLicense, and TextSource. We also strongly prefer that an LCSH line be included with the .conf file, but will look the LCSH up ourselves if you have trouble deciding on a value. (You can look at other .conf files for examples.)

When you feel 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=
===Guide to Writing [[OSIS Bibles]]===

===[[DevTools:OSISBookNames|OSIS Book Name Abbreviations]]===
===List of Known [[Module Repositories]]===
===[[Module Requests]]===
===[[New Modules]]===

Module Requests

2007-10-05T13:30:40Z

Spookylukey: /* Commentaries */

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.

====Bible Versions====
*Nederlands Bijbelgenootschap [http://www.biblija.net/biblija.cgi?lang=nl], [http://80.252.86.246/]
*Turkish Kutsal Kitap [http://www.kitabimukaddes.com/] [http://www.translation-trust.org/html/home.html]
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'''
*German revidierte Luther Bible 1984 [http://www.dbg.de]

====Books====
<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>

====Commentaries====
<ul>
<li>Calvin's Commentaries [http://www.ccel.org/ccel/calvin/commentaries.i.html]
 
Work is in progress. Current approach is to combine ThML files from CCEL and convert to OSIS.
This work is mostly done - see: http://crosswire.org/svn/sword-tools/trunk/modules/calvinscommentaries/
 
 
The next step requires a module importer for OSIS commentaries -- the current OSIS importer assumes that the document is formatted as a Bible.
</li>
</ul>

====Devotionals====

====Lexicons====

DevTools:Misc

2007-10-05T13:25:26Z

Spookylukey: Location and documentation for sword-tools

Some miscellaneous development tools are available in a Subversion repository available at:

http://crosswire.org/svn/sword-tools/

This contains tools, programs and libraries in various languages that are usually used for the creation of modules. It includes scripts that module authors may use in their preparation of modules. These are mainly undocumented and not intended for any public release. Documentation of ''some'' of these tools can be found below or in the READMEs in the repository.

== thml2osis ==

This is an XSLT program that attempts to convert ThML sources (such as those on CCEL) into valid OSIS, as losslessly as possible. The OSIS can then be used for creating SWORD modules. See the README in the relevant directory for more information.

Module Requests

2007-10-05T13:09:24Z

Spookylukey: /* Commentaries */

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.

====Bible Versions====
*Nederlands Bijbelgenootschap [http://www.biblija.net/biblija.cgi?lang=nl], [http://80.252.86.246/]
*Turkish Kutsal Kitap [http://www.kitabimukaddes.com/] [http://www.translation-trust.org/html/home.html]
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'''
*German revidierte Luther Bible 1984 [http://www.dbg.de]

====Books====
<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>

====Commentaries====
<ul>
<li>Calvin's Commentaries [http://www.ccel.org/ccel/calvin/commentaries.i.html]
- work in progress - see http://crosswire.org/svn/sword-tools/trunk/modules/calvinscommentaries/</li>
</ul>

====Devotionals====

====Lexicons====

Frontends:KioSword

2007-07-11T12:56:03Z

Spookylukey: Added page about Kio-Sword

Kio-Sword is a lightweight Sword frontend for [http://www.kde.org KDE] that integrates into the KDE web browser, Konqueror.

It is intended to be used as a companion to [http://www.bibletime.info/ BibleTime], providing very quick access to your Sword modules. It currently does not provide an easy way to install modules -- it is assumed you will use something like BibleTime for this.

See the [http://lukeplant.me.uk/kio-sword/ Kio-Sword homepage] for more.