CrossWire Bible Society - User contributions [en]

Module Submission

2023-06-15T14:32:37Z

Domcox: /* What's next? */ Fix broken link

----
'''<span style="color: crimson">For information on module licensing''' → please look at [[DevTools:Module Submission and Copyrights]]
----

= How-To Name your module =
Each module needs a name that be used as a unique identifier. Valid characters for the name are limited to alphanumeric characters, numeric characters and underscore. PCRE class [A-Za-z0-9\_].

Normalized names of module contains usually<ref name="Eng">For historical reasons, modules in English do not have any language prefix.</ref> 3 letters for language, followed by a short name descibing the work. Language is encoded in ISO 639-3 code. See [http://www.sil.org/iso639-3/codes.asp] for a list of codes.

The name has to be set in CamelCase format. Example for The French Bible David Martin 1707: <code>FreBDM1707</code><ref name="bdm">The published year was added to differentiate this version from successive revisions in 1744, 1855. Otherwise we could just have named it FreBDM.</ref>

<references />

= How-To name your source files =

You should provide 2 files:

* 1 Source text which will be converted to SWORD format. The source text must be unique and cannot be splitted in several files.
* 1 Configuration file which tells Sword how to recognize and what to do with your module.

The files reflects the name of your module in '''lowercase''' followed by an extension.

Extensions for the text file are:

* OSIS: <code>.osis.xml</code>
* TEI: <code>.tei.xml</code>
* VPL: <code>.vpl</code>
* IMP: <code>.imp</code>
* ThML: <code>.thml</code>

For the configuration file, the extension is <code>.conf</code>.

So, for the <code>FreBDM1707</code> module encoded in OSIS, we have <code>frebdm1707.osis.xml</code> and <code>frebdm1707.conf</code> files.

= How-To prepare your source files =

We will accept only plain texts in VPL<ref name="vpl">Only for Bibles in KJV versification</ref> or texts marked up in OSIS or TEI, with the sole exception texts based on CCEL documents that are marked up in ThML.

<references />

== Check your OSIS before submitting ==

OSIS 2.1 is now the preferred format for Bibles, Commentaries and General Books. TEI is the prefered format for dictionaries.

OSIS texts need to have the CamelCase module name as <code>workID</code> and an appropriate <code>osisRefWork</code> entry within the appropriate header section. The document language needs to be set correctly, ISO 639-1 codes are preferred, and ISO 639-3 codes when ISO 639-1 codes do not exist for the given language. Examples:

Bible:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Bible" xml:lang="he">
</pre>

Commentary:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Commentary" xml:lang="gr">
</pre>
General Book:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="GenBook" xml:lang="en">
</pre>

== Please validate your OSIS or TEI text ==
See: Guide to [[Validate_OSIS_or_TEI_text]]

== Check your configuration file ==
We require that the following minimum set of module configuration fields are included: <code>Description</code>, <code>About</code>, <code>DistributionLicense</code>, and <code>TextSource</code>. Ensure that your module complies with our stated copyright policy.

= Copyrighted Material =
If your got permission to distribute a new module which is under copyright, please send a copy of the authorization in a file named copyright.<extension> like <code>copyright.pdf</code>, <code>copyright.png</code>...

= Other files =

Besides source, conf and copyright files we accept:
* Cascading style sheet (CSS) file used to format the contents of a module
* Media subdir containing multimedia files, commonly <code>Images</code> subdir.

= How-To submit your files =
Submit only source files. Do not submit built modules that you have imported to Sword format. Avoid spaces in folder and file names.

Send an email to <code>modules@crosswire.org</code> describing the module and your files with one of the options below:

''Note: Pressing one of the following modules@crosswire.org links will open a new mail window already filled with a sample text.''

== Files attached ==

It is highly recommended to zip your files, as they are text files they will be highly compressed with the double benefit to reduce storage and make transmitting them much easier.
Feel free to attach your zip file to the email sent to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Please%20find%20the%20attached%20zip%20archive%20with%20source%20and%20.conf%20files.%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org]. Actually the biggest file (30MB) we have is 3MB once zipped. Supported file formats: <code>tar.gz</code>; <code>tgz</code>; <code>tar.bz2</code>; <code>tb2</code>; <code>bz2</code>; <code>gz</code>; <code>zip</code>; <code>gmx</code>; <code>Z</code>; <code>7z</code>

== Link to a zip file ==

If you own a repository on the Internet, you may also store your zipped file on your repository and send the URL to this file instead to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20zip%20archive%20of%20the%20module%20with%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].

== Link to a git Repository ==

If you built your module on a public Git/GitLab/GitHub, you may want to share the <code>git clone</code> URL in the email to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20Git%20repository%20of%20the%20module%20containing%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].

We do accept git URL but there are some limitations, though:

* We expect to run into a flat structure, so:
** Module files (source, .conf) shouldn't go into a subdir
** Optional files like copyright, style.css must be at the root of your repository
** Only multimedia files (audio/video/images) should go in their own subdir, typically <code>images</code> for dictionaries
** A script subdir containing tools for converting an original source file to OSIS is welcome

Example:
<pre>
git
|
+-- copyright.pdf
+-- images/
+-- module.osis.xml
+-- module.conf
+-- script/
+-- style.css
+-- README.md
</pre>
* Try to not put other files in the repository, they are more misleading than handy. Original text URL should be linked in <code>README.md</code>. If you really need to keep the original source text in plain format, USFM ot whatever in a subdir, please add this subdir to .gitignore.
<code>$ echo sources/ >> .gitignore</code>

* No more than 1 module per git repository.

It is sometimes easier to run <code>git archive</code> and attach the resulting zip file to the email.

= What's next? =
Modules submitted to Crosswire are generally reviewed as quickly as possible, most are often accepted.

We build a binary version by using our creation and diagnostic tools: https://wiki.crosswire.org/File_Formats#The_SWORD_Project_Utilities.

== Build failure ==
If the build fails, you'll be noticed by this mail:

<pre>
This is to announce that fatal errors were encountered
while processing the module <your-module> which caused
the build to fail.

Please refer to the attached build log for more details
about the error encountered.

Useful information to fix the problem can be found in
our Wiki in the '''Module development''' section at:
https://wiki.crosswire.org.

yours,

P.S.: This email is sent automatically.

</pre>

It’s OK to make mistakes, so do not be discouraged, read the build log and if you find anything that is unclear along the way, do not hesitate to ask questions. Then, once fixed, don't hesitate to re-send your corrected module.

== Successful build ==
The build was sucessful, you'll receive this mail:

<pre>
This is to announce that we have just now uploaded <your-module>
in the CrossWire beta repository for testing purposes.

If no raised concern nor a quality alert has been sent on the list,
<your-module> will be published in a week.

Many thanks to everyone who contributed to this release.

yours

P.S.: This email is sent automatically.

</pre>

Your module is now available to download from the Beta repository. It will be tested in this repository for around a week, and if everything is ok it will be regularly published.

----
<div style="text-align:center">'''If you do not comply with the above your module submission might end up being deprioritised and will certainly not get uploaded as fast as it could be otherwise'''</div>
----

Please note: Do not edit this page unless you are actually ''directly'' involved with uploading modules onto the server. If you have a comment or addition to make, but you are not part of this particular effort, please use talk page.
[[Category:Modules]]

Module Submission

2021-02-18T21:18:11Z

Domcox: Add information about the built process

----
'''<span style="color: crimson">For information on module licensing''' → please look at [[DevTools:Module Submission and Copyrights]]
----

= How-To Name your module =
Each module needs a name that be used as a unique identifier. Valid characters for the name are limited to alphanumeric characters, numeric characters and underscore. PCRE class [A-Za-z0-9\_].

Normalized names of module contains usually<ref name="Eng">For historical reasons, modules in English do not have any language prefix.</ref> 3 letters for language, followed by a short name descibing the work. Language is encoded in ISO 639-3 code. See [http://www.sil.org/iso639-3/codes.asp] for a list of codes.

The name has to be set in CamelCase format. Example for The French Bible David Martin 1707: <code>FreBDM1707</code><ref name="bdm">The published year was added to differentiate this version from successive revisions in 1744, 1855. Otherwise we could just have named it FreBDM.</ref>

<references />

= How-To name your source files =

You should provide 2 files:

* 1 Source text which will be converted to SWORD format. The source text must be unique and cannot be splitted in several files.
* 1 Configuration file which tells Sword how to recognize and what to do with your module.

The files reflects the name of your module in '''lowercase''' followed by an extension.

Extensions for the text file are:

* OSIS: <code>.osis.xml</code>
* TEI: <code>.tei.xml</code>
* VPL: <code>.vpl</code>
* IMP: <code>.imp</code>
* ThML: <code>.thml</code>

For the configuration file, the extension is <code>.conf</code>.

So, for the <code>FreBDM1707</code> module encoded in OSIS, we have <code>frebdm1707.osis.xml</code> and <code>frebdm1707.conf</code> files.

= How-To prepare your source files =

We will accept only plain texts in VPL<ref name="vpl">Only for Bibles in KJV versification</ref> or texts marked up in OSIS or TEI, with the sole exception texts based on CCEL documents that are marked up in ThML.

<references />

== Check your OSIS before submitting ==

OSIS 2.1 is now the preferred format for Bibles, Commentaries and General Books. TEI is the prefered format for dictionaries.

OSIS texts need to have the CamelCase module name as <code>workID</code> and an appropriate <code>osisRefWork</code> entry within the appropriate header section. The document language needs to be set correctly, ISO 639-1 codes are preferred, and ISO 639-3 codes when ISO 639-1 codes do not exist for the given language. Examples:

Bible:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Bible" xml:lang="he">
</pre>

Commentary:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Commentary" xml:lang="gr">
</pre>
General Book:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="GenBook" xml:lang="en">
</pre>

== Please validate your OSIS or TEI text ==
See: Guide to [[Validate_OSIS_or_TEI_text]]

== Check your configuration file ==
We require that the following minimum set of module configuration fields are included: <code>Description</code>, <code>About</code>, <code>DistributionLicense</code>, and <code>TextSource</code>. Ensure that your module complies with our stated copyright policy.

= Copyrighted Material =
If your got permission to distribute a new module which is under copyright, please send a copy of the authorization in a file named copyright.<extension> like <code>copyright.pdf</code>, <code>copyright.png</code>...

= Other files =

Besides source, conf and copyright files we accept:
* Cascading style sheet (CSS) file used to format the contents of a module
* Media subdir containing multimedia files, commonly <code>Images</code> subdir.

= How-To submit your files =
Submit only source files. Do not submit built modules that you have imported to Sword format. Avoid spaces in folder and file names.

Send an email to <code>modules@crosswire.org</code> describing the module and your files with one of the options below:

''Note: Pressing one of the following modules@crosswire.org links will open a new mail window already filled with a sample text.''

== Files attached ==

It is highly recommended to zip your files, as they are text files they will be highly compressed with the double benefit to reduce storage and make transmitting them much easier.
Feel free to attach your zip file to the email sent to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Please%20find%20the%20attached%20zip%20archive%20with%20source%20and%20.conf%20files.%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org]. Actually the biggest file (30MB) we have is 3MB once zipped. Supported file formats: <code>tar.gz</code>; <code>tgz</code>; <code>tar.bz2</code>; <code>tb2</code>; <code>bz2</code>; <code>gz</code>; <code>zip</code>; <code>gmx</code>; <code>Z</code>; <code>7z</code>

== Link to a zip file ==

If you own a repository on the Internet, you may also store your zipped file on your repository and send the URL to this file instead to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20zip%20archive%20of%20the%20module%20with%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].

== Link to a git Repository ==

If you built your module on a public Git/GitLab/GitHub, you may want to share the <code>git clone</code> URL in the email to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20Git%20repository%20of%20the%20module%20containing%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].

We do accept git URL but there are some limitations, though:

* We expect to run into a flat structure, so:
** Module files (source, .conf) shouldn't go into a subdir
** Optional files like copyright, style.css must be at the root of your repository
** Only multimedia files (audio/video/images) should go in their own subdir, typically <code>images</code> for dictionaries
** A script subdir containing tools for converting an original source file to OSIS is welcome

Example:
<pre>
git
|
+-- copyright.pdf
+-- images/
+-- module.osis.xml
+-- module.conf
+-- script/
+-- style.css
+-- README.md
</pre>
* Try to not put other files in the repository, they are more misleading than handy. Original text URL should be linked in <code>README.md</code>. If you really need to keep the original source text in plain format, USFM ot whatever in a subdir, please add this subdir to .gitignore.
<code>$ echo sources/ >> .gitignore</code>

* No more than 1 module per git repository.

It is sometimes easier to run <code>git archive</code> and attach the resulting zip file to the email.

= What's next? =
Modules submitted to Crosswire are generally reviewed as quickly as possible, most are often accepted.

We build a binary version by using our creation and diagnostic tools: https://wiki.crosswire.orgFile_Formats#The_SWORD_Project_Utilities.

== Build failure ==
If the build fails, you'll be noticed by this mail:

<pre>
This is to announce that fatal errors were encountered
while processing the module <your-module> which caused
the build to fail.

Please refer to the attached build log for more details
about the error encountered.

Useful information to fix the problem can be found in
our Wiki in the '''Module development''' section at:
https://wiki.crosswire.org.

yours,

P.S.: This email is sent automatically.

</pre>

It’s OK to make mistakes, so do not be discouraged, read the build log and if you find anything that is unclear along the way, do not hesitate to ask questions. Then, once fixed, don't hesitate to re-send your corrected module.

== Successfull build ==
The build was sucessful, you'll receive this mail:

<pre>
This is to announce that we have just now uploaded <your-module>
in the CrossWire beta repository for testing purposes.

If no raised concern nor a quality alert has been sent on the list,
<your-module> will be published in a week.

Many thanks to everyone who contributed to this release.

yours

P.S.: This email is sent automatically.

</pre>

Your module is now available to download from the Beta repository. It will be tested in this repository for around a week, and if everything is ok it will be regularly published.

----
<div style="text-align:center">'''If you do not comply with the above your module submission might end up being deprioritised and will certainly not get uploaded as fast as it could be otherwise'''</div>
----

Please note: Do not edit this page unless you are actually ''directly'' involved with uploading modules onto the server. If you have a comment or addition to make, but you are not part of this particular effort, please use talk page.
[[Category:Modules]]

Module Submission

2021-02-18T17:43:28Z

Domcox: /* Link to a git Repository */ Add welcomed scripts dir

----
'''<span style="color: crimson">For information on module licensing''' → please look at [[DevTools:Module Submission and Copyrights]]
----

= How-To Name your module =
Each module needs a name that be used as a unique identifier. Valid characters for the name are limited to alphanumeric characters, numeric characters and underscore. PCRE class [A-Za-z0-9\_].

Normalized names of module contains usually<ref name="Eng">For historical reasons, modules in English do not have any language prefix.</ref> 3 letters for language, followed by a short name descibing the work. Language is encoded in ISO 639-3 code. See [http://www.sil.org/iso639-3/codes.asp] for a list of codes.

The name has to be set in CamelCase format. Example for The French Bible David Martin 1707: <code>FreBDM1707</code><ref name="bdm">The published year was added to differentiate this version from successive revisions in 1744, 1855. Otherwise we could just have named it FreBDM.</ref>

<references />

= How-To name your source files =

You should provide 2 files:

* 1 Source text which will be converted to SWORD format. The source text must be unique and cannot be splitted in several files.
* 1 Configuration file which tells Sword how to recognize and what to do with your module.

The files reflects the name of your module in '''lowercase''' followed by an extension.

Extensions for the text file are:

* OSIS: <code>.osis.xml</code>
* TEI: <code>.tei.xml</code>
* VPL: <code>.vpl</code>
* IMP: <code>.imp</code>
* ThML: <code>.thml</code>

For the configuration file, the extension is <code>.conf</code>.

So, for the <code>FreBDM1707</code> module encoded in OSIS, we have <code>frebdm1707.osis.xml</code> and <code>frebdm1707.conf</code> files.

= How-To prepare your source files =

We will accept only plain texts in VPL<ref name="vpl">Only for Bibles in KJV versification</ref> or texts marked up in OSIS or TEI, with the sole exception texts based on CCEL documents that are marked up in ThML.

<references />

== Check your OSIS before submitting ==

OSIS 2.1 is now the preferred format for Bibles, Commentaries and General Books. TEI is the prefered format for dictionaries.

OSIS texts need to have the CamelCase module name as <code>workID</code> and an appropriate <code>osisRefWork</code> entry within the appropriate header section. The document language needs to be set correctly, ISO 639-1 codes are preferred, and ISO 639-3 codes when ISO 639-1 codes do not exist for the given language. Examples:

Bible:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Bible" xml:lang="he">
</pre>

Commentary:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Commentary" xml:lang="gr">
</pre>
General Book:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="GenBook" xml:lang="en">
</pre>

== Please validate your OSIS or TEI text ==
See: Guide to [[Validate_OSIS_or_TEI_text]]

== Check your configuration file ==
We require that the following minimum set of module configuration fields are included: <code>Description</code>, <code>About</code>, <code>DistributionLicense</code>, and <code>TextSource</code>. Ensure that your module complies with our stated copyright policy.

= Copyrighted Material =
If your got permission to distribute a new module which is under copyright, please send a copy of the authorization in a file named copyright.<extension> like <code>copyright.pdf</code>, <code>copyright.png</code>...

= Other files =

Besides source, conf and copyright files we accept:
* Cascading style sheet (CSS) file used to format the contents of a module
* Media subdir containing multimedia files, commonly <code>Images</code> subdir.

= How-To submit your files =
Submit only source files. Do not submit built modules that you have imported to Sword format. Avoid spaces in folder and file names.

Send an email to <code>modules@crosswire.org</code> describing the module and your files with one of the options below:

''Note: Pressing one of the following modules@crosswire.org links will open a new mail window already filled with a sample text.''

== Files attached ==

It is highly recommended to zip your files, as they are text files they will be highly compressed with the double benefit to reduce storage and make transmitting them much easier.
Feel free to attach your zip file to the email sent to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Please%20find%20the%20attached%20zip%20archive%20with%20source%20and%20.conf%20files.%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org]. Actually the biggest file (30MB) we have is 3MB once zipped. Supported file formats: <code>tar.gz</code>; <code>tgz</code>; <code>tar.bz2</code>; <code>tb2</code>; <code>bz2</code>; <code>gz</code>; <code>zip</code>; <code>gmx</code>; <code>Z</code>; <code>7z</code>

== Link to a zip file ==

If you own a repository on the Internet, you may also store your zipped file on your repository and send the URL to this file instead to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20zip%20archive%20of%20the%20module%20with%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].

== Link to a git Repository ==

If you built your module on a public Git/GitLab/GitHub, you may want to share the <code>git clone</code> URL in the email to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20Git%20repository%20of%20the%20module%20containing%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].

We do accept git URL but there are some limitations, though:

* We expect to run into a flat structure, so:
** Module files (source, .conf) shouldn't go into a subdir
** Optional files like copyright, style.css must be at the root of your repository
** Only multimedia files (audio/video/images) should go in their own subdir, typically <code>images</code> for dictionaries
** A script subdir containing tools for converting an original source file to OSIS is welcome

Example:
<pre>
git
|
+-- copyright.pdf
+-- images/
+-- module.osis.xml
+-- module.conf
+-- script/
+-- style.css
+-- README.md
</pre>
* Try to not put other files in the repository, they are more misleading than handy. Original text URL should be linked in <code>README.md</code>. If you really need to keep the original source text in plain format, USFM ot whatever in a subdir, please add this subdir to .gitignore.
<code>$ echo sources/ >> .gitignore</code>

* No more than 1 module per git repository.

It is sometimes easier to run <code>git archive</code> and attach the resulting zip file to the email.

----
<div style="text-align:center">'''If you do not comply with the above your module submission might end up being deprioritised and will certainly not get uploaded as fast as it could be otherwise'''</div>
----

Please note: Do not edit this page unless you are actually ''directly'' involved with uploading modules onto the server. If you have a comment or addition to make, but you are not part of this particular effort, please use talk page.
[[Category:Modules]]

DevTools:conf Files

2021-01-25T13:58:54Z

Domcox: /* Required Elements with defaults */ Typo

This page describes important information about module configuration (.conf) files. All SWORD modules require one.

Please look also at our detailed and commented [[Tutorial:Writing Conf files|tutorial]].

== Key elements of a SWORD module.conf ==

Some keys can be repeated. Many not.

Some can have values that span more than 1 line with '\' at the end of a line indicating that the text on the next line continues the value. Don't use continuation unless allowed. It will produce different results in different front ends.

RTF is allowed in some values.

Some allow HTML <a href="xxx">label</a>hypertext links. HTML is not allowed otherwise.

Values specifications are shown as '''<content spec>'''. The < and > are not to be included.

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

The order of elements specified in a conf file is immaterial, except where specified otherwise.

===Required Elements===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| [ModName]
| Each conf file begins with a unique identifier for a module placed within brackets, e.g., [KJV1611]. This must be first in the file. Valid characters for this abbreviation are limited to [https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions PCRE] class <tt>[A-Za-z0-9_]</tt>.<ref>That excludes the space and hyphen characters!</ref><br/>
The Abbreviation element is meant to allow for localization of this field.<br/>
The .conf file should be named the lowercase of this abbreviation followed by .conf. For example, kjv1611.conf.
|  
|  
|-
| Abbreviation<ref>We advise against explicitly declaring a redundant Abbreviation identical to the ModName. Abbreviation values should try to be unique to avoid user confusion.</ref>
|
'''<string>'''<br/>
The abbreviation displayed to the user. If not supplied, the unique ModName will be used. This field allows for localization-- showing a different abbreviation depending on the user's locale.

| [ModName]
| [[DevTools:conf Files#Localization|Localization]]
|-
| Description
|
'''<string>'''<br/>
This is a short (1 line) title of the module.
|  
| [[DevTools:conf Files#Localization|Localization]]
|-
| DataPath
| <relative system path pointing to the data files>
DataPath is the path to the module data files relative to the SWORD module library root directory. This path should start with "./modules". If the DataPath indicates a directory it should end with a '/'. Otherwise the module name is both the directory and the prefix for each file in that directory. Although DataPath can point to any folder or files under the root of the SWORD module library, the following conventions are recommended and must be used for modules wishing to be included in a CrossWire repository:

Paths used for a module named [MyModule], depending on<BR>(a) the type of module (Bible text, commentary, lexicon or dictionary<ref>Daily devotionals & glossaries go in subdirectories under lexdict. A glossary is between two languages.</ref>, general book) and<BR>(b) the data driver (ModDrv parameter) are:

:./modules/texts/rawtext/mymodule/
:./modules/texts/rawtext4/mymodule/
:./modules/texts/ztext/mymodule/
:./modules/texts/ztext4/mymodule/
:./modules/comments/zcom/mymodule/
:./modules/comments/zcom4/mymodule/
:./modules/comments/hrefcom/mymodule/
:./modules/comments/rawcom/mymodule/
:./modules/comments/rawcom4/mymodule/
:./modules/comments/rawfiles/mymodule/
:./modules/lexdict/zld/mymodule/mymodule
:./modules/lexdict/rawld/mymodule/mymodule
:./modules/lexdict/rawld/devotionals/mymodule/mymodule
:./modules/lexdict/rawld/glossaries/mymodule/mymodule
:./modules/lexdict/rawld4/mymodule/mymodule
:./modules/genbook/rawgenbook/mymodule/mymodule

|  
|  
|-
| ModDrv
|
'''RawText''' (for uncompressed Bibles)<br/>
'''RawText4''' (for uncompressed Bibles having entries greater than 64K bytes)<ref name="text4">e.g. If the Bible contains large introduction sections</ref><br/>
'''zText''' (for compressed Bibles)<br/>
'''zText4''' (for compressed Bibles having entries greater than 64K bytes)<ref name="text4">e.g. If the Bible contains large introduction sections</ref><ref name="sv">zText4 & zCom4 modules require MinimumVersion=1.8 or later.</ref><br/>
'''RawCom''' (for uncompressed Commentaries)<br/>
'''RawCom4''' (for uncompressed Commentaries having entries greater than 64K bytes)<br/>
'''zCom''' (for compressed Commentaries)<br/>
'''zCom4''' (for compressed Commentaries having entries greater than 64K bytes)<ref name="sv">zText4 & zCom4 modules require SwordVersion=1.8 or later.</ref><br/>
'''HREFCom''' (each module entry must be only a URL to the body for the entry; experimental)<br/>
'''RawFiles''' (stores each entry in a simple text file in the datapath; recommended for Personal Commentary)<br/>
'''RawLD''' (for uncompressed Dictionaries)<br/>
'''RawLD4''' (for uncompressed Dictionaries having entries greater than 64K bytes)<br/>
'''zLD''' (for compressed Dictionaries)<br/>
'''RawGenBook''' (for uncompressed tree keyed modules)
|  
|  
|}

<references />

===Required Elements with defaults ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| SourceType<ref>Omitting this for a non-plaintext module has unpredictable effects.</ref>
|
'''Plaintext'''<br/>
'''OSIS''' ([http://www.bibletechnologies.net Open Scriptural Information Standard])<br/>
'''TEI''' ([http://www.tei-c.org Text Encoding Initiative])<br/>
Specifies the '''markup''' used in the module. The preferred markup is OSIS. TEI is preferred for dictionaries until OSIS supports dictionaries. While SourceType has a default, it is a best practice to specify it.<br/>

Legacy modules may have a key here stating:

'''GBF''' ([http://www.ebible.org/bible/gbf.htm General Bible Format])<br/>
'''ThML''' ([http://www.ccel.org/ThML Theological Markup Language])<br/>

In SWORD, for modules encoded with ThML, OSIS or TEI, each verse, dictionary entry, and book division needs to be well-formed XML or it will result in display problems in some front-ends.
| Plaintext
|  
|-
| Encoding
|
'''UTF-8'''<br/>
'''UTF-16'''<br/>
'''SCSU''' ([http://en.wikipedia.org/wiki/Standard_Compression_Scheme_for_Unicode Standard Compression Scheme for Unicode])<br/>
Indicates how the text in the conf and in the module are encoded.

The preferred encoding of texts is UTF-8. Other than Hebrew, UTF-8 modules must be encoded with [http://unicode.org/reports/tr15/ Normalization Form C (NFC)]. Biblical Hebrew requires special handling.<ref>Unicode normalization can easily break Biblical Hebrew text. See on page 9 in the [http://www.sbl-site.org/Fonts/SBLHebrewUserManual1.5x.pdf SBL Hebrew Font User Manual].</ref> A few other languages may require special handling.<ref>e.g. If they are mentioned in Table 10 in the [http://unicode.org/reports/tr15/#Corrigendum_5_Sequences Corrigendum 5 Sequences].</ref><ref>The improper normalization of exceptional codepoints can be prevented by inserting a [https://en.wikipedia.org/wiki/Combining_Grapheme_Joiner Combining Grapheme Joiner].</ref>

To date, no modules use UTF-16 or SCSU. Legacy modules may hold a key here '''Latin-1''' referring solely to Windows Codepage 1252, a superset of ISO-8859-1. Front-end implementors wishing to use such modules should use "cp1252" or "windows1252" explicitly, not "Latin-1" provided by some programming language libraries.''
| Latin-1
|  
|-
| CompressType
|
'''ZIP'''<br/>
'''LZSS''' ([http://en.wikipedia.org/wiki/Lempel%E2%80%93Ziv%E2%80%93Storer%E2%80%93Szymanski Lempel Ziv Storer Szymanski])<br/>
'''BZIP2'''<br/>
'''XZ'''<br/>
Used for modules having a ModDrv of zText, zCom or zLD to indicate the compression algorithm.
While CompressType has a default, it is best practice to specify it.
ZIP is the preferred format.
| LZSS
|  
|-
| BlockType
|
'''BOOK'''<br/>
'''CHAPTER'''<br/>
'''VERSE'''<br/>
Used for modules having a ModDrv of zText (Bibles) and zCom (Commentaries) to indicate how much of the work is compressed into a block. The trade off is size for speed, with BOOK taking the least overall space and the longest time and VERSE taking the greatest overall space and the least time. While BlockType has a default, it is a best practice to specify it. Most Bibles use BOOK and larger Commentaries use CHAPTER. To date, no module uses VERSE.
| CHAPTER
|  
|-
| BlockCount
|
'''<integer>'''<br/>
Used for modules having a ModDrv of zLD to indicate the number of entries in a compressed block. Higher values will make the module slower, but smaller. It is best practice to take the default and not specify it.
| 200
|  
|-
| Versification
|
'''Calvin'''<br/>
'''Catholic'''<br/>
'''Catholic2'''<br/>
'''Darby_Fr'''<br/>
'''German'''<br/>
'''KJV'''<br/>
'''KJVA'''<br/>
'''LXX'''<br/>
'''Leningrad'''<br/>
'''Luther'''<br/>
'''MT'''<br/>
'''NRSV'''<br/>
'''NRSVA'''<br/>
'''Orthodox'''<br/>
'''Segond'''<br/>
'''Synodal'''<br/>
'''SynodalProt'''<br/>
'''Vulg'''<br/>
Used to specify the versification employed by a Bible module. Refer to [[Alternate Versification]].
| KJV
|  
|-
| CipherKey
|
'''<string>'''<br/>
Indicates that a module is enciphered and that the module is (un)locked. When the key has no value ("CipherKey=") the module is locked. When it has a value, the module is unlocked.

A good key is something that is hard to guess. Typically in a format matching the pattern: /[0-9]{4}[A-Za-z]{4}[0-9]{4}[A-Za-z]{4}/. Internally the key can be any byte sequence from 1 to 255 bytes in length. But it needs to be readable, plain text, without leading or trailing spaces.
|  
|  
|-
| KeyType
|
'''TreeKey'''<br/>
'''VerseKey'''<br/>
Used for RawGenBook to indicate whether the module contains a book or a Bible. At this time VerseKey is not yet supported and is being developed as a solution for Bibles which do not conform to any supported versification system in SWORD. It is best practice to take the default and not specify it.
| TreeKey
|  
|-
| CaseSensitiveKeys
|
Used for Dictionaries whose keys are case sensitive. This key is used to suppress normalization to UPPER CASE before comparison.<br/>
Only allowable value: '''true'''
| false
|  
|}

<references />

=== Elements required for proper rendering ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| GlobalOptionFilter
|
'''UTF8Cantillation''' (For Hebrew texts having cantillation marks)<ref>See https://en.wikipedia.org/wiki/Cantillation</ref><br/>
'''UTF8GreekAccents''' (For Greek texts having accents)<ref>For detailed background, see https://en.wikipedia.org/wiki/Greek_diacritics</ref><ref>This filter can have undesirable side-effects when applied to non-Greek text!</ref><br/>
'''UTF8HebrewPoints''' (For Hebrew texts having vowel points)<ref>See https://en.wikipedia.org/wiki/Niqqud</ref><br/>
'''UTF8ArabicPoints''' (For Arabic texts having vowel points)<ref>See https://en.wikipedia.org/wiki/Arabic_diacritics</ref><br/>
'''OSISLemma''' (For OSIS texts having lemmas)<ref>Must precede OSISStrongs.</ref><br/>
'''OSISMorphSegmentation''' (For OSIS texts having morphological segmentation elements)<ref>Currently, only some JSword based front-ends seem to support this feature. The SWORD engine has the switch available, but no change in output is effected.</ref><br/>
'''OSISStrongs''' (For OSIS texts having Strong's Numbers)<ref name="strongs">See https://en.wikipedia.org/wiki/Strong%27s_Concordance#Strong.27s_numbers</ref><br/>
'''OSISFootnotes''' (For OSIS texts having informational notes)<br/>
'''OSISScripref''' (For OSIS texts having [[OSIS Bibles#Marking_cross-references_note|cross reference]] type notes)<br/>
'''OSISMorph''' (For OSIS texts having morphology information)<br/>
'''OSISHeadings''' (For OSIS texts having non-canonical headings)<br/>
'''OSISVariants''' (For OSIS texts having variant readings)<br/>
'''OSISRedLetterWords''' (For OSIS texts marking the Words of Christ)<ref name="red">See https://en.wikipedia.org/wiki/Red_letter_edition</ref><br/>
'''OSISGlosses''' (For OSIS texts with glosses)<ref>Minimum SWORD version of 1.7.0 in the module .conf is required for OSISGlosses.</ref><br/>
'''OSISXlit''' (For OSIS texts that include transliterated forms)<ref>The Samaritan Pentateuch module SP is an example of using xlit.</ref><br/>
'''OSISEnum''' (For OSIS texts with enumerated words)<ref>The Samaritan Pentateuch module SP is an example of using enum.</ref><br/>
'''OSISReferenceLinks''' (For OSIS texts with glossary links)<ref>New in SWORD 1.7.0 - This filter requires six vertical bar-delimited fields, of which the following is an example.
<pre>
GlobalOptionFilter=OSISReferenceLinks|Reference Material Links|Hide or show links to study helps in the Biblical text.|x-glossary||On
</pre>
Here are the different field meanings:
# "OSISReferenceLinks" = option filter class name (option class name internal to the engine). Always the same for this kind of filter.
# "Reference Material Links" = Visible name of this OSISReferenceLinks filter. This is what the user will see in the Global Options toggle lists.
# "Hide or show..." = A readable user tip explaining what the filter does.
# "x-glossary" = Tells this OSISReferenceLinks filter to filter all references with type="x-glossary".
# (empty) = Tells this OSISReferenceLinks filter to also require that subType="something" in order to filter. Empty means ALL type="x-glossary" references will be filtered regardless of subType.
# "On" = Default filter toggle value ("On" or "Off")
</ref><ref>It is allowed to have multiple OSISReferenceLinks entries in a single conf file.</ref><br/>
Each of these filters removes/hides the text's feature, when activated by the application.<ref>It's not implied that every front-end supports all of the listed option filters.</ref>

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

Legacy modules may also have following keys:

'''OSISRuby'''<ref>See [https://en.wikipedia.org/wiki/Ruby_character Ruby character] and [https://en.wikipedia.org/wiki/Furigana Furigana]</ref> (For OSIS texts with glosses)<ref>Deprecated in 1.7.0. Use OSISGlosses instead.</ref><br/>
'''GBFStrongs''' (For GBF texts having Strong's Numbers)<ref name="strongs">See https://en.wikipedia.org/wiki/Strong%27s_Concordance#Strong.27s_numbers</ref><br/>
'''GBFFootnotes''' (For GBF texts having footnotes)<br/>
'''GBFMorph''' (For GBF texts having morphology information)<br/>
'''GBFHeadings''' (For GBF texts having headings)<br/>
'''GBFRedLetterWords''' (For GBF texts marking the Words of Christ)<ref name="red">See https://en.wikipedia.org/wiki/Red_letter_edition</ref><br/>
'''ThMLStrongs''' (For THML texts having Strong's Numbers)<ref name="strongs">See https://en.wikipedia.org/wiki/Strong%27s_Concordance#Strong.27s_numbers</ref><br/>
'''ThMLFootnotes''' (For THML texts having footnotes)<br/>
'''ThMLScripref''' (For THML texts having cross references)<br/>
'''ThMLMorph''' (For THML texts having morphology information)<br/>
'''ThMLHeadings''' (For THML texts having headings)<br/>
'''ThMLVariants''' (For THML texts having variant readings)<br/>
'''ThMLLemma''' (For THML texts having lemmas)<br/>

|  
| Repeats
|-
| Direction
|
'''LtoR''' (<u>L</u>eft to <u>R</u>ight)<br/>
'''RtoL''' (<u>R</u>ight to <u>L</u>eft)<br/>
'''BiDi''' (<u>Bidi</u>rectional)<br/>
Indicate whether the language's script is a left to right script or a right to left script.<ref>JSword validates the direction property against the Lang of the module.</ref> Languages such as Hebrew, Arabic, Urdu, and Farsi have a right to left script. If the RtoL script is transliterated into a LtoR script, set the value to LtoR. If a module has both RtoL and LtoR text, then it is BiDi.
| LtoR
|  
|-
| DisplayLevel
| '''<integer>'''<br/>
Used for General Book module types (these are keyed with a TreeKey table of contents). Indicates the preferred level from a leaf in the tree to display for context. e.g., 1 will only show the requested entry; 2 will show the entry, surrounded by all siblings, etc.
| 1
|  
|-
| Font
| '''<string>'''<br/>
Specify the [[Fonts|font]] to be used for display of the module if it is available.<ref>Specifying a font may not be sufficient for some modules. The required font features may depend on a particular smart font engine, which may not be compiled into the front-end application.</ref> 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.
|  
|  
|-
| <del>OSISqToTick</del> (deprecated)<ref>For further details, refer to [http://www.crosswire.org/bugs/browse/MOD-188 MOD-188] in CrossWire bugs.</ref>
| This attribute is deprecated in favor of the marker attribute on the q element. E.g.: <pre><q who="Jesus" marker="">....</q></pre><br/>
<del>true/false</del><br/>
<del>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.</del>
| true
|  
|-
| Feature
|
'''StrongsNumbers''' (for modules that include Strong's numbers)<br/>
'''GreekDef''' (for dictionary modules with Strong's number encoded Greek definitions)<br/>
'''HebrewDef''' (for dictionary modules with Strong's number encoded Hebrew definitions)<br/>
'''GreekParse''' (for dictionary modules with Greek morphology expansions)<br/>
'''HebrewParse''' (for dictionary modules with Hebrew morphology expansions)<br/>
'''DailyDevotion''' (for daily devotionals using one of the LD drivers and keyed with MM.DD)<br/>
'''Glossary''' (for collections of glosses using one of the LD drivers)<br/>
'''Images''' (for modules that contain images of any type)<br/>
'''NoParagraphs''' (for modules without any paragraphing information, which are typically typeset with a verse per line<ref>This feature is intended to be informational to front-end developers. Ideally, front-ends will render these modules with a verse per line rather than as a single big chapter-length paragraph block.</ref><ref>The occurrence of a small number of paragraph elements in a module (such as might be used merely to format the colophon at the end of each Pauline epistle) does not rule out the use of this feature.</ref>)
|  
| Repeats
|-
| GlossaryFrom
| '''<lang identifier>'''<br/>
Glossaries map one language to another. This value indicates the language being translated from.
See Lang below for a discussion of valid values.
|  
|  
|-
| GlossaryTo
| '''<lang identifier>'''<br/>
Glossaries map one language to another. This value indicates the language being translated to.
See Lang below for a discussion of valid values.
|  
|  
|-
| PreferredCSSXHTML
| '''<filename>'''<br/>
Names a file in the module's DataPath that should be referenced for the renderer as CSS display controls.
Generality is advised: Use controls that are not specific to any particular rendering engine, e.g. WebKit.
|  
|  
|}
<references />

=== Optional elements to support particular features ===
==== CaseInsensitiveKeys ====
Intended for use with Lexicon/Dictionary & Glossary modules. This field will make the order of the keys based upon the mixed case keys, but the index is still sorted by byte order of those keys. There are some scripts that don’t have upper/lower case (e.g. Arabic) and some languages where a naïve toUpper() will result in the wrong character (e.g. Turkish/Azeri lowercase dotted i and capital dotted İ).

CaseInsensitiveKeys=true|false

It is fine to use toUpper() for internal normalization, but having keys in all caps when showing to a user is annoying. The problem is that the display order needs to follow something that makes sense to a user when the dictionary is presented as a list.

[https://github.com/JohnAustinDev/xulsword xulsword] has a different solution involving a configuration item not yet used by SWORD master.

LangSortOrder=AaBbCcDdEe...

This is used by xulsword to sort the keys of a dictionary/glossary in original alphabetical order. Here's an actual example for module TKLDICT which has Lang=tk-Latn (i.e. Türkmençe):

LangSortOrder=AaBbCcÇçDdEeÄäŻżFfGgHhIiJjKkLlMmNnŇňOoÖöPpQqRrSsŞşTtUuÜüVvWwXxYyÝýZzŽž

This method would need to be modified in order to support alphabets (such as [http://en.wikipedia.org/wiki/Welsh_orthography Welsh]) that include any [http://en.wikipedia.org/wiki/Digraph_%28orthography%29 digraphs].

==== StrongsPadding ====
At the heart of our lexicon/dictionary drivers, we have some old logic which tries to detect if a key value is a Strong's number, and if so, then pad it with leading zeros accordingly. To support this logic, the recognition has recently been added for an optional new .conf entry for lexicon/dictionary modules:

StrongsPadding=true|false

'''Notes:'''
# So as not to break everything, this currently defaults to true if it is not present in the lexdict module's .conf file
# It can be set to false if you are building a lexdict module which has entries which may be misconstrued as Strong's numbers.
# In a couple years, we'll probably switch the default to false, so it would be nice to add this line and set the value to true on modules which really do require the logic.
# This is only available in SWORD version 1.7 or later. JSword never had this problem.

==== Strip Filters ====
SWORD has the concept of "filtering" a module's text at different processing points for purposes other than rendering.<br>One of these filter-points is for searching and we call these filters '''Strip Filters'''.

Strip Filters are typically named something like '''OSISPlain''' or '''GBFPlain''', etc. These typically take all the markup out of an entry and prepare the text to be searched, but anything can be done to the text to prepare it further for searching. We typically remove accents and vowel points from Greek and Hebrew respectively.

Any Strip Filter can be added to a module by the module author with a line in the .conf file, such as:

LocalStripFilter=GBFPlain

If diacritics need to be removed from Arabic, then we can certainly add a filter for this as well. The conf line would be:

LocalStripFilter=UTF8ArabicPoints

Our current list of filters can be found by browsing the source folder here:

http://crosswire.org/svn/sword/trunk/src/modules/filters/

They're pretty concise and don't involve much knowledge from the rest of the engine, making them easy to write if we need a new one.

This processing can replace or be complimentary to any processing done by clucene. Here's an example of what's used with the [http://papyri.info/docs/ddbdp Duke Databank of Papyri] with specialist software that's based on SWORD.

LocalStripFilter=PapyriPlain

Since we need to strip markup, and other things clucene will likely never support (see '''PapyriPlain''' – annotations like [,],?{,}, underdot) we need this preprocessing mechanism to prepare the text before searching. We also maintain searching functionality apart from "fast indexed searching".<ref>Currently supplied by clucene, but could be implemented by any other fast search framework that we might want to integrate in future.</ref>

'''Note:'''
<references />

=== General informatic and installer elements ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| About
|
'''<string>'''<br/>
A lengthier description and may include copyright, source, etc. information, possibly duplicating information in other elements.
|  
| [[DevTools:conf Files#Continuation|Continuation]]<br/>[[DevTools:conf Files#RTF|RTF]]<br/>[[DevTools:conf Files#Localization|Localization]]
|-
| SwordVersionDate
|
'''<yyyy-mm-dd>''' ([http://en.wikipedia.org/wiki/ISO_8601#Calendar_dates ISO 8601 Date])<br/>
Indicates the date that the module was changed.
|  
|  
|-
| Version
|
'''<version string>'''<br/>
Gives the module's revision number. Incrementing it when changes are made alerts users of the SWORD Installers to the presence of updated modules. Please start with version 1.0 and increment by 0.1 for minor updates and by larger values for more major updates such as a new text source. Changes to this conf file should also increment the version number. Do not use non-numbers, such as 1.4a.

CrossWire's standard practice is to indicate updates that only require a .conf-file update/download by incrementing the third most significant number (the revision number). For example, if module version 1.2 requires a .conf-file update. A new .conf file with version number 1.2.1 could be released.
| 1.0
|  
|-
| History_x.x
| '''<string>'''<br/>
x.x is taken from the Version value.

Indicates what has changed between different versions. Each time a version is incremented a history line with that version number should explain the change.

It is recommended that each explanation be suffixed by the corresponding SwordVersionDate value.
|  
| Repeats<br/>[[DevTools:conf Files#Localization|Localization]]
|-
| MinimumVersion<ref>See http://tracker.crosswire.org/browse/API-201</ref>
|
'''<version string>'''<br/>
Identifies the [[Sword library versions | minimum version]] of the SWORD library required for this module.<ref>Required to support a Bible/Commentary module that has an [[Alternate Versification]].</ref>
| 1.5.1a
|  
|-
| Category
|valign="top"|
This is used by installers to further categorize the modules beyond what can be figured out by the ModDrv and Feature.<br/>
'''Biblical Texts''' (for Bibles)<br/>
'''Commentaries'''<br/>
'''Lexicons / Dictionaries'''<br/>
'''Glossaries''' (for modules with Feature=Glossary)<br/>
'''Daily Devotional''' (for modules with Feature=DailyDevotion)<br/>
'''Generic Books''' (for anything else....)<br/>
'''Maps''' (for modules that primarily consist of maps)<br/>
'''Images''' (for modules that primarily consist of images)<br/>
'''Cults / Unorthodox / Questionable Material'''<br/>
'''Essays''' (for essays)<ref>'''Essays''' is handled as a subset of '''Generic Books'''.</ref>
|
Biblical Texts<br/>
  ''ModDrv=RawText'' or<br/>
  ''ModDrv=RawText4'' or<br/>
  ''ModDrv=zText'' or<br/>
  ''ModDrv=zText4''<br/>
Commentaries<br/>
  ''ModDrv=HRefCom'' or<br/>
  ''ModDrv=RawCom'' or<br/>
  ''ModDrv=RawCom4'' or<br/>
  ''ModDrv=RawFiles'' or<br/>
  ''ModDrv=zCom'' or<br/>
  ''ModDrv=zCom4''<br/>
Lexicons / Dictionaries<br/>
  ''ModDrv=RawLD'' or<br/>
  ''ModDrv=RawLD4'' or<br/>
  ''ModDrv=zLD''<br/>
Glossaries<br/>
  ''Feature=Glossary'' and<br/>
  ''ModDrv=RawLD'' or<br/>
  ''ModDrv=RawLD4'' or<br/>
  ''ModDrv=zLD''<br/>
Daily Devotional<br/>
  ''Feature=DailyDevotion'' and<br/>
  ''ModDrv=RawLD'' or<br/>
  ''ModDrv=RawLD4'' or<br/>
  ''ModDrv=zLD''<br/>
Generic Books<br/>
  ''ModDrv=RawGenBook''<br/>
|  
|-
| LCSH
| '''<tree/string>'''<br/>
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.
|  
|  
|-
| Lang
|
'''<Language[-Script]?[-Region]?>'''<br/>
The language identifier is a combination of sub-tags for '''Language''' and optionally '''Script''', and/or '''Region''', according to [http://www.rfc-editor.org/rfc/bcp/bcp47.txt BCP 47] and [http://tools.ietf.org/html/rfc4647 RFC 4647]. Private use extensions defined by BCP 47 (e.g. x-, qaa, and Qaaa) should be avoided wherever possible.

'''Language sub-tag''' ''(Regex: /[a-z]{2,3}/)'':<br/>
This is the primary language code of the module according to [http://en.wikipedia.org/wiki/ISO_639 ISO 639 parts 1, 2, 3 and 5]. Some languages have several codes. Use the following to determine the best choice:<br/>
:When available use a 2-letter [http://en.wikipedia.org/wiki/ISO_639-1 ISO 639-1] code ([http://www.loc.gov/standards/iso639-2/php/code_list.php registrar]), (e.g. ''en'' for English).
:If there is none for the given language, use an [http://en.wikipedia.org/wiki/ISO_639-2 ISO 639-2/T] code ([http://www.loc.gov/standards/iso639-2/php/code_list.php registrar]) (e.g. ceb for Cebuano).
:Failing that, use a [http://en.wikipedia.org/wiki/ISO_639-3 ISO 639-3] code ([http://www-01.sil.org/iso639-3/codes.asp registrar]), which covers over 7000 languages.
:Finally, use a [http://en.wikipedia.org/wiki/ISO_639-5 ISO 639-5] code ([http://www.loc.gov/standards/iso639-5/id.php registrar]) for macro languages.
The [http://www-01.sil.org/iso639-3/codes.asp ISO639-3 registrar] page gives up-to-date table on all of the above.

'''Script sub-tag''' ''(Regex: /[A-Z][a-z]{3}/)'':<br/>
If a text is script-specific, such as a Latin vs. Cyrillic Serbian Bible or a Bible transliterated into other than its native script, include the [http://en.wikipedia.org/wiki/ISO_15924 ISO 15924 script code] ([http://unicode.org/iso15924/iso15924-codes.html registrar]) after the language code (e.g. sr-Latn for Latin script Serbian, sr-Cyrl for Cyrillic script Serbian).

'''Region sub-tag''': ''(Regex: /[A-Z]{2}/)''<br/>
If a text is region (country)-specific, such as the Anglicized NIV, include the [http://en.wikipedia.org/wiki/ISO_3166-1 ISO 3166-1 region code] ([http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html registrar]) after the script code (or language code if no country code is present) (e.g. en-GB for UK English).

'''Combinations'''''(Regex: /[a-z]{2,3}(-[A-Z][a-z]{3})?(-[A-Z]{2})?/)'':<br/>
Individual sub-tags (language, script, and region) are always separated by a hyphen. Identifiers should be as basic and succinct as possible. A script should not be specified for a language written in its expected script, unless the language has multiple common scripts (as in the case of Serbian above). A region should not be specified unless a text should be categorized separately from others texts in that language that do not specify a region.
| en
|  
|-
| InstallSize
|
'''<integer>'''<br/>
Indicates the total byte size of the module on disk, excluding the the size of any Lucene index files.

For modules in the CrossWire repositories, this is automatically generated and overwritten if needed.
|  
|  
|-
| Obsoletes
|
'''<ModName>'''<br/>
Each instance of this element gives a former ModName that is made obsolete by this module.
|  
| Repeats
|-
| OSISVersion
|
'''<version string>'''<br/>
Identifies the OSIS schema version employed in the OSIS source document. The current version is 2.1.1

It is recommended that this be present for every OSIS module.
|  
|
|-
| Companion<ref>Many (xulsword compatible) modules in the [[Official and Affiliated Module Repositories#Institute_for_Bible_Translation|IBT Repository]] make use of this field. See also https://github.com/johnaustindev/osis-converters</ref>
|
'''<ModName[, ModName]*>'''<br/>
Specifies companion module(s) that should be opened together<br/>
e.g. When Bible and Commentary and/or Glossary modules are distributed together.
|  
|
|}
'''Note:'''
<references/>

=== Copyright & Licensing related elements ===

{| width="100%" border="1" class="sortable"
! width="10%"|Element
! width="70%"|Values (type or enumerated)
! width="10%"|Default Value
! width="10%"|Allows
|-
| Copyright
|
'''<string>'''<br/>
Contains the copyright notice for the work, including the year of copyright and the owner of the copyright.
|  
| [[DevTools:conf Files#Continuation|Continuation]]<br/>[[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightHolder
|
'''<string>'''<br/>
Contains the name of the copyright holder.
|  
| [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightDate
|
'''<yyyy>''' ([http://en.wikipedia.org/wiki/ISO_8601#Years ISO 8601 Year])
|  
| [[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightNotes
|
'''<string>'''
|  
| [[DevTools:conf Files#Continuation|Continuation]]<br/>[[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightContactName
|
'''<string>'''<br/>
Contains the name of the copyright holder.
|  
| [[DevTools:conf Files#Continuation|Continuation]]<br/>[[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightContactNotes
|
'''<string>'''
|  
| [[DevTools:conf Files#Continuation|Continuation]]<br/>[[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightContactAddress
|
'''<string>'''<br/>
Contains the mailing address of the copyright holder.
|  
| [[DevTools:conf Files#Continuation|Continuation]]<br/>[[DevTools:conf Files#Localization|Localization]]
|-
| CopyrightContactEmail
|
'''<string>'''<br/>
Contains the email address of the copyright holder, preferably in the form:<br/> name at xyz dot com
|  
| [[DevTools:conf Files#Localization|Localization]]
|-
| ShortPromo
|
'''<string>'''<br/>
A link to the home page for the module, perhaps with an encouragement to visit the site.
|  
| HTML Link<br/>[[DevTools:conf Files#Localization|Localization]]
|-
| ShortCopyright
|
'''<string>'''
|  
| [[DevTools:conf Files#Localization|Localization]]
|- id="distlic"
| DistributionLicense
|
'''Public Domain'''<br/>
'''Copyrighted'''<br/>
'''Copyrighted; Permission to distribute granted to CrossWire'''<ref>Modules in other repositories may have a different organization name instead of CrossWire.</ref><br/>
'''Copyrighted; Permission granted to distribute non-commercially in SWORD format'''<br/>
'''Copyrighted; Free non-commercial distribution'''<br/>
'''Copyrighted; Freely distributable'''<br/>
'''[http://www.gnu.org/copyleft/fdl.html GFDL]'''<br/>
'''[http://www.gnu.org/copyleft/gpl.html GPL]'''<br/>
'''Creative Commons: BY-NC-ND 4.0'''<br/>
'''Creative Commons: BY-NC-SA 4.0'''<br/>
'''Creative Commons: BY-NC 4.0'''<br/>
'''Creative Commons: BY-ND 4.0'''<br/>
'''Creative Commons: BY-SA 4.0'''<br/>
'''Creative Commons: BY 4.0'''<br/>
'''Creative Commons: [http://creativecommons.org/publicdomain/zero/1.0/ CC0]'''<br/>
Use one of these strings '''verbatim'''. The actual copyright and/or license information is held in other elements.<br/>The last seven are different [https://creativecommons.org/licenses/ Creative Commons licenses].
|  
|  
|-
| DistributionNotes
|
'''<string>'''<br/>
Indicates any additional notes about distribution of the module.
|  
| [[DevTools:conf Files#Continuation|Continuation]]<br/>[[DevTools:conf Files#Localization|Localization]]
|-
| TextSource
|
'''<string>'''<br/>
Indicates, either in prose (such as "CCEL") or as a URL of the source of the text
|  
| [[DevTools:conf Files#Continuation|Continuation]]
|-
| UnlockInfo
|
'''<string>'''<br/>
Contains unlock instructions for the user, intended to be displayed upon attempt to install the module. These instructions typically include a URL pointing to an exact location within a publisher's online store where a user can directly purchase an unlock key (CipherKey) for the module.
|  
| [[DevTools:conf Files#RTF|RTF]]<br/>[[DevTools:conf Files#Continuation|Continuation]]<br/>[[DevTools:conf Files#Localization|Localization]]<br/>HTML Link
|}
'''Note:'''
<references/>

== Uniqueness ==
For comparing two versions of a module during module development, the module names and locations must be unique. For JSword based front-ends such as Bible Desktop, there is a further requirement, the Description items must be different.

== Analysis Tools ==
* [[User:Dmsmith|DMSmith]] has created a script to analyse conf files and report anomalies.
* [[User:David Haslam|David Haslam]] has created a '''User Defined Language''' called '''CONF''' as a Syntax Highlighter for '''Notepad++''' (Windows). Download from [https://github.com/DavidHaslam/CONF].

== Automated generation ==
* For new module submissions to CrossWire, [[User:Refdoc|Refdoc]] now maintains a script called '''confmaker''' that includes the ''automated generation'' of module conf files, given the minimum ''non-automatable'' requirements by the module submitter.

== See also ==
* [[BibTeX entries]]

[[Category:Development tools|Conf files]]
[[Category:Localization|Conf files]]
[[Category:Versification|Conf files]]
[[Category:Copyright|Conf files]]

Module Submission

2021-01-11T09:14:57Z

Domcox: /* Files attached */ Added list of file formats

----
'''<span style="color: crimson">For information on module licensing''' → please look at [[DevTools:Module Submission and Copyrights]]
----

= How-To Name your module =
Each module needs a name that be used as a unique identifier. Valid characters for the name are limited to alphanumeric characters, numeric characters and underscore. PCRE class [A-Za-z0-9\_].

Normalized names of module contains usually<ref name="Eng">For historical reasons, modules in English do not have any language prefix.</ref> 3 letters for language, followed by a short name descibing the work. Language is encoded in ISO 639-3 code. See [http://www.sil.org/iso639-3/codes.asp] for a list of codes.

The name has to be set in CamelCase format. Example for The French Bible David Martin 1707: <code>FreBDM1707</code><ref name="bdm">The published year was added to differentiate this version from successive revisions in 1744, 1855. Otherwise we could just have named it FreBDM.</ref>

<references />

= How-To name your source files =

You should provide 2 files:

* 1 Source text which will be converted to SWORD format. The source text must be unique and cannot be splitted in several files.
* 1 Configuration file which tells Sword how to recognize and what to do with your module.

The files reflects the name of your module in '''lowercase''' followed by an extension.

Extensions for the text file are:

* OSIS: <code>.osis.xml</code>
* TEI: <code>.tei.xml</code>
* VPL: <code>.vpl</code>
* IMP: <code>.imp</code>
* ThML: <code>.thml</code>

For the configuration file, the extension is <code>.conf</code>.

So, for the <code>FreBDM1707</code> module encoded in OSIS, we have <code>frebdm1707.osis.xml</code> and <code>frebdm1707.conf</code> files.

= How-To prepare your source files =

We will accept only plain texts in VPL<ref name="vpl">Only for Bibles in KJV versification</ref> or texts marked up in OSIS or TEI, with the sole exception texts based on CCEL documents that are marked up in ThML.

<references />

== Check your OSIS before submitting ==

OSIS 2.1 is now the preferred format for Bibles, Commentaries and General Books. TEI is the prefered format for dictionaries.

OSIS texts need to have the CamelCase module name as <code>workID</code> and an appropriate <code>osisRefWork</code> entry within the appropriate header section. The document language needs to be set correctly, ISO 639-1 codes are preferred, and ISO 639-3 codes when ISO 639-1 codes do not exist for the given language. Examples:

Bible:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Bible" xml:lang="he">
</pre>

Commentary:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Commentary" xml:lang="gr">
</pre>
General Book:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="GenBook" xml:lang="en">
</pre>

== Please validate your OSIS or TEI text ==
See: Guide to [[Validate_OSIS_or_TEI_text]]

== Check your configuration file ==
We require that the following minimum set of module configuration fields are included: <code>Description</code>, <code>About</code>, <code>DistributionLicense</code>, and <code>TextSource</code>. Ensure that your module complies with our stated copyright policy.

= Copyrighted Material =
If your got permission to distribute a new module which is under copyright, please send a copy of the authorization in a file named copyright.<extension> like <code>copyright.pdf</code>, <code>copyright.png</code>...

= Other files =

Besides source, conf and copyright files we accept:
* Cascading style sheet (CSS) file used to format the contents of a module
* Media subdir containing multimedia files, commonly <code>Images</code> subdir.

= How-To submit your files =
Submit only source files. Do not submit built modules that you have imported to Sword format. Avoid spaces in folder and file names.

Send an email to <code>modules@crosswire.org</code> describing the module and your files with one of the options below:

''Note: Pressing one of the following modules@crosswire.org links will open a new mail window already filled with a sample text.''

== Files attached ==

It is highly recommended to zip your files, as they are text files they will be highly compressed with the double benefit to reduce storage and make transmitting them much easier.
Feel free to attach your zip file to the email sent to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Please%20find%20the%20attached%20zip%20archive%20with%20source%20and%20.conf%20files.%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org]. Actually the biggest file (30MB) we have is 3MB once zipped. Supported file formats: <code>tar.gz</code>; <code>tgz</code>; <code>tar.bz2</code>; <code>tb2</code>; <code>bz2</code>; <code>gz</code>; <code>zip</code>; <code>gmx</code>; <code>Z</code>; <code>7z</code>

== Link to a zip file ==

If you own a repository on the Internet, you may also store your zipped file on your repository and send the URL to this file instead to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20zip%20archive%20of%20the%20module%20with%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].

== Link to a git Repository ==

If you built your module on a public Git/GitLab/GitHub, you may want to share the <code>git clone</code> URL in the email to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20Git%20repository%20of%20the%20module%20containing%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].

We do accept git URL but there are some limitations, though:

* We expect to run into a flat structure, so Module files (source, .conf) shouldn't go in a subdir. Optional files like copyright, style.css should be at the root of your repository as well. Only multimedia files (audio/video/images) should go in their own subdir, typically <code>images</code> for dictionaries.
Example:
<pre>
git
|
+-- module.osis.xml
+-- module.conf
+-- style.css
+-- images/
+-- copyright.pdf
+-- README.md
</pre>
* Try to not put other files in the repository, they are more misleading than handy. Original text URL should be linked in <code>README.md</code>. If you really need to keep the original source text in plain format, USFM ot whatever in a subdir, please add this subdir to .gitignore.
<code>$ echo sources/ >> .gitignore</code>

* No more than 1 module per git repository.

It is sometimes easier to run <code>git archive</code> and attach the resulting zip file to the email.

----
<div style="text-align:center">'''If you do not comply with the above your module submission might end up being deprioritised and will certainly not get uploaded as fast as it could be otherwise'''</div>
----

Please note: Do not edit this page unless you are actually ''directly'' involved with uploading modules onto the server. If you have a comment or addition to make, but you are not part of this particular effort, please use talk page.
[[Category:Modules]]

Module Submission

2021-01-10T18:55:04Z

Domcox: /* Submit your files */ How-To added

----
'''<span style="color: crimson">For information on module licensing''' → please look at [[DevTools:Module Submission and Copyrights]]
----

= How-To Name your module =
Each module needs a name that be used as a unique identifier. Valid characters for the name are limited to alphanumeric characters, numeric characters and underscore. PCRE class [A-Za-z0-9\_].

Normalized names of module contains usually<ref name="Eng">For historical reasons, modules in English do not have any language prefix.</ref> 3 letters for language, followed by a short name descibing the work. Language is encoded in ISO 639-3 code. See [http://www.sil.org/iso639-3/codes.asp] for a list of codes.

The name has to be set in CamelCase format. Example for The French Bible David Martin 1707: <code>FreBDM1707</code><ref name="bdm">The published year was added to differentiate this version from successive revisions in 1744, 1855. Otherwise we could just have named it FreBDM.</ref>

<references />

= How-To name your source files =

You should provide 2 files:

* 1 Source text which will be converted to SWORD format. The source text must be unique and cannot be splitted in several files.
* 1 Configuration file which tells Sword how to recognize and what to do with your module.

The files reflects the name of your module in '''lowercase''' followed by an extension.

Extensions for the text file are:

* OSIS: <code>.osis.xml</code>
* TEI: <code>.tei.xml</code>
* VPL: <code>.vpl</code>
* IMP: <code>.imp</code>
* ThML: <code>.thml</code>

For the configuration file, the extension is <code>.conf</code>.

So, for the <code>FreBDM1707</code> module encoded in OSIS, we have <code>frebdm1707.osis.xml</code> and <code>frebdm1707.conf</code> files.

= How-To prepare your source files =

We will accept only plain texts in VPL<ref name="vpl">Only for Bibles in KJV versification</ref> or texts marked up in OSIS or TEI, with the sole exception texts based on CCEL documents that are marked up in ThML.

<references />

== Check your OSIS before submitting ==

OSIS 2.1 is now the preferred format for Bibles, Commentaries and General Books. TEI is the prefered format for dictionaries.

OSIS texts need to have the CamelCase module name as <code>workID</code> and an appropriate <code>osisRefWork</code> entry within the appropriate header section. The document language needs to be set correctly, ISO 639-1 codes are preferred, and ISO 639-3 codes when ISO 639-1 codes do not exist for the given language. Examples:

Bible:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Bible" xml:lang="he">
</pre>

Commentary:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Commentary" xml:lang="gr">
</pre>
General Book:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="GenBook" xml:lang="en">
</pre>

== Please validate your OSIS or TEI text ==
See: Guide to [[Validate_OSIS_or_TEI_text]]

== Check your configuration file ==
We require that the following minimum set of module configuration fields are included: <code>Description</code>, <code>About</code>, <code>DistributionLicense</code>, and <code>TextSource</code>. Ensure that your module complies with our stated copyright policy.

= Copyrighted Material =
If your got permission to distribute a new module which is under copyright, please send a copy of the authorization in a file named copyright.<extension> like <code>copyright.pdf</code>, <code>copyright.png</code>...

= Other files =

Besides source, conf and copyright files we accept:
* Cascading style sheet (CSS) file used to format the contents of a module
* Media subdir containing multimedia files, commonly <code>Images</code> subdir.

= How-To submit your files =
Submit only source files. Do not submit built modules that you have imported to Sword format. Avoid spaces in folder and file names.

Send an email to <code>modules@crosswire.org</code> describing the module and your files with one of the options below:

''Note: Pressing one of the following modules@crosswire.org links will open a new mail window already filled with a sample text.''

== Files attached ==

It is highly recommended to zip your files, as they are text files they will be highly compressed with the double benefit to reduce storage and make transmitting them much easier.
Feel free to attach your zip file to the email sent to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Please%20find%20the%20attached%20zip%20archive%20with%20source%20and%20.conf%20files.%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org]. Actually the biggest file (30MB) we have is 3MB once zipped.

== Link to a zip file ==

If you own a repository on the Internet, you may also store your zipped file on your repository and send the URL to this file instead to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20zip%20archive%20of%20the%20module%20with%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].

== Link to a git Repository ==

If you built your module on a public Git/GitLab/GitHub, you may want to share the <code>git clone</code> URL in the email to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20Git%20repository%20of%20the%20module%20containing%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].

We do accept git URL but there are some limitations, though:

* We expect to run into a flat structure, so Module files (source, .conf) shouldn't go in a subdir. Optional files like copyright, style.css should be at the root of your repository as well. Only multimedia files (audio/video/images) should go in their own subdir, typically <code>images</code> for dictionaries.
Example:
<pre>
git
|
+-- module.osis.xml
+-- module.conf
+-- style.css
+-- images/
+-- copyright.pdf
+-- README.md
</pre>
* Try to not put other files in the repository, they are more misleading than handy. Original text URL should be linked in <code>README.md</code>. If you really need to keep the original source text in plain format, USFM ot whatever in a subdir, please add this subdir to .gitignore.
<code>$ echo sources/ >> .gitignore</code>

* No more than 1 module per git repository.

It is sometimes easier to run <code>git archive</code> and attach the resulting zip file to the email.

----
<div style="text-align:center">'''If you do not comply with the above your module submission might end up being deprioritised and will certainly not get uploaded as fast as it could be otherwise'''</div>
----

Please note: Do not edit this page unless you are actually ''directly'' involved with uploading modules onto the server. If you have a comment or addition to make, but you are not part of this particular effort, please use talk page.
[[Category:Modules]]

Module Submission

2021-01-10T18:53:37Z

Domcox: /* Other files */ typo

----
'''<span style="color: crimson">For information on module licensing''' → please look at [[DevTools:Module Submission and Copyrights]]
----

= How-To Name your module =
Each module needs a name that be used as a unique identifier. Valid characters for the name are limited to alphanumeric characters, numeric characters and underscore. PCRE class [A-Za-z0-9\_].

Normalized names of module contains usually<ref name="Eng">For historical reasons, modules in English do not have any language prefix.</ref> 3 letters for language, followed by a short name descibing the work. Language is encoded in ISO 639-3 code. See [http://www.sil.org/iso639-3/codes.asp] for a list of codes.

The name has to be set in CamelCase format. Example for The French Bible David Martin 1707: <code>FreBDM1707</code><ref name="bdm">The published year was added to differentiate this version from successive revisions in 1744, 1855. Otherwise we could just have named it FreBDM.</ref>

<references />

= How-To name your source files =

You should provide 2 files:

* 1 Source text which will be converted to SWORD format. The source text must be unique and cannot be splitted in several files.
* 1 Configuration file which tells Sword how to recognize and what to do with your module.

The files reflects the name of your module in '''lowercase''' followed by an extension.

Extensions for the text file are:

* OSIS: <code>.osis.xml</code>
* TEI: <code>.tei.xml</code>
* VPL: <code>.vpl</code>
* IMP: <code>.imp</code>
* ThML: <code>.thml</code>

For the configuration file, the extension is <code>.conf</code>.

So, for the <code>FreBDM1707</code> module encoded in OSIS, we have <code>frebdm1707.osis.xml</code> and <code>frebdm1707.conf</code> files.

= How-To prepare your source files =

We will accept only plain texts in VPL<ref name="vpl">Only for Bibles in KJV versification</ref> or texts marked up in OSIS or TEI, with the sole exception texts based on CCEL documents that are marked up in ThML.

<references />

== Check your OSIS before submitting ==

OSIS 2.1 is now the preferred format for Bibles, Commentaries and General Books. TEI is the prefered format for dictionaries.

OSIS texts need to have the CamelCase module name as <code>workID</code> and an appropriate <code>osisRefWork</code> entry within the appropriate header section. The document language needs to be set correctly, ISO 639-1 codes are preferred, and ISO 639-3 codes when ISO 639-1 codes do not exist for the given language. Examples:

Bible:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Bible" xml:lang="he">
</pre>

Commentary:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Commentary" xml:lang="gr">
</pre>
General Book:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="GenBook" xml:lang="en">
</pre>

== Please validate your OSIS or TEI text ==
See: Guide to [[Validate_OSIS_or_TEI_text]]

== Check your configuration file ==
We require that the following minimum set of module configuration fields are included: <code>Description</code>, <code>About</code>, <code>DistributionLicense</code>, and <code>TextSource</code>. Ensure that your module complies with our stated copyright policy.

= Copyrighted Material =
If your got permission to distribute a new module which is under copyright, please send a copy of the authorization in a file named copyright.<extension> like <code>copyright.pdf</code>, <code>copyright.png</code>...

= Other files =

Besides source, conf and copyright files we accept:
* Cascading style sheet (CSS) file used to format the contents of a module
* Media subdir containing multimedia files, commonly <code>Images</code> subdir.

= Submit your files =
Submit only source files. Do not submit built modules that you have imported to Sword format. Avoid spaces in folder and file names.

Send an email to <code>modules@crosswire.org</code> describing the module and your files with one of the options below:

''Note: Pressing one of the following modules@crosswire.org links will open a new mail window already filled with a sample text.''

== Files attached ==

It is highly recommended to zip your files, as they are text files they will be highly compressed with the double benefit to reduce storage and make transmitting them much easier.
Feel free to attach your zip file to the email sent to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Please%20find%20the%20attached%20zip%20archive%20with%20source%20and%20.conf%20files.%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org]. Actually the biggest file (30MB) we have is 3MB once zipped.

== Link to a zip file ==

If you own a repository on the Internet, you may also store your zipped file on your repository and send the URL to this file instead to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20zip%20archive%20of%20the%20module%20with%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].

== Link to a git Repository ==

If you built your module on a public Git/GitLab/GitHub, you may want to share the <code>git clone</code> URL in the email to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20Git%20repository%20of%20the%20module%20containing%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].

We do accept git URL but there are some limitations, though:

* We expect to run into a flat structure, so Module files (source, .conf) shouldn't go in a subdir. Optional files like copyright, style.css should be at the root of your repository as well. Only multimedia files (audio/video/images) should go in their own subdir, typically <code>images</code> for dictionaries.
Example:
<pre>
git
|
+-- module.osis.xml
+-- module.conf
+-- style.css
+-- images/
+-- copyright.pdf
+-- README.md
</pre>
* Try to not put other files in the repository, they are more misleading than handy. Original text URL should be linked in <code>README.md</code>. If you really need to keep the original source text in plain format, USFM ot whatever in a subdir, please add this subdir to .gitignore.
<code>$ echo sources/ >> .gitignore</code>

* No more than 1 module per git repository.

It is sometimes easier to run <code>git archive</code> and attach the resulting zip file to the email.

----
<div style="text-align:center">'''If you do not comply with the above your module submission might end up being deprioritised and will certainly not get uploaded as fast as it could be otherwise'''</div>
----

Please note: Do not edit this page unless you are actually ''directly'' involved with uploading modules onto the server. If you have a comment or addition to make, but you are not part of this particular effort, please use talk page.
[[Category:Modules]]

Module Submission

2021-01-10T18:53:10Z

Domcox: /* Copyrighted Material */ Added Other files

----
'''<span style="color: crimson">For information on module licensing''' → please look at [[DevTools:Module Submission and Copyrights]]
----

= How-To Name your module =
Each module needs a name that be used as a unique identifier. Valid characters for the name are limited to alphanumeric characters, numeric characters and underscore. PCRE class [A-Za-z0-9\_].

Normalized names of module contains usually<ref name="Eng">For historical reasons, modules in English do not have any language prefix.</ref> 3 letters for language, followed by a short name descibing the work. Language is encoded in ISO 639-3 code. See [http://www.sil.org/iso639-3/codes.asp] for a list of codes.

The name has to be set in CamelCase format. Example for The French Bible David Martin 1707: <code>FreBDM1707</code><ref name="bdm">The published year was added to differentiate this version from successive revisions in 1744, 1855. Otherwise we could just have named it FreBDM.</ref>

<references />

= How-To name your source files =

You should provide 2 files:

* 1 Source text which will be converted to SWORD format. The source text must be unique and cannot be splitted in several files.
* 1 Configuration file which tells Sword how to recognize and what to do with your module.

The files reflects the name of your module in '''lowercase''' followed by an extension.

Extensions for the text file are:

* OSIS: <code>.osis.xml</code>
* TEI: <code>.tei.xml</code>
* VPL: <code>.vpl</code>
* IMP: <code>.imp</code>
* ThML: <code>.thml</code>

For the configuration file, the extension is <code>.conf</code>.

So, for the <code>FreBDM1707</code> module encoded in OSIS, we have <code>frebdm1707.osis.xml</code> and <code>frebdm1707.conf</code> files.

= How-To prepare your source files =

We will accept only plain texts in VPL<ref name="vpl">Only for Bibles in KJV versification</ref> or texts marked up in OSIS or TEI, with the sole exception texts based on CCEL documents that are marked up in ThML.

<references />

== Check your OSIS before submitting ==

OSIS 2.1 is now the preferred format for Bibles, Commentaries and General Books. TEI is the prefered format for dictionaries.

OSIS texts need to have the CamelCase module name as <code>workID</code> and an appropriate <code>osisRefWork</code> entry within the appropriate header section. The document language needs to be set correctly, ISO 639-1 codes are preferred, and ISO 639-3 codes when ISO 639-1 codes do not exist for the given language. Examples:

Bible:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Bible" xml:lang="he">
</pre>

Commentary:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Commentary" xml:lang="gr">
</pre>
General Book:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="GenBook" xml:lang="en">
</pre>

== Please validate your OSIS or TEI text ==
See: Guide to [[Validate_OSIS_or_TEI_text]]

== Check your configuration file ==
We require that the following minimum set of module configuration fields are included: <code>Description</code>, <code>About</code>, <code>DistributionLicense</code>, and <code>TextSource</code>. Ensure that your module complies with our stated copyright policy.

= Copyrighted Material =
If your got permission to distribute a new module which is under copyright, please send a copy of the authorization in a file named copyright.<extension> like <code>copyright.pdf</code>, <code>copyright.png</code>...

= Other files =

Besides Source, conf and copyright files we accept:
* Cascading style sheet (CSS) file used to format the contents of a module
* Media subdir containing multimedia files, commonly <code>Images</code> subdir.

= Submit your files =
Submit only source files. Do not submit built modules that you have imported to Sword format. Avoid spaces in folder and file names.

Send an email to <code>modules@crosswire.org</code> describing the module and your files with one of the options below:

''Note: Pressing one of the following modules@crosswire.org links will open a new mail window already filled with a sample text.''

== Files attached ==

It is highly recommended to zip your files, as they are text files they will be highly compressed with the double benefit to reduce storage and make transmitting them much easier.
Feel free to attach your zip file to the email sent to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Please%20find%20the%20attached%20zip%20archive%20with%20source%20and%20.conf%20files.%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org]. Actually the biggest file (30MB) we have is 3MB once zipped.

== Link to a zip file ==

If you own a repository on the Internet, you may also store your zipped file on your repository and send the URL to this file instead to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20zip%20archive%20of%20the%20module%20with%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].

== Link to a git Repository ==

If you built your module on a public Git/GitLab/GitHub, you may want to share the <code>git clone</code> URL in the email to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20Git%20repository%20of%20the%20module%20containing%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].

We do accept git URL but there are some limitations, though:

* We expect to run into a flat structure, so Module files (source, .conf) shouldn't go in a subdir. Optional files like copyright, style.css should be at the root of your repository as well. Only multimedia files (audio/video/images) should go in their own subdir, typically <code>images</code> for dictionaries.
Example:
<pre>
git
|
+-- module.osis.xml
+-- module.conf
+-- style.css
+-- images/
+-- copyright.pdf
+-- README.md
</pre>
* Try to not put other files in the repository, they are more misleading than handy. Original text URL should be linked in <code>README.md</code>. If you really need to keep the original source text in plain format, USFM ot whatever in a subdir, please add this subdir to .gitignore.
<code>$ echo sources/ >> .gitignore</code>

* No more than 1 module per git repository.

It is sometimes easier to run <code>git archive</code> and attach the resulting zip file to the email.

----
<div style="text-align:center">'''If you do not comply with the above your module submission might end up being deprioritised and will certainly not get uploaded as fast as it could be otherwise'''</div>
----

Please note: Do not edit this page unless you are actually ''directly'' involved with uploading modules onto the server. If you have a comment or addition to make, but you are not part of this particular effort, please use talk page.
[[Category:Modules]]

Module Submission

2021-01-10T18:44:22Z

Domcox: /* Copyrighted Material */ Section on its own

----
'''<span style="color: crimson">For information on module licensing''' → please look at [[DevTools:Module Submission and Copyrights]]
----

= How-To Name your module =
Each module needs a name that be used as a unique identifier. Valid characters for the name are limited to alphanumeric characters, numeric characters and underscore. PCRE class [A-Za-z0-9\_].

Normalized names of module contains usually<ref name="Eng">For historical reasons, modules in English do not have any language prefix.</ref> 3 letters for language, followed by a short name descibing the work. Language is encoded in ISO 639-3 code. See [http://www.sil.org/iso639-3/codes.asp] for a list of codes.

The name has to be set in CamelCase format. Example for The French Bible David Martin 1707: <code>FreBDM1707</code><ref name="bdm">The published year was added to differentiate this version from successive revisions in 1744, 1855. Otherwise we could just have named it FreBDM.</ref>

<references />

= How-To name your source files =

You should provide 2 files:

* 1 Source text which will be converted to SWORD format. The source text must be unique and cannot be splitted in several files.
* 1 Configuration file which tells Sword how to recognize and what to do with your module.

The files reflects the name of your module in '''lowercase''' followed by an extension.

Extensions for the text file are:

* OSIS: <code>.osis.xml</code>
* TEI: <code>.tei.xml</code>
* VPL: <code>.vpl</code>
* IMP: <code>.imp</code>
* ThML: <code>.thml</code>

For the configuration file, the extension is <code>.conf</code>.

So, for the <code>FreBDM1707</code> module encoded in OSIS, we have <code>frebdm1707.osis.xml</code> and <code>frebdm1707.conf</code> files.

= How-To prepare your source files =

We will accept only plain texts in VPL<ref name="vpl">Only for Bibles in KJV versification</ref> or texts marked up in OSIS or TEI, with the sole exception texts based on CCEL documents that are marked up in ThML.

<references />

== Check your OSIS before submitting ==

OSIS 2.1 is now the preferred format for Bibles, Commentaries and General Books. TEI is the prefered format for dictionaries.

OSIS texts need to have the CamelCase module name as <code>workID</code> and an appropriate <code>osisRefWork</code> entry within the appropriate header section. The document language needs to be set correctly, ISO 639-1 codes are preferred, and ISO 639-3 codes when ISO 639-1 codes do not exist for the given language. Examples:

Bible:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Bible" xml:lang="he">
</pre>

Commentary:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Commentary" xml:lang="gr">
</pre>
General Book:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="GenBook" xml:lang="en">
</pre>

== Please validate your OSIS or TEI text ==
See: Guide to [[Validate_OSIS_or_TEI_text]]

== Check your configuration file ==
We require that the following minimum set of module configuration fields are included: <code>Description</code>, <code>About</code>, <code>DistributionLicense</code>, and <code>TextSource</code>. Ensure that your module complies with our stated copyright policy.

= Copyrighted Material =
If your got permission to distribute a new module which is under copyright, please send a copy of the authorization in a file named copyright.<extension> like <code>copyright.pdf</code>, <code>copyright.png</code>...

= Submit your files =
Submit only source files. Do not submit built modules that you have imported to Sword format. Avoid spaces in folder and file names.

Send an email to <code>modules@crosswire.org</code> describing the module and your files with one of the options below:

''Note: Pressing one of the following modules@crosswire.org links will open a new mail window already filled with a sample text.''

== Files attached ==

It is highly recommended to zip your files, as they are text files they will be highly compressed with the double benefit to reduce storage and make transmitting them much easier.
Feel free to attach your zip file to the email sent to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Please%20find%20the%20attached%20zip%20archive%20with%20source%20and%20.conf%20files.%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org]. Actually the biggest file (30MB) we have is 3MB once zipped.

== Link to a zip file ==

If you own a repository on the Internet, you may also store your zipped file on your repository and send the URL to this file instead to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20zip%20archive%20of%20the%20module%20with%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].

== Link to a git Repository ==

If you built your module on a public Git/GitLab/GitHub, you may want to share the <code>git clone</code> URL in the email to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20Git%20repository%20of%20the%20module%20containing%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].

We do accept git URL but there are some limitations, though:

* We expect to run into a flat structure, so Module files (source, .conf) shouldn't go in a subdir. Optional files like copyright, style.css should be at the root of your repository as well. Only multimedia files (audio/video/images) should go in their own subdir, typically <code>images</code> for dictionaries.
Example:
<pre>
git
|
+-- module.osis.xml
+-- module.conf
+-- style.css
+-- images/
+-- copyright.pdf
+-- README.md
</pre>
* Try to not put other files in the repository, they are more misleading than handy. Original text URL should be linked in <code>README.md</code>. If you really need to keep the original source text in plain format, USFM ot whatever in a subdir, please add this subdir to .gitignore.
<code>$ echo sources/ >> .gitignore</code>

* No more than 1 module per git repository.

It is sometimes easier to run <code>git archive</code> and attach the resulting zip file to the email.

----
<div style="text-align:center">'''If you do not comply with the above your module submission might end up being deprioritised and will certainly not get uploaded as fast as it could be otherwise'''</div>
----

Please note: Do not edit this page unless you are actually ''directly'' involved with uploading modules onto the server. If you have a comment or addition to make, but you are not part of this particular effort, please use talk page.
[[Category:Modules]]

Module Submission

2021-01-10T18:42:57Z

Domcox: 'Source text must be unique' info added.

----
'''<span style="color: crimson">For information on module licensing''' → please look at [[DevTools:Module Submission and Copyrights]]
----

= How-To Name your module =
Each module needs a name that be used as a unique identifier. Valid characters for the name are limited to alphanumeric characters, numeric characters and underscore. PCRE class [A-Za-z0-9\_].

Normalized names of module contains usually<ref name="Eng">For historical reasons, modules in English do not have any language prefix.</ref> 3 letters for language, followed by a short name descibing the work. Language is encoded in ISO 639-3 code. See [http://www.sil.org/iso639-3/codes.asp] for a list of codes.

The name has to be set in CamelCase format. Example for The French Bible David Martin 1707: <code>FreBDM1707</code><ref name="bdm">The published year was added to differentiate this version from successive revisions in 1744, 1855. Otherwise we could just have named it FreBDM.</ref>

<references />

= How-To name your source files =

You should provide 2 files:

* 1 Source text which will be converted to SWORD format. The source text must be unique and cannot be splitted in several files.
* 1 Configuration file which tells Sword how to recognize and what to do with your module.

The files reflects the name of your module in '''lowercase''' followed by an extension.

Extensions for the text file are:

* OSIS: <code>.osis.xml</code>
* TEI: <code>.tei.xml</code>
* VPL: <code>.vpl</code>
* IMP: <code>.imp</code>
* ThML: <code>.thml</code>

For the configuration file, the extension is <code>.conf</code>.

So, for the <code>FreBDM1707</code> module encoded in OSIS, we have <code>frebdm1707.osis.xml</code> and <code>frebdm1707.conf</code> files.

= How-To prepare your source files =

We will accept only plain texts in VPL<ref name="vpl">Only for Bibles in KJV versification</ref> or texts marked up in OSIS or TEI, with the sole exception texts based on CCEL documents that are marked up in ThML.

<references />

== Check your OSIS before submitting ==

OSIS 2.1 is now the preferred format for Bibles, Commentaries and General Books. TEI is the prefered format for dictionaries.

OSIS texts need to have the CamelCase module name as <code>workID</code> and an appropriate <code>osisRefWork</code> entry within the appropriate header section. The document language needs to be set correctly, ISO 639-1 codes are preferred, and ISO 639-3 codes when ISO 639-1 codes do not exist for the given language. Examples:

Bible:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Bible" xml:lang="he">
</pre>

Commentary:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Commentary" xml:lang="gr">
</pre>
General Book:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="GenBook" xml:lang="en">
</pre>

== Please validate your OSIS or TEI text ==
See: Guide to [[Validate_OSIS_or_TEI_text]]

== Check your configuration file ==
We require that the following minimum set of module configuration fields are included: <code>Description</code>, <code>About</code>, <code>DistributionLicense</code>, and <code>TextSource</code>. Ensure that your module complies with our stated copyright policy.

== Copyrighted Material ==
If your got permission to distribute a new module which is under copyright, please send a copy of the authorization in a file named copyright.<extension> like <code>copyright.pdf</code>, <code>copyright.png</code>...

= Submit your files =
Submit only source files. Do not submit built modules that you have imported to Sword format. Avoid spaces in folder and file names.

Send an email to <code>modules@crosswire.org</code> describing the module and your files with one of the options below:

''Note: Pressing one of the following modules@crosswire.org links will open a new mail window already filled with a sample text.''

== Files attached ==

It is highly recommended to zip your files, as they are text files they will be highly compressed with the double benefit to reduce storage and make transmitting them much easier.
Feel free to attach your zip file to the email sent to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Please%20find%20the%20attached%20zip%20archive%20with%20source%20and%20.conf%20files.%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org]. Actually the biggest file (30MB) we have is 3MB once zipped.

== Link to a zip file ==

If you own a repository on the Internet, you may also store your zipped file on your repository and send the URL to this file instead to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20zip%20archive%20of%20the%20module%20with%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].

== Link to a git Repository ==

If you built your module on a public Git/GitLab/GitHub, you may want to share the <code>git clone</code> URL in the email to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20Git%20repository%20of%20the%20module%20containing%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].

We do accept git URL but there are some limitations, though:

* We expect to run into a flat structure, so Module files (source, .conf) shouldn't go in a subdir. Optional files like copyright, style.css should be at the root of your repository as well. Only multimedia files (audio/video/images) should go in their own subdir, typically <code>images</code> for dictionaries.
Example:
<pre>
git
|
+-- module.osis.xml
+-- module.conf
+-- style.css
+-- images/
+-- copyright.pdf
+-- README.md
</pre>
* Try to not put other files in the repository, they are more misleading than handy. Original text URL should be linked in <code>README.md</code>. If you really need to keep the original source text in plain format, USFM ot whatever in a subdir, please add this subdir to .gitignore.
<code>$ echo sources/ >> .gitignore</code>

* No more than 1 module per git repository.

It is sometimes easier to run <code>git archive</code> and attach the resulting zip file to the email.

----
<div style="text-align:center">'''If you do not comply with the above your module submission might end up being deprioritised and will certainly not get uploaded as fast as it could be otherwise'''</div>
----

Please note: Do not edit this page unless you are actually ''directly'' involved with uploading modules onto the server. If you have a comment or addition to make, but you are not part of this particular effort, please use talk page.
[[Category:Modules]]

Module Submission

2021-01-10T18:40:10Z

Domcox: /* How-To prepare your files */

----
'''<span style="color: crimson">For information on module licensing''' → please look at [[DevTools:Module Submission and Copyrights]]
----

= How-To Name your module =
Each module needs a name that be used as a unique identifier. Valid characters for the name are limited to alphanumeric characters, numeric characters and underscore. PCRE class [A-Za-z0-9\_].

Normalized names of module contains usually<ref name="Eng">For historical reasons, modules in English do not have any language prefix.</ref> 3 letters for language, followed by a short name descibing the work. Language is encoded in ISO 639-3 code. See [http://www.sil.org/iso639-3/codes.asp] for a list of codes.

The name has to be set in CamelCase format. Example for The French Bible David Martin 1707: <code>FreBDM1707</code><ref name="bdm">The published year was added to differentiate this version from successive revisions in 1744, 1855. Otherwise we could just have named it FreBDM.</ref>

<references />

= How-To name your files =
You should provide 2 files:
* 1 source text which will be converted to SWORD format.
* 1 Configuration file which tells Sword how to recognize and what to do with your module.

The files reflects the name of your module in '''lowercase''' followed by an extension.

Extensions for the text file are:

* OSIS: <code>.osis.xml</code>

* TEI: <code>.tei.xml</code>

* VPL: <code>.vpl</code>

* IMP: <code>.imp</code>

* ThML: <code>.thml</code>

For the configuration file, the extension is <code>.conf</code>.

So, for the <code>FreBDM1707</code> module encoded in OSIS, we have <code>frebdm1707.osis.xml</code> and <code>frebdm1707.conf</code> files.

= How-To prepare your source files =

We will accept only plain texts in VPL<ref name="vpl">Only for Bibles in KJV versification</ref> or texts marked up in OSIS or TEI, with the sole exception texts based on CCEL documents that are marked up in ThML.

<references />

== Check your OSIS before submitting ==

OSIS 2.1 is now the preferred format for Bibles, Commentaries and General Books. TEI is the prefered format for dictionaries.

OSIS texts need to have the CamelCase module name as <code>workID</code> and an appropriate <code>osisRefWork</code> entry within the appropriate header section. The document language needs to be set correctly, ISO 639-1 codes are preferred, and ISO 639-3 codes when ISO 639-1 codes do not exist for the given language. Examples:

Bible:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Bible" xml:lang="he">
</pre>

Commentary:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Commentary" xml:lang="gr">
</pre>
General Book:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="GenBook" xml:lang="en">
</pre>

== Please validate your OSIS or TEI text ==
See: Guide to [[Validate_OSIS_or_TEI_text]]

== Check your configuration file ==
We require that the following minimum set of module configuration fields are included: <code>Description</code>, <code>About</code>, <code>DistributionLicense</code>, and <code>TextSource</code>. Ensure that your module complies with our stated copyright policy.

== Copyrighted Material ==
If your got permission to distribute a new module which is under copyright, please send a copy of the authorization in a file named copyright.<extension> like <code>copyright.pdf</code>, <code>copyright.png</code>...

= Submit your files =
Submit only source files. Do not submit built modules that you have imported to Sword format. Avoid spaces in folder and file names.

Send an email to <code>modules@crosswire.org</code> describing the module and your files with one of the options below:

''Note: Pressing one of the following modules@crosswire.org links will open a new mail window already filled with a sample text.''

== Files attached ==

It is highly recommended to zip your files, as they are text files they will be highly compressed with the double benefit to reduce storage and make transmitting them much easier.
Feel free to attach your zip file to the email sent to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Please%20find%20the%20attached%20zip%20archive%20with%20source%20and%20.conf%20files.%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org]. Actually the biggest file (30MB) we have is 3MB once zipped.

== Link to a zip file ==

If you own a repository on the Internet, you may also store your zipped file on your repository and send the URL to this file instead to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20zip%20archive%20of%20the%20module%20with%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].

== Link to a git Repository ==

If you built your module on a public Git/GitLab/GitHub, you may want to share the <code>git clone</code> URL in the email to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20Git%20repository%20of%20the%20module%20containing%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].

We do accept git URL but there are some limitations, though:

* We expect to run into a flat structure, so Module files (source, .conf) shouldn't go in a subdir. Optional files like copyright, style.css should be at the root of your repository as well. Only multimedia files (audio/video/images) should go in their own subdir, typically <code>images</code> for dictionaries.
Example:
<pre>
git
|
+-- module.osis.xml
+-- module.conf
+-- style.css
+-- images/
+-- copyright.pdf
+-- README.md
</pre>
* Try to not put other files in the repository, they are more misleading than handy. Original text URL should be linked in <code>README.md</code>. If you really need to keep the original source text in plain format, USFM ot whatever in a subdir, please add this subdir to .gitignore.
<code>$ echo sources/ >> .gitignore</code>

* No more than 1 module per git repository.

It is sometimes easier to run <code>git archive</code> and attach the resulting zip file to the email.

----
<div style="text-align:center">'''If you do not comply with the above your module submission might end up being deprioritised and will certainly not get uploaded as fast as it could be otherwise'''</div>
----

Please note: Do not edit this page unless you are actually ''directly'' involved with uploading modules onto the server. If you have a comment or addition to make, but you are not part of this particular effort, please use talk page.
[[Category:Modules]]

Module Submission

2021-01-10T18:34:53Z

Domcox: /* How-To name your files */

----
'''<span style="color: crimson">For information on module licensing''' → please look at [[DevTools:Module Submission and Copyrights]]
----

= How-To Name your module =
Each module needs a name that be used as a unique identifier. Valid characters for the name are limited to alphanumeric characters, numeric characters and underscore. PCRE class [A-Za-z0-9\_].

Normalized names of module contains usually<ref name="Eng">For historical reasons, modules in English do not have any language prefix.</ref> 3 letters for language, followed by a short name descibing the work. Language is encoded in ISO 639-3 code. See [http://www.sil.org/iso639-3/codes.asp] for a list of codes.

The name has to be set in CamelCase format. Example for The French Bible David Martin 1707: <code>FreBDM1707</code><ref name="bdm">The published year was added to differentiate this version from successive revisions in 1744, 1855. Otherwise we could just have named it FreBDM.</ref>

<references />

= How-To name your files =
You should provide 2 files:
* 1 source text which will be converted to SWORD format.
* 1 Configuration file which tells Sword how to recognize and what to do with your module.

The files reflects the name of your module in '''lowercase''' followed by an extension.

Extensions for the text file are:

* OSIS: <code>.osis.xml</code>

* TEI: <code>.tei.xml</code>

* VPL: <code>.vpl</code>

* IMP: <code>.imp</code>

* ThML: <code>.thml</code>

For the configuration file, the extension is <code>.conf</code>.

So, for the <code>FreBDM1707</code> module encoded in OSIS, we have <code>frebdm1707.osis.xml</code> and <code>frebdm1707.conf</code> files.

= How-To prepare your files =

We will accept only plain texts in VPL<ref name="vpl">Only for Bibles in KJV versification</ref> or texts marked up in OSIS or TEI, with the sole exception texts based on CCEL documents that are marked up in ThML.

<references />

== Check your OSIS before submitting ==

OSIS 2.1 is now the preferred format for Bibles, Commentaries and General Books. TEI is the prefered format for dictionaries.

OSIS texts need to have the CamelCase module name as <code>workID</code> and an appropriate <code>osisRefWork</code> entry within the appropriate header section. The document language needs to be set correctly, ISO 639-1 codes are preferred, and ISO 639-3 codes when ISO 639-1 codes do not exist for the given language. Examples:

Bible:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Bible" xml:lang="he">
</pre>

Commentary:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Commentary" xml:lang="gr">
</pre>
General Book:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="GenBook" xml:lang="en">
</pre>

== Please validate your OSIS or TEI text ==
See: Guide to [[Validate_OSIS_or_TEI_text]]

== Check your configuration file ==
We require that the following minimum set of module configuration fields are included: <code>Description</code>, <code>About</code>, <code>DistributionLicense</code>, and <code>TextSource</code>. Ensure that your module complies with our stated copyright policy.

== Copyrighted Material ==
If your got permission to distribute a new module which is under copyright, please send a copy of the authorization in a file named copyright.<extension> like <code>copyright.pdf</code>, <code>copyright.png</code>...

= Submit your files =
Submit only source files. Do not submit built modules that you have imported to Sword format. Avoid spaces in folder and file names.

Send an email to <code>modules@crosswire.org</code> describing the module and your files with one of the options below:

''Note: Pressing one of the following modules@crosswire.org links will open a new mail window already filled with a sample text.''

== Files attached ==

It is highly recommended to zip your files, as they are text files they will be highly compressed with the double benefit to reduce storage and make transmitting them much easier.
Feel free to attach your zip file to the email sent to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Please%20find%20the%20attached%20zip%20archive%20with%20source%20and%20.conf%20files.%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org]. Actually the biggest file (30MB) we have is 3MB once zipped.

== Link to a zip file ==

If you own a repository on the Internet, you may also store your zipped file on your repository and send the URL to this file instead to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20zip%20archive%20of%20the%20module%20with%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].

== Link to a git Repository ==

If you built your module on a public Git/GitLab/GitHub, you may want to share the <code>git clone</code> URL in the email to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20Git%20repository%20of%20the%20module%20containing%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].

We do accept git URL but there are some limitations, though:

* We expect to run into a flat structure, so Module files (source, .conf) shouldn't go in a subdir. Optional files like copyright, style.css should be at the root of your repository as well. Only multimedia files (audio/video/images) should go in their own subdir, typically <code>images</code> for dictionaries.
Example:
<pre>
git
|
+-- module.osis.xml
+-- module.conf
+-- style.css
+-- images/
+-- copyright.pdf
+-- README.md
</pre>
* Try to not put other files in the repository, they are more misleading than handy. Original text URL should be linked in <code>README.md</code>. If you really need to keep the original source text in plain format, USFM ot whatever in a subdir, please add this subdir to .gitignore.
<code>$ echo sources/ >> .gitignore</code>

* No more than 1 module per git repository.

It is sometimes easier to run <code>git archive</code> and attach the resulting zip file to the email.

----
<div style="text-align:center">'''If you do not comply with the above your module submission might end up being deprioritised and will certainly not get uploaded as fast as it could be otherwise'''</div>
----

Please note: Do not edit this page unless you are actually ''directly'' involved with uploading modules onto the server. If you have a comment or addition to make, but you are not part of this particular effort, please use talk page.
[[Category:Modules]]

Module Submission

2021-01-10T18:26:40Z

Domcox: /* How-To name your files */ Fix typo

----
'''<span style="color: crimson">For information on module licensing''' → please look at [[DevTools:Module Submission and Copyrights]]
----

= How-To Name your module =
Each module needs a name that be used as a unique identifier. Valid characters for the name are limited to alphanumeric characters, numeric characters and underscore. PCRE class [A-Za-z0-9\_].

Normalized names of module contains usually<ref name="Eng">For historical reasons, modules in English do not have any language prefix.</ref> 3 letters for language, followed by a short name descibing the work. Language is encoded in ISO 639-3 code. See [http://www.sil.org/iso639-3/codes.asp] for a list of codes.

The name has to be set in CamelCase format. Example for The French Bible David Martin 1707: <code>FreBDM1707</code><ref name="bdm">The published year was added to differentiate this version from successive revisions in 1744, 1855. Otherwise we could just have named it FreBDM.</ref>

<references />

= How-To name your files =
The source file reflects the name of your module in '''lowercase''' followed by an extension.

For the configuration file, the extension is <code>.conf</code>.

Extensions for the text file are:

* OSIS: <code>.osis.xml</code>

* TEI: <code>.tei.xml</code>

* VPL: <code>.vpl</code>

* IMP: <code>.imp</code>

* ThML: <code>.thml</code>

So, for the <code>FreBDM1707</code> module encoded in OSIS, we have <code>frebdm1707.osis.xml</code> and <code>frebdm1707.conf</code> files.

= How-To prepare your files =

We will accept only plain texts in VPL<ref name="vpl">Only for Bibles in KJV versification</ref> or texts marked up in OSIS or TEI, with the sole exception texts based on CCEL documents that are marked up in ThML.

<references />

== Check your OSIS before submitting ==

OSIS 2.1 is now the preferred format for Bibles, Commentaries and General Books. TEI is the prefered format for dictionaries.

OSIS texts need to have the CamelCase module name as <code>workID</code> and an appropriate <code>osisRefWork</code> entry within the appropriate header section. The document language needs to be set correctly, ISO 639-1 codes are preferred, and ISO 639-3 codes when ISO 639-1 codes do not exist for the given language. Examples:

Bible:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Bible" xml:lang="he">
</pre>

Commentary:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Commentary" xml:lang="gr">
</pre>
General Book:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="GenBook" xml:lang="en">
</pre>

== Please validate your OSIS or TEI text ==
See: Guide to [[Validate_OSIS_or_TEI_text]]

== Check your configuration file ==
We require that the following minimum set of module configuration fields are included: <code>Description</code>, <code>About</code>, <code>DistributionLicense</code>, and <code>TextSource</code>. Ensure that your module complies with our stated copyright policy.

== Copyrighted Material ==
If your got permission to distribute a new module which is under copyright, please send a copy of the authorization in a file named copyright.<extension> like <code>copyright.pdf</code>, <code>copyright.png</code>...

= Submit your files =
Submit only source files. Do not submit built modules that you have imported to Sword format. Avoid spaces in folder and file names.

Send an email to <code>modules@crosswire.org</code> describing the module and your files with one of the options below:

''Note: Pressing one of the following modules@crosswire.org links will open a new mail window already filled with a sample text.''

== Files attached ==

It is highly recommended to zip your files, as they are text files they will be highly compressed with the double benefit to reduce storage and make transmitting them much easier.
Feel free to attach your zip file to the email sent to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Please%20find%20the%20attached%20zip%20archive%20with%20source%20and%20.conf%20files.%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org]. Actually the biggest file (30MB) we have is 3MB once zipped.

== Link to a zip file ==

If you own a repository on the Internet, you may also store your zipped file on your repository and send the URL to this file instead to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20zip%20archive%20of%20the%20module%20with%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].

== Link to a git Repository ==

If you built your module on a public Git/GitLab/GitHub, you may want to share the <code>git clone</code> URL in the email to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20Git%20repository%20of%20the%20module%20containing%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].

We do accept git URL but there are some limitations, though:

* We expect to run into a flat structure, so Module files (source, .conf) shouldn't go in a subdir. Optional files like copyright, style.css should be at the root of your repository as well. Only multimedia files (audio/video/images) should go in their own subdir, typically <code>images</code> for dictionaries.
Example:
<pre>
git
|
+-- module.osis.xml
+-- module.conf
+-- style.css
+-- images/
+-- copyright.pdf
+-- README.md
</pre>
* Try to not put other files in the repository, they are more misleading than handy. Original text URL should be linked in <code>README.md</code>. If you really need to keep the original source text in plain format, USFM ot whatever in a subdir, please add this subdir to .gitignore.
<code>$ echo sources/ >> .gitignore</code>

* No more than 1 module per git repository.

It is sometimes easier to run <code>git archive</code> and attach the resulting zip file to the email.

----
<div style="text-align:center">'''If you do not comply with the above your module submission might end up being deprioritised and will certainly not get uploaded as fast as it could be otherwise'''</div>
----

Please note: Do not edit this page unless you are actually ''directly'' involved with uploading modules onto the server. If you have a comment or addition to make, but you are not part of this particular effort, please use talk page.
[[Category:Modules]]

Module Submission

2021-01-01T13:20:09Z

Domcox: /* Link to a zip file */ mailto edit

----
'''<span style="color: crimson">For information on module licensing''' → please look at [[DevTools:Module Submission and Copyrights]]
----

= How-To Name your module =
Each module needs a name that be used as a unique identifier. Valid characters for the name are limited to alphanumeric characters, numeric characters and underscore. PCRE class [A-Za-z0-9\_].

Normalized names of module contains usually<ref name="Eng">For historical reasons, modules in English do not have any language prefix.</ref> 3 letters for language, followed by a short name descibing the work. Language is encoded in ISO 639-3 code. See [http://www.sil.org/iso639-3/codes.asp] for a list of codes.

The name has to be set in CamelCase format. Example for The French Bible David Martin 1707: <code>FreBDM1707</code><ref name="bdm">The published year was added to differentiate this version from successive revisions in 1744, 1855. Otherwise we could just have named it FreBDM.</ref>

<references />

= How-To name your files =
The source files reflects the name of your module in '''lowercase''' followed by an extension.

For the configuration file, the extension is <code>.conf</code>.

Extensions for the text file are:

* OSIS: <code>.osis.xml</code>

* TEI: <code>.tei.xml</code>

* VPL: <code>.vpl</code>

* IMP: <code>.imp</code>

* ThML: <code>.thml</code>

So, for the <code>FreBDM1707</code> module encoded in OSIS, we have <code>frebdm1707.osis.xml</code> and <code>frebdm1707.conf</code> files.

= How-To prepare your files =

We will accept only plain texts in VPL<ref name="vpl">Only for Bibles in KJV versification</ref> or texts marked up in OSIS or TEI, with the sole exception texts based on CCEL documents that are marked up in ThML.

<references />

== Check your OSIS before submitting ==

OSIS 2.1 is now the preferred format for Bibles, Commentaries and General Books. TEI is the prefered format for dictionaries.

OSIS texts need to have the CamelCase module name as <code>workID</code> and an appropriate <code>osisRefWork</code> entry within the appropriate header section. The document language needs to be set correctly, ISO 639-1 codes are preferred, and ISO 639-3 codes when ISO 639-1 codes do not exist for the given language. Examples:

Bible:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Bible" xml:lang="he">
</pre>

Commentary:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Commentary" xml:lang="gr">
</pre>
General Book:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="GenBook" xml:lang="en">
</pre>

== Please validate your OSIS or TEI text ==
See: Guide to [[Validate_OSIS_or_TEI_text]]

== Check your configuration file ==
We require that the following minimum set of module configuration fields are included: <code>Description</code>, <code>About</code>, <code>DistributionLicense</code>, and <code>TextSource</code>. Ensure that your module complies with our stated copyright policy.

== Copyrighted Material ==
If your got permission to distribute a new module which is under copyright, please send a copy of the authorization in a file named copyright.<extension> like <code>copyright.pdf</code>, <code>copyright.png</code>...

= Submit your files =
Submit only source files. Do not submit built modules that you have imported to Sword format. Avoid spaces in folder and file names.

Send an email to <code>modules@crosswire.org</code> describing the module and your files with one of the options below:

''Note: Pressing one of the following modules@crosswire.org links will open a new mail window already filled with a sample text.''

== Files attached ==

It is highly recommended to zip your files, as they are text files they will be highly compressed with the double benefit to reduce storage and make transmitting them much easier.
Feel free to attach your zip file to the email sent to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Please%20find%20the%20attached%20zip%20archive%20with%20source%20and%20.conf%20files.%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org]. Actually the biggest file (30MB) we have is 3MB once zipped.

== Link to a zip file ==

If you own a repository on the Internet, you may also store your zipped file on your repository and send the URL to this file instead to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20zip%20archive%20of%20the%20module%20with%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].

== Link to a git Repository ==

If you built your module on a public Git/GitLab/GitHub, you may want to share the <code>git clone</code> URL in the email to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20Git%20repository%20of%20the%20module%20containing%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].

We do accept git URL but there are some limitations, though:

* We expect to run into a flat structure, so Module files (source, .conf) shouldn't go in a subdir. Optional files like copyright, style.css should be at the root of your repository as well. Only multimedia files (audio/video/images) should go in their own subdir, typically <code>images</code> for dictionaries.
Example:
<pre>
git
|
+-- module.osis.xml
+-- module.conf
+-- style.css
+-- images/
+-- copyright.pdf
+-- README.md
</pre>
* Try to not put other files in the repository, they are more misleading than handy. Original text URL should be linked in <code>README.md</code>. If you really need to keep the original source text in plain format, USFM ot whatever in a subdir, please add this subdir to .gitignore.
<code>$ echo sources/ >> .gitignore</code>

* No more than 1 module per git repository.

It is sometimes easier to run <code>git archive</code> and attach the resulting zip file to the email.

----
<div style="text-align:center">'''If you do not comply with the above your module submission might end up being deprioritised and will certainly not get uploaded as fast as it could be otherwise'''</div>
----

Please note: Do not edit this page unless you are actually ''directly'' involved with uploading modules onto the server. If you have a comment or addition to make, but you are not part of this particular effort, please use talk page.
[[Category:Modules]]

Module Submission

2021-01-01T13:17:50Z

Domcox: /* Files attached */ mailto edit

----
'''<span style="color: crimson">For information on module licensing''' → please look at [[DevTools:Module Submission and Copyrights]]
----

= How-To Name your module =
Each module needs a name that be used as a unique identifier. Valid characters for the name are limited to alphanumeric characters, numeric characters and underscore. PCRE class [A-Za-z0-9\_].

Normalized names of module contains usually<ref name="Eng">For historical reasons, modules in English do not have any language prefix.</ref> 3 letters for language, followed by a short name descibing the work. Language is encoded in ISO 639-3 code. See [http://www.sil.org/iso639-3/codes.asp] for a list of codes.

The name has to be set in CamelCase format. Example for The French Bible David Martin 1707: <code>FreBDM1707</code><ref name="bdm">The published year was added to differentiate this version from successive revisions in 1744, 1855. Otherwise we could just have named it FreBDM.</ref>

<references />

= How-To name your files =
The source files reflects the name of your module in '''lowercase''' followed by an extension.

For the configuration file, the extension is <code>.conf</code>.

Extensions for the text file are:

* OSIS: <code>.osis.xml</code>

* TEI: <code>.tei.xml</code>

* VPL: <code>.vpl</code>

* IMP: <code>.imp</code>

* ThML: <code>.thml</code>

So, for the <code>FreBDM1707</code> module encoded in OSIS, we have <code>frebdm1707.osis.xml</code> and <code>frebdm1707.conf</code> files.

= How-To prepare your files =

We will accept only plain texts in VPL<ref name="vpl">Only for Bibles in KJV versification</ref> or texts marked up in OSIS or TEI, with the sole exception texts based on CCEL documents that are marked up in ThML.

<references />

== Check your OSIS before submitting ==

OSIS 2.1 is now the preferred format for Bibles, Commentaries and General Books. TEI is the prefered format for dictionaries.

OSIS texts need to have the CamelCase module name as <code>workID</code> and an appropriate <code>osisRefWork</code> entry within the appropriate header section. The document language needs to be set correctly, ISO 639-1 codes are preferred, and ISO 639-3 codes when ISO 639-1 codes do not exist for the given language. Examples:

Bible:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Bible" xml:lang="he">
</pre>

Commentary:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Commentary" xml:lang="gr">
</pre>
General Book:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="GenBook" xml:lang="en">
</pre>

== Please validate your OSIS or TEI text ==
See: Guide to [[Validate_OSIS_or_TEI_text]]

== Check your configuration file ==
We require that the following minimum set of module configuration fields are included: <code>Description</code>, <code>About</code>, <code>DistributionLicense</code>, and <code>TextSource</code>. Ensure that your module complies with our stated copyright policy.

== Copyrighted Material ==
If your got permission to distribute a new module which is under copyright, please send a copy of the authorization in a file named copyright.<extension> like <code>copyright.pdf</code>, <code>copyright.png</code>...

= Submit your files =
Submit only source files. Do not submit built modules that you have imported to Sword format. Avoid spaces in folder and file names.

Send an email to <code>modules@crosswire.org</code> describing the module and your files with one of the options below:

''Note: Pressing one of the following modules@crosswire.org links will open a new mail window already filled with a sample text.''

== Files attached ==

It is highly recommended to zip your files, as they are text files they will be highly compressed with the double benefit to reduce storage and make transmitting them much easier.
Feel free to attach your zip file to the email sent to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Please%20find%20the%20attached%20zip%20archive%20with%20source%20and%20.conf%20files.%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org]. Actually the biggest file (30MB) we have is 3MB once zipped.

== Link to a zip file ==

If you own a repository on the Internet, you may also store your zipped file on your repository and send the URL to this file instead to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20zip%20archive%20with%20OSIS%20(or%20TEI%20or%20other%20type)%20file%20and%20.conf%20file%3A%20%3Curl%3E%0D%0A%0D%0AVersion%3A%20%3Cyour-module-version%3E%0D%0AChangelog%3A%20(for%20updates%20only)%3CWhat's%20new%3E%0D%0AType%3D%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0AVersification%3D(optional%20for%20Bibles%20and%20Commentaries%2C%20if%20not%20KJV)%0D%0A%0D%0AThanks! modules@crosswire.org].

== Link to a git Repository ==

If you built your module on a public Git/GitLab/GitHub, you may want to share the <code>git clone</code> URL in the email to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20Git%20repository%20of%20the%20module%20containing%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].

We do accept git URL but there are some limitations, though:

* We expect to run into a flat structure, so Module files (source, .conf) shouldn't go in a subdir. Optional files like copyright, style.css should be at the root of your repository as well. Only multimedia files (audio/video/images) should go in their own subdir, typically <code>images</code> for dictionaries.
Example:
<pre>
git
|
+-- module.osis.xml
+-- module.conf
+-- style.css
+-- images/
+-- copyright.pdf
+-- README.md
</pre>
* Try to not put other files in the repository, they are more misleading than handy. Original text URL should be linked in <code>README.md</code>. If you really need to keep the original source text in plain format, USFM ot whatever in a subdir, please add this subdir to .gitignore.
<code>$ echo sources/ >> .gitignore</code>

* No more than 1 module per git repository.

It is sometimes easier to run <code>git archive</code> and attach the resulting zip file to the email.

----
<div style="text-align:center">'''If you do not comply with the above your module submission might end up being deprioritised and will certainly not get uploaded as fast as it could be otherwise'''</div>
----

Please note: Do not edit this page unless you are actually ''directly'' involved with uploading modules onto the server. If you have a comment or addition to make, but you are not part of this particular effort, please use talk page.
[[Category:Modules]]

Module Submission

2021-01-01T13:15:28Z

Domcox: /* Submit your files */

----
'''<span style="color: crimson">For information on module licensing''' → please look at [[DevTools:Module Submission and Copyrights]]
----

= How-To Name your module =
Each module needs a name that be used as a unique identifier. Valid characters for the name are limited to alphanumeric characters, numeric characters and underscore. PCRE class [A-Za-z0-9\_].

Normalized names of module contains usually<ref name="Eng">For historical reasons, modules in English do not have any language prefix.</ref> 3 letters for language, followed by a short name descibing the work. Language is encoded in ISO 639-3 code. See [http://www.sil.org/iso639-3/codes.asp] for a list of codes.

The name has to be set in CamelCase format. Example for The French Bible David Martin 1707: <code>FreBDM1707</code><ref name="bdm">The published year was added to differentiate this version from successive revisions in 1744, 1855. Otherwise we could just have named it FreBDM.</ref>

<references />

= How-To name your files =
The source files reflects the name of your module in '''lowercase''' followed by an extension.

For the configuration file, the extension is <code>.conf</code>.

Extensions for the text file are:

* OSIS: <code>.osis.xml</code>

* TEI: <code>.tei.xml</code>

* VPL: <code>.vpl</code>

* IMP: <code>.imp</code>

* ThML: <code>.thml</code>

So, for the <code>FreBDM1707</code> module encoded in OSIS, we have <code>frebdm1707.osis.xml</code> and <code>frebdm1707.conf</code> files.

= How-To prepare your files =

We will accept only plain texts in VPL<ref name="vpl">Only for Bibles in KJV versification</ref> or texts marked up in OSIS or TEI, with the sole exception texts based on CCEL documents that are marked up in ThML.

<references />

== Check your OSIS before submitting ==

OSIS 2.1 is now the preferred format for Bibles, Commentaries and General Books. TEI is the prefered format for dictionaries.

OSIS texts need to have the CamelCase module name as <code>workID</code> and an appropriate <code>osisRefWork</code> entry within the appropriate header section. The document language needs to be set correctly, ISO 639-1 codes are preferred, and ISO 639-3 codes when ISO 639-1 codes do not exist for the given language. Examples:

Bible:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Bible" xml:lang="he">
</pre>

Commentary:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Commentary" xml:lang="gr">
</pre>
General Book:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="GenBook" xml:lang="en">
</pre>

== Please validate your OSIS or TEI text ==
See: Guide to [[Validate_OSIS_or_TEI_text]]

== Check your configuration file ==
We require that the following minimum set of module configuration fields are included: <code>Description</code>, <code>About</code>, <code>DistributionLicense</code>, and <code>TextSource</code>. Ensure that your module complies with our stated copyright policy.

== Copyrighted Material ==
If your got permission to distribute a new module which is under copyright, please send a copy of the authorization in a file named copyright.<extension> like <code>copyright.pdf</code>, <code>copyright.png</code>...

= Submit your files =
Submit only source files. Do not submit built modules that you have imported to Sword format. Avoid spaces in folder and file names.

Send an email to <code>modules@crosswire.org</code> describing the module and your files with one of the options below:

''Note: Pressing one of the following modules@crosswire.org links will open a new mail window already filled with a sample text.''

== Files attached ==

It is highly recommended to zip your files, as they are text files they will be highly compressed with the double benefit to reduce storage and make transmitting them much easier.
Feel free to attach your zip file to the email sent to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Please%20find%20the%20attached%20zip%20archive%20with%20OSIS%20(or%20TEI%20or%20other%20type)%20file%20and%20.conf%20file.%0D%0A%0D%0AVersion%3A%20%3Cyour-module-version%3E%0D%0AChangelog%3A%20(for%20updates%20only)%3CWhat's%20new%3E%0D%0AType%3D%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0AVersification%3D(optional%20for%20Bibles%20and%20Commentaries%2C%20if%20not%20KJV)%0D%0A%0D%0AThanks! modules@crosswire.org]. Actually the biggest file (30MB) we have is 3MB once zipped.

== Link to a zip file ==

If you own a repository on the Internet, you may also store your zipped file on your repository and send the URL to this file instead to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20zip%20archive%20with%20OSIS%20(or%20TEI%20or%20other%20type)%20file%20and%20.conf%20file%3A%20%3Curl%3E%0D%0A%0D%0AVersion%3A%20%3Cyour-module-version%3E%0D%0AChangelog%3A%20(for%20updates%20only)%3CWhat's%20new%3E%0D%0AType%3D%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0AVersification%3D(optional%20for%20Bibles%20and%20Commentaries%2C%20if%20not%20KJV)%0D%0A%0D%0AThanks! modules@crosswire.org].

== Link to a git Repository ==

If you built your module on a public Git/GitLab/GitHub, you may want to share the <code>git clone</code> URL in the email to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20Git%20repository%20of%20the%20module%20containing%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].

We do accept git URL but there are some limitations, though:

* We expect to run into a flat structure, so Module files (source, .conf) shouldn't go in a subdir. Optional files like copyright, style.css should be at the root of your repository as well. Only multimedia files (audio/video/images) should go in their own subdir, typically <code>images</code> for dictionaries.
Example:
<pre>
git
|
+-- module.osis.xml
+-- module.conf
+-- style.css
+-- images/
+-- copyright.pdf
+-- README.md
</pre>
* Try to not put other files in the repository, they are more misleading than handy. Original text URL should be linked in <code>README.md</code>. If you really need to keep the original source text in plain format, USFM ot whatever in a subdir, please add this subdir to .gitignore.
<code>$ echo sources/ >> .gitignore</code>

* No more than 1 module per git repository.

It is sometimes easier to run <code>git archive</code> and attach the resulting zip file to the email.

----
<div style="text-align:center">'''If you do not comply with the above your module submission might end up being deprioritised and will certainly not get uploaded as fast as it could be otherwise'''</div>
----

Please note: Do not edit this page unless you are actually ''directly'' involved with uploading modules onto the server. If you have a comment or addition to make, but you are not part of this particular effort, please use talk page.
[[Category:Modules]]

Module Submission

2021-01-01T13:15:12Z

Domcox: /* Submit your files */ fix typo

----
'''<span style="color: crimson">For information on module licensing''' → please look at [[DevTools:Module Submission and Copyrights]]
----

= How-To Name your module =
Each module needs a name that be used as a unique identifier. Valid characters for the name are limited to alphanumeric characters, numeric characters and underscore. PCRE class [A-Za-z0-9\_].

Normalized names of module contains usually<ref name="Eng">For historical reasons, modules in English do not have any language prefix.</ref> 3 letters for language, followed by a short name descibing the work. Language is encoded in ISO 639-3 code. See [http://www.sil.org/iso639-3/codes.asp] for a list of codes.

The name has to be set in CamelCase format. Example for The French Bible David Martin 1707: <code>FreBDM1707</code><ref name="bdm">The published year was added to differentiate this version from successive revisions in 1744, 1855. Otherwise we could just have named it FreBDM.</ref>

<references />

= How-To name your files =
The source files reflects the name of your module in '''lowercase''' followed by an extension.

For the configuration file, the extension is <code>.conf</code>.

Extensions for the text file are:

* OSIS: <code>.osis.xml</code>

* TEI: <code>.tei.xml</code>

* VPL: <code>.vpl</code>

* IMP: <code>.imp</code>

* ThML: <code>.thml</code>

So, for the <code>FreBDM1707</code> module encoded in OSIS, we have <code>frebdm1707.osis.xml</code> and <code>frebdm1707.conf</code> files.

= How-To prepare your files =

We will accept only plain texts in VPL<ref name="vpl">Only for Bibles in KJV versification</ref> or texts marked up in OSIS or TEI, with the sole exception texts based on CCEL documents that are marked up in ThML.

<references />

== Check your OSIS before submitting ==

OSIS 2.1 is now the preferred format for Bibles, Commentaries and General Books. TEI is the prefered format for dictionaries.

OSIS texts need to have the CamelCase module name as <code>workID</code> and an appropriate <code>osisRefWork</code> entry within the appropriate header section. The document language needs to be set correctly, ISO 639-1 codes are preferred, and ISO 639-3 codes when ISO 639-1 codes do not exist for the given language. Examples:

Bible:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Bible" xml:lang="he">
</pre>

Commentary:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Commentary" xml:lang="gr">
</pre>
General Book:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="GenBook" xml:lang="en">
</pre>

== Please validate your OSIS or TEI text ==
See: Guide to [[Validate_OSIS_or_TEI_text]]

== Check your configuration file ==
We require that the following minimum set of module configuration fields are included: <code>Description</code>, <code>About</code>, <code>DistributionLicense</code>, and <code>TextSource</code>. Ensure that your module complies with our stated copyright policy.

== Copyrighted Material ==
If your got permission to distribute a new module which is under copyright, please send a copy of the authorization in a file named copyright.<extension> like <code>copyright.pdf</code>, <code>copyright.png</code>...

= Submit your files =
Submit only source files. Do not submit built modules that you have imported to Sword format. Avoid spaces in folder and file names.

Send an email to <code>modules@crosswire.org modules@crosswire.org</code> describing the module and your files with one of the options below:

''Note: Pressing one of the following modules@crosswire.org links will open a new mail window already filled with a sample text.''

== Files attached ==

It is highly recommended to zip your files, as they are text files they will be highly compressed with the double benefit to reduce storage and make transmitting them much easier.
Feel free to attach your zip file to the email sent to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Please%20find%20the%20attached%20zip%20archive%20with%20OSIS%20(or%20TEI%20or%20other%20type)%20file%20and%20.conf%20file.%0D%0A%0D%0AVersion%3A%20%3Cyour-module-version%3E%0D%0AChangelog%3A%20(for%20updates%20only)%3CWhat's%20new%3E%0D%0AType%3D%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0AVersification%3D(optional%20for%20Bibles%20and%20Commentaries%2C%20if%20not%20KJV)%0D%0A%0D%0AThanks! modules@crosswire.org]. Actually the biggest file (30MB) we have is 3MB once zipped.

== Link to a zip file ==

If you own a repository on the Internet, you may also store your zipped file on your repository and send the URL to this file instead to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20zip%20archive%20with%20OSIS%20(or%20TEI%20or%20other%20type)%20file%20and%20.conf%20file%3A%20%3Curl%3E%0D%0A%0D%0AVersion%3A%20%3Cyour-module-version%3E%0D%0AChangelog%3A%20(for%20updates%20only)%3CWhat's%20new%3E%0D%0AType%3D%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0AVersification%3D(optional%20for%20Bibles%20and%20Commentaries%2C%20if%20not%20KJV)%0D%0A%0D%0AThanks! modules@crosswire.org].

== Link to a git Repository ==

If you built your module on a public Git/GitLab/GitHub, you may want to share the <code>git clone</code> URL in the email to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20Git%20repository%20of%20the%20module%20containing%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].

We do accept git URL but there are some limitations, though:

* We expect to run into a flat structure, so Module files (source, .conf) shouldn't go in a subdir. Optional files like copyright, style.css should be at the root of your repository as well. Only multimedia files (audio/video/images) should go in their own subdir, typically <code>images</code> for dictionaries.
Example:
<pre>
git
|
+-- module.osis.xml
+-- module.conf
+-- style.css
+-- images/
+-- copyright.pdf
+-- README.md
</pre>
* Try to not put other files in the repository, they are more misleading than handy. Original text URL should be linked in <code>README.md</code>. If you really need to keep the original source text in plain format, USFM ot whatever in a subdir, please add this subdir to .gitignore.
<code>$ echo sources/ >> .gitignore</code>

* No more than 1 module per git repository.

It is sometimes easier to run <code>git archive</code> and attach the resulting zip file to the email.

----
<div style="text-align:center">'''If you do not comply with the above your module submission might end up being deprioritised and will certainly not get uploaded as fast as it could be otherwise'''</div>
----

Please note: Do not edit this page unless you are actually ''directly'' involved with uploading modules onto the server. If you have a comment or addition to make, but you are not part of this particular effort, please use talk page.
[[Category:Modules]]

Module Submission

2021-01-01T13:13:53Z

Domcox: /* Link to a git Repository */ fix typo

----
'''<span style="color: crimson">For information on module licensing''' → please look at [[DevTools:Module Submission and Copyrights]]
----

= How-To Name your module =
Each module needs a name that be used as a unique identifier. Valid characters for the name are limited to alphanumeric characters, numeric characters and underscore. PCRE class [A-Za-z0-9\_].

Normalized names of module contains usually<ref name="Eng">For historical reasons, modules in English do not have any language prefix.</ref> 3 letters for language, followed by a short name descibing the work. Language is encoded in ISO 639-3 code. See [http://www.sil.org/iso639-3/codes.asp] for a list of codes.

The name has to be set in CamelCase format. Example for The French Bible David Martin 1707: <code>FreBDM1707</code><ref name="bdm">The published year was added to differentiate this version from successive revisions in 1744, 1855. Otherwise we could just have named it FreBDM.</ref>

<references />

= How-To name your files =
The source files reflects the name of your module in '''lowercase''' followed by an extension.

For the configuration file, the extension is <code>.conf</code>.

Extensions for the text file are:

* OSIS: <code>.osis.xml</code>

* TEI: <code>.tei.xml</code>

* VPL: <code>.vpl</code>

* IMP: <code>.imp</code>

* ThML: <code>.thml</code>

So, for the <code>FreBDM1707</code> module encoded in OSIS, we have <code>frebdm1707.osis.xml</code> and <code>frebdm1707.conf</code> files.

= How-To prepare your files =

We will accept only plain texts in VPL<ref name="vpl">Only for Bibles in KJV versification</ref> or texts marked up in OSIS or TEI, with the sole exception texts based on CCEL documents that are marked up in ThML.

<references />

== Check your OSIS before submitting ==

OSIS 2.1 is now the preferred format for Bibles, Commentaries and General Books. TEI is the prefered format for dictionaries.

OSIS texts need to have the CamelCase module name as <code>workID</code> and an appropriate <code>osisRefWork</code> entry within the appropriate header section. The document language needs to be set correctly, ISO 639-1 codes are preferred, and ISO 639-3 codes when ISO 639-1 codes do not exist for the given language. Examples:

Bible:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Bible" xml:lang="he">
</pre>

Commentary:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Commentary" xml:lang="gr">
</pre>
General Book:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="GenBook" xml:lang="en">
</pre>

== Please validate your OSIS or TEI text ==
See: Guide to [[Validate_OSIS_or_TEI_text]]

== Check your configuration file ==
We require that the following minimum set of module configuration fields are included: <code>Description</code>, <code>About</code>, <code>DistributionLicense</code>, and <code>TextSource</code>. Ensure that your module complies with our stated copyright policy.

== Copyrighted Material ==
If your got permission to distribute a new module which is under copyright, please send a copy of the authorization in a file named copyright.<extension> like <code>copyright.pdf</code>, <code>copyright.png</code>...

= Submit your files =
Submit only source files. Do not submit built modules that you have imported to Sword format. Avoid spaces in folder and file names.

Send an email to [mailto:modules@crosswire.org modules@crosswire.org] describing the module and your files with one of the options below:

''Note: Pressing one of the following modules@crosswire.org links will open a new mail window already filled with a sample text.''

== Files attached ==

It is highly recommended to zip your files, as they are text files they will be highly compressed with the double benefit to reduce storage and make transmitting them much easier.
Feel free to attach your zip file to the email sent to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Please%20find%20the%20attached%20zip%20archive%20with%20OSIS%20(or%20TEI%20or%20other%20type)%20file%20and%20.conf%20file.%0D%0A%0D%0AVersion%3A%20%3Cyour-module-version%3E%0D%0AChangelog%3A%20(for%20updates%20only)%3CWhat's%20new%3E%0D%0AType%3D%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0AVersification%3D(optional%20for%20Bibles%20and%20Commentaries%2C%20if%20not%20KJV)%0D%0A%0D%0AThanks! modules@crosswire.org]. Actually the biggest file (30MB) we have is 3MB once zipped.

== Link to a zip file ==

If you own a repository on the Internet, you may also store your zipped file on your repository and send the URL to this file instead to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20zip%20archive%20with%20OSIS%20(or%20TEI%20or%20other%20type)%20file%20and%20.conf%20file%3A%20%3Curl%3E%0D%0A%0D%0AVersion%3A%20%3Cyour-module-version%3E%0D%0AChangelog%3A%20(for%20updates%20only)%3CWhat's%20new%3E%0D%0AType%3D%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0AVersification%3D(optional%20for%20Bibles%20and%20Commentaries%2C%20if%20not%20KJV)%0D%0A%0D%0AThanks! modules@crosswire.org].

== Link to a git Repository ==

If you built your module on a public Git/GitLab/GitHub, you may want to share the <code>git clone</code> URL in the email to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20Git%20repository%20of%20the%20module%20containing%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].

We do accept git URL but there are some limitations, though:

* We expect to run into a flat structure, so Module files (source, .conf) shouldn't go in a subdir. Optional files like copyright, style.css should be at the root of your repository as well. Only multimedia files (audio/video/images) should go in their own subdir, typically <code>images</code> for dictionaries.
Example:
<pre>
git
|
+-- module.osis.xml
+-- module.conf
+-- style.css
+-- images/
+-- copyright.pdf
+-- README.md
</pre>
* Try to not put other files in the repository, they are more misleading than handy. Original text URL should be linked in <code>README.md</code>. If you really need to keep the original source text in plain format, USFM ot whatever in a subdir, please add this subdir to .gitignore.
<code>$ echo sources/ >> .gitignore</code>

* No more than 1 module per git repository.

It is sometimes easier to run <code>git archive</code> and attach the resulting zip file to the email.

----
<div style="text-align:center">'''If you do not comply with the above your module submission might end up being deprioritised and will certainly not get uploaded as fast as it could be otherwise'''</div>
----

Please note: Do not edit this page unless you are actually ''directly'' involved with uploading modules onto the server. If you have a comment or addition to make, but you are not part of this particular effort, please use talk page.
[[Category:Modules]]

Module Submission

2021-01-01T13:11:04Z

Domcox: /* Link to a git Repository */ Add information about GIT submission

----
'''<span style="color: crimson">For information on module licensing''' → please look at [[DevTools:Module Submission and Copyrights]]
----

= How-To Name your module =
Each module needs a name that be used as a unique identifier. Valid characters for the name are limited to alphanumeric characters, numeric characters and underscore. PCRE class [A-Za-z0-9\_].

Normalized names of module contains usually<ref name="Eng">For historical reasons, modules in English do not have any language prefix.</ref> 3 letters for language, followed by a short name descibing the work. Language is encoded in ISO 639-3 code. See [http://www.sil.org/iso639-3/codes.asp] for a list of codes.

The name has to be set in CamelCase format. Example for The French Bible David Martin 1707: <code>FreBDM1707</code><ref name="bdm">The published year was added to differentiate this version from successive revisions in 1744, 1855. Otherwise we could just have named it FreBDM.</ref>

<references />

= How-To name your files =
The source files reflects the name of your module in '''lowercase''' followed by an extension.

For the configuration file, the extension is <code>.conf</code>.

Extensions for the text file are:

* OSIS: <code>.osis.xml</code>

* TEI: <code>.tei.xml</code>

* VPL: <code>.vpl</code>

* IMP: <code>.imp</code>

* ThML: <code>.thml</code>

So, for the <code>FreBDM1707</code> module encoded in OSIS, we have <code>frebdm1707.osis.xml</code> and <code>frebdm1707.conf</code> files.

= How-To prepare your files =

We will accept only plain texts in VPL<ref name="vpl">Only for Bibles in KJV versification</ref> or texts marked up in OSIS or TEI, with the sole exception texts based on CCEL documents that are marked up in ThML.

<references />

== Check your OSIS before submitting ==

OSIS 2.1 is now the preferred format for Bibles, Commentaries and General Books. TEI is the prefered format for dictionaries.

OSIS texts need to have the CamelCase module name as <code>workID</code> and an appropriate <code>osisRefWork</code> entry within the appropriate header section. The document language needs to be set correctly, ISO 639-1 codes are preferred, and ISO 639-3 codes when ISO 639-1 codes do not exist for the given language. Examples:

Bible:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Bible" xml:lang="he">
</pre>

Commentary:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Commentary" xml:lang="gr">
</pre>
General Book:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="GenBook" xml:lang="en">
</pre>

== Please validate your OSIS or TEI text ==
See: Guide to [[Validate_OSIS_or_TEI_text]]

== Check your configuration file ==
We require that the following minimum set of module configuration fields are included: <code>Description</code>, <code>About</code>, <code>DistributionLicense</code>, and <code>TextSource</code>. Ensure that your module complies with our stated copyright policy.

== Copyrighted Material ==
If your got permission to distribute a new module which is under copyright, please send a copy of the authorization in a file named copyright.<extension> like <code>copyright.pdf</code>, <code>copyright.png</code>...

= Submit your files =
Submit only source files. Do not submit built modules that you have imported to Sword format. Avoid spaces in folder and file names.

Send an email to [mailto:modules@crosswire.org modules@crosswire.org] describing the module and your files with one of the options below:

''Note: Pressing one of the following modules@crosswire.org links will open a new mail window already filled with a sample text.''

== Files attached ==

It is highly recommended to zip your files, as they are text files they will be highly compressed with the double benefit to reduce storage and make transmitting them much easier.
Feel free to attach your zip file to the email sent to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Please%20find%20the%20attached%20zip%20archive%20with%20OSIS%20(or%20TEI%20or%20other%20type)%20file%20and%20.conf%20file.%0D%0A%0D%0AVersion%3A%20%3Cyour-module-version%3E%0D%0AChangelog%3A%20(for%20updates%20only)%3CWhat's%20new%3E%0D%0AType%3D%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0AVersification%3D(optional%20for%20Bibles%20and%20Commentaries%2C%20if%20not%20KJV)%0D%0A%0D%0AThanks! modules@crosswire.org]. Actually the biggest file (30MB) we have is 3MB once zipped.

== Link to a zip file ==

If you own a repository on the Internet, you may also store your zipped file on your repository and send the URL to this file instead to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20zip%20archive%20with%20OSIS%20(or%20TEI%20or%20other%20type)%20file%20and%20.conf%20file%3A%20%3Curl%3E%0D%0A%0D%0AVersion%3A%20%3Cyour-module-version%3E%0D%0AChangelog%3A%20(for%20updates%20only)%3CWhat's%20new%3E%0D%0AType%3D%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0AVersification%3D(optional%20for%20Bibles%20and%20Commentaries%2C%20if%20not%20KJV)%0D%0A%0D%0AThanks! modules@crosswire.org].

== Link to a git Repository ==

If you built your module on a public Git/GitLab/GitHub, you may want to share the <code>git clone</code> URL in the email to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20Git%20repository%20of%20the%20module%20containing%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].

We do accept git URL but there are some limitations, though:

* We expect to run into a flat structure, so Module files (source, .conf) shouldn't go in a subdir. Optional files like copyright, style.css should be at the root of your repository as well. Only multimedia files (audio/video/images) should go in their own subdir, typically <code>images</code> for dictionaries.
Example:
<pre>
git
|
+-- module.osis.xml
+-- module.conf
+-- style.css
+-- images/
+-- license.pdf
+-- README.md
</pre>
* Try to not put other files in the repository, they are more misleading than handy. Original text URL should be linked in <code>README.md</code>. If you really need to keep the original source text in plain format, USFM ot whatever in a subdir, please add this subdir to .gitignore.
<code>$ echo sources/ >> .gitignore</code>

* No more than 1 module per git repository.

It is sometimes easier to run <code>git archive</code> and attach the resulting zip file to the email.

----
<div style="text-align:center">'''If you do not comply with the above your module submission might end up being deprioritised and will certainly not get uploaded as fast as it could be otherwise'''</div>
----

Please note: Do not edit this page unless you are actually ''directly'' involved with uploading modules onto the server. If you have a comment or addition to make, but you are not part of this particular effort, please use talk page.
[[Category:Modules]]

Module Submission

2020-12-21T17:34:55Z

Domcox: /* How-To name your files */ fix typo

----
'''<span style="color: crimson">For information on module licensing''' → please look at [[DevTools:Module Submission and Copyrights]]
----

= How-To Name your module =
Each module needs a name that be used as a unique identifier. Valid characters for the name are limited to alphanumeric characters, numeric characters and underscore. PCRE class [A-Za-z0-9\_].

Normalized names of module contains usually<ref name="Eng">For historical reasons, modules in English do not have any language prefix.</ref> 3 letters for language, followed by a short name descibing the work. Language is encoded in ISO 639-3 code. See [http://www.sil.org/iso639-3/codes.asp] for a list of codes.

The name has to be set in CamelCase format. Example for The French Bible David Martin 1707: <code>FreBDM1707</code><ref name="bdm">The published year was added to differentiate this version from successive revisions in 1744, 1855. Otherwise we could just have named it FreBDM.</ref>

<references />

= How-To name your files =
The source files reflects the name of your module in '''lowercase''' followed by an extension.

For the configuration file, the extension is <code>.conf</code>.

Extensions for the text file are:

* OSIS: <code>.osis.xml</code>

* TEI: <code>.tei.xml</code>

* VPL: <code>.vpl</code>

* IMP: <code>.imp</code>

* ThML: <code>.thml</code>

So, for the <code>FreBDM1707</code> module encoded in OSIS, we have <code>frebdm1707.osis.xml</code> and <code>frebdm1707.conf</code> files.

= How-To prepare your files =

We will accept only plain texts in VPL<ref name="vpl">Only for Bibles in KJV versification</ref> or texts marked up in OSIS or TEI, with the sole exception texts based on CCEL documents that are marked up in ThML.

<references />

== Check your OSIS before submitting ==

OSIS 2.1 is now the preferred format for Bibles, Commentaries and General Books. TEI is the prefered format for dictionaries.

OSIS texts need to have the CamelCase module name as <code>workID</code> and an appropriate <code>osisRefWork</code> entry within the appropriate header section. The document language needs to be set correctly, ISO 639-1 codes are preferred, and ISO 639-3 codes when ISO 639-1 codes do not exist for the given language. Examples:

Bible:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Bible" xml:lang="he">
</pre>

Commentary:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Commentary" xml:lang="gr">
</pre>
General Book:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="GenBook" xml:lang="en">
</pre>

== Please validate your OSIS or TEI text ==
See: Guide to [[Validate_OSIS_or_TEI_text]]

== Check your configuration file ==
We require that the following minimum set of module configuration fields are included: <code>Description</code>, <code>About</code>, <code>DistributionLicense</code>, and <code>TextSource</code>. Ensure that your module complies with our stated copyright policy.

== Copyrighted Material ==
If your got permission to distribute a new module which is under copyright, please send a copy of the authorization in a file named copyright.<extension> like <code>copyright.pdf</code>, <code>copyright.png</code>...

= Submit your files =
Submit only source files. Do not submit built modules that you have imported to Sword format. Avoid spaces in folder and file names.

Send an email to [mailto:modules@crosswire.org modules@crosswire.org] describing the module and your files with one of the options below:

''Note: Pressing one of the following modules@crosswire.org links will open a new mail window already filled with a sample text.''

== Files attached ==

It is highly recommended to zip your files, as they are text files they will be highly compressed with the double benefit to reduce storage and make transmitting them much easier.
Feel free to attach your zip file to the email sent to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Please%20find%20the%20attached%20zip%20archive%20with%20OSIS%20(or%20TEI%20or%20other%20type)%20file%20and%20.conf%20file.%0D%0A%0D%0AVersion%3A%20%3Cyour-module-version%3E%0D%0AChangelog%3A%20(for%20updates%20only)%3CWhat's%20new%3E%0D%0AType%3D%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0AVersification%3D(optional%20for%20Bibles%20and%20Commentaries%2C%20if%20not%20KJV)%0D%0A%0D%0AThanks! modules@crosswire.org]. Actually the biggest file (30MB) we have is 3MB once zipped.

== Link to a zip file ==

If you own a repository on the Internet, you may also store your zipped file on your repository and send the URL to this file instead to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20zip%20archive%20with%20OSIS%20(or%20TEI%20or%20other%20type)%20file%20and%20.conf%20file%3A%20%3Curl%3E%0D%0A%0D%0AVersion%3A%20%3Cyour-module-version%3E%0D%0AChangelog%3A%20(for%20updates%20only)%3CWhat's%20new%3E%0D%0AType%3D%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0AVersification%3D(optional%20for%20Bibles%20and%20Commentaries%2C%20if%20not%20KJV)%0D%0A%0D%0AThanks! modules@crosswire.org].

== Link to a git Repository ==

If you built your module on a public Git/GitLab/GitHub, you may want to share the <code>git clone</code> URL in the email to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20Git%20repository%20of%20the%20module%2C%20containing%20OSIS%20(or%20TEI%20or%20other%20type)%20file%20and%20.conf%20file%3A%20%3Curl%3E%0D%0A%0D%0AVersion%3A%20%3Cyour-module-version%3E%0D%0AChangelog%3A%20(for%20updates%20only)%3CWhat's%20new%3E%0D%0AType%3D%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0AVersification%3D(optional%20for%20Bibles%20and%20Commentaries%2C%20if%20not%20KJV)%0D%0A%0D%0AThanks! modules@crosswire.org].

We do accept git URL but there are some limitations, though:

* We expect to run into a flat structure, so Module files (source, .conf) shouldn't go in a subdir. Optional files like copyright, style.css should be at the root of your repository as well. Only multimedia files (audio/video/images) should go in their own subdir, typically <code>images</code> for dictionaries.
Example:
<pre>
git
|
+-- module.osis.xml
+-- module.conf
+-- style.css
+-- images/
+-- sources/
</pre>
* If you keep the original source text in plain format, USFM ot whatever in a subdir, please add this subdir to .gitignore as we are not very interested in cloning it.
<code>$ echo sources/ >> .gitignore</code>

* No more than 1 module per git repository.

It is sometimes easier to run <code>git archive</code> and attach the resulting zip file to the email.

----
<div style="text-align:center">'''If you do not comply with the above your module submission might end up being deprioritised and will certainly not get uploaded as fast as it could be otherwise'''</div>
----

Please note: Do not edit this page unless you are actually ''directly'' involved with uploading modules onto the server. If you have a comment or addition to make, but you are not part of this particular effort, please use talk page.
[[Category:Modules]]

Module Submission

2020-12-21T17:34:26Z

Domcox: /* Submit your files */ Avoid spaces

----
'''<span style="color: crimson">For information on module licensing''' → please look at [[DevTools:Module Submission and Copyrights]]
----

= How-To Name your module =
Each module needs a name that be used as a unique identifier. Valid characters for the name are limited to alphanumeric characters, numeric characters and underscore. PCRE class [A-Za-z0-9\_].

Normalized names of module contains usually<ref name="Eng">For historical reasons, modules in English do not have any language prefix.</ref> 3 letters for language, followed by a short name descibing the work. Language is encoded in ISO 639-3 code. See [http://www.sil.org/iso639-3/codes.asp] for a list of codes.

The name has to be set in CamelCase format. Example for The French Bible David Martin 1707: <code>FreBDM1707</code><ref name="bdm">The published year was added to differentiate this version from successive revisions in 1744, 1855. Otherwise we could just have named it FreBDM.</ref>

<references />

= How-To name your files =
The source files reflects the name of your module in '''lowercase''' followed by an extension.

For the configuration file, the extension is <code>.conf</code>.

Extensions for the text file:

* OSIS: <code>.osis.xml</code>

* TEI: <code>.tei.xml</code>

* VPL: <code>.vpl</code>

* IMP: <code>.imp</code>

* ThML: <code>.thml</code>

So, for the <code>FreBDM1707</code> module encoded in OSIS, we have <code>frebdm1707.osis.xml</code> and <code>frebdm1707.conf</code> files.

= How-To prepare your files =

We will accept only plain texts in VPL<ref name="vpl">Only for Bibles in KJV versification</ref> or texts marked up in OSIS or TEI, with the sole exception texts based on CCEL documents that are marked up in ThML.

<references />

== Check your OSIS before submitting ==

OSIS 2.1 is now the preferred format for Bibles, Commentaries and General Books. TEI is the prefered format for dictionaries.

OSIS texts need to have the CamelCase module name as <code>workID</code> and an appropriate <code>osisRefWork</code> entry within the appropriate header section. The document language needs to be set correctly, ISO 639-1 codes are preferred, and ISO 639-3 codes when ISO 639-1 codes do not exist for the given language. Examples:

Bible:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Bible" xml:lang="he">
</pre>

Commentary:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Commentary" xml:lang="gr">
</pre>
General Book:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="GenBook" xml:lang="en">
</pre>

== Please validate your OSIS or TEI text ==
See: Guide to [[Validate_OSIS_or_TEI_text]]

== Check your configuration file ==
We require that the following minimum set of module configuration fields are included: <code>Description</code>, <code>About</code>, <code>DistributionLicense</code>, and <code>TextSource</code>. Ensure that your module complies with our stated copyright policy.

== Copyrighted Material ==
If your got permission to distribute a new module which is under copyright, please send a copy of the authorization in a file named copyright.<extension> like <code>copyright.pdf</code>, <code>copyright.png</code>...

= Submit your files =
Submit only source files. Do not submit built modules that you have imported to Sword format. Avoid spaces in folder and file names.

Send an email to [mailto:modules@crosswire.org modules@crosswire.org] describing the module and your files with one of the options below:

''Note: Pressing one of the following modules@crosswire.org links will open a new mail window already filled with a sample text.''

== Files attached ==

It is highly recommended to zip your files, as they are text files they will be highly compressed with the double benefit to reduce storage and make transmitting them much easier.
Feel free to attach your zip file to the email sent to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Please%20find%20the%20attached%20zip%20archive%20with%20OSIS%20(or%20TEI%20or%20other%20type)%20file%20and%20.conf%20file.%0D%0A%0D%0AVersion%3A%20%3Cyour-module-version%3E%0D%0AChangelog%3A%20(for%20updates%20only)%3CWhat's%20new%3E%0D%0AType%3D%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0AVersification%3D(optional%20for%20Bibles%20and%20Commentaries%2C%20if%20not%20KJV)%0D%0A%0D%0AThanks! modules@crosswire.org]. Actually the biggest file (30MB) we have is 3MB once zipped.

== Link to a zip file ==

If you own a repository on the Internet, you may also store your zipped file on your repository and send the URL to this file instead to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20zip%20archive%20with%20OSIS%20(or%20TEI%20or%20other%20type)%20file%20and%20.conf%20file%3A%20%3Curl%3E%0D%0A%0D%0AVersion%3A%20%3Cyour-module-version%3E%0D%0AChangelog%3A%20(for%20updates%20only)%3CWhat's%20new%3E%0D%0AType%3D%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0AVersification%3D(optional%20for%20Bibles%20and%20Commentaries%2C%20if%20not%20KJV)%0D%0A%0D%0AThanks! modules@crosswire.org].

== Link to a git Repository ==

If you built your module on a public Git/GitLab/GitHub, you may want to share the <code>git clone</code> URL in the email to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20Git%20repository%20of%20the%20module%2C%20containing%20OSIS%20(or%20TEI%20or%20other%20type)%20file%20and%20.conf%20file%3A%20%3Curl%3E%0D%0A%0D%0AVersion%3A%20%3Cyour-module-version%3E%0D%0AChangelog%3A%20(for%20updates%20only)%3CWhat's%20new%3E%0D%0AType%3D%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0AVersification%3D(optional%20for%20Bibles%20and%20Commentaries%2C%20if%20not%20KJV)%0D%0A%0D%0AThanks! modules@crosswire.org].

We do accept git URL but there are some limitations, though:

* We expect to run into a flat structure, so Module files (source, .conf) shouldn't go in a subdir. Optional files like copyright, style.css should be at the root of your repository as well. Only multimedia files (audio/video/images) should go in their own subdir, typically <code>images</code> for dictionaries.
Example:
<pre>
git
|
+-- module.osis.xml
+-- module.conf
+-- style.css
+-- images/
+-- sources/
</pre>
* If you keep the original source text in plain format, USFM ot whatever in a subdir, please add this subdir to .gitignore as we are not very interested in cloning it.
<code>$ echo sources/ >> .gitignore</code>

* No more than 1 module per git repository.

It is sometimes easier to run <code>git archive</code> and attach the resulting zip file to the email.

----
<div style="text-align:center">'''If you do not comply with the above your module submission might end up being deprioritised and will certainly not get uploaded as fast as it could be otherwise'''</div>
----

Please note: Do not edit this page unless you are actually ''directly'' involved with uploading modules onto the server. If you have a comment or addition to make, but you are not part of this particular effort, please use talk page.
[[Category:Modules]]

Module Submission

2020-12-20T19:36:01Z

Domcox: /* Link to a git Repository */ Add module limit per repository

----
'''<span style="color: crimson">For information on module licensing''' → please look at [[DevTools:Module Submission and Copyrights]]
----

= How-To Name your module =
Each module needs a name that be used as a unique identifier. Valid characters for the name are limited to alphanumeric characters, numeric characters and underscore. PCRE class [A-Za-z0-9\_].

Normalized names of module contains usually<ref name="Eng">For historical reasons, modules in English do not have any language prefix.</ref> 3 letters for language, followed by a short name descibing the work. Language is encoded in ISO 639-3 code. See [http://www.sil.org/iso639-3/codes.asp] for a list of codes.

The name has to be set in CamelCase format. Example for The French Bible David Martin 1707: <code>FreBDM1707</code><ref name="bdm">The published year was added to differentiate this version from successive revisions in 1744, 1855. Otherwise we could just have named it FreBDM.</ref>

<references />

= How-To name your files =
The source files reflects the name of your module in '''lowercase''' followed by an extension.

For the configuration file, the extension is <code>.conf</code>.

Extensions for the text file:

* OSIS: <code>.osis.xml</code>

* TEI: <code>.tei.xml</code>

* VPL: <code>.vpl</code>

* IMP: <code>.imp</code>

* ThML: <code>.thml</code>

So, for the <code>FreBDM1707</code> module encoded in OSIS, we have <code>frebdm1707.osis.xml</code> and <code>frebdm1707.conf</code> files.

= How-To prepare your files =

We will accept only plain texts in VPL<ref name="vpl">Only for Bibles in KJV versification</ref> or texts marked up in OSIS or TEI, with the sole exception texts based on CCEL documents that are marked up in ThML.

<references />

== Check your OSIS before submitting ==

OSIS 2.1 is now the preferred format for Bibles, Commentaries and General Books. TEI is the prefered format for dictionaries.

OSIS texts need to have the CamelCase module name as <code>workID</code> and an appropriate <code>osisRefWork</code> entry within the appropriate header section. The document language needs to be set correctly, ISO 639-1 codes are preferred, and ISO 639-3 codes when ISO 639-1 codes do not exist for the given language. Examples:

Bible:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Bible" xml:lang="he">
</pre>

Commentary:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Commentary" xml:lang="gr">
</pre>
General Book:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="GenBook" xml:lang="en">
</pre>

== Please validate your OSIS or TEI text ==
See: Guide to [[Validate_OSIS_or_TEI_text]]

== Check your configuration file ==
We require that the following minimum set of module configuration fields are included: <code>Description</code>, <code>About</code>, <code>DistributionLicense</code>, and <code>TextSource</code>. Ensure that your module complies with our stated copyright policy.

== Copyrighted Material ==
If your got permission to distribute a new module which is under copyright, please send a copy of the authorization in a file named copyright.<extension> like <code>copyright.pdf</code>, <code>copyright.png</code>...

= Submit your files =
Submit only source files. Do not submit built modules that you have imported to Sword format.

Send an email to [mailto:modules@crosswire.org modules@crosswire.org] describing the module and your files with one of the options below:

''Note: Pressing one of the following modules@crosswire.org links will open a new mail window already filled with a sample text.''

== Files attached ==

It is highly recommended to zip your files, as they are text files they will be highly compressed with the double benefit to reduce storage and make transmitting them much easier.
Feel free to attach your zip file to the email sent to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Please%20find%20the%20attached%20zip%20archive%20with%20OSIS%20(or%20TEI%20or%20other%20type)%20file%20and%20.conf%20file.%0D%0A%0D%0AVersion%3A%20%3Cyour-module-version%3E%0D%0AChangelog%3A%20(for%20updates%20only)%3CWhat's%20new%3E%0D%0AType%3D%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0AVersification%3D(optional%20for%20Bibles%20and%20Commentaries%2C%20if%20not%20KJV)%0D%0A%0D%0AThanks! modules@crosswire.org]. Actually the biggest file (30MB) we have is 3MB once zipped.

== Link to a zip file ==

If you own a repository on the Internet, you may also store your zipped file on your repository and send the URL to this file instead to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20zip%20archive%20with%20OSIS%20(or%20TEI%20or%20other%20type)%20file%20and%20.conf%20file%3A%20%3Curl%3E%0D%0A%0D%0AVersion%3A%20%3Cyour-module-version%3E%0D%0AChangelog%3A%20(for%20updates%20only)%3CWhat's%20new%3E%0D%0AType%3D%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0AVersification%3D(optional%20for%20Bibles%20and%20Commentaries%2C%20if%20not%20KJV)%0D%0A%0D%0AThanks! modules@crosswire.org].

== Link to a git Repository ==

If you built your module on a public Git/GitLab/GitHub, you may want to share the <code>git clone</code> URL in the email to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20Git%20repository%20of%20the%20module%2C%20containing%20OSIS%20(or%20TEI%20or%20other%20type)%20file%20and%20.conf%20file%3A%20%3Curl%3E%0D%0A%0D%0AVersion%3A%20%3Cyour-module-version%3E%0D%0AChangelog%3A%20(for%20updates%20only)%3CWhat's%20new%3E%0D%0AType%3D%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0AVersification%3D(optional%20for%20Bibles%20and%20Commentaries%2C%20if%20not%20KJV)%0D%0A%0D%0AThanks! modules@crosswire.org].

We do accept git URL but there are some limitations, though:

* We expect to run into a flat structure, so Module files (source, .conf) shouldn't go in a subdir. Optional files like copyright, style.css should be at the root of your repository as well. Only multimedia files (audio/video/images) should go in their own subdir, typically <code>images</code> for dictionaries.
Example:
<pre>
git
|
+-- module.osis.xml
+-- module.conf
+-- style.css
+-- images/
+-- sources/
</pre>
* If you keep the original source text in plain format, USFM ot whatever in a subdir, please add this subdir to .gitignore as we are not very interested in cloning it.
<code>$ echo sources/ >> .gitignore</code>

* No more than 1 module per git repository.

It is sometimes easier to run <code>git archive</code> and attach the resulting zip file to the email.

----
<div style="text-align:center">'''If you do not comply with the above your module submission might end up being deprioritised and will certainly not get uploaded as fast as it could be otherwise'''</div>
----

Please note: Do not edit this page unless you are actually ''directly'' involved with uploading modules onto the server. If you have a comment or addition to make, but you are not part of this particular effort, please use talk page.
[[Category:Modules]]

Module Submission

2020-12-20T17:25:22Z

Domcox: /* Link to a git Repository */ Add examples

----
'''<span style="color: crimson">For information on module licensing''' → please look at [[DevTools:Module Submission and Copyrights]]
----

= How-To Name your module =
Each module needs a name that be used as a unique identifier. Valid characters for the name are limited to alphanumeric characters, numeric characters and underscore. PCRE class [A-Za-z0-9\_].

Normalized names of module contains usually<ref name="Eng">For historical reasons, modules in English do not have any language prefix.</ref> 3 letters for language, followed by a short name descibing the work. Language is encoded in ISO 639-3 code. See [http://www.sil.org/iso639-3/codes.asp] for a list of codes.

The name has to be set in CamelCase format. Example for The French Bible David Martin 1707: <code>FreBDM1707</code><ref name="bdm">The published year was added to differentiate this version from successive revisions in 1744, 1855. Otherwise we could just have named it FreBDM.</ref>

<references />

= How-To name your files =
The source files reflects the name of your module in '''lowercase''' followed by an extension.

For the configuration file, the extension is <code>.conf</code>.

Extensions for the text file:

* OSIS: <code>.osis.xml</code>

* TEI: <code>.tei.xml</code>

* VPL: <code>.vpl</code>

* IMP: <code>.imp</code>

* ThML: <code>.thml</code>

So, for the <code>FreBDM1707</code> module encoded in OSIS, we have <code>frebdm1707.osis.xml</code> and <code>frebdm1707.conf</code> files.

= How-To prepare your files =

We will accept only plain texts in VPL<ref name="vpl">Only for Bibles in KJV versification</ref> or texts marked up in OSIS or TEI, with the sole exception texts based on CCEL documents that are marked up in ThML.

<references />

== Check your OSIS before submitting ==

OSIS 2.1 is now the preferred format for Bibles, Commentaries and General Books. TEI is the prefered format for dictionaries.

OSIS texts need to have the CamelCase module name as <code>workID</code> and an appropriate <code>osisRefWork</code> entry within the appropriate header section. The document language needs to be set correctly, ISO 639-1 codes are preferred, and ISO 639-3 codes when ISO 639-1 codes do not exist for the given language. Examples:

Bible:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Bible" xml:lang="he">
</pre>

Commentary:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Commentary" xml:lang="gr">
</pre>
General Book:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="GenBook" xml:lang="en">
</pre>

== Please validate your OSIS or TEI text ==
See: Guide to [[Validate_OSIS_or_TEI_text]]

== Check your configuration file ==
We require that the following minimum set of module configuration fields are included: <code>Description</code>, <code>About</code>, <code>DistributionLicense</code>, and <code>TextSource</code>. Ensure that your module complies with our stated copyright policy.

== Copyrighted Material ==
If your got permission to distribute a new module which is under copyright, please send a copy of the authorization in a file named copyright.<extension> like <code>copyright.pdf</code>, <code>copyright.png</code>...

= Submit your files =
Submit only source files. Do not submit built modules that you have imported to Sword format.

Send an email to [mailto:modules@crosswire.org modules@crosswire.org] describing the module and your files with one of the options below:

''Note: Pressing one of the following modules@crosswire.org links will open a new mail window already filled with a sample text.''

== Files attached ==

It is highly recommended to zip your files, as they are text files they will be highly compressed with the double benefit to reduce storage and make transmitting them much easier.
Feel free to attach your zip file to the email sent to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Please%20find%20the%20attached%20zip%20archive%20with%20OSIS%20(or%20TEI%20or%20other%20type)%20file%20and%20.conf%20file.%0D%0A%0D%0AVersion%3A%20%3Cyour-module-version%3E%0D%0AChangelog%3A%20(for%20updates%20only)%3CWhat's%20new%3E%0D%0AType%3D%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0AVersification%3D(optional%20for%20Bibles%20and%20Commentaries%2C%20if%20not%20KJV)%0D%0A%0D%0AThanks! modules@crosswire.org]. Actually the biggest file (30MB) we have is 3MB once zipped.

== Link to a zip file ==

If you own a repository on the Internet, you may also store your zipped file on your repository and send the URL to this file instead to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20zip%20archive%20with%20OSIS%20(or%20TEI%20or%20other%20type)%20file%20and%20.conf%20file%3A%20%3Curl%3E%0D%0A%0D%0AVersion%3A%20%3Cyour-module-version%3E%0D%0AChangelog%3A%20(for%20updates%20only)%3CWhat's%20new%3E%0D%0AType%3D%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0AVersification%3D(optional%20for%20Bibles%20and%20Commentaries%2C%20if%20not%20KJV)%0D%0A%0D%0AThanks! modules@crosswire.org].

== Link to a git Repository ==

If you built your module on a public Git/GitLab/GitHub, you may want to share the <code>git clone</code> URL in the email to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20Git%20repository%20of%20the%20module%2C%20containing%20OSIS%20(or%20TEI%20or%20other%20type)%20file%20and%20.conf%20file%3A%20%3Curl%3E%0D%0A%0D%0AVersion%3A%20%3Cyour-module-version%3E%0D%0AChangelog%3A%20(for%20updates%20only)%3CWhat's%20new%3E%0D%0AType%3D%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0AVersification%3D(optional%20for%20Bibles%20and%20Commentaries%2C%20if%20not%20KJV)%0D%0A%0D%0AThanks! modules@crosswire.org].

We do accept git URL but there are some limitations, though:

* We expect to run into a flat structure, so Module files (source, .conf) shouldn't go in a subdir. Optional files like copyright, style.css should be at the root of your repository as well. Only multimedia files (audio/video/images) should go in their own subdir, typically <code>images</code> for dictionaries.
Example:
<pre>
git
|
+-- module.osis.xml
+-- module.conf
+-- style.css
+-- images/
+-- sources/
</pre>
* If you keep the original source text in plain format, USFM ot whatever in a subdir, please add this subdir to .gitignore as we are not very interested in cloning it.
<code>$ echo sources/ >> .gitignore</code>

It is sometimes easier to run <code>git archive</code> and attach the resulting zip file to the email.

----
<div style="text-align:center">'''If you do not comply with the above your module submission might end up being deprioritised and will certainly not get uploaded as fast as it could be otherwise'''</div>
----

Please note: Do not edit this page unless you are actually ''directly'' involved with uploading modules onto the server. If you have a comment or addition to make, but you are not part of this particular effort, please use talk page.
[[Category:Modules]]

Module Submission

2020-12-19T19:25:46Z

Domcox: /* Submit your files */ Add mail samples

----
'''<span style="color: crimson">For information on module licensing''' → please look at [[DevTools:Module Submission and Copyrights]]
----

= How-To Name your module =
Each module needs a name that be used as a unique identifier. Valid characters for the name are limited to alphanumeric characters, numeric characters and underscore. PCRE class [A-Za-z0-9\_].

Normalized names of module contains usually<ref name="Eng">For historical reasons, modules in English do not have any language prefix.</ref> 3 letters for language, followed by a short name descibing the work. Language is encoded in ISO 639-3 code. See [http://www.sil.org/iso639-3/codes.asp] for a list of codes.

The name has to be set in CamelCase format. Example for The French Bible David Martin 1707: <code>FreBDM1707</code><ref name="bdm">The published year was added to differentiate this version from successive revisions in 1744, 1855. Otherwise we could just have named it FreBDM.</ref>

<references />

= How-To name your files =
The source files reflects the name of your module in '''lowercase''' followed by an extension.

For the configuration file, the extension is <code>.conf</code>.

Extensions for the text file:

* OSIS: <code>.osis.xml</code>

* TEI: <code>.tei.xml</code>

* VPL: <code>.vpl</code>

* IMP: <code>.imp</code>

* ThML: <code>.thml</code>

So, for the <code>FreBDM1707</code> module encoded in OSIS, we have <code>frebdm1707.osis.xml</code> and <code>frebdm1707.conf</code> files.

= How-To prepare your files =

We will accept only plain texts in VPL<ref name="vpl">Only for Bibles in KJV versification</ref> or texts marked up in OSIS or TEI, with the sole exception texts based on CCEL documents that are marked up in ThML.

<references />

== Check your OSIS before submitting ==

OSIS 2.1 is now the preferred format for Bibles, Commentaries and General Books. TEI is the prefered format for dictionaries.

OSIS texts need to have the CamelCase module name as <code>workID</code> and an appropriate <code>osisRefWork</code> entry within the appropriate header section. The document language needs to be set correctly, ISO 639-1 codes are preferred, and ISO 639-3 codes when ISO 639-1 codes do not exist for the given language. Examples:

Bible:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Bible" xml:lang="he">
</pre>

Commentary:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="Commentary" xml:lang="gr">
</pre>
General Book:
<pre>
<osisText osisIDWork="MyModule" osisRefWork="GenBook" xml:lang="en">
</pre>

== Please validate your OSIS or TEI text ==
See: Guide to [[Validate_OSIS_or_TEI_text]]

== Check your configuration file ==
We require that the following minimum set of module configuration fields are included: <code>Description</code>, <code>About</code>, <code>DistributionLicense</code>, and <code>TextSource</code>. Ensure that your module complies with our stated copyright policy.

== Copyrighted Material ==
If your got permission to distribute a new module which is under copyright, please send a copy of the authorization in a file named copyright.<extension> like <code>copyright.pdf</code>, <code>copyright.png</code>...

= Submit your files =
Submit only source files. Do not submit built modules that you have imported to Sword format.

Send an email to [mailto:modules@crosswire.org modules@crosswire.org] describing the module and your files with one of the options below:

''Note: Pressing one of the following modules@crosswire.org links will open a new mail window already filled with a sample text.''

== Files attached ==

It is highly recommended to zip your files, as they are text files they will be highly compressed with the double benefit to reduce storage and make transmitting them much easier.
Feel free to attach your zip file to the email sent to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Please%20find%20the%20attached%20zip%20archive%20with%20OSIS%20(or%20TEI%20or%20other%20type)%20file%20and%20.conf%20file.%0D%0A%0D%0AVersion%3A%20%3Cyour-module-version%3E%0D%0AChangelog%3A%20(for%20updates%20only)%3CWhat's%20new%3E%0D%0AType%3D%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0AVersification%3D(optional%20for%20Bibles%20and%20Commentaries%2C%20if%20not%20KJV)%0D%0A%0D%0AThanks! modules@crosswire.org]. Actually the biggest file (30MB) we have is 3MB once zipped.

== Link to a zip file ==

If you own a repository on the Internet, you may also store your zipped file on your repository and send the URL to this file instead to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20zip%20archive%20with%20OSIS%20(or%20TEI%20or%20other%20type)%20file%20and%20.conf%20file%3A%20%3Curl%3E%0D%0A%0D%0AVersion%3A%20%3Cyour-module-version%3E%0D%0AChangelog%3A%20(for%20updates%20only)%3CWhat's%20new%3E%0D%0AType%3D%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0AVersification%3D(optional%20for%20Bibles%20and%20Commentaries%2C%20if%20not%20KJV)%0D%0A%0D%0AThanks! modules@crosswire.org].

== Link to a git Repository ==

If you built your module on a public Git/GitLab/GitHub, you may want to share the <code>git clone</code> URL in the email to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20Git%20repository%20of%20the%20module%2C%20containing%20OSIS%20(or%20TEI%20or%20other%20type)%20file%20and%20.conf%20file%3A%20%3Curl%3E%0D%0A%0D%0AVersion%3A%20%3Cyour-module-version%3E%0D%0AChangelog%3A%20(for%20updates%20only)%3CWhat's%20new%3E%0D%0AType%3D%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0AVersification%3D(optional%20for%20Bibles%20and%20Commentaries%2C%20if%20not%20KJV)%0D%0A%0D%0AThanks! modules@crosswire.org].

We do accept git URL but there are some limitations, though:

* We expect to run into a flat structure, so Module files (source, .conf) shouldn't go in a subdir. Optional files like copyright, style.css should be at the root of your repository as well. Only multimedia files (audio/video/images) should go in their own subdir, typically <code>images</code> for dictionaries.
* If you keep the original source text in plain format, USFM ot whatever in a subdir, please add this subdir to .gitignore as we are not very interested in cloning it.

It is sometimes easier to run <code>git archive</code> and attach the resulting zip file to the email.

----
<div style="text-align:center">'''If you do not comply with the above your module submission might end up being deprioritised and will certainly not get uploaded as fast as it could be otherwise'''</div>
----

Please note: Do not edit this page unless you are actually ''directly'' involved with uploading modules onto the server. If you have a comment or addition to make, but you are not part of this particular effort, please use talk page.
[[Category:Modules]]

OSIS Genbooks

2020-12-19T10:21:32Z

Domcox: Change osisRefWork="book" to osisRefWork="GenBook"

=Introduction=
Much of what follows applies to any OSIS file, but there are a few features unique to genbooks (mainly in structure). This document aims to provide a complete, though not exhaustive, account of how to encode an OSIS genbook to become a SWORD module.

Keep in mind that, as with any XML document, elements are arranged hierarchically. The root node ends with the </osis> element, so the rest of the document occurs within that container. Within that is the Work node. Within that is the Header and then the Body of the text, which are parallel to each other. For a complete OSIS XML file, see Example OSIS Genbook below.

=Root Node=
The root node for a Genbook is the same as any other OSIS document.

<pre><?xml version="1.0" encoding="UTF-8"?>

<osis xsi:schemaLocation="http://www.bibletechnologies.net/2003/OSIS/namespace
http://www.bibletechnologies.net/osisCore.2.1.1.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://www.bibletechnologies.net/2003/OSIS/namespace">

</osis>
</pre>

=Work Container=

The Work container for a Genbook is the same as any other OSIS document except the reference system (osisRefWork) is simply "GenBook".

<pre>
<osisText osisRefWork="GenBook" xml:lang="en" osisIDWork="WorkID">

</osisText>
</pre>

=Header=
The Header should contain work elements for the current work and any other works to which this document links. In this example, the Bible is linked through Scripture references, and the KJV default reference scheme is used. More detailed information can be added, but the following is sufficient for a simple book with one author.

<pre>
<header>

<work osisWork="WorkID">
<title>OSISGenbook</title>
<creator role="aut">Author's Name</creator>
</work>

<work osisWork="Bible">
<refSystem>Bible</refSystem>
</work>

</header>
</pre>

=Body=
==Basic Structure==
A <body> element is not used in OSIS. Instead, the body consists of <nowiki><div></nowiki> elements in a hierarchical structure. If you are encoding a collection of works by the same author, you can use the element <nowiki><div type="bookGroup"></nowiki> for the outer container. Otherwise start with <nowiki><div type="book"></nowiki>. The following represents several levels of containers.

<pre>
<div type="book" osisID="Book">
<div type="majorSection" osisID="majorSection 1">
<div type="chapter" osisID="Chapter 1">
<div type="section">
<div type="subSection">
</div>
</div>
</div>
</div>
</div>
</pre>

Of course you decide what is in the osisID (within the bounds of what the schema allows--basically you should stick to letters, numbers, and spaces), and the <title> element can be used to create titles for each chapter, etc. You may define your hierarchy to as much detail as you like. However, remember that readers of SWORD genbooks can only read one container at a time, so if you define lots of subsections it forces the reader to flip through them. If those parts are short, consider just adding section titles and limiting your containers to chapters for ease of reading.

==Basic Formatting==
===Titles===
Titles are defined using the <title> element:
<pre><title>Title Name</title></pre>
===Paragraphs===
Paragraphs are defined using the <nowiki><p></nowiki> element.
<pre><p>Your paragraph goes here.</p></pre>
===Italic Text===
For italics, use the <nowiki><hi type="italic"></nowiki> element.
<pre><hi type="italic">Italic text</hi></pre>
===Bold Text===
To make text display in bold type, use the <nowiki><hi type="bold"></nowiki> element.
<pre><hi type="bold">Bold text</hi></pre>
===Superscript and Subscript===
To make text superscript and subscript, just use the <nowiki><hi></nowiki> element with the type defined as "super" for superscript text and "sub" for subscript text.
<pre><hi type="super">Superscript text</hi>

<hi type="sub">Subscript text</hi></pre>

==Footnotes and Endnotes==
Footnotes and endnotes are encoded in the same way except for their type name. Both use the <nowiki><note></nowiki> element. Using the "n" attribute you can define the number, letter, or symbol which you want to appear for the note, but not all front-ends will display that.
<pre><note type="x-footnote" n="1">Footnote text</note>

<note type="x-endnote" n="i">Endnote text</note></pre>

==Scripture References and Other Links==
===Scripture References===
Scripture references may be encoded as links which some front-ends will use to open that reference in a Bible window. This is done using the <nowiki><reference></nowiki> element with the attribute "osisRef" defining the target verse or passage. Note the variety of possibilities for these kinds of references below.
<pre>
<reference osisRef="Gen.1.1">Genesis 1:1</reference>
<reference osisRef="Ps.119">Psalm 119</reference>
<reference osisRef="Prov.1-Prov.9">Proverbs 1-9</reference>
<reference osisRef="2Cor.6.14-2Cor.7.1">
</pre>
Bible book names are those abbreviations found in the OSIS manual (they basically follow the SBL abbreviations), and each portion of the reference is separated by a period. In a range of verses the book and chapter must be repeated and separated by a dash.
===Internal Links===
Links from an OSIS module to a non-verse-keyed OSIS module should use an '''osisRef''' of the format<ref>Currently this syntax works but does not validate to '''osisCore.2.1.1.xsd'''</ref>:

Module:Div1/Div2/Div3

Hence, if the module '''EarlyFathers''' were OSIS<ref>It's actually ThML. Install from the Xiphos repository.</ref>, the introduction page may look like:

<pre>
<div type="section" osisID="Introduction">
<title>The Early Church Fathers Series</title>
<p>
This module is a massive 37-volume compendium of writings of the early church fathers including
<reference osisRef="EarlyFathers:ANF01/Ignatius">Ignatius</reference>,
<reference osisRef="EarlyFathers:ANF01/Justin_Martyr">Justin Martyr</reference>,
<reference osisRef="EarlyFathers:ANF01/Irenæus">Irenaeus</reference>, and
<reference osisRef="EarlyFathers:TOC">many others</reference>.
</p>
</div>
</pre>
'''Note:'''
<references />

===External Links===
Links from one OSIS genbook to another OSIS genbook uses the same syntax as the internal links, above.

==Images==
You can easily place images in your books using the <figure/> element. This element is "milestoned," meaning it isn't a container. The forward slash near the end signals that fact. Use the "src" attribute to define the location of the image relative to the compiled module. In the example below, the image "crosswire.jpg" resides in a folder "images" in the same folder as the compiled module.
<pre><figure src="images/crosswire.jpg"/></pre>

==Tables==
Tables require a bit of work to get set up but can be useful for some purposes. The entire table is contained in a <table> element, and each row is then contained in a <row> element. For each column in each row a <cell> element contains the text of that cell. The following table creates column labels in bold type and includes two columns and two rows below the label row.
<pre><table>
<row>
<cell><hi type="bold">Column 1 Label</hi></cell>
<cell><hi type="bold">Column 2 Label</hi></cell>
</row>
<row>
<cell>Column 1, Row 1</cell>
<cell>Column 2, Row 1</cell>
</row>
<row>
<cell>Column 1, Row 2</cell>
<cell>Column 2, Row 2</cell>
</row>
</table></pre>
==Foreign Languages==
Sometimes you may have multiple languages in a work, and in that case you should use the <nowiki><foreign></nowiki> element. That way if you have different fonts defined for different languages you are able to make the display more appropriate for the reader. A Hebrew example looks like this:
<pre><foreign xml:lang="he">עִבְרִי</foreign>
</pre>
You have to define the language of the language that is foreign to the module's language using the "xml:lang" attribute.
=Example OSIS Genbook=
The following is the text of a valid OSIS XML file which serves as a template for an OSIS Genbook for SWORD. Not all possible features are demonstrated here, but the file serves as an example of how to encode a Genbook. You should be able to copy the contents to a text editor, save it to a file as *.xml, and validate it against the OSIS schema.

<pre><?xml version="1.0" encoding="UTF-8"?>

<osis xsi:schemaLocation="http://www.bibletechnologies.net/2003/OSIS/namespace
http://www.bibletechnologies.net/osisCore.2.1.1.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://www.bibletechnologies.net/2003/OSIS/namespace">

<osisText osisRefWork="GenBook" xml:lang="en" osisIDWork="WorkID">
<header>
<work osisWork="WorkID">
<title>OSISGenbook</title>
<creator role="aut">Author's Name</creator>
</work>
<work osisWork="Bible">
<refSystem>Bible</refSystem>
</work>
</header>

<div type="book" osisID="Book Title">
<title>Book Title</title>
<title type="x-author">Author's Name</title>
<p>Copyright</p>

<p>
<figure src="images/crosswire.jpg"/>
</p>

<div type="chapter" osisID="Chapter 1">
<p>This is Chapter 1, the introduction.
<reference osisRef="Gen.1.1">Genesis 1:1</reference> is the first verse in the Bible.
<reference osisRef="Rev.22.21">Rev 22:21</reference> is the last verse in the Bible.
<reference osisRef="Ps.119">Psalm 119</reference> is the longest chapter in the Bible.
<reference osisRef="Prov.1-Prov.9">Proverbs 1-9</reference> introduce the book of Proverbs.
<reference osisRef="John.1-John.1.18">John 1:1-18</reference> introduces the book of John.
<reference osisRef="2Cor.6.14-2Cor.7.1">2 Corinthians 6:14-7:1</reference> teaches about holiness.
</p>

<div type="section">
<title>Section 1</title>
<p>This is chapter 1, section 1.</p>
<table>
<row>
<cell>
<hi type="bold">Column 1 Label</hi>
</cell>
<cell>
<hi type="bold">Column 2 Label</hi>
</cell>
</row>
<row>
<cell>Column 1, Row 1</cell>
<cell>Column 2, Row 1</cell>
</row>
<row>
<cell>Column 1, Row 2</cell>
<cell>Column 2, Row 2</cell>
</row>
</table>
</div>

<div type="section">
<title>Section 2</title>
<p>This is chapter 1, section 2.<note type="x-footnote" n="1">Footnote</note>
</p>
</div>
</div>

<div type="chapter" osisID="Chapter 2">
<p>This is Chapter 2, the introduction.<note type="x-endnote" n="i">Endnote</note>
</p>

<div type="section">
<title>Section 1</title>
<p>This is chapter 2, section 1.</p>
</div>

<div type="section">
<title>Section 2</title>
<p>This is chapter 2, section 2.</p>
<p>Default <hi type="italic">Italics</hi>
</p>
<p>Default <hi type="bold">Bold</hi>
</p>
<p>Default<hi type="super">SuperScript</hi>
</p>
<p>Default<hi type="sub">Subscript</hi>
</p>
<p>This is Hebrew: <foreign xml:lang="he">עִבְרִי</foreign>.</p>
</div>
</div>

</div>
</osisText>
</osis>
</pre>

= Making a Genbook module =
'''xml2gbs''' (currently version 1.0) is the OSIS/ThML/TEI General Book module creation tool<ref>Use under Linux. The Windows edition has an undiagnosed bug that is not likely to be fixed soon.</ref> for the SWORD Project.
usage:
xml2gbs [-l] [-i] [-fT|-fO|-fE] <filename> [modname]
-l uses long div names in ThML files
-i exports to IMP format instead of creating a module
-fO, -fT, and -fE will set the importer to expect OSIS, ThML, or TEI format respectively
(otherwise it attempts to autodetect)
'''Note:'''
<references />

[[Category:Guides|OSIS Genbooks]]
[[Category:OSIS]]
[[Category:Genbook]]

OSIS Commentaries

2020-12-19T09:51:22Z

Domcox: /* Introduction */ Add general structure

== Introduction ==
In SWORD a commentary is structured just like a Bible. The difference is that instead of verse text the commentary has discussion about verse text.

==General structure==

To produce an OSIS Commentary, you can use this template:

<pre>
<?xml version="1.0" encoding="UTF-8"?>
<osis
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://www.bibletechnologies.net/2003/OSIS/namespace"
xmlns:osis="http://www.bibletechnologies.net/2003/OSIS/namespace"
xsi:schemaLocation="http://www.bibletechnologies.net/2003/OSIS/namespace http://www.bibletechnologies.net/osisCore.2.1.1.xsd">
<osisText osisIDWork="{NAME}" osisRefWork="Commentary" xml:lang="{LANG}" canonical="true">
<header>
{HEADER}
</header>
<div type="bookGroup">
{BODY}
</div>
</osisText>
</osis>
</pre>

== Markup ==
An OSIS Commentary differs from an OSIS Bible in that an [[OSIS Bibles]] use:
<pre>
<verse osisID="Gen.1.1">Blah blah...</verse>
</pre>

But the fundamental mechanism of markup for an OSIS commentary replaces that with:
<pre>
<div type="section" annotateType="commentary" annotateRef="Gen.1.1"><p>Blah blah...</p></div>
</pre>

A couple of things to note:

'''type'''<br/>This attribute can have any valid value or even be absent. osis2mod will not use this value.

'''annotateType'''<br/>This attribute must have the value ''commentary'' and will be used to know that we are processing an entry for a commentary.

'''annotateRef'''<br/>This attribute can contain any valid osisRef, but the references must not have a work prefix, such as 'Bible:'. The default for all references and the only ones that SWORD supports at this time are Bible references. We'll tackle work prefixes at a later date.

A single reference uses single "osisID":
annotateRef="Gen.1.1"

A range will be of the form, "osisID-osisID":
annotateRef="Gen.1.1-Gen.2.3"
where the first and the second reference are complete osisIDs and they are separated by a - (and no spaces). And the first reference must precede the second.

Discontinuous references are to be separated by whitespace, "osisRef osisRef". For example:
annotateRef="Gen.1.1 Gen1.5"

== Importing ==
[[osis2mod]] (>= 1.5.11) is used for both Bibles and Commentaries. See [[osis2mod]] for details.

== Config file ==
It's very important that all the necessary properties are included in the .conf file, otherwise the commentary module may not behave as required.<br>
e.g. The module being made from OSIS source text, this property should be specified:
SourceType=OSIS
Otherwise, it would default to Plaintext. For further details, please refer to [[DevTools:conf Files]].

[[Category:Guides|OSIS Commentaries]]

[[Category:OSIS]]

OSIS Commentaries

2020-12-19T09:48:28Z

Domcox: /* Markup */ back

== Introduction ==
In SWORD a commentary is structured just like a Bible. The difference is that instead of verse text the commentary has discussion about verse text.

== Markup ==
An OSIS Commentary differs from an OSIS Bible in that an [[OSIS Bibles]] use:
<pre>
<verse osisID="Gen.1.1">Blah blah...</verse>
</pre>

But the fundamental mechanism of markup for an OSIS commentary replaces that with:
<pre>
<div type="section" annotateType="commentary" annotateRef="Gen.1.1"><p>Blah blah...</p></div>
</pre>

A couple of things to note:

'''type'''<br/>This attribute can have any valid value or even be absent. osis2mod will not use this value.

'''annotateType'''<br/>This attribute must have the value ''commentary'' and will be used to know that we are processing an entry for a commentary.

'''annotateRef'''<br/>This attribute can contain any valid osisRef, but the references must not have a work prefix, such as 'Bible:'. The default for all references and the only ones that SWORD supports at this time are Bible references. We'll tackle work prefixes at a later date.

A single reference uses single "osisID":
annotateRef="Gen.1.1"

A range will be of the form, "osisID-osisID":
annotateRef="Gen.1.1-Gen.2.3"
where the first and the second reference are complete osisIDs and they are separated by a - (and no spaces). And the first reference must precede the second.

Discontinuous references are to be separated by whitespace, "osisRef osisRef". For example:
annotateRef="Gen.1.1 Gen1.5"

== Importing ==
[[osis2mod]] (>= 1.5.11) is used for both Bibles and Commentaries. See [[osis2mod]] for details.

== Config file ==
It's very important that all the necessary properties are included in the .conf file, otherwise the commentary module may not behave as required.<br>
e.g. The module being made from OSIS source text, this property should be specified:
SourceType=OSIS
Otherwise, it would default to Plaintext. For further details, please refer to [[DevTools:conf Files]].

[[Category:Guides|OSIS Commentaries]]

[[Category:OSIS]]

OSIS Commentaries

2020-12-19T09:47:39Z

Domcox: /* Markup */ typo

== Introduction ==
In SWORD a commentary is structured just like a Bible. The difference is that instead of verse text the commentary has discussion about verse text.

== Markup ==
An OSIS Commentary differs from an OSIS Bible in that an [[OSIS Bibles]] use:
<pre>
<verse osisID="Gen.1.1">Blah blah...</verse>
</pre>

But the fundamental mechanism of markup for an OSIS commentary replaces that with:
<pre>
<div type="section" annotateType="commentary" annotateRef="Gen.1.1"><p>Blah blah...</p></div>
</pre>

A couple of things to note:

'''type'''<br/>This attribute can have any valid value or even be absent. osis2mod will not use this value.

'''annotateType'''<br/>This attribute must have the value ''Commentary'' and will be used to know that we are processing an entry for a commentary.

'''annotateRef'''<br/>This attribute can contain any valid osisRef, but the references must not have a work prefix, such as 'Bible:'. The default for all references and the only ones that SWORD supports at this time are Bible references. We'll tackle work prefixes at a later date.

A single reference uses single "osisID":
annotateRef="Gen.1.1"

A range will be of the form, "osisID-osisID":
annotateRef="Gen.1.1-Gen.2.3"
where the first and the second reference are complete osisIDs and they are separated by a - (and no spaces). And the first reference must precede the second.

Discontinuous references are to be separated by whitespace, "osisRef osisRef". For example:
annotateRef="Gen.1.1 Gen1.5"

== Importing ==
[[osis2mod]] (>= 1.5.11) is used for both Bibles and Commentaries. See [[osis2mod]] for details.

== Config file ==
It's very important that all the necessary properties are included in the .conf file, otherwise the commentary module may not behave as required.<br>
e.g. The module being made from OSIS source text, this property should be specified:
SourceType=OSIS
Otherwise, it would default to Plaintext. For further details, please refer to [[DevTools:conf Files]].

[[Category:Guides|OSIS Commentaries]]

[[Category:OSIS]]

OSIS Bibles

2020-12-19T09:47:00Z

Domcox: /* General structure */ Fix typo

==OSIS==
OSIS is an XML Schema definition for Bibles and other Biblical research texts, which enables ministries and other organizations to collaborate more easily. Traditionally, these organizations have stored their documents in disparate, proprietary markups, making it difficult when they wish to share in service with each other. OSIS provides a common markup for multiple visions.

CrossWire is committed to supporting the OSIS initiative. We have developed OSIS import and export tools which work with our SWORD engine, making OSIS documents available to all of our SWORD software.

The latest OSIS Schema definition and supporting information was once available at: [http://www.bibletechnologies.net/].<BR> However, the '''BTG''' no longer exists. See http://ebible.org/osis/

==Introduction==
This page is for practical examples of how to encode a Bible in OSIS 2.1.1 for building a SWORD module with [[osis2mod]]. It represents CrossWire's experience and best practices in creating modules.

Every OSIS SWORD module must be created from a well-formed and valid OSIS 2.1.1 document. While it is a desirable goal for any such document to be acceptable, SWORD has some particular requirements which are discussed here.

The schema for '''OSIS 2.1.1''' that was formally at [http://www.bibletechnologies.net/osisCore.2.1.1.xsd] is preserved at http://crosswire.org/osis/osisCore.2.1.1.xsd.
<br />We are maintaining an updated schema at: http://www.crosswire.org/~dmsmith/osis/osisCore.2.1.1-cw-latest.xsd that may be used in place of the official BibleTechnologies URL for validating OSIS files.
<br />See also [[OSIS_211_CR#CrossWire_updated_schema| CrossWire updated schema]].

The March 2006 version of the OSIS Manual may be found [http://www.crosswire.org/OSIS/OSIS%202.1.1%20User%20Manual%2006March2006.pdf here] (PDF).

A good example of an OSIS document can be found at http://www.crosswire.org/~dmsmith/kjv2006.
<BR>The latest releases are found under http://www.crosswire.org/~dmsmith/kjv2011/

See also [[OSIS Book Abbreviations|OSIS Book Name Abbreviations]].

==General structure==

An OSIS document is a ''well-formed XML'' document, valid according to the ''OSIS schema''.
You can the most current version [http://www.crosswire.org/~dmsmith/osis/osisCore.2.1.1-cw-latest.xsd here].<ref>See also [[OSIS Tutorial#The_Root_Element|root element]]</ref>

To produce a Bible, you can use this template:

<pre>
<?xml version="1.0" encoding="UTF-8"?>
<osis
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://www.bibletechnologies.net/2003/OSIS/namespace"
xmlns:osis="http://www.bibletechnologies.net/2003/OSIS/namespace"
xsi:schemaLocation="http://www.bibletechnologies.net/2003/OSIS/namespace http://www.bibletechnologies.net/osisCore.2.1.1.xsd">
<osisText osisIDWork="{NAME}" osisRefWork="Bible" xml:lang="{LANG}" canonical="true">
<header>
{HEADER}
</header>
<div type="bookGroup">
{BODY}
</div>
</osisText>
</osis>
</pre>

With the following values:
; {NAME}: Normalized name of the Bible version (Usually 3 letters for language, 3 for translation)
; {LANG}: IETF language code-- ISO 639-1 codes are preferred, and ISO 639-3 codes are preferred when ISO 639-1 codes do not exist for the given language. See [http://www.sil.org/iso639-3/codes.asp] for a list of codes.
; {HEADER}: Description of the included text; see below
; {BODY}: Text; see below

For text without any character outside ASCII, you can use US-ASCII encoding (usually for english text). For every other language, please use UTF-8 and NFC. See the [[OSIS Bibles#Tools|tools]] section if you need to convert.

<references />
===Header===
This is the minimum contents of the header required for validation. It is also what <tt>usfm2osis.pl</tt> produces. A valid OSIS header may include more than this.
<header>
<work osisWork="{Name}"/>
</header>

===Body===

Here is the general structure of the body content:
<pre>
<div type="bookGroup">
<title>Old Testament</title>
<div type="book" osisID="Gen" canonical="true">
<title type="main" short="Genesis">Genesis</title>
<chapter osisID="Gen.1" chapterTitle="CHAPTER 1.">
<title type="chapter">CHAPTER 1.</title>
<verse sID="Gen.1.1" osisID="Gen.1.1"/>In the beginning ...
<verse eID="Gen.1.1"/>
<verse sID="Gen.1.2" osisID="Gen.1.2"/>And the earth was without form ...
<verse eID="Gen.1.2"/>
...
</chapter>
</div>
</div>
</pre>
'''Notes:'''
# The top level bookGroup division is not mandatory.
# If they are used, the bookGroup division for the New Testament should have a similar structure.
# Any '''div''' element defaults canonical to false. You need to set it to true on elements representing the structure of the original text.

===OSIS Milestones===
OSIS allows for two potentially overlapping structures: Document structure (BSP) and verse structure (BCV).

Document structure is dominated by book, sections and paragraphs (BSP), additionally with titles, quotes and poetic material. While verse structure is indicated by book, chapter and verse numbers (BCV). While a SWORD module requires verse structure, the best way to encode a module with deep markup is with document structure. [[Osis2mod]] is responsible for transforming document structure into verse structure.

Because these two systems can overlap and because XML does not allow for overlapping elements, OSIS defines a milestone mechanism for both document and verse structure elements.

For:
<X ... attribute list ...>
...
</X>
the milestoned form is:
<X sID="g1" ... attribute list .../>
...
<X eID="g1"/>

According to the OSIS manual, for any given element X that defines a milestoneable form, all the instances of X in the document must use one form or the other and may not use both. The value of each sID attribute must be unique within the document.

Verse milestone sID/eID attributes can even have values that denote a verse range. This is purely for convenience to human readers.

It is allowable to use milestone elements for verses alone, or for both verses and chapters. The body example above is for the former.

Although, the order of sID and osisID attributes within a milestone element is insignificant (as is the case for XML attributes in general), it helps for human readability to have the sID element first, such that it might be aligned with the corresponding eID element, as in the body example above.

==== Limitations of XML validators ====

An [[OSIS Bibles#Valid_OSIS_test|XML validator]] cannot validate whether OSIS milestones are used properly. It cannot validate:
* that an element is consistently either milestoned or not.
* that for each element with an sID that there is a paired element with an eID.<ref>osis2mod does not crash if the eID milestones are all missing, but the resulting module may appear to be void of text.</ref>
* that each paired sID/eID have the same attribute value.
* that different sID/eID pairs of the same element type do not overlap.<ref>If they weren't milestones, one would say they should be properly nested.</ref>
* that the values of the osisID attributes are valid and correspond to the text demarcated by the verse milesones, etc.

'''Notes:'''
<references />

==== Notes about OSIS elements ====
* For an OSIS document to be valid it must use the non-milestoned <div> and <lg> elements.
* There is no milestoned version of the <p> element. From a practical perspective, this means that the milestoned verse element should be used when paragraphs are used.
* The milestoned chapter element must be used when the paragraph is spanning over a chapter.
* The SWORD engine cannot handle sub-identifiers separated by ! in an osisID, so osis2mod strips these off from the osisIDs for verses. They are only of use for the osisIDs for notes.

===Recommended approach===
* For chapters, use <chapter>...</chapter> container elements (except in the rare case that other container elements cross chapter boundaries)<ref>Conversion scripts such as [[Converting SFM Bibles to OSIS#usfm2osis.py|usfm2osis.py]] generally produce the milestone elements for chapters.</ref>
* For verses, use milestone elements (unless container elements will suffice) – see [[OSIS Bibles/BSPExample]].
* For paragraphs, use the <p>...</p> container element
* For poetry, use container elements <lg>...</lg> to indicate stanzas (or other types of line groups) and <l>...</l> to indicate lines
* For quoted text, use the <q>...</q> container element
* For translation changes, use the <transChange>...</transChange> container element<ref>Except where the text is within a <w> which is not allowed by OSIS. For these cases use the alternative <seg subType="x-added" type="x-transChange">...</seg> </ref>

<references />

==Examples==
===Marking Paragraphs===
There is no milestoned version of the <tt><p></tt> element. Typically paragraphs surround whole verses. That is, they start and end between verses. If a paragraph begins or ends in a verse and extends beyond that verse, then the whole document must use the milestoned version of <tt><verse></tt>.
<pre>
<div type="book" osisID="Gen" canonical="true">
<title type="main">LE PREMIER LIVRE DE MOÏSE dit LA GENÈSE</title>
<chapter osisID="Gen.1" chapterTitle="Chapitre 1"><title type="chapter">Chapitre 1</title>
<p>
<verse sID="Gen.1.1" osisID="Gen.1.1" n="1"/>Au commencement Dieu créa les
cieux et la terre.<verse eID="Gen.1.1"/>
</p>
<p>
<verse sID="Gen.1.2" osisID="Gen.1.2" n="2"/>Et la terre était désolation et
vide, et il y avait des ténèbres sur la face de l'abîme. Et l'Esprit de Dieu
planait sur la face des eaux.<verse eID="Gen.1.2"/>
</p>
<p>
<verse sID="Gen.1.3" osisID="Gen.1.3" n="3"/>Et Dieu dit : Que la lumière
soit. Et la lumière fut.<verse eID="Gen.1.3"/>
<verse sID="Gen.1.4" osisID="Gen.1.4" n="4"/>Et Dieu vit la lumière, qu'elle
était bonne ; et Dieu sépara la lumière d'avec les ténèbres.
<verse eID="Gen.1.4"/>
<verse sID="Gen.1.5" osisID="Gen.1.5" n="5"/>Et Dieu appela la lumière Jour ;
et les ténèbres, il les appela Nuit. Et il y eut soir, et il y eut matin :
&#8212; premier jour.<verse eID="Gen.1.5"/>
</p>
...
</pre>

{| border="1"
|+Result
|
<sup>'''(1)'''</sup> Au commencement Dieu créa les cieux et la terre.

<sup>'''(2)'''</sup> Et la terre était désolation et vide, et il y avait des ténèbres sur la face de l'abîme. Et l'Esprit de Dieu planait sur la face des eaux.

<sup>'''(3)''' </sup>Et Dieu dit : Que la lumière soit. Et la lumière fut. <sup>'''(4)'''</sup> Et Dieu vit la lumière, qu'elle était bonne ; et Dieu sépara la lumière d'avec les ténèbres. <sup>'''(5)'''</sup> Et Dieu appela la lumière Jour ; et les ténèbres, il les appela Nuit. Et il y eut soir, et il y eut matin : — premier jour.
|}

Note: [[osis2mod]] converts a paragraph start into <tt><div type="paragraph" sID="genX"/></tt> and a paragraph end into <tt><div type="paragraph" eID="genX"/></tt>.

===Marking Quotations===
Most of the SWORD front-end applications can show a chapter at a time and some can show isolated verses. This means that all of the SWORD applications can show partial quotations, such as the Sermon on the Mount which begins in Matt 5 and ends in Matt 7.

====Default quotation marks====
By default, SWORD will use <tt>"</tt> for quotations. The following describes various ways to influence this.

====Indicating the nesting of a quote====
When a quote is contained in a quote, it is customary to set the level attribute to indicate the depth of the nesting. For example, Jeremiah 23:38 is part of a larger quote and has a back and forth dialog of nested quotes:

<pre>
But if you say,
<q level="2" sID="1"/>
The burden of the Lord,
<q level="2" eID="1"/>
thus says the Lord,
<q level="2" sID="3"/>
Because you have said these words,
<q level="3" sID="4"/>
The burden of the Lord,
<q level="3" eID="4"/>
when I sent to you, saying,
<q level="3" sID="5"/>
You shall not say,
<q level="4" sID="6"/>
The burden of the Lord,
<q level="4" eID="6"/>
<q level="3" eID="5"/>
</pre>
A couple of things to note about this verse. First, the level attribute is on both the sID and the eID pair, matching in value. Second, this is an example of a verse that has a quote that starts in the middle and finishes in another verse.

In this case, SWORD will use the level to determine whether to use <tt>"</tt> or <tt>'</tt> for quotes. Odd levels will use <tt>"</tt> and even levels will use <tt>'</tt>. This is in accordance with American English usage, which is the opposite of British English usage. Nesting levels up to five can be found in the Bible.<ref>Jeremiah 27:1-11; 29:1-28, 30-32; 34:1-5; and Ezekiel 1-36</ref>

<references />

====Supplying alternative quotation marks====
The quote element has a marker attribute that can be used to control the quotation marks. SWORD applications will always use this value when rendering the quote. When the marker attribute is the null string, it will render no quotation mark at all.<ref>e.g. The KJV module has <tt>marker=""</tt> because the text of the KJV Bible does not use any quotation marks.</ref>

To specify "curly" quotes you can use the following values:
{|border=1
!Description!!Char!!HTML Entity!!Unicode
|-align=center
|Opening double quote||“||&#8220;||U+201C
|-align=center
|Closing double quote||”||&#8221;||U+201D
|-align=center
|Opening single quote||‘||&#8216;||U+2018
|-align=center
|Closing single quote||’||&#8217;||U+2019
|}

To use different marks to start and end a quote, use the milestoned version of the quote.
<q marker="“" sID="qN"/> ... <q marker="”" eID="qN"/>

There is further information about English quotation marks and their usage in [http://en.wikipedia.org/wiki/Quotation_marks].

Quotation marks have a variety of forms in different languages and in different media. See [http://en.wikipedia.org/wiki/Quotation_mark,_non-English_usage Quotation mark, non-English usage].<ref>When modules are being converted from digitized source text used in other Bible software, it may be the case that quotation marks in the text source differ from those in the original published edition, whether due to inherent constraints of the other software, or for other causes.</ref>

'''Note:'''
<references />

====Continuation quotation marks====
The <tt><milestone type="cQuote"/></tt> can be used to indicate the presence of a continued quote. If the marker attribute is present, it will use that otherwise it will use a straight double quote, ". Since there is no level attribute on the milestone element, it is best to specify the marker attribute.

====Marking the Words of Christ====
To indicate that a quote is something that Jesus said<ref>http://en.wikipedia.org/wiki/Red_letter_edition</ref>, use the attribute <tt>who="Jesus"</tt>.

<pre>
<verse osisID="Luke.22.35 sID="Luke.22.35"/>
Then Jesus asked them, <q who="Jesus" marker="">When I sent you without purse,
bag or sandals, did you lack anything?</q>
<verse eID="Luke.22.35"/>
</pre>

{| border="1"
|+Result
|
Then Jesus asked them, <span style="color:#A00">When I sent you without purse, bag or sandals, did you lack anything?</span>
|}

'''Note:'''
<references />

===Marking poetic material===
Poetry is marked up with <lg>, line group, and <l>, line, elements. The line element supports indentation with the level attribute. When the level attribute is not present or it is level="1", this should be interpreted as the first level of the line group. When level="2" it is indented relative to level="1". The same is true for each subsequent level.

The level attribute is used to indicate indentation. A value of 1 means no indentation, the same as not specifying a level attribute. A value of 2 means to indent one. And so forth.

<pre>
<chapter osisID="Exod.15" chapterTitle="Chapitre 15"><title type="chapter">Chapter 15</title>
<p>
<verse sID="Exod.15.1" osisID="Exod.15.1" n="1"/>
Then sang Moses and the children of Israel this song unto the LORD, and spake, saying,
</p>
<lg>
<l level="1">I will sing unto the LORD, for he hath triumphed gloriously:</l>
<l level="2">the horse and his rider hath he thrown into the sea.</l>
<verse eID="Exod.15.1"/>

<verse sID="Exod.15.2" osisID="Exod.15.2" n="2"/>
<l level="1">The LORD is my strength and song, and he is become my salvation:</l>
<l level="2">he is my God, and I will prepare him an habitation;</l>
<l level="2">my father's God, and I will exalt him.</l>
<verse eID="Exod.15.2"/>

<verse sID="Exod.15.3" osisID="Exod.15.3" n="3"/>
<l level="1">The LORD is a man of war:</l>
<l level="2">the LORD is his name.</l>
<verse eID="Exod.15.3"/>

<verse sID="Exod.15.4" osisID="Exod.15.4" n="4"/>
<l level="1">Pharaoh's chariots and his host hath he cast into the sea:</l>
<l level="2">his chosen captains also are drowned in the Red sea.</l>
<verse eID="Exod.15.4"/>

<verse sID="Exod.15.5" osisID="Exod.15.5" n="5"/>
<l level="1">The depths have covered them:</l>
<l level="2">they sank into the bottom as a stone.</l>
<verse eID="Exod.15.5"/>
...
</pre>

{| border="1"
|+Result
|
<sup>'''(1)'''</sup> Then sang Moses and the children of Israel this song unto the LORD, and spake, saying,

::''I will sing unto the LORD, for he hath triumphed gloriously:''
::::''the horse and his rider hath he thrown into the sea.''

::<sup>'''(2)'''</sup> ''The LORD is my strength and song, and he is become my salvation:''
::::''he is my God, and I will prepare him an habitation;''
::::''my father's God, and I will exalt him.''

::<sup>'''(3)'''</sup> ''The LORD is a man of war:''
::::''the LORD is his name.''

::<sup>'''(4)'''</sup> ''Pharaoh's chariots and his host hath he cast into the sea:''
::::''his chosen captains also are drowned in the Red sea.''

::<sup>'''(5)'''</sup> ''The depths have covered them:''
::::''they sank into the bottom as a stone.''
|}

'''Note:'''

# While OSIS defines a milestoned version of the <tt><lg></tt> element, its use (rather than the container version) will not produce a valid XML document. The <tt><l></tt> element can only occur within an <tt><lg></tt> container, so use of <tt><lg/></tt> milestones prevents use of <tt><l></tt> elements.

==== Marking acrostic poetry headings ====
Use <tt>type="acrostic"</tt> as the title attribute for the stanza headings in acrostic passages such as Psalm 119. Whether or not this Psalm uses a poetry line group for each stanza, each title element should be placed before its related stanza.

=== Marking lemmas & morphology ===
====Marking Strong's numbers====
To mark up [http://en.wikipedia.org/wiki/Strong%27s_Concordance Strong's numbers], you first need to declare a workID in the header of the OSIS document:
<pre>
<header>
...
<work osisWork="strong">
<refSystem>Dict.Strongs</refSystem>
</work>
...
</header>
</pre>

SWORD does not actually use this declaration, but it is required to have a proper OSIS document.

And while OSIS allows arbitrary workIDs, SWORD can only handle "strong" and a few variants.

<pre>
<w lemma="strong:H0853 strong:H03045">knew</w>
</pre>

The <w> element is used to surround the text that is represented by the Strong's number. It may be that the text is a phrase and it may be that more than one Strong's number defines the text.

When more than one Strong's number defines the text, each must be prefixed with a workID and must be separated from each other by a space. (While OSIS allows for the defining of default workIDs, SWORD requires that the workIDs be used.)

The actual Strong's Number should indicate whether it is Hebrew (H) or Greek (G) followed by the number. The number may be 0 padded up to 5 digits as in H00001.

====Marking morphology====
In a similar manner to marking with Strong's numbers, morphology can also be noted. Since morphology regards the original language, Strong's numbers will be shown at the same time.

As with Strong's numbers, a workID needs to be defined. Here we are defining one for Robinson's Morphology Codes. And while SWORD will ignore this declaration, "robinson" is hard-coded into SWORD for Greek morphology codes.
<pre>
<header>
...
<work osisWork="robinson">
<refSystem>Dict.Robinson</refSystem>
</work>
...
</header>
</pre>

Example markup of Robinson's Morphology Codes in the KJV module:
<pre>
<w lemma="strong:G3588 strong:G80" morph="robinson:T-APM robinson:N-APM" src="7 8">his brethren</w>
</pre>
In this example, lemma, morph and src form parallel arrays. The first strong: mapping to the first robinson: and the first src value, etc.

The workID should be name of a current, future, or potential lexicon module in which the morphology code could be looked up. For example, morph="packard:D" represents a reference to morphology code "D" in a module named Packard, whether or not a Packard module has been created or released. (Currently, SWORD offers lexicon modules named Robinson and Packard, both for Greek morphology.)

The src attribute is used here to indicate the word position in the original Greek.

====Marking other lemmas====
The lemma attribute of the <tt><w></tt> element can contain any number of other lemmas. Like Strong's numbers and morphology codes, these need to have a workID declared in the header. SWORD presumes that these lemma workIDs all start with "lemma." (note the final period). The portion of the workID following "lemma." should be name of a current, future, or potential lexicon module in which the lemma could be looked up. For example, lemma="lemma.TWOT:271" represents a reference to lemma #271 in a module named TWOT (i.e the Theological Workbook of the Old Testament), whether or not a TWOT module has been created or released. As far as SWORD is concerned, there can be any number of these space-delimited values in a lemma attribute and they can be in any order, even interspersed among the "strong:" lemmas.

Example of a lemma markup for the Greek words from the [https://en.wikipedia.org/wiki/Textus_Receptus TR] in the KJV module:
<w lemma="strong:G976 lemma.TR:βιβλος" morph="robinson:N-NSF" src="1">The book</w>

SWORD has the ability to show or hide non-Strong's lemmas as a group. See [[DevTools:conf Files#Elements_required_for_proper_rendering|GlobalOptionFilter=OSISLemma]] – for OSIS texts having lemmas.

==== Marking glosses ====
Gloss markup uses the <tt>gloss</tt> attribute of the <tt><w></tt> element. The syntax is illustrated by this line exported from the module JapMeiji.
<pre>
<w gloss="はじめ">元始</w>に<w gloss="かみ">神</w><w gloss="てんち">天地</w>を<w gloss="つくり">創造</w>たまへり
</pre>
Display of glosses can be toggled (in [[Choosing a SWORD program#Module_Support|compatible front-ends]]) by having this line in the [[DevTools:conf Files#Elements_required_for_proper_rendering|.conf file]]:
GlobalOptionFilter=OSISGlosses
==== Marking encoded transliterations ====
Transliteration markup uses the xlit attribute of the <w> element. The syntax is illustrated by this line exported from the module SP.
<w gloss="in_beginnings" lemma="strong:H7225" morph="ב_ראשית" n="1" xlit="Latn:b_raShit">בראשית</w>
Display of encoded transliterations can be toggled (in [[Choosing a SWORD program#Module_Support|compatible front-ends]]) by having this line in the [[DevTools:conf Files#Elements_required_for_proper_rendering|.conf file]]:
GlobalOptionFilter=OSISXlit
==== Marking enumerated words ====
Enumerated words markup uses the n attribute in the <w> element. The syntax is illustrated in the previous subsection.

Display of enumerated words can be toggled (in [[Choosing a SWORD program#Module_Support|compatible front-ends]]) by having this line in the [[DevTools:conf Files#Elements_required_for_proper_rendering|.conf file]]:
GlobalOptionFilter=OSISEnum

==== Marking morpheme segmentation ====

In languages such as Biblical Hebrew, parts of words may be split into semantic segments using the XML '''seg''' element, thus:

<w><seg type="x-morph">וַ</seg><seg type="x-morph">יִּקְרָ֨א</seg></w>

Display of morpheme segmentation<ref>Currently, only some JSword based front-ends seem to support this feature. The SWORD engine has the switch available, but no change in output is effected.</ref> can be toggled (in [[Choosing a SWORD program#Module_Support|compatible front-ends]]<ref>e.g. STEP Bible uses these structures to provide colour coding. It just uses 2 colours to show different parts, alternating between the two.</ref>) by having this line in the [[DevTools:conf Files#Elements_required_for_proper_rendering|.conf file]]:
GlobalOptionFilter=OSISMorphSegmentation

'''Note:'''
<references />

===Marking the divine name===
The <tt><divineName></tt> tag is reserved for representations of the tetragrammaton יהוה (YHWH). These occur in the Old Testament as <span style="font-variant: small-caps;">Lord</span>, <span style="font-variant: small-caps;">God</span> and <span style="font-variant: small-caps;">Yah</span>. Not every instance of Lord or God is a translation of this.

The content of the divineName element is the word Lord, God or Yah, not in all upper case (i.e. not LORD, GOD, or YAH). SWORD will either convert it to small-caps or uppercase.

Note, if it is the use is possessive it is permissible to have the following:
<pre>
<divineName>Lord's</divineName>
</pre>

However, it is inadvisable to include any other punctuation within the tag pair. Thus the following is '''not''' good practice (the quotation mark should ''precede'' the start tag):
<pre>
<divineName>“God </divineName> .....”
</pre>

When also marking with Strong's numbers you will need to do it one of two ways:
<pre>
<divineName><w lemma="strong:H3068">Lord's</w><divineName>
or
<w lemma="strong:H3068">of the <seg><divineName>Lord</divineName></seg></w>
</pre>

The latter form uses a workaround to allow the embedding of <tt><divineName></tt> in a <tt><w></tt>, since OSIS does not allow for this, but does allow for <tt><seg></tt> to be in a <tt><w></tt> and to contain <tt><divineName></tt>.

'''Note:''' See also [[OSIS 211 CR#Allow_.3CdivineName.3E_within_.3Cw.3E|OSIS change requests: Allow <divineName> within <w>]].

===Marking sections and titles===
A section is marked with:
<pre>
<div type="section">
...
</div>
</pre>

In OSIS the <tt><title></tt> element is used to provide general headings. Titles should be placed at the top of the container that they title, not before.
<pre>
<div type="book">
<title>A book title</title>
<chapter>
<title type="chapter">A title chapter</title>
<div type="section">
<title>A section title</title>
...
</div>
...
</chapter>
</div>
</pre>
Using <tt>type="chapter"</tt> or <tt>type="main"</tt> is needed by [[osis2mod]] to distinguish chapter titles from verse titles. When SWORD stores an OSIS document it does so as an index of verses. It has special indexes for book and chapter titles. SWORD does not store the <tt><verse></tt> tags. So when it comes to storing a title in the following verse, [[osis2mod]] generates special markup to indicate that the title stands before the verse. SWORD uses this to place the verse number.

It is recommended that chapter labels (converted from the USFM tag \cl) be coded like this (Malayalam) example:
<title type="chapter" subType="chapterLabel">൧. അദ്ധ്യായം.</title>
This ensures that these labels are not treated differently to other chapter titles.

'''Note:'''
# The <tt><head></tt> element is used to provide headings for tables, lists and cast groups. There are errors in the OSIS 2.1.1 manual that use the <tt><head></tt> incorrectly.

==== Marking pre-verse titles ====
There is no special markup for pre-verse titles. '''Osis2mod''' will determine what titles belong to the book, the chapter and otherwise if the above advice is followed.

'''Note:'''
# See also [[OSIS pre-verse titles]].

====Marking parallel passage headings====
These may be marked in a similar manner to [[OSIS Bibles#Marking_cross-references_notes|cross-reference notes]]. Example: (Welsh Beibl for Matt.3)
<pre>
<title type="parallel">(
<reference type="parallel" osisRef="Mark.1.1-Mark.1.8">Marc 1:1-8</reference>;
<reference type="parallel" osisRef="Luke.3.1-Luke.3.18">Luc 3:1-18</reference>;
<reference type="parallel" osisRef="John.1.19-John.1.28">Ioan 1:19-28</reference>)
</title>
</pre>
'''Notes:'''
# Each parallel passage has a separate reference element.
# Each reference element may have the optional attribute type="parallel".
# Each reference element has a valid osisRef attribute. Typically this is for a contiguous range of verses.
# The displayed reference for each passage uses the locale for the language.
# Reference elements are typically separated by a semicolon and space.
# The displayed title is typically enclosed within parentheses, which are not part of any reference element.
# Localized book names may or may not be abbreviated. If abbreviations are used, ideally they should be used consistently throughout the whole Bible.
# Abbreviated localized book names may or may not end with a full stop.
# The localized chapter verse separator may be other than a colon.
# The range specifier is typically a [http://en.wikipedia.org/wiki/Hyphen-minus hyphen-minus] but alternatively may be an [http://en.wikipedia.org/wiki/Dash#En_dash en dash].
# Special care is required when:
:*There is more than one passage listed for the same book, when typically the book name is given only for the first passage.
:*There is more than one passage listed for the same chapter, when typically the chapter number is given only for the first passage.
:*The parallel passage is in the same book, when typically the book name is omitted in the displayed reference.
:*The parallel passage is one or more whole chapters (or psalms), when typically the verse numbers are omitted.
:*The parallel passage is a range of verses in a "single chapter" book, when typically the chapter number is omitted.<br>Example: Jude 3-24 is sometimes used as parallel with 2 Peter 2.
:*The parallel passage is a range that spans a chapter divison, and where the range separator might even be an [http://en.wikipedia.org/wiki/Dash#Em_dash em dash] or an [http://en.wikipedia.org/wiki/Dash#En_dash en dash] rather than a hyphen-minus. Example: Exodus 35:30—36:1

===Marking notes===
The note element can appear in any element that can contain text ''outside'' of the '''header''' element.

NB. The examples in this section include the use of sub-identifiers in '''osisID'''s for notes.
<pre>
<verse sID="Gen.1.1" osisID="Gen.1.1" n="1"/>Au commencement
Dieu<note osisRef="Gen.1.1" osisID="Gen.1.1!1" n="1"><hi type="italic">en hébreu</hi> : Élohim,
(<hi type="italic">pluriel d</hi>'Éloah, le Dieu suprême), la Déité, <hi type="italic">dans
le sens absolu</hi>.</note> créa les cieux et la terre.<verse eID="Gen.1.1"/>

<verse sID="Gen.1.2" osisID="Gen.1.2" n="2"/>Et la terre était désolation et
vide<note osisRef="Gen.1.2" osisID="Gen.1.2!1" n="2">le vide.</note>, et il y avait des ténèbres
sur la face de l'abîme. Et l'Esprit de Dieu planait sur la face des eaux.<verse eID="Gen.1.2"/>
</pre>

{| border="1"
|+Result
|
# Au commencement Dieu¹ créa les cieux et la terre.
# Et la terre était désolation et vide², et il y avait des ténèbres sur la face de l'abîme. Et l'Esprit de Dieu planait sur la face des eaux.

*¹ ''en hébreu'': Élohim, (''pluriel d'''Éloah, le Dieu suprême), la Déité, ''dans le sens absolu''.
*² le vide.
|}

The note should be attached to what it refers to, either ''after'' (as is the case here) or ''before''. There should no additional space surrounding the note, but only what is in the text.

These notes can have any type other than '''crossReference'''.

For more detailed information about the '''note''' element, please refer to sections '''8.3''' to '''8.6''' of the '''OSIS Reference Manual'''.

====Notes with an annotation reference====
An OSIS file converted correctly from USFM files may contain notes with an annotation reference. The syntax should be like this:
<note placement="foot"><reference type="annotateRef" osisRef="Matt.1.19">1:19</reference> The footnote informational text is here.</note>

An annotation reference is usually generated when converting from USFM for notes containing the tag <tt>\fr </tt> or <tt>\xo </tt>.<ref>The human readable reference is typically just the chapter and verse number, as in this example.</ref>

This example is for a note tagged for a word in Matt.1.19. and it illustrates that the reference element has two attributes.
* <tt>type="annotateRef"</tt> – this defines the note as having an annotation reference
* <tt>osisRef="Matt.1.19"</tt> – this specifies the origin of the note, and makes the "1:19" display as a link in the footnote panel.
The space at the start of the footnote text is required in order to separate the reference from the text.

'''Note:'''
<references />

====Marking cross-references notes====
SWORD provides the ability for a user to show or hide cross-references. To achieve this you embed one or more <tt><reference></tt> elements in a <tt><note type="crossReference">...</note></tt>. If this is not done, then the cross-references will always show inline in the text.

<pre>
<note type="crossReference" n="t" osisID="Jer.24.7!crossReference.t">
<reference osisRef="Jer.32.39">ch. 32:39</reference>;
<reference osisRef="Deut.30.6">Deut. 30:6</reference>;
<reference osisRef="Ezek.11.19">Ezek. 11:19</reference>;
<reference osisRef="Ezek.36.26-Ezek.36.27">36:26, 27</reference>.
</note>
</pre>

Here is a breakdown.

Regarding the <tt><note></tt> element:

:<tt>type="crossReference"</tt> is one of the predefined OSIS note types. SWORD looks for this value to show/hide cross-references.

:<tt>n="t"</tt> is the marker for the cross-reference note. This can be either of the following:
:# A serially allocated index letter in the range <tt>a-z</tt>.
:# A custom xref note marker symbol (or scheme) as may be specified by the author/translator.
:btw. Source text [[Converting SFM Bibles to OSIS|converted from USFM]] usually adopts method 1.

:The given '''osisID''' is based upon the location of the note. In order to not conflict with the verse's osisID and to construct a unique id, the ! (extension mark, ''aka'' sub-identifier) syntax is used. This is further qualified by the note's '''type''' and '''n''' value, separated by a dot.

:Observe the punctuation marks between references and (optionally) after the last reference. There is typically a space after each semicolon.

:This note pertains to a single verse and it is given an '''osisRef'''.

Regarding the <tt><reference></tt> elements:

:The <tt><reference></tt> element is replaced by SWORD with a link to the reference with the text of the element being shown as link text.<ref>Some front-ends (e.g. Xiphos, PocketSword) never display the raw cross-reference text (the original text wrapped within each '''reference''' element. Instead they display a preview of each cross-referenced linked verse.</ref>

:While the '''osisRef''' can point to multiple verses, most SWORD applications cannot handle a link that goes to more than one verse or a contiguous range of verses. Xiphos (for example) just generates a verse list in the side panel.

:Here we see that each '''reference''' element is separated by punctuation (the semicolon at the end of each line).

Some of the notes given under [[OSIS Bibles#Marking_parallel_passage_headings|Marking parallel passage headings]] are also applicable here.

For non-English Bibles, the punctuation marks used as separators in displayed Scripture references can be different. Even with English, there can be variations between Bible versions.

Special care is required when the cross-reference includes additional prose text which is not a scripture reference. This often arises in [[Converting SFM Bibles to OSIS|Bibles converted from SFM]]. Unless and until this issue is fixed, it becomes almost impossible to parse the reference elements such that the OSIS references can be added automatically.

Further care is often required to deal with minor errors of punctuation that translators are prone to make in footnotes with cross-references.

'''Note:'''
<references />

====Marking references in Right to Left scripts====
To ensure that the ''human readable'' reference is correctly displayed in Bibles with a '''Right to Left''' script, the translator[s] may have made judicious use of the special Unicode character '''RIGHT TO LEFT MARK''' ['''RLM'''] (U+200F).

The RLM being invisible, its presence may easily go unnoticed, yet script developers need to be aware of it. The procedure to convert the ''human readable'' reference to the ''machine readable'' '''osisRef''' value must ensure that the RLM is deleted from the latter.

=====Technical details=====
The key to understanding this is the exact placements of the '''RLM''' in references in a RtoL script.

* before the colon separator between chapter and verse
* before the hyphen/minus (or endash) used as the verse range separator
* before an ''ordinary'' comma between verse numbers in a list (not required when the ''Arabic'' comma is used)
* before the chapter number in the caller reference, because that becomes the start of the displayed footnote in SWORD apps.

'''Example:'''

Here's a '''note''' element in the OSIS source: (of the UrduGeo module)

<code>
<note placement="foot"><reference type="annotateRef" osisRef="2Kgs.12.4">‏12‏:4</reference> <catchWord>مردم شماری کے ٹیکس: </catchWord>دیکھئے <seg type="x-nested"><reference osisRef="Exod.11.16-Exod.11.30">خروج 11‏:16‏-30</reference></seg> </note>
</code>

Here's the same Unicode text converted to PCRE.

<code>
<note placement="foot"><reference type="annotateRef" osisRef="2Kgs.12.4">\x{200F}12\x{200F}:4</reference> <catchWord>\x{0645}\x{0631}\x{062F}\x{0645} \x{0634}\x{0645}\x{0627}\x{0631}\x{06CC} \x{06A9}\x{06D2} \x{0679}\x{06CC}\x{06A9}\x{0633}: </catchWord>\x{062F}\x{06CC}\x{06A9}\x{06BE}\x{0626}\x{06D2} <seg type="x-nested"><reference osisRef="Exod.11.16-Exod.11.30">\x{062E}\x{0631}\x{0648}\x{062C} 11\x{200F}:16\x{200F}-30</reference></seg> </note>
</code>

Observe the '''four''' instances of <code>\x{200F}</code> which is the '''RLM''' described above.

:''Further details to be added to illustrate the footnote as displayed in Xiphos.''

===Marking variants===
SWORD recognizes the element '''seg''' with '''type="x-variant"''' as marking variants present in different versions of a text<ref>This feature requires the front-end to have been compiled with SWORD version 1.7 or later.</ref>. The attribute '''subType''' should be added, with a value of '''"x-1"''' or '''"x-2"''' to indicate whether the reading is the primary or secondary variant. At present, SWORD supports only 2 different readings per text. The method is illustrated below:
<pre>
The text of the Bible
<seg type="x-variant" subType="x-1">may </seg>
<seg type="x-variant" subType="x-2">can </seg>
contain variant readings.
</pre>
This illustrates a primary reading "may " and a secondary reading "can ". Observe the space included in both seg elements. If these spaces were omitted, the variant words would be joined when displaying all readings.

==== Filter ====
Variant readings in OSIS modules may be switched by the SWORD engine when the module conf file includes:
GlobalOptionFilter=OSISVariants
'''Note:'''
<references/>

==== Examples ====
* The TR module contains 246 locations where two such variants are marked.
* The WHNU module contains 1473 locations where two variants are marked.

==== SWORD implementation ====
The SWORD API provides for these three choices:
[Primary Reading|Secondary Reading|All Readings]
Example: In Xiphos version 3.1.6 or later, the module context menu provides these three options for any module that has variants.

SWORD does not supply its own delimiters to distinguish between variants. When displaying text that contains variants, it may not be obvious where these are located.

==Tools==

===Bible Technologies Group===
The '''BTG''' that sponsored the OSIS committee and hosted the OSIS schema no longer exists.
References below that use the domain '''www.bibletechnologies.net''' will no longer work.
The schema location therefore now needs to be for a local copy on your computer or to a copy hosted by CrossWire or elsewhere.

For more up to date details, see [[OSIS 211 CR]] which includes CrossWire's own updated schema.

===Valid OSIS test===
A valid XML document one that is well-formed and conforms to the formal definition provided in a schema (or DTD). A document cannot have elements, attributes, or entities not defined in the schema. A schema can also define ''how'' entities may be nested, the possible values of attributes, etc.

Many programs capable of schema validation exist. Most [http://en.wikipedia.org/wiki/XML_editor XML editors] ([http://xml-copy-editor.sourceforge.net/ XML Copy Editor], [http://en.wikipedia.org/wiki/Oxygen_XML_Editor Oxygen], [http://en.wikipedia.org/wiki/XMLSpy XMLSpy], [http://www.topologi.com/ Topologi], etc.) support some sort of XML schema validation. The Windows based text editor [http://en.wikipedia.org/wiki/Notepad%2B%2B Notepad++] supports Unicode and has an [https://github.com/morbac/xmltools XML Tools] plugin which can perform syntax checking and validation.

There are also some online facilities for XML validation, e.g. [http://www.freeformatter.com/xml-validator-xsd.html].

====xmllint====
libxml2, available for Linux, Windows, & MacOS, includes a command-line validator called xmllint. To check that a document is valid against OSIS schema, use the following command.
<pre>
$ xmllint --noout --schema http://crosswire.org/osis/osisCore.2.1.1.xsd myfile.osis.xml
</pre>

'''Notes:'''
# Internet access is required to validate your document using a remote schema.
# Even if you use a local copy of the OSIS schema, it calls on [http://www.w3.org/XML/1998/namespace] via HTTP.
# Having a VPN connection may sometimes interfere with the use of XML validation tools.
# Some firewalls or proxies also prevent or interfere with the use of these tools.

To install xmllint, simply install libxml2 via your distribution's standard package management system in Linux or download the Windows binary from our [http://www.crosswire.org/ftpmirror/pub/sword/utils/win32/ mirror]. You also need to install "libxml2-utils". In this last package is program "xmllint".

====lxml (Python)====
[http://lxml.de/ lxml] is a toolkit that can be used within a Python script to validate an XML file.

"The lxml XML toolkit is a Pythonic binding for the C libraries libxml2 and libxslt."

====Online XML Validators====
The external links section of http://en.wikipedia.org/wiki/XML_Validation lists at least three online validators. Some or all of these can validate against external XML schema.

==Creating a SWORD Module==
Use [[osis2mod]] to create the module.

== See also ==
*[[OSIS]] – a partial list of other OSIS related pages and external links.

*[[Converting SFM Bibles to OSIS]] – describes how to prepare a single OSIS XML file for a Biblical text supplied as several USFM files.

== External links ==

* [http://en.wikipedia.org/wiki/List_of_Bible_verses_not_included_in_modern_translations List of Bible verses not included in modern translations]

* [http://xml.coverpages.org/DeRoseEML2004.pdf Markup Overlap: A Review and a Horse] – Steven DeRose (2004) Bible Technologies Group.

[[Category:Guides|OSIS Bibles]]

[[Category:OSIS|OSIS Bibles]]

[[Category:Morphology|OSIS Bibles]]

Module Submission

2020-12-17T21:05:50Z

Domcox: /* How-To name your files */ Fix typo

Module Submission

2020-12-15T09:46:57Z

Domcox: /* Link to a git Repository */ Remove git cloning --branch tag section

Module Submission

2020-12-14T20:36:47Z

Domcox: fix typo

Module Submission

2020-12-14T20:35:57Z

Domcox: Changes to reflect the upgraded publishing framework

DevTools:Module Submission and Copyrights

2020-12-14T16:46:50Z

Domcox: Fix typo

CrossWise does respect copyrights and takes in general a very cautious view in these matters.

==General Policy==

If there is a hint of a doubt regarding the public domain status we do not publish a text unless we have permissions, either explicitly relating to us or via free licensing (Creative Commons and the like). If we believe we require explicit permissions then we welcome the assistance of community members to obtain these, but in the end it will always be the module team or the director who needs to receive the permissions from the copyright owner.

In this way we have on occasion forgone texts we really would like to publish and other projects felt free to publish, but we still believe that this approach has born fruit.

There are occasionally situations where people decided that the only likely approach to convince a copyright owner to grant permissions is to create a module as showcase. This is, dependent on the legislation at place, a potentially very risky undertaking, but clearly who does so believes that the risk is acceptable for them personally or , thanks to local legislation is not a problem for them. As long as such modules are not discussed (explicitely or implicitly) or offered on the list for testing purposes or otherwise and as long as these people do not describe themselves as CrossWire volunteers to the publishers, then we as a community do not take a further view on this.

Beyond the above, some jurisdictions will permit private use, reuse and transformation of texts otherwise restricted. This is great for individuals, but it does not enable us as an entity to assist with this. Please do not discuss your attempts in this way on the mailing list. You are of course allowed to discuss technical problems around encoding on the list, but making such private use modules available for others via the list or otherwise is not something we want to see or be involved in.

==Examples==
Below some typical examples encountered in the years

# "I am working on this Bible text in my language. The text is ancient, around 200 years old, but still very relevant for my country's church. I have put my source text into Github and would be grateful about some coding advice" thanks, no questions, all are happy.
# " I am the technical guy of the Bible society of X and we want to make our new translation wider available. Can some help me to fix A, B and C , I can make the full module available to testers. Our director will write a letter to your module team regarding distribution rights as module" thanks no problem. Discuss your preliminaries and technical examples with original text if necessary here on the list.
# "I have obtained the text of the NIV by scraping this website.... Can you help to fix my module?" Sorry, stop right here, we do not want any discussion about this and certainly do not want it here.
# I have created a module of this translation into my language , the translation is from 1960, still in copyright, but our bible society is publishing the text with a license allowing free redistribution as long As the text remains unchanged. " " thanks, sounds really interesting, can you point us at where it says that you can freely redistribute?"
# "I believe that the Bible should never be copyrighted and have created a collection of modules of modern translations to make use of my belief." No debate necessary, move on please. But do not stay here.
# "I am making use of this scholarly edition, and while it is only 30 years old, I believe I am justified to make a module because scientist crave nothing more than exposure and use of the text as a module should be allowed under academic freedom. I have further interesting theories of copyright exemptions in which only I believe, but I am sure I am right!", " well, we do not agree and we do not recognise your exemptions on the law as we know it, so please do not advertise or discuss your new modules here. "
# "I am making use of this scholarly edition and the editors and copyright holders are really keen to see it in module form, where can they send a letter to confirm this?" "Right here, right here, many thanks, brilliant news"
# "My country is an interesting one, as it has never subscribed to the Berne convention, but it introduced copyright in 1987. Everything before is under public domain. Can I publish this Bible in my language, it was published in 1985.?" Ah, this is an interesting one...

==Mistaken publication==

We will withdraw as fast as we technically can any text we suspect of being incorrectly published. If you believe that a text is wrongly published please send an email to modules@crosswire.org

==Summary==

We are not lawyers, what we have learned over the years is condensed above and it boils down to - we want to get it right and if we err, we rather err on side of the caution.

[[Category:Development tools|Module Submission and Copyrights]]
[[Category:Copyright|Module Submission and Copyrights]]
[[Category:Modules|Module Submission and Copyrights]]

DevTools:Module Submission and Copyrights

2020-12-14T16:45:28Z

Domcox: Fix typo

CrossWise does respect copyrights and takes in general a very cautious view in these matters.

==General Policy==

If there is a hint of a doubt regarding the public domain status we do not publish a text unless we have permissions, either explicitly relating to us or via free licensing (Creative Commons and the like). If we believe we require explicit permissions then we welcome the assistance of community members to obtain these, but in the end it will always be the module team or the director who needs to receive the permissions from the copyright owner.

In this way we have on occasion forgone texts we really would like to publish and other projects felt free to publish, but we still believe that this approach has born fruit.

There are occasionally situations where people decided that the only likely approach to convince a copyright owner to grant permissions is to create a module as showcase. This is, dependent on the legislation at place, a potentially very risky undertaking, but clearly who does so believes that the risk is acceptable for them personally or , thanks to local legislation is not a problem for them. As long as such modules are not discussed (explicitely or implicitly) or offered on the list for testing purposes or otherwise and as long as these people do not describe themselves as CrossWire volunteers to the publishers, then we as a community do not take a further view on this.

Beyond the above, some jurisdictions will permit private use, reuse and transformation of texts otherwise restricted. This is great for individuals, but it does not enable us as an entity to assist with this. Please do not discuss your attempts in this way on the mailing list. You are of course allowed to discuss technical problems around encoding on the list, but making such private use modules available for others via the list or otherwise is not something we want to see or be involved in.

==Examples==
Below some typical examples encountered in the years

# "I am working on this Bible text in my language. The text is ancient, around 200 years old, but still very relevant for my country's church. I have put my source text into Github and would be grateful about some coding advice" thanks, no questions, all are happy.
# " I am the technical guy of the Bible society of X and we want to make our new translation wider available. Can some help me to fix A, B and C , I can make the full module available to testers. Our director will write a letter to your module team regarding distribution rights as module" thanks no problem. Discuss your preliminaries and technical examples with original text if necessary here on the list.
# "I have obtained the text of the NIV by scraping this website.... Can you help to fix my module?" Sorry, stop right here, we do not want any discussion about this and certainly do not want it here.
# I have created a module of this translation into my language , the translation is from 1960, still in copyright, but our bible society is publishhing the text with a license allowing free redistribution as long As the text remains unchanged. " " thanks, sounds really interesting, can you point us at where it says that you can freely redistribute?"
# "I believe that the Bible should never be copyrighted and have created a collection of modules of modern translations to make use of my belief." No debate necessary, move on please. But do not stay here.
# "I am making use of this scholarly edition, and while it is only 30 years old, I believe I am justified to make a module because scientist crave nothing more than exposure and use of the text as a module should be allowed under academic freedom. I have further interesting theories of copyright exemptions in which only I believe, but I am sure I am right!", " well, we do not agree and we do not recognise your exemptions on the law as we know it, so please do not advertise or discuss your new modules here. "
# "I am making use of this scholarly edition and the editors and copyright holders are really keen to see it in module form, where can they send a letter to confirm this?" "Right here, right here, many thanks, brilliant news"
# "My country is an interesting one, as it has never subscribed to the Berne convention, but it introduced copyright in 1987. Everything before is under public domain. Can I publish this Bible in my language, it was published in 1985.?" Ah, this is an interesting one...

==Mistaken publication==

We will withdraw as fast as we technically can any text we suspect of being incorrectly published. If you believe that a text is wrongly published please send an email to modules@crosswire.org

==Summary==

We are not lawyers, what we have learned over the years is condensed above and it boils down to - we want to get it right and if we err, we rather err on side of the caution.

[[Category:Development tools|Module Submission and Copyrights]]
[[Category:Copyright|Module Submission and Copyrights]]
[[Category:Modules|Module Submission and Copyrights]]

Module Submission

2020-10-27T20:31:10Z

Domcox: Fix confmaker.pl link

'''Please note: Do not edit this page unless you are actually ''directly'' involved with uploading modules onto the server. If you have a comment or addition to make, but you are not part of this particular effort, please use talk page'''

''For information on module licensing please look at [[DevTools:Module Submission and Copyrights]]''

Module submissions are to a large extent now automated.

To make it simple (and subsequently fast) please prepare your modules in following fashion

# Please check and validate your OSIS or TEI text. Please create a test module for yourself and check it for typical mistakes:
## Poorly encoded verse ranges, empty verses
## Wrong Bible book identifiers. The identifiers are ''not'' abbreviations in the normal sense - even though they look like English language abbreviations. They are intended to be machine readable internal identifiers. Mistakes will render your module unreadable
# OSIS texts need to have the CamelCase module name as workID and a 'osisRefWork="Bible"' or 'osisRefWork="Commentary"' entry within the appropriate header section.
# The document language needs to be set correctly
# If you can run Perl please run confmaker.pl on your text (found in the [https://crosswire.org/svn/sword-tools/trunk/modules/conf/confmaker.pl sword-tools repository]). Sometimes OSIS texts have spurious tag entries which are picked up by the script and set as module options in the conf file. Our scripts ''will'' pick up e.g. the single title element you have not even noticed and they will realise there is a single footnote somewhere - and set the relevant option in the module conf file. To undo this by hand is tedious and ''will'' slow down publication. If you do not want your module at this moment in time to have that kind of entry in its conf file, please do not submit texts containing such elements. You may have started a next stage in your module making already - but submitted OSIS texts should be clean and solely containing what you are willing to see published.
# The preparation of our conf files is automated. Please do not submit a complete conf file, but restrict yourself to the non-calculated elements. If you do otherwise, we will need to delete the irrelevant lines, which is prone to create confusion. Automatically added entries are the [ModuleName] line, all filter options, size, language, data path, osis version, sword version date, minimum sword version, scope.
# For visual reasons it is good to have your history entries sorted in ascending order at the very bottom of your conf file fragment.
# As modules are potentially updated for various reasons (tool updates etc) in between releases of new source texts, the module version and the latest history entry should not be in the conf file fragment submitted but in your covering email. These entries added in a different way to your module.

'''If you do not comply with the above your module submission might end up being deprioritised and will certainly not get uploaded as fast as it could be otherwise'''

[[Category:Modules]]

OSIS Bibles

2020-07-31T12:42:57Z

Domcox: Added link to the updated OSIS schema

==OSIS==
OSIS is an XML Schema definition for Bibles and other Biblical research texts, which enables ministries and other organizations to collaborate more easily. Traditionally, these organizations have stored their documents in disparate, proprietary markups, making it difficult when they wish to share in service with each other. OSIS provides a common markup for multiple visions.

CrossWire is committed to supporting the OSIS initiative. We have developed OSIS import and export tools which work with our SWORD engine, making OSIS documents available to all of our SWORD software.

The latest OSIS Schema definition and supporting information was once available at: [http://www.bibletechnologies.net/].<BR> However, the '''BTG''' no longer exists. See http://ebible.org/osis/

==Introduction==
This page is for practical examples of how to encode a Bible in OSIS 2.1.1 for building a SWORD module with [[osis2mod]]. It represents CrossWire's experience and best practices in creating modules.

Every OSIS SWORD module must be created from a well-formed and valid OSIS 2.1.1 document. While it is a desirable goal for any such document to be acceptable, SWORD has some particular requirements which are discussed here.

The schema for '''OSIS 2.1.1''' that was formally at [http://www.bibletechnologies.net/osisCore.2.1.1.xsd] is preserved at http://crosswire.org/osis/osisCore.2.1.1.xsd.
<br />We are maintaining an updated schema at: http://www.crosswire.org/~dmsmith/osis/osisCore.2.1.1-cw-latest.xsd that may be used in place of the official BibleTechnologies URL for validating OSIS files.
<br />See also [[OSIS_211_CR#CrossWire_updated_schema| CrossWire updated schema]].

The March 2006 version of the OSIS Manual may be found [http://www.crosswire.org/OSIS/OSIS%202.1.1%20User%20Manual%2006March2006.pdf here] (PDF).

A good example of an OSIS document can be found at http://www.crosswire.org/~dmsmith/kjv2006.
<BR>The latest releases are found under http://www.crosswire.org/~dmsmith/kjv2011/

See also [[OSIS Book Abbreviations|OSIS Book Name Abbreviations]].

==General structure==

An OSIS document is a ''well-formed XML'' document, valid according to the ''OSIS schema''.
You can the most current version [http://www.crosswire.org/~dmsmith/osis/osisCore.2.1.1-cw-latest.xsd here].<ref>See also [[OSIS Tutorial#The_Root_Element|root element]]</ref>

To produce a Bible, you can use this template:

<pre>
<?xml version="1.0" encoding="UTF-8"?>
<osis
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://www.bibletechnologies.net/2003/OSIS/namespace"
xmlns:osis="http://www.bibletechnologies.net/2003/OSIS/namespace"
xsi:schemaLocation="http://www.bibletechnologies.net/2003/OSIS/namespace http://www.bibletechnologies.net/osisCore.2.1.1.xsd">
<osisText osisIDWork="{NAME}" osisRefWork="bible" xml:lang="{LANG}" canonical="true">
<header>
{HEADER}
</header>
<div type="bookGroup">
{BODY}
</div>
</osisText>
</osis>
</pre>

With the following values:
; {NAME}: Normalized name of the Bible version (Usually 3 letters for language, 3 for translation)
; {LANG}: IETF language code-- ISO 639-1 codes are preferred, and ISO 639-3 codes are preferred when ISO 639-1 codes do not exist for the given language. See [http://www.sil.org/iso639-3/codes.asp] for a list of codes.
; {HEADER}: Description of the included text; see below
; {BODY}: Text; see below

For text without any character outside ASCII, you can use US-ASCII encoding (usually for english text). For every other language, please use UTF-8 and NFC. See the [[OSIS Bibles#Tools|tools]] section if you need to convert.

<references />
===Header===
This is the minimum contents of the header required for validation. It is also what <tt>usfm2osis.pl</tt> produces. A valid OSIS header may include more than this.
<header>
<work osisWork="{Name}"/>
</header>

===Body===

Here is the general structure of the body content:
<pre>
<div type="bookGroup">
<title>Old Testament</title>
<div type="book" osisID="Gen" canonical="true">
<title type="main" short="Genesis">Genesis</title>
<chapter osisID="Gen.1" chapterTitle="CHAPTER 1.">
<title type="chapter">CHAPTER 1.</title>
<verse sID="Gen.1.1" osisID="Gen.1.1"/>In the beginning ...
<verse eID="Gen.1.1"/>
<verse sID="Gen.1.2" osisID="Gen.1.2"/>And the earth was without form ...
<verse eID="Gen.1.2"/>
...
</chapter>
</div>
</div>
</pre>
'''Notes:'''
# The top level bookGroup division is not mandatory.
# If they are used, the bookGroup division for the New Testament should have a similar structure.
# Any '''div''' element defaults canonical to false. You need to set it to true on elements representing the structure of the original text.

===OSIS Milestones===
OSIS allows for two potentially overlapping structures: Document structure (BSP) and verse structure (BCV).

Document structure is dominated by book, sections and paragraphs (BSP), additionally with titles, quotes and poetic material. While verse structure is indicated by book, chapter and verse numbers (BCV). While a SWORD module requires verse structure, the best way to encode a module with deep markup is with document structure. [[Osis2mod]] is responsible for transforming document structure into verse structure.

Because these two systems can overlap and because XML does not allow for overlapping elements, OSIS defines a milestone mechanism for both document and verse structure elements.

For:
<X ... attribute list ...>
...
</X>
the milestoned form is:
<X sID="g1" ... attribute list .../>
...
<X eID="g1"/>

According to the OSIS manual, for any given element X that defines a milestoneable form, all the instances of X in the document must use one form or the other and may not use both. The value of each sID attribute must be unique within the document.

Verse milestone sID/eID attributes can even have values that denote a verse range. This is purely for convenience to human readers.

It is allowable to use milestone elements for verses alone, or for both verses and chapters. The body example above is for the former.

Although, the order of sID and osisID attributes within a milestone element is insignificant (as is the case for XML attributes in general), it helps for human readability to have the sID element first, such that it might be aligned with the corresponding eID element, as in the body example above.

==== Limitations of XML validators ====

An [[OSIS Bibles#Valid_OSIS_test|XML validator]] cannot validate whether OSIS milestones are used properly. It cannot validate:
* that an element is consistently either milestoned or not.
* that for each element with an sID that there is a paired element with an eID.<ref>osis2mod does not crash if the eID milestones are all missing, but the resulting module may appear to be void of text.</ref>
* that each paired sID/eID have the same attribute value.
* that different sID/eID pairs of the same element type do not overlap.<ref>If they weren't milestones, one would say they should be properly nested.</ref>
* that the values of the osisID attributes are valid and correspond to the text demarcated by the verse milesones, etc.

'''Notes:'''
<references />

==== Notes about OSIS elements ====
* For an OSIS document to be valid it must use the non-milestoned <div> and <lg> elements.
* There is no milestoned version of the <p> element. From a practical perspective, this means that the milestoned verse element should be used when paragraphs are used.
* The milestoned chapter element must be used when the paragraph is spanning over a chapter.
* The SWORD engine cannot handle sub-identifiers separated by ! in an osisID, so osis2mod strips these off from the osisIDs for verses. They are only of use for the osisIDs for notes.

===Recommended approach===
* For chapters, use <chapter>...</chapter> container elements (except in the rare case that other container elements cross chapter boundaries)<ref>Conversion scripts such as [[Converting SFM Bibles to OSIS#usfm2osis.py|usfm2osis.py]] generally produce the milestone elements for chapters.</ref>
* For verses, use milestone elements (unless container elements will suffice) – see [[OSIS Bibles/BSPExample]].
* For paragraphs, use the <p>...</p> container element
* For poetry, use container elements <lg>...</lg> to indicate stanzas (or other types of line groups) and <l>...</l> to indicate lines
* For quoted text, use the <q>...</q> container element
* For translation changes, use the <transChange>...</transChange> container element<ref>Except where the text is within a <w> which is not allowed by OSIS. For these cases use the alternative <seg subType="x-added" type="x-transChange">...</seg> </ref>

<references />

==Examples==
===Marking Paragraphs===
There is no milestoned version of the <tt><p></tt> element. Typically paragraphs surround whole verses. That is, they start and end between verses. If a paragraph begins or ends in a verse and extends beyond that verse, then the whole document must use the milestoned version of <tt><verse></tt>.
<pre>
<div type="book" osisID="Gen" canonical="true">
<title type="main">LE PREMIER LIVRE DE MOÏSE dit LA GENÈSE</title>
<chapter osisID="Gen.1" chapterTitle="Chapitre 1"><title type="chapter">Chapitre 1</title>
<p>
<verse sID="Gen.1.1" osisID="Gen.1.1" n="1"/>Au commencement Dieu créa les
cieux et la terre.<verse eID="Gen.1.1"/>
</p>
<p>
<verse sID="Gen.1.2" osisID="Gen.1.2" n="2"/>Et la terre était désolation et
vide, et il y avait des ténèbres sur la face de l'abîme. Et l'Esprit de Dieu
planait sur la face des eaux.<verse eID="Gen.1.2"/>
</p>
<p>
<verse sID="Gen.1.3" osisID="Gen.1.3" n="3"/>Et Dieu dit : Que la lumière
soit. Et la lumière fut.<verse eID="Gen.1.3"/>
<verse sID="Gen.1.4" osisID="Gen.1.4" n="4"/>Et Dieu vit la lumière, qu'elle
était bonne ; et Dieu sépara la lumière d'avec les ténèbres.
<verse eID="Gen.1.4"/>
<verse sID="Gen.1.5" osisID="Gen.1.5" n="5"/>Et Dieu appela la lumière Jour ;
et les ténèbres, il les appela Nuit. Et il y eut soir, et il y eut matin :
&#8212; premier jour.<verse eID="Gen.1.5"/>
</p>
...
</pre>

{| border="1"
|+Result
|
<sup>'''(1)'''</sup> Au commencement Dieu créa les cieux et la terre.

<sup>'''(2)'''</sup> Et la terre était désolation et vide, et il y avait des ténèbres sur la face de l'abîme. Et l'Esprit de Dieu planait sur la face des eaux.

<sup>'''(3)''' </sup>Et Dieu dit : Que la lumière soit. Et la lumière fut. <sup>'''(4)'''</sup> Et Dieu vit la lumière, qu'elle était bonne ; et Dieu sépara la lumière d'avec les ténèbres. <sup>'''(5)'''</sup> Et Dieu appela la lumière Jour ; et les ténèbres, il les appela Nuit. Et il y eut soir, et il y eut matin : — premier jour.
|}

Note: [[osis2mod]] converts a paragraph start into <tt><div type="paragraph" sID="genX"/></tt> and a paragraph end into <tt><div type="paragraph" eID="genX"/></tt>.

===Marking Quotations===
Most of the SWORD front-end applications can show a chapter at a time and some can show isolated verses. This means that all of the SWORD applications can show partial quotations, such as the Sermon on the Mount which begins in Matt 5 and ends in Matt 7.

====Default quotation marks====
By default, SWORD will use <tt>"</tt> for quotations. The following describes various ways to influence this.

====Indicating the nesting of a quote====
When a quote is contained in a quote, it is customary to set the level attribute to indicate the depth of the nesting. For example, Jeremiah 23:38 is part of a larger quote and has a back and forth dialog of nested quotes:

<pre>
But if you say,
<q level="2" sID="1"/>
The burden of the Lord,
<q level="2" eID="1"/>
thus says the Lord,
<q level="2" sID="3"/>
Because you have said these words,
<q level="3" sID="4"/>
The burden of the Lord,
<q level="3" eID="4"/>
when I sent to you, saying,
<q level="3" sID="5"/>
You shall not say,
<q level="4" sID="6"/>
The burden of the Lord,
<q level="4" eID="6"/>
<q level="3" eID="5"/>
</pre>
A couple of things to note about this verse. First, the level attribute is on both the sID and the eID pair, matching in value. Second, this is an example of a verse that has a quote that starts in the middle and finishes in another verse.

In this case, SWORD will use the level to determine whether to use <tt>"</tt> or <tt>'</tt> for quotes. Odd levels will use <tt>"</tt> and even levels will use <tt>'</tt>. This is in accordance with American English usage, which is the opposite of British English usage. Nesting levels up to five can be found in the Bible.<ref>Jeremiah 27:1-11; 29:1-28, 30-32; 34:1-5; and Ezekiel 1-36</ref>

<references />

====Supplying alternative quotation marks====
The quote element has a marker attribute that can be used to control the quotation marks. SWORD applications will always use this value when rendering the quote. When the marker attribute is the null string, it will render no quotation mark at all.<ref>e.g. The KJV module has <tt>marker=""</tt> because the text of the KJV Bible does not use any quotation marks.</ref>

To specify "curly" quotes you can use the following values:
{|border=1
!Description!!Char!!HTML Entity!!Unicode
|-align=center
|Opening double quote||“||&#8220;||U+201C
|-align=center
|Closing double quote||”||&#8221;||U+201D
|-align=center
|Opening single quote||‘||&#8216;||U+2018
|-align=center
|Closing single quote||’||&#8217;||U+2019
|}

To use different marks to start and end a quote, use the milestoned version of the quote.
<q marker="“" sID="qN"/> ... <q marker="”" eID="qN"/>

There is further information about English quotation marks and their usage in [http://en.wikipedia.org/wiki/Quotation_marks].

Quotation marks have a variety of forms in different languages and in different media. See [http://en.wikipedia.org/wiki/Quotation_mark,_non-English_usage Quotation mark, non-English usage].<ref>When modules are being converted from digitized source text used in other Bible software, it may be the case that quotation marks in the text source differ from those in the original published edition, whether due to inherent constraints of the other software, or for other causes.</ref>

'''Note:'''
<references />

====Continuation quotation marks====
The <tt><milestone type="cQuote"/></tt> can be used to indicate the presence of a continued quote. If the marker attribute is present, it will use that otherwise it will use a straight double quote, ". Since there is no level attribute on the milestone element, it is best to specify the marker attribute.

====Marking the Words of Christ====
To indicate that a quote is something that Jesus said<ref>http://en.wikipedia.org/wiki/Red_letter_edition</ref>, use the attribute <tt>who="Jesus"</tt>.

<pre>
<verse osisID="Luke.22.35 sID="Luke.22.35"/>
Then Jesus asked them, <q who="Jesus" marker="">When I sent you without purse,
bag or sandals, did you lack anything?</q>
<verse eID="Luke.22.35"/>
</pre>

{| border="1"
|+Result
|
Then Jesus asked them, <span style="color:#A00">When I sent you without purse, bag or sandals, did you lack anything?</span>
|}

'''Note:'''
<references />

===Marking poetic material===
Poetry is marked up with <lg>, line group, and <l>, line, elements. The line element supports indentation with the level attribute. When the level attribute is not present or it is level="1", this should be interpreted as the first level of the line group. When level="2" it is indented relative to level="1". The same is true for each subsequent level.

The level attribute is used to indicate indentation. A value of 1 means no indentation, the same as not specifying a level attribute. A value of 2 means to indent one. And so forth.

<pre>
<chapter osisID="Exod.15" chapterTitle="Chapitre 15"><title type="chapter">Chapter 15</title>
<p>
<verse sID="Exod.15.1" osisID="Exod.15.1" n="1"/>
Then sang Moses and the children of Israel this song unto the LORD, and spake, saying,
</p>
<lg>
<l level="1">I will sing unto the LORD, for he hath triumphed gloriously:</l>
<l level="2">the horse and his rider hath he thrown into the sea.</l>
<verse eID="Exod.15.1"/>

<verse sID="Exod.15.2" osisID="Exod.15.2" n="2"/>
<l level="1">The LORD is my strength and song, and he is become my salvation:</l>
<l level="2">he is my God, and I will prepare him an habitation;</l>
<l level="2">my father's God, and I will exalt him.</l>
<verse eID="Exod.15.2"/>

<verse sID="Exod.15.3" osisID="Exod.15.3" n="3"/>
<l level="1">The LORD is a man of war:</l>
<l level="2">the LORD is his name.</l>
<verse eID="Exod.15.3"/>

<verse sID="Exod.15.4" osisID="Exod.15.4" n="4"/>
<l level="1">Pharaoh's chariots and his host hath he cast into the sea:</l>
<l level="2">his chosen captains also are drowned in the Red sea.</l>
<verse eID="Exod.15.4"/>

<verse sID="Exod.15.5" osisID="Exod.15.5" n="5"/>
<l level="1">The depths have covered them:</l>
<l level="2">they sank into the bottom as a stone.</l>
<verse eID="Exod.15.5"/>
...
</pre>

{| border="1"
|+Result
|
<sup>'''(1)'''</sup> Then sang Moses and the children of Israel this song unto the LORD, and spake, saying,

::''I will sing unto the LORD, for he hath triumphed gloriously:''
::::''the horse and his rider hath he thrown into the sea.''

::<sup>'''(2)'''</sup> ''The LORD is my strength and song, and he is become my salvation:''
::::''he is my God, and I will prepare him an habitation;''
::::''my father's God, and I will exalt him.''

::<sup>'''(3)'''</sup> ''The LORD is a man of war:''
::::''the LORD is his name.''

::<sup>'''(4)'''</sup> ''Pharaoh's chariots and his host hath he cast into the sea:''
::::''his chosen captains also are drowned in the Red sea.''

::<sup>'''(5)'''</sup> ''The depths have covered them:''
::::''they sank into the bottom as a stone.''
|}

'''Note:'''

# While OSIS defines a milestoned version of the <tt><lg></tt> element, its use (rather than the container version) will not produce a valid XML document. The <tt><l></tt> element can only occur within an <tt><lg></tt> container, so use of <tt><lg/></tt> milestones prevents use of <tt><l></tt> elements.

==== Marking acrostic poetry headings ====
Use <tt>type="acrostic"</tt> as the title attribute for the stanza headings in acrostic passages such as Psalm 119. Whether or not this Psalm uses a poetry line group for each stanza, each title element should be placed before its related stanza.

=== Marking lemmas & morphology ===
====Marking Strong's numbers====
To mark up [http://en.wikipedia.org/wiki/Strong%27s_Concordance Strong's numbers], you first need to declare a workID in the header of the OSIS document:
<pre>
<header>
...
<work osisWork="strong">
<refSystem>Dict.Strongs</refSystem>
</work>
...
</header>
</pre>

SWORD does not actually use this declaration, but it is required to have a proper OSIS document.

And while OSIS allows arbitrary workIDs, SWORD can only handle "strong" and a few variants.

<pre>
<w lemma="strong:H0853 strong:H03045">knew</w>
</pre>

The <w> element is used to surround the text that is represented by the Strong's number. It may be that the text is a phrase and it may be that more than one Strong's number defines the text.

When more than one Strong's number defines the text, each must be prefixed with a workID and must be separated from each other by a space. (While OSIS allows for the defining of default workIDs, SWORD requires that the workIDs be used.)

The actual Strong's Number should indicate whether it is Hebrew (H) or Greek (G) followed by the number. The number may be 0 padded up to 5 digits as in H00001.

====Marking morphology====
In a similar manner to marking with Strong's numbers, morphology can also be noted. Since morphology regards the original language, Strong's numbers will be shown at the same time.

As with Strong's numbers, a workID needs to be defined. Here we are defining one for Robinson's Morphology Codes. And while SWORD will ignore this declaration, "robinson" is hard-coded into SWORD for Greek morphology codes.
<pre>
<header>
...
<work osisWork="robinson">
<refSystem>Dict.Robinson</refSystem>
</work>
...
</header>
</pre>

Example markup of Robinson's Morphology Codes in the KJV module:
<pre>
<w lemma="strong:G3588 strong:G80" morph="robinson:T-APM robinson:N-APM" src="7 8">his brethren</w>
</pre>
In this example, lemma, morph and src form parallel arrays. The first strong: mapping to the first robinson: and the first src value, etc.

The workID should be name of a current, future, or potential lexicon module in which the morphology code could be looked up. For example, morph="packard:D" represents a reference to morphology code "D" in a module named Packard, whether or not a Packard module has been created or released. (Currently, SWORD offers lexicon modules named Robinson and Packard, both for Greek morphology.)

The src attribute is used here to indicate the word position in the original Greek.

====Marking other lemmas====
The lemma attribute of the <tt><w></tt> element can contain any number of other lemmas. Like Strong's numbers and morphology codes, these need to have a workID declared in the header. SWORD presumes that these lemma workIDs all start with "lemma." (note the final period). The portion of the workID following "lemma." should be name of a current, future, or potential lexicon module in which the lemma could be looked up. For example, lemma="lemma.TWOT:271" represents a reference to lemma #271 in a module named TWOT (i.e the Theological Workbook of the Old Testament), whether or not a TWOT module has been created or released. As far as SWORD is concerned, there can be any number of these space-delimited values in a lemma attribute and they can be in any order, even interspersed among the "strong:" lemmas.

Example of a lemma markup for the Greek words from the [https://en.wikipedia.org/wiki/Textus_Receptus TR] in the KJV module:
<w lemma="strong:G976 lemma.TR:βιβλος" morph="robinson:N-NSF" src="1">The book</w>

SWORD has the ability to show or hide non-Strong's lemmas as a group. See [[DevTools:conf Files#Elements_required_for_proper_rendering|GlobalOptionFilter=OSISLemma]] – for OSIS texts having lemmas.

==== Marking glosses ====
Gloss markup uses the <tt>gloss</tt> attribute of the <tt><w></tt> element. The syntax is illustrated by this line exported from the module JapMeiji.
<pre>
<w gloss="はじめ">元始</w>に<w gloss="かみ">神</w><w gloss="てんち">天地</w>を<w gloss="つくり">創造</w>たまへり
</pre>
Display of glosses can be toggled (in [[Choosing a SWORD program#Module_Support|compatible front-ends]]) by having this line in the [[DevTools:conf Files#Elements_required_for_proper_rendering|.conf file]]:
GlobalOptionFilter=OSISGlosses
==== Marking encoded transliterations ====
Transliteration markup uses the xlit attribute of the <w> element. The syntax is illustrated by this line exported from the module SP.
<w gloss="in_beginnings" lemma="strong:H7225" morph="ב_ראשית" n="1" xlit="Latn:b_raShit">בראשית</w>
Display of encoded transliterations can be toggled (in [[Choosing a SWORD program#Module_Support|compatible front-ends]]) by having this line in the [[DevTools:conf Files#Elements_required_for_proper_rendering|.conf file]]:
GlobalOptionFilter=OSISXlit
==== Marking enumerated words ====
Enumerated words markup uses the n attribute in the <w> element. The syntax is illustrated in the previous subsection.

Display of enumerated words can be toggled (in [[Choosing a SWORD program#Module_Support|compatible front-ends]]) by having this line in the [[DevTools:conf Files#Elements_required_for_proper_rendering|.conf file]]:
GlobalOptionFilter=OSISEnum

==== Marking morpheme segmentation ====

In languages such as Biblical Hebrew, parts of words may be split into semantic segments using the XML '''seg''' element, thus:

<w><seg type="x-morph">וַ</seg><seg type="x-morph">יִּקְרָ֨א</seg></w>

Display of morpheme segmentation<ref>Currently, only some JSword based front-ends seem to support this feature. The SWORD engine has the switch available, but no change in output is effected.</ref> can be toggled (in [[Choosing a SWORD program#Module_Support|compatible front-ends]]<ref>e.g. STEP Bible uses these structures to provide colour coding. It just uses 2 colours to show different parts, alternating between the two.</ref>) by having this line in the [[DevTools:conf Files#Elements_required_for_proper_rendering|.conf file]]:
GlobalOptionFilter=OSISMorphSegmentation

'''Note:'''
<references />

===Marking the divine name===
The <tt><divineName></tt> tag is reserved for representations of the tetragrammaton יהוה (YHWH). These occur in the Old Testament as <span style="font-variant: small-caps;">Lord</span>, <span style="font-variant: small-caps;">God</span> and <span style="font-variant: small-caps;">Yah</span>. Not every instance of Lord or God is a translation of this.

The content of the divineName element is the word Lord, God or Yah, not in all upper case (i.e. not LORD, GOD, or YAH). SWORD will either convert it to small-caps or uppercase.

Note, if it is the use is possessive it is permissible to have the following:
<pre>
<divineName>Lord's</divineName>
</pre>

However, it is inadvisable to include any other punctuation within the tag pair. Thus the following is '''not''' good practice (the quotation mark should ''precede'' the start tag):
<pre>
<divineName>“God </divineName> .....”
</pre>

When also marking with Strong's numbers you will need to do it one of two ways:
<pre>
<divineName><w lemma="strong:H3068">Lord's</w><divineName>
or
<w lemma="strong:H3068">of the <seg><divineName>Lord</divineName></seg></w>
</pre>

The latter form uses a workaround to allow the embedding of <tt><divineName></tt> in a <tt><w></tt>, since OSIS does not allow for this, but does allow for <tt><seg></tt> to be in a <tt><w></tt> and to contain <tt><divineName></tt>.

'''Note:''' See also [[OSIS 211 CR#Allow_.3CdivineName.3E_within_.3Cw.3E|OSIS change requests: Allow <divineName> within <w>]].

===Marking sections and titles===
A section is marked with:
<pre>
<div type="section">
...
</div>
</pre>

In OSIS the <tt><title></tt> element is used to provide general headings. Titles should be placed at the top of the container that they title, not before.
<pre>
<div type="book">
<title>A book title</title>
<chapter>
<title type="chapter">A title chapter</title>
<div type="section">
<title>A section title</title>
...
</div>
...
</chapter>
</div>
</pre>
Using <tt>type="chapter"</tt> or <tt>type="main"</tt> is needed by [[osis2mod]] to distinguish chapter titles from verse titles. When SWORD stores an OSIS document it does so as an index of verses. It has special indexes for book and chapter titles. SWORD does not store the <tt><verse></tt> tags. So when it comes to storing a title in the following verse, [[osis2mod]] generates special markup to indicate that the title stands before the verse. SWORD uses this to place the verse number.

It is recommended that chapter labels (converted from the USFM tag \cl) be coded like this (Malayalam) example:
<title type="chapter" subType="chapterLabel">൧. അദ്ധ്യായം.</title>
This ensures that these labels are not treated differently to other chapter titles.

'''Note:'''
# The <tt><head></tt> element is used to provide headings for tables, lists and cast groups. There are errors in the OSIS 2.1.1 manual that use the <tt><head></tt> incorrectly.

==== Marking pre-verse titles ====
There is no special markup for pre-verse titles. Osis2mod will determine what titles belong to the book, the chapter and otherwise if the above advice is followed.

'''Note:'''
# See also [[OSIS pre-verse titles]].

====Marking parallel passage headings====
These may be marked in a similar manner to [[OSIS Bibles#Marking_cross-references_notes|cross-reference notes]]. Example: (Welsh Beibl for Matt.3)
<pre>
<title type="parallel">(
<reference type="parallel" osisRef="Mark.1.1-Mark.1.8">Marc 1:1-8</reference>;
<reference type="parallel" osisRef="Luke.3.1-Luke.3.18">Luc 3:1-18</reference>;
<reference type="parallel" osisRef="John.1.19-John.1.28">Ioan 1:19-28</reference>)
</title>
</pre>
'''Notes:'''
# Each parallel passage has a separate reference element.
# Each reference element may have the optional attribute type="parallel".
# Each reference element has a valid osisRef attribute. Typically this is for a contiguous range of verses.
# The displayed reference for each passage uses the locale for the language.
# Reference elements are typically separated by a semicolon and space.
# The displayed title is typically enclosed within parentheses, which are not part of any reference element.
# Localized book names may or may not be abbreviated. If abbreviations are used, ideally they should be used consistently throughout the whole Bible.
# Abbreviated localized book names may or may not end with a full stop.
# The localized chapter verse separator may be other than a colon.
# The range specifier is typically a [http://en.wikipedia.org/wiki/Hyphen-minus hyphen-minus] but alternatively may be an [http://en.wikipedia.org/wiki/Dash#En_dash en dash].
# Special care is required when:
:*There is more than one passage listed for the same book, when typically the book name is given only for the first passage.
:*There is more than one passage listed for the same chapter, when typically the chapter number is given only for the first passage.
:*The parallel passage is in the same book, when typically the book name is omitted in the displayed reference.
:*The parallel passage is one or more whole chapters (or psalms), when typically the verse numbers are omitted.
:*The parallel passage is a range of verses in a "single chapter" book, when typically the chapter number is omitted.<br>Example: Jude 3-24 is sometimes used as parallel with 2 Peter 2.
:*The parallel passage is a range that spans a chapter divison, and where the range separator might even be an [http://en.wikipedia.org/wiki/Dash#Em_dash em dash] or an [http://en.wikipedia.org/wiki/Dash#En_dash en dash] rather than a hyphen-minus. Example: Exodus 35:30—36:1

===Marking notes===
The note element can appear in any element that can contain text ''outside'' of the '''header''' element.

NB. The examples in this section include the use of sub-identifiers in '''osisID'''s for notes.
<pre>
<verse sID="Gen.1.1" osisID="Gen.1.1" n="1"/>Au commencement
Dieu<note osisRef="Gen.1.1" osisID="Gen.1.1!1" n="1"><hi type="italic">en hébreu</hi> : Élohim,
(<hi type="italic">pluriel d</hi>'Éloah, le Dieu suprême), la Déité, <hi type="italic">dans
le sens absolu</hi>.</note> créa les cieux et la terre.<verse eID="Gen.1.1"/>

<verse sID="Gen.1.2" osisID="Gen.1.2" n="2"/>Et la terre était désolation et
vide<note osisRef="Gen.1.2" osisID="Gen.1.2!1" n="2">le vide.</note>, et il y avait des ténèbres
sur la face de l'abîme. Et l'Esprit de Dieu planait sur la face des eaux.<verse eID="Gen.1.2"/>
</pre>

{| border="1"
|+Result
|
# Au commencement Dieu¹ créa les cieux et la terre.
# Et la terre était désolation et vide², et il y avait des ténèbres sur la face de l'abîme. Et l'Esprit de Dieu planait sur la face des eaux.

*¹ ''en hébreu'': Élohim, (''pluriel d'''Éloah, le Dieu suprême), la Déité, ''dans le sens absolu''.
*² le vide.
|}

The note should be attached to what it refers to, either ''after'' (as is the case here) or ''before''. There should no additional space surrounding the note, but only what is in the text.

These notes can have any type other than '''crossReference'''.

For more detailed information about the '''note''' element, please refer to sections '''8.3''' to '''8.6''' of the '''OSIS Reference Manual'''.

====Notes with an annotation reference====
An OSIS file converted correctly from USFM files may contain notes with an annotation reference. The syntax should be like this:
<note placement="foot"><reference type="annotateRef" osisRef="Matt.1.19">1:19</reference> The footnote informational text is here.</note>

An annotation reference is usually generated when converting from USFM for notes containing the tag <tt>\fr </tt> or <tt>\xo </tt>.<ref>The human readable reference is typically just the chapter and verse number, as in this example.</ref>

This example is for a note tagged for a word in Matt.1.19. and it illustrates that the reference element has two attributes.
* <tt>type="annotateRef"</tt> – this defines the note as having an annotation reference
* <tt>osisRef="Matt.1.19"</tt> – this specifies the origin of the note, and makes the "1:19" display as a link in the footnote panel.
The space at the start of the footnote text is required in order to separate the reference from the text.

'''Note:'''
<references />

====Marking cross-references notes====
SWORD provides the ability for a user to show or hide cross-references. To achieve this you embed one or more <tt><reference></tt> elements in a <tt><note type="crossReference">...</note></tt>. If this is not done, then the cross-references will always show inline in the text.

<pre>
<note type="crossReference" n="t" osisID="Jer.24.7!crossReference.t">
<reference osisRef="Jer.32.39">ch. 32:39</reference>;
<reference osisRef="Deut.30.6">Deut. 30:6</reference>;
<reference osisRef="Ezek.11.19">Ezek. 11:19</reference>;
<reference osisRef="Ezek.36.26-Ezek.36.27">36:26, 27</reference>.
</note>
</pre>

Here is a breakdown.

Regarding the <tt><note></tt> element:

:<tt>type="crossReference"</tt> is one of the predefined OSIS note types. SWORD looks for this value to show/hide cross-references.

:<tt>n="t"</tt> is the marker for the cross-reference note. This can be either of the following:
:# A serially allocated index letter in the range <tt>a-z</tt>.
:# A custom xref note marker symbol (or scheme) as may be specified by the author/translator.
:btw. Source text [[Converting SFM Bibles to OSIS|converted from USFM]] usually adopts method 1.

:The given '''osisID''' is based upon the location of the note. In order to not conflict with the verse's osisID and to construct a unique id, the ! (extension mark, ''aka'' sub-identifier) syntax is used. This is further qualified by the note's '''type''' and '''n''' value, separated by a dot.

:Observe the punctuation marks between references and (optionally) after the last reference. There is typically a space after each semicolon.

:This note pertains to a single verse and it is given an '''osisRef'''.

Regarding the <tt><reference></tt> elements:

:The <tt><reference></tt> element is replaced by SWORD with a link to the reference with the text of the element being shown as link text.<ref>Some front-ends (e.g. Xiphos, PocketSword) never display the raw cross-reference text (the original text wrapped within each '''reference''' element. Instead they display a preview of each cross-referenced linked verse.</ref>

:While the '''osisRef''' can point to multiple verses, most SWORD applications cannot handle a link that goes to more than one verse or a contiguous range of verses. Xiphos (for example) just generates a verse list in the side panel.

:Here we see that each '''reference''' element is separated by punctuation (the semicolon at the end of each line).

Some of the notes given under [[OSIS Bibles#Marking_parallel_passage_headings|Marking parallel passage headings]] are also applicable here.

For non-English Bibles, the punctuation marks used as separators in displayed Scripture references can be different. Even with English, there can be variations between Bible versions.

Special care is required when the cross-reference includes additional prose text which is not a scripture reference. This often arises in [[Converting SFM Bibles to OSIS|Bibles converted from SFM]]. Unless and until this issue is fixed, it becomes almost impossible to parse the reference elements such that the OSIS references can be added automatically.

Further care is often required to deal with minor errors of punctuation that translators are prone to make in footnotes with cross-references.

'''Note:'''
<references />

====Marking references in Right to Left scripts====
To ensure that the ''human readable'' reference is correctly displayed in Bibles with a '''Right to Left''' script, the translator[s] may have made judicious use of the special Unicode character '''RIGHT TO LEFT MARK''' ['''RLM'''] (U+200F).

The RLM being invisible, its presence may easily go unnoticed, yet script developers need to be aware of it. The procedure to convert the ''human readable'' reference to the ''machine readable'' '''osisRef''' value must ensure that the RLM is deleted from the latter.

=====Technical details=====
The key to understanding this is the exact placements of the '''RLM''' in references in a RtoL script.

* before the colon separator between chapter and verse
* before the hyphen/minus (or endash) used as the verse range separator
* before an ''ordinary'' comma between verse numbers in a list (not required when the ''Arabic'' comma is used)
* before the chapter number in the caller reference, because that becomes the start of the displayed footnote in SWORD apps.

'''Example:'''

Here's a '''note''' element in the OSIS source: (of the UrduGeo module)

<code>
<note placement="foot"><reference type="annotateRef" osisRef="2Kgs.12.4">‏12‏:4</reference> <catchWord>مردم شماری کے ٹیکس: </catchWord>دیکھئے <seg type="x-nested"><reference osisRef="Exod.11.16-Exod.11.30">خروج 11‏:16‏-30</reference></seg> </note>
</code>

Here's the same Unicode text converted to PCRE.

<code>
<note placement="foot"><reference type="annotateRef" osisRef="2Kgs.12.4">\x{200F}12\x{200F}:4</reference> <catchWord>\x{0645}\x{0631}\x{062F}\x{0645} \x{0634}\x{0645}\x{0627}\x{0631}\x{06CC} \x{06A9}\x{06D2} \x{0679}\x{06CC}\x{06A9}\x{0633}: </catchWord>\x{062F}\x{06CC}\x{06A9}\x{06BE}\x{0626}\x{06D2} <seg type="x-nested"><reference osisRef="Exod.11.16-Exod.11.30">\x{062E}\x{0631}\x{0648}\x{062C} 11\x{200F}:16\x{200F}-30</reference></seg> </note>
</code>

Observe the '''four''' instances of <code>\x{200F}</code> which is the '''RLM''' described above.

:''Further details to be added to illustrate the footnote as displayed in Xiphos.''

===Marking variants===
SWORD recognizes the element '''seg''' with '''type="x-variant"''' as marking variants present in different versions of a text<ref>This feature requires the front-end to have been compiled with SWORD version 1.7 or later.</ref>. The attribute '''subType''' should be added, with a value of '''"x-1"''' or '''"x-2"''' to indicate whether the reading is the primary or secondary variant. At present, SWORD supports only 2 different readings per text. The method is illustrated below:
<pre>
The text of the Bible
<seg type="x-variant" subType="x-1">may </seg>
<seg type="x-variant" subType="x-2">can </seg>
contain variant readings.
</pre>
This illustrates a primary reading "may " and a secondary reading "can ". Observe the space included in both seg elements. If these spaces were omitted, the variant words would be joined when displaying all readings.

==== Filter ====
Variant readings in OSIS modules may be switched by the SWORD engine when the module conf file includes:
GlobalOptionFilter=OSISVariants
'''Note:'''
<references/>

==== Examples ====
* The TR module contains 246 locations where two such variants are marked.
* The WHNU module contains 1473 locations where two variants are marked.

==== SWORD implementation ====
The SWORD API provides for these three choices:
[Primary Reading|Secondary Reading|All Readings]
Example: In Xiphos version 3.1.6 or later, the module context menu provides these three options for any module that has variants.

SWORD does not supply its own delimiters to distinguish between variants. When displaying text that contains variants, it may not be obvious where these are located.

==Tools==

===Bible Technologies Group===
The '''BTG''' that sponsored the OSIS committee and hosted the OSIS schema no longer exists.
References below that use the domain '''www.bibletechnologies.net''' will no longer work.
The schema location therefore now needs to be for a local copy on your computer or to a copy hosted by CrossWire or elsewhere.

For more up to date details, see [[OSIS 211 CR]] which includes CrossWire's own updated schema.

===Valid OSIS test===
A valid XML document one that is well-formed and conforms to the formal definition provided in a schema (or DTD). A document cannot have elements, attributes, or entities not defined in the schema. A schema can also define ''how'' entities may be nested, the possible values of attributes, etc.

Many programs capable of schema validation exist. Most [http://en.wikipedia.org/wiki/XML_editor XML editors] ([http://xml-copy-editor.sourceforge.net/ XML Copy Editor], [http://en.wikipedia.org/wiki/Oxygen_XML_Editor Oxygen], [http://en.wikipedia.org/wiki/XMLSpy XMLSpy], [http://www.topologi.com/ Topologi], etc.) support some sort of XML schema validation. The Windows based text editor [http://en.wikipedia.org/wiki/Notepad%2B%2B Notepad++] supports Unicode and has an [https://github.com/morbac/xmltools XML Tools] plugin which can perform syntax checking and validation.

There are also some online facilities for XML validation, e.g. [http://www.freeformatter.com/xml-validator-xsd.html].

====xmllint====
libxml2, available for Linux, Windows, & MacOS, includes a command-line validator called xmllint. To check that a document is valid against OSIS schema, use the following command.
<pre>
$ xmllint --noout --schema http://crosswire.org/osis/osisCore.2.1.1.xsd myfile.osis.xml
</pre>

'''Notes:'''
# Internet access is required to validate your document using a remote schema.
# Even if you use a local copy of the OSIS schema, it calls on [http://www.w3.org/XML/1998/namespace] via HTTP.
# Having a VPN connection may sometimes interfere with the use of XML validation tools.
# Some firewalls or proxies also prevent or interfere with the use of these tools.

To install xmllint, simply install libxml2 via your distribution's standard package management system in Linux or download the Windows binary from our [http://www.crosswire.org/ftpmirror/pub/sword/utils/win32/ mirror]. You also need to install "libxml2-utils". In this last package is program "xmllint".

====lxml (Python)====
[http://lxml.de/ lxml] is a toolkit that can be used within a Python script to validate an XML file.

"The lxml XML toolkit is a Pythonic binding for the C libraries libxml2 and libxslt."

====Online XML Validators====
The external links section of http://en.wikipedia.org/wiki/XML_Validation lists at least three online validators. Some or all of these can validate against external XML schema.

==Creating a SWORD Module==
Use [[osis2mod]] to create the module.

== See also ==
*[[OSIS]] – a partial list of other OSIS related pages and external links.

*[[Converting SFM Bibles to OSIS]] – describes how to prepare a single OSIS XML file for a Biblical text supplied as several USFM files.

== External links ==

* [http://en.wikipedia.org/wiki/List_of_Bible_verses_not_included_in_modern_translations List of Bible verses not included in modern translations]

* [http://xml.coverpages.org/DeRoseEML2004.pdf Markup Overlap: A Review and a Horse] – Steven DeRose (2004) Bible Technologies Group.

[[Category:Guides|OSIS Bibles]]

[[Category:OSIS|OSIS Bibles]]

[[Category:Morphology|OSIS Bibles]]

Main Page

2020-06-13T19:37:18Z

Domcox: /* Module development */ Add guide to XML validation

{| cellspacing="1" width="100%"
|- valign="top"
|style="border: 1px solid green;padding-left:1em;padding-right:0.5em;background:#E4FFDF;padding-bottom:0.5em;" width="100%"|
==Welcome to the CrossWire developers' wiki==

Check out our [[Current Projects|current projects]] page to see how you might use your skills. Please also look at our general [[Volunteers|volunteering]] page.

If you want to help in this wiki, please [mailto://support@crosswire.org request] an account.

Here is the [http://tracker.crosswire.org bugs] database. Chat with SWORD developers on IRC: [http://webchat.freenode.net/?randomnick=1&channels=sword&prompt=1 #sword] on FreeNode.

|}
{| cellspacing="1" width="100%"
|- valign="top"

| style="background:#E8F1FF;border-style:solid;border-width:1px;border-color:#00ccFF;padding-left:1em;padding-right:0.5em; padding-bottom:0.5em;" width="50%"|

==Front-end Bible study applications==

===SWORD based front-ends===
* [[Frontends:BibleCS|The SWORD Project for Windows]] (internally known as BibleCS)
* [[Frontends:Eloquent|Eloquent]] MacOS application
* [[Frontends:Xiphos|Xiphos]] Windows and Linux Desktop application
* [[Frontends:BibleTime|BibleTime]] Windows and Linux Desktop application
* [[Frontends:The_Bible_Tool|The Bible Tool]] – web server application
* [[Frontends:PocketSword|PocketSword]] iOS application
* [[Frontends:Bishop|Bishop]] Android & iOS application
* [[Frontends:Holy Bible|Holy Bible]] Windows Desktop application
* [http://www.godehardt.org/losung.html GLosung] – Gottes Wort für deinen Desktop
* [[Frontends:Ezra Project|Ezra Project]] Windows, Linux, macOS Desktop application

===JSword based front-ends===
* [[Frontends:BibleDesktop|BibleDesktop]]
* [http://www.kiyut.com/products/alkitab/ Alkitab Bible Study]
* [[Frontends:GSword|GSword]] – CCIM Online Bible Studio
* [https://mjdenham.github.io/and-bible/ And Bible] – for Android OS
* [http://www.stepbible.org/ STEP Bible] – developed at [http://www.tyndale.cam.ac.uk/ Tyndale House]

=== Front-ends in general ===
* [[Choosing a SWORD program]]
* [[Frontends:No longer being actively developed|Front-ends no longer being actively developed]]

==SWORD module sources==
* [[Official and Affiliated Module Repositories]]
* [[Other Module Sources]]
* [[Creating and Maintaining a Module Repository]]

==Public relations, website, user assistance==
* [[Contact| Contact us]]
* CrossWire's [[Copyright|copyright]] policy
* [[EnduserFAQ|Frequently Asked Questions]]
* [[Help:Contents|Help]], [[Help:Bugs|Bugs]] and [[Help:Mailing Lists|Mailing Lists]]
* [[SWORD CD]]

|valign="top" bgcolor="#FFE8E8" style="border-style:solid;border-width:1px;border-color:#FF6060;padding-left:1em;padding-right:0.5em; padding-bottom:0.5em;" width="50%"|

==Back-end API development tools==
* [[DevTools:SWORD|SWORD Engine (C++)]]
** Compiling and installing SWORD
*** on [[Tutorial:Compiling & Installing SWORD| Linux/MacOS/Unix]]
*** on or for [[Tutorial:Compiling & Installing SWORD on Windows|Windows]]
*** with [[DevTools:CMake|CMake]]
** [[:DevTools:Code Examples|Code Examples]]
** [[Tutorial:How SWORD works]]
** [[DevTools:Locale Files|Locale Files]]
** [[DevTools:Bindings|SWIG Bindings]], [[DevTools:CSharp Bindings on Windows|C# Bindings on Windows]], [[DevTools:JNI Bindings for Android|Android Bindings]]
** bug reports with or without appended patches to our [http://tracker.crosswire.org/projects/API/issues/API-119?filter=allopenissues|bug tracker]
* [[DevTools:JSword|JSword Engine (Java)]]
** [[DevTools:JSword/Personal Commentary|Personal Commentary]]
** [[DevTools:JSword/Internationalization|Internationalization]]

==Open Scriptures Information Standard==
* A basic [[OSIS Tutorial|OSIS XML tutorial]]
* [[OSIS 211 CR| OSIS 2.1.1 schema change requests]]
* [https://www.crosswire.org/~dmsmith/osis/osisCore.2.1.1-cw-latest.xsd OSIS schema]
* [[List of eXtensions to OSIS used in SWORD]]

==Ancillary software==
* [[BibleSync]] – for Bible software shared co-navigation
* [[DevTools:ICU|International Components for Unicode (ICU)]]

== Development proposals and discussions ==
* [[Whiteboard]]

==Module development==
* How to create [[DevTools:Modules|SWORD Modules]] & [[DevTools:conf Files|Module Configuration Files]]
* Guides to writing
**[[OSIS Bibles]], [[OSIS Commentaries]],
**[[OSIS Genbooks]], [[TEI Dictionaries]]
* Guide to [[Validate_OSIS_or_TEI_text]]
* Guide to [[Converting SFM Bibles to OSIS]]
* About [[Alternate Versification|Bible Versification]] schemes
* About [[File Formats]] and related [[File Formats#The_SWORD_Project_Utilities|Utility Programs]]
* About Unicode [[Encoding]]s, [[Fonts]] & [[DevTools:Text Editors|Text Editors]]
-----
* [[Module Development Collaboration]]
* [[Notes on particular CrossWire modules]]
* [[Module Requests]] and [[Non-CrossWire Text-Development Projects|Text Development]]
* [[Module Submission]]

|}
{| cellspacing="1" width="100%"
|- valign="top"
|style="border: 1px solid gray;padding-left:1em;padding-right:0.5em;background:#E8E8E8;padding-bottom:0.5em;" width="100%"|

==Getting started in wiki collaboration==
A wiki is a place to share documentation and development information.
* New user account [mailto://support@crosswire.org|requests] are now moderated. Anyone who has been a member for at least 4 days can edit a wiki once they have [[Special:Userlogin|logged in]].
* If you are new to wikis, consult the [http://meta.wikipedia.org/wiki/MediaWiki_User's_Guide User's Guide] or the [http://www.mediawiki.org/wiki/Help:FAQ MediaWiki FAQ] for information on using the wiki software .
* Look to see what might need attention by visiting [[Wiki Maintenance]]
* You may experiment with wiki using our [[CrossWire:Sandbox|Sandbox]].
* Another way to navigate the wiki is to click on [[:Category:Categories]].

|}

[[Category:CrossWire]]
[[Category:SWORD Frontends]]
[[Category:SWORD]]
[[Category:JSword]]
[[Category:OSIS]]
[[Category:Modules]]
[[Category:Development tools]]
[[Category:Support]]
__NOTOC__

Validate OSIS or TEI text

2020-06-08T19:11:27Z

Domcox: /* Emacs */

= Syntax Check and Valid OSIS/TEI files =

An OSIS or TEI test is an XML Document that must be:
# <b>Well formed</b>, it means that its syntax must conforms to the XML specs. An XML file that is not well formed is not an XML file.
# <b>Valid</b>. A valid XML document is well-formed and conforms to the formal definition provided in a schema (or DTD). A document cannot have elements, attributes, or entities not defined in the schema. A schema can also define how entities may be nested, the possible values of attributes, etc.

There are online facilities for XML validation, many programs capable of schema validation exist and most [http://en.wikipedia.org/wiki/XML_editor XML editors] ([http://xml-copy-editor.sourceforge.net/ XML Copy Editor], [http://en.wikipedia.org/wiki/Oxygen_XML_Editor Oxygen], [http://en.wikipedia.org/wiki/XMLSpy XMLSpy], [http://www.topologi.com/ Topologi], etc.) support some sort of XML schema validation.

= Bible Technologies Group =
The '''BTG''' that sponsored the OSIS committee and hosted the OSIS schema no longer exists.
The schema location therefore now needs to be for a local copy on your computer or to a copy hosted by CrossWire or elsewhere.

For more up to date details, see [[OSIS 211 CR]] which includes CrossWire's own updated schema.

== Schema ==
Before validating XML files, you first need to download a schema from Crosswire.
* For OSIS encoded source files: osisCore.2.1.1-cw-latest.xsd:
:https://www.crosswire.org/~dmsmith/osis/osisCore.2.1.1-cw-latest.xsd
* For TEI encoded source files: teiP5osis.2.5.0.xsd:
:http://www.crosswire.org/OSIS/teiP5osis.2.5.0.xsd

= Online validators =
The first and simpliest option for checking an XML file is to use
online validators. They will check if your XML is both well-formed and
valid.

Here are two websites, you'll find others on the Internet.

- Core Filing XML Schema Validator
https://www.corefiling.com/opensource/schemaValidate/
Accept huge files (tested with a 5.5MB file)

- FreeFormatter Validator
https://www.freeformatter.com/xml-validator-xsd.html
The maximum size limit for file upload is 2MB

With these validators, you have to upload the XML File and the schema
(.xsd) file to the website before validating.

We no not recommend online validation, it may raises privacy
concerns with copyright texts, and although it may be fine for a one shot
validation task, it becomes quickly boring when you're creating and
editing a text and want periodically validate your work.

= CLI Validators =
When you're editing a text, one of the fastest option for checking your
XML is to use a CLI tool.

== xmllint ==
The simplest way is to use the xmllint program included with libxml2.
For Mac and Linux users, you likely already have xmllint installed.
Windows users willing to try xmllint will find interesting instructions
here:
https://techrina.net/2019/01/25/using-xmllint-program-for-windows-7/

To validate an OSIS xml file enter:

xmllint --noout --schema osisCore.2.1.1-cw-latest.xsd test.osis.xml

To validate a TEI xml file enter:

xmllint --noout --schema teiP5osis.2.5.0.xsd test.tei.xml

== xmlstarlet ==
XMLStarlet is an open source XML toolkit that you can use with Linux,
Mac or Windows. XMLStarlet is linked statically to both libxml2 and
libxslt, so generally all you need to process XML documents is one
executable file, it may be a better option for Windows users.

On Linux, xmlstarlet is available as a regular package.

For Mac or Windows, the download page is at:
http://xmlstar.sourceforge.net/download.php

To validate a TEI XML file enter:

xmlstarlet val --xsd ../../schemas/teiP5osis.2.5.0.xsd test.tei.xml

== Xerces ==
Xerces is Apache's collection of software libraries for parsing,
validating, serializing and manipulating XML. The implementation is
available in the Java, C++ and Perl programming languages, the Java
version having the most features.

=== xerces-c ===
On Ubuntu/debian, you can install xerces-c tools:

apt install libxerces-c-samples

To validate an OSIS XML file enter:

StdInParse -v=always -n -s < test.osis.xml.

You'll find the full syntax here:
https://xerces.apache.org/xerces-c/stdinparse-3.html

=== xsd-validator by Adrian Mouat ===
There isn’t a simple way to immediately run the Xerces validator in
Java from the command line. For that reason, Adrian Mouat wrote a Java
program to solve this issue.

It's called 'xsd-validator', for installing it:

Either clone the git repository at:
https://github.com/amouat/xsd-validator.git
or download xsd-validator zip from:
https://github.com/amouat/xsd-validator/releases/download/v1.0/xsdv-1.0.zip

To validate an OSIS XML file enter:

cd xsd-validator
./xsdv.sh osisCore.2.1.1-cw-latest.xsd test.osis.xml

There is also a cmd file that you can use to run xsdv from a windows Command Prompt.

For installing xsd-validator, run:

sudo ant install

= Editors Supporting Validation =
The final choice is to use an editor with validation on the fly. If
you’re doing a lot of XML editing and validation it may well be worth
looking into one of the editors listed below.

NOTE: If for any reason they do not find a schema, many editor silently fallback to only checking if the file is well-formed, which may generate false-positive results. To be sure, run the Solomon test:
Add tag <code><solomonTest /></code> in your text.
This tag conforms to the XML specifications but is not part of our schemas, so the editor must show up an error.

== Notepad++ ==

With XML Tools plugin for Notepad++, Notepad++ will allow you to clean
up unformatted files, check XML syntax function if you want just to
check your existing XML file for errors, or use Enable Auto Validation
for automatic validation of code as it is being written among other
features.

Go to the “Plugins” menu, then to “Plugin Manager”, then “Show Plugin
Manager”. Look for XML Tools in the opened window, set the checkbox,
and click the button “Install”.

You must restart Notepad ++ after installation.

== Sublime Text ==

Validate XML files on the fly with this [http://www.sublimetext.com/ Sublime Text 3] plugin:<br/>
https://packagecontrol.io/packages/Exalt

== Emacs ==

It's a little bit tricky, but you can configure Emacs to provide the
following features:

* Easy navigation
* Validation on the fly
* Auto completion

=== Use nxml-mode for editing XML ===
The first thing to do is to force Emacs to use nxml mode instead of xml
mode when editing XML files. nxml-mode uses the nXML extension to
provide automatic validation and lots of other helpful functions for
editing XML files.

Add the following lines to your ~/.emacs file:
<pre>
(setq auto-mode-alist (cons '("\\.xml$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.xsl$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.xhtml$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.page$" . nxml-mode) auto-mode-alist))

(autoload 'xml-mode "nxml" "XML editing mode" t)

(eval-after-load 'rng-loc
'(add-to-list 'rng-schema-locating-files "~/.schema/schemas.xml"))
</pre>

If you are using Emacs 24 or higher, you will also need this line that
will give you auto-completion:

(global-set-key [C-return] 'completion-at-point)

=== Set-up Crosswire Schemas ===
nxml-mode validates XML files using schemas in relaxng compact format
(.rnc). We have to convert our files from .xsd format to .rnc.

Converting XSD is a very hard task; the XSD specification is complex. It seems that available command line tools that convert from xsd (XML Schema) to rng (RelaxNG) have problems of some sort.

We use Sun RELAX NG Converter, nowadays bundled with the (Sun)
'Multi-Schema Validator' to convert .xsd to .rng, then we use trang to
convert .rng to .rnc:

Install on Fedora:
<pre>
# sudo dnf install msv-rngconv trang
</pre>
==== Convert from .xsd to .rng: ====

rngconv osisCore.2.1.1-cw-latest.xsd > osisCore.2.1.1-cw-latest.rng

==== Convert from .rng to .rnc ====
<pre>
trang -I rng -O rnc osisCore.2.1.1-cw-latest.rng osisCore.2.1.1-cw-latest.rnc
</pre>

=== Tell nxml where to find our schemas ===
We have already (see above) set the variable rng-schema-locating-files
to "~/.schema/schemas.xml

Now, we have to copy our new .rnc schemas in the .schema dir

mkdir -p ~/.schema
cp osisCore.2.1.1-cw-latest.rnc teiP5osis.2.5.0.rnc ~/.schema

and create ~/.schema/schemas.xml:
<pre>
<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
<namespace ns="http://www.crosswire.org/2013/TEIOSIS/namespace" uri="teiP5osis.2.5.0.rnc"/>
<namespace ns="http://www.bibletechnologies.net/2003/OSIS/namespace" uri="osisCore.2.1.1-cw-latest.rnc"/>
</locatingRules>
</pre>

=== Auto-completion ===
Type a < character and hit Ctrl+Enter for a list of valid tags. You can
type a few letters and hit Tab to use auto-completion. Hit Enter to
insert the given tag. This also works with attributes: simply add a
space after the tag, and hit Ctrl+Enter for attribute auto-completion.

=== Links ===
https://fedoraproject.org/wiki/How_to_use_Emacs_for_XML_editing
https://lgfang.github.io/mynotes/emacs/emacs-xml.html#sec-9
https://www.emacswiki.org/emacs/NxmlMode

= Validating from Windows Explorer =
Here is a simple application for validating XML files from within
Windows Explorer.

https://www.codeproject.com/Articles/8431/A-Simple-XML-Validator

= Python =
It's relatively straighforward to validate a file with Python:

Let's create simplest validator.py
<pre>
from lxml import etree

def validate(xml_path: str, xsd_path: str) -> bool:

xmlschema_doc = etree.parse(xsd_path)
xmlschema = etree.XMLSchema(xmlschema_doc)

xml_doc = etree.parse(xml_path)
result = xmlschema.validate(xml_doc)

return result
</pre>
then write and run main.py
<pre>
from validator import validate

if validate("path/to/file.xml", "path/to/scheme.xsd"):
print('Valid! :)')
else:
print('Not valid! :(')
</pre>

Validate OSIS or TEI text

2020-06-08T18:48:14Z

Domcox: /* Schema */

= Syntax Check and Valid OSIS/TEI files =

An OSIS or TEI test is an XML Document that must be:
# <b>Well formed</b>, it means that its syntax must conforms to the XML specs. An XML file that is not well formed is not an XML file.
# <b>Valid</b>. A valid XML document is well-formed and conforms to the formal definition provided in a schema (or DTD). A document cannot have elements, attributes, or entities not defined in the schema. A schema can also define how entities may be nested, the possible values of attributes, etc.

There are online facilities for XML validation, many programs capable of schema validation exist and most [http://en.wikipedia.org/wiki/XML_editor XML editors] ([http://xml-copy-editor.sourceforge.net/ XML Copy Editor], [http://en.wikipedia.org/wiki/Oxygen_XML_Editor Oxygen], [http://en.wikipedia.org/wiki/XMLSpy XMLSpy], [http://www.topologi.com/ Topologi], etc.) support some sort of XML schema validation.

= Bible Technologies Group =
The '''BTG''' that sponsored the OSIS committee and hosted the OSIS schema no longer exists.
The schema location therefore now needs to be for a local copy on your computer or to a copy hosted by CrossWire or elsewhere.

For more up to date details, see [[OSIS 211 CR]] which includes CrossWire's own updated schema.

== Schema ==
Before validating XML files, you first need to download a schema from Crosswire.
* For OSIS encoded source files: osisCore.2.1.1-cw-latest.xsd:
:https://www.crosswire.org/~dmsmith/osis/osisCore.2.1.1-cw-latest.xsd
* For TEI encoded source files: teiP5osis.2.5.0.xsd:
:http://www.crosswire.org/OSIS/teiP5osis.2.5.0.xsd

= Online validators =
The first and simpliest option for checking an XML file is to use
online validators. They will check if your XML is both well-formed and
valid.

Here are two websites, you'll find others on the Internet.

- Core Filing XML Schema Validator
https://www.corefiling.com/opensource/schemaValidate/
Accept huge files (tested with a 5.5MB file)

- FreeFormatter Validator
https://www.freeformatter.com/xml-validator-xsd.html
The maximum size limit for file upload is 2MB

With these validators, you have to upload the XML File and the schema
(.xsd) file to the website before validating.

We no not recommend online validation, it may raises privacy
concerns with copyright texts, and although it may be fine for a one shot
validation task, it becomes quickly boring when you're creating and
editing a text and want periodically validate your work.

= CLI Validators =
When you're editing a text, one of the fastest option for checking your
XML is to use a CLI tool.

== xmllint ==
The simplest way is to use the xmllint program included with libxml2.
For Mac and Linux users, you likely already have xmllint installed.
Windows users willing to try xmllint will find interesting instructions
here:
https://techrina.net/2019/01/25/using-xmllint-program-for-windows-7/

To validate an OSIS xml file enter:

xmllint --noout --schema osisCore.2.1.1-cw-latest.xsd test.osis.xml

To validate a TEI xml file enter:

xmllint --noout --schema teiP5osis.2.5.0.xsd test.tei.xml

== xmlstarlet ==
XMLStarlet is an open source XML toolkit that you can use with Linux,
Mac or Windows. XMLStarlet is linked statically to both libxml2 and
libxslt, so generally all you need to process XML documents is one
executable file, it may be a better option for Windows users.

On Linux, xmlstarlet is available as a regular package.

For Mac or Windows, the download page is at:
http://xmlstar.sourceforge.net/download.php

To validate a TEI XML file enter:

xmlstarlet val --xsd ../../schemas/teiP5osis.2.5.0.xsd test.tei.xml

== Xerces ==
Xerces is Apache's collection of software libraries for parsing,
validating, serializing and manipulating XML. The implementation is
available in the Java, C++ and Perl programming languages, the Java
version having the most features.

=== xerces-c ===
On Ubuntu/debian, you can install xerces-c tools:

apt install libxerces-c-samples

To validate an OSIS XML file enter:

StdInParse -v=always -n -s < test.osis.xml.

You'll find the full syntax here:
https://xerces.apache.org/xerces-c/stdinparse-3.html

=== xsd-validator by Adrian Mouat ===
There isn’t a simple way to immediately run the Xerces validator in
Java from the command line. For that reason, Adrian Mouat wrote a Java
program to solve this issue.

It's called 'xsd-validator', for installing it:

Either clone the git repository at:
https://github.com/amouat/xsd-validator.git
or download xsd-validator zip from:
https://github.com/amouat/xsd-validator/releases/download/v1.0/xsdv-1.0.zip

To validate an OSIS XML file enter:

cd xsd-validator
./xsdv.sh osisCore.2.1.1-cw-latest.xsd test.osis.xml

There is also a cmd file that you can use to run xsdv from a windows Command Prompt.

For installing xsd-validator, run:

sudo ant install

= Editors Supporting Validation =
The final choice is to use an editor with validation on the fly. If
you’re doing a lot of XML editing and validation it may well be worth
looking into one of the editors listed below.

NOTE: If for any reason they do not find a schema, many editor silently fallback to only checking if the file is well-formed, which may generate false-positive results. To be sure, run the Solomon test:
Add tag <code><solomonTest /></code> in your text.
This tag conforms to the XML specifications but is not part of our schemas, so the editor must show up an error.

== Notepad++ ==

With XML Tools plugin for Notepad++, Notepad++ will allow you to clean
up unformatted files, check XML syntax function if you want just to
check your existing XML file for errors, or use Enable Auto Validation
for automatic validation of code as it is being written among other
features.

Go to the “Plugins” menu, then to “Plugin Manager”, then “Show Plugin
Manager”. Look for XML Tools in the opened window, set the checkbox,
and click the button “Install”.

You must restart Notepad ++ after installation.

== Sublime Text ==

Validate XML files on the fly with this [http://www.sublimetext.com/ Sublime Text 3] plugin:<br/>
https://packagecontrol.io/packages/Exalt

== Emacs ==

It's a little bit tricky, but you can configure Emacs to provide the
following features:

- Easy navigation
- Validation on the fly
- Auto completion

=== Use nxml-mode for editing XML ===
The first thing to do is to force Emacs to use nxml mode instead of xml
mode when editing XML files. nxml-mode uses the nXML extension to
provide automatic validation and lots of other helpful functions for
editing XML files.

Add the following lines to your ~/.emacs file:
<pre>
(setq auto-mode-alist (cons '("\\.xml$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.xsl$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.xhtml$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.page$" . nxml-mode) auto-mode-alist))

(autoload 'xml-mode "nxml" "XML editing mode" t)

(eval-after-load 'rng-loc
'(add-to-list 'rng-schema-locating-files "~/.schema/schemas.xml"))
</pre>

If you are using Emacs 24 or higher, you will also need this line that
will give you auto-completion:

(global-set-key [C-return] 'completion-at-point)

=== Set-up Crosswire Schemas ===
nxml-mode validates XML files using schemas in relaxng compact format
(.rnc). We have to convert our files from .xsd format to .rnc.

We use Sun RELAX NG Converter, nowadays bundled with the (Sun)
'Multi-Schema Validator' to convert .xsd to .rng, then we use trang to
convert .rng to .rnc:

Install on Fedora:
<pre>
# sudo dnf install msv-rngconv trang
</pre>
==== Convert from .xsd to .rng: ====

rngconv osisCore.2.1.1-cw-latest.xsd > osisCore.2.1.1-cw-latest.rng

==== Convert from .rng to .rnc ====
<pre>
trang -I rng -O rnc osisCore.2.1.1-cw-latest.rng osisCore.2.1.1-cw-latest.rnc
</pre>

=== Tell nxml where to find our schemas ===
We have already (see above) set the variable rng-schema-locating-files
to "~/.schema/schemas.xml

Now, we have to copy our new .rnc schemas in the .schema dir

mkdir -p ~/.schema
cp osisCore.2.1.1-cw-latest.rnc teiP5osis.2.5.0.rnc ~/.schema

and create ~/.schema/schemas.xml:
<pre>
<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
<namespace ns="http://www.crosswire.org/2013/TEIOSIS/namespace" uri="teiP5osis.2.5.0.rnc"/>
<namespace ns="http://www.bibletechnologies.net/2003/OSIS/namespace" uri="osisCore.2.1.1-cw-latest.rnc"/>
</locatingRules>
</pre>

=== Auto-completion ===
Type a < character and hit Ctrl+Enter for a list of valid tags. You can
type a few letters and hit Tab to use auto-completion. Hit Enter to
insert the given tag. This also works with attributes: simply add a
space after the tag, and hit Ctrl+Enter for attribute auto-completion.

=== Links ===
https://fedoraproject.org/wiki/How_to_use_Emacs_for_XML_editing
https://lgfang.github.io/mynotes/emacs/emacs-xml.html#sec-9
https://www.emacswiki.org/emacs/NxmlMode

= Validating from Windows Explorer =
Here is a simple application for validating XML files from within
Windows Explorer.

https://www.codeproject.com/Articles/8431/A-Simple-XML-Validator

= Python =
It's relatively straighforward to validate a file with Python:

Let's create simplest validator.py
<pre>
from lxml import etree

def validate(xml_path: str, xsd_path: str) -> bool:

xmlschema_doc = etree.parse(xsd_path)
xmlschema = etree.XMLSchema(xmlschema_doc)

xml_doc = etree.parse(xml_path)
result = xmlschema.validate(xml_doc)

return result
</pre>
then write and run main.py
<pre>
from validator import validate

if validate("path/to/file.xml", "path/to/scheme.xsd"):
print('Valid! :)')
else:
print('Not valid! :(')
</pre>

Validate OSIS or TEI text

2020-06-08T18:46:04Z

Domcox: /* Notepad++ */

= Syntax Check and Valid OSIS/TEI files =

An OSIS or TEI test is an XML Document that must be:
# <b>Well formed</b>, it means that its syntax must conforms to the XML specs. An XML file that is not well formed is not an XML file.
# <b>Valid</b>. A valid XML document is well-formed and conforms to the formal definition provided in a schema (or DTD). A document cannot have elements, attributes, or entities not defined in the schema. A schema can also define how entities may be nested, the possible values of attributes, etc.

There are online facilities for XML validation, many programs capable of schema validation exist and most [http://en.wikipedia.org/wiki/XML_editor XML editors] ([http://xml-copy-editor.sourceforge.net/ XML Copy Editor], [http://en.wikipedia.org/wiki/Oxygen_XML_Editor Oxygen], [http://en.wikipedia.org/wiki/XMLSpy XMLSpy], [http://www.topologi.com/ Topologi], etc.) support some sort of XML schema validation.

= Bible Technologies Group =
The '''BTG''' that sponsored the OSIS committee and hosted the OSIS schema no longer exists.
The schema location therefore now needs to be for a local copy on your computer or to a copy hosted by CrossWire or elsewhere.

For more up to date details, see [[OSIS 211 CR]] which includes CrossWire's own updated schema.

== Schema ==
Before validating XML files, you first need to download a schema from Crosswire.
* For OSIS encoded source files: osisCore.2.1.1-cw-latest.xsd (https://www.crosswire.org/~dmsmith/osis/osisCore.2.1.1-cw-latest.xsd)
* For TEI encoded source files: teiP5osis.2.5.0.xsd (http://www.crosswire.org/OSIS/teiP5osis.2.5.0.xsd)

= Online validators =
The first and simpliest option for checking an XML file is to use
online validators. They will check if your XML is both well-formed and
valid.

Here are two websites, you'll find others on the Internet.

- Core Filing XML Schema Validator
https://www.corefiling.com/opensource/schemaValidate/
Accept huge files (tested with a 5.5MB file)

- FreeFormatter Validator
https://www.freeformatter.com/xml-validator-xsd.html
The maximum size limit for file upload is 2MB

With these validators, you have to upload the XML File and the schema
(.xsd) file to the website before validating.

We no not recommend online validation, it may raises privacy
concerns with copyright texts, and although it may be fine for a one shot
validation task, it becomes quickly boring when you're creating and
editing a text and want periodically validate your work.

= CLI Validators =
When you're editing a text, one of the fastest option for checking your
XML is to use a CLI tool.

== xmllint ==
The simplest way is to use the xmllint program included with libxml2.
For Mac and Linux users, you likely already have xmllint installed.
Windows users willing to try xmllint will find interesting instructions
here:
https://techrina.net/2019/01/25/using-xmllint-program-for-windows-7/

To validate an OSIS xml file enter:

xmllint --noout --schema osisCore.2.1.1-cw-latest.xsd test.osis.xml

To validate a TEI xml file enter:

xmllint --noout --schema teiP5osis.2.5.0.xsd test.tei.xml

== xmlstarlet ==
XMLStarlet is an open source XML toolkit that you can use with Linux,
Mac or Windows. XMLStarlet is linked statically to both libxml2 and
libxslt, so generally all you need to process XML documents is one
executable file, it may be a better option for Windows users.

On Linux, xmlstarlet is available as a regular package.

For Mac or Windows, the download page is at:
http://xmlstar.sourceforge.net/download.php

To validate a TEI XML file enter:

xmlstarlet val --xsd ../../schemas/teiP5osis.2.5.0.xsd test.tei.xml

== Xerces ==
Xerces is Apache's collection of software libraries for parsing,
validating, serializing and manipulating XML. The implementation is
available in the Java, C++ and Perl programming languages, the Java
version having the most features.

=== xerces-c ===
On Ubuntu/debian, you can install xerces-c tools:

apt install libxerces-c-samples

To validate an OSIS XML file enter:

StdInParse -v=always -n -s < test.osis.xml.

You'll find the full syntax here:
https://xerces.apache.org/xerces-c/stdinparse-3.html

=== xsd-validator by Adrian Mouat ===
There isn’t a simple way to immediately run the Xerces validator in
Java from the command line. For that reason, Adrian Mouat wrote a Java
program to solve this issue.

It's called 'xsd-validator', for installing it:

Either clone the git repository at:
https://github.com/amouat/xsd-validator.git
or download xsd-validator zip from:
https://github.com/amouat/xsd-validator/releases/download/v1.0/xsdv-1.0.zip

To validate an OSIS XML file enter:

cd xsd-validator
./xsdv.sh osisCore.2.1.1-cw-latest.xsd test.osis.xml

There is also a cmd file that you can use to run xsdv from a windows Command Prompt.

For installing xsd-validator, run:

sudo ant install

= Editors Supporting Validation =
The final choice is to use an editor with validation on the fly. If
you’re doing a lot of XML editing and validation it may well be worth
looking into one of the editors listed below.

NOTE: If for any reason they do not find a schema, many editor silently fallback to only checking if the file is well-formed, which may generate false-positive results. To be sure, run the Solomon test:
Add tag <code><solomonTest /></code> in your text.
This tag conforms to the XML specifications but is not part of our schemas, so the editor must show up an error.

== Notepad++ ==

With XML Tools plugin for Notepad++, Notepad++ will allow you to clean
up unformatted files, check XML syntax function if you want just to
check your existing XML file for errors, or use Enable Auto Validation
for automatic validation of code as it is being written among other
features.

Go to the “Plugins” menu, then to “Plugin Manager”, then “Show Plugin
Manager”. Look for XML Tools in the opened window, set the checkbox,
and click the button “Install”.

You must restart Notepad ++ after installation.

== Sublime Text ==

Validate XML files on the fly with this [http://www.sublimetext.com/ Sublime Text 3] plugin:<br/>
https://packagecontrol.io/packages/Exalt

== Emacs ==

It's a little bit tricky, but you can configure Emacs to provide the
following features:

- Easy navigation
- Validation on the fly
- Auto completion

=== Use nxml-mode for editing XML ===
The first thing to do is to force Emacs to use nxml mode instead of xml
mode when editing XML files. nxml-mode uses the nXML extension to
provide automatic validation and lots of other helpful functions for
editing XML files.

Add the following lines to your ~/.emacs file:
<pre>
(setq auto-mode-alist (cons '("\\.xml$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.xsl$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.xhtml$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.page$" . nxml-mode) auto-mode-alist))

(autoload 'xml-mode "nxml" "XML editing mode" t)

(eval-after-load 'rng-loc
'(add-to-list 'rng-schema-locating-files "~/.schema/schemas.xml"))
</pre>

If you are using Emacs 24 or higher, you will also need this line that
will give you auto-completion:

(global-set-key [C-return] 'completion-at-point)

=== Set-up Crosswire Schemas ===
nxml-mode validates XML files using schemas in relaxng compact format
(.rnc). We have to convert our files from .xsd format to .rnc.

We use Sun RELAX NG Converter, nowadays bundled with the (Sun)
'Multi-Schema Validator' to convert .xsd to .rng, then we use trang to
convert .rng to .rnc:

Install on Fedora:
<pre>
# sudo dnf install msv-rngconv trang
</pre>
==== Convert from .xsd to .rng: ====

rngconv osisCore.2.1.1-cw-latest.xsd > osisCore.2.1.1-cw-latest.rng

==== Convert from .rng to .rnc ====
<pre>
trang -I rng -O rnc osisCore.2.1.1-cw-latest.rng osisCore.2.1.1-cw-latest.rnc
</pre>

=== Tell nxml where to find our schemas ===
We have already (see above) set the variable rng-schema-locating-files
to "~/.schema/schemas.xml

Now, we have to copy our new .rnc schemas in the .schema dir

mkdir -p ~/.schema
cp osisCore.2.1.1-cw-latest.rnc teiP5osis.2.5.0.rnc ~/.schema

and create ~/.schema/schemas.xml:
<pre>
<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
<namespace ns="http://www.crosswire.org/2013/TEIOSIS/namespace" uri="teiP5osis.2.5.0.rnc"/>
<namespace ns="http://www.bibletechnologies.net/2003/OSIS/namespace" uri="osisCore.2.1.1-cw-latest.rnc"/>
</locatingRules>
</pre>

=== Auto-completion ===
Type a < character and hit Ctrl+Enter for a list of valid tags. You can
type a few letters and hit Tab to use auto-completion. Hit Enter to
insert the given tag. This also works with attributes: simply add a
space after the tag, and hit Ctrl+Enter for attribute auto-completion.

=== Links ===
https://fedoraproject.org/wiki/How_to_use_Emacs_for_XML_editing
https://lgfang.github.io/mynotes/emacs/emacs-xml.html#sec-9
https://www.emacswiki.org/emacs/NxmlMode

= Validating from Windows Explorer =
Here is a simple application for validating XML files from within
Windows Explorer.

https://www.codeproject.com/Articles/8431/A-Simple-XML-Validator

= Python =
It's relatively straighforward to validate a file with Python:

Let's create simplest validator.py
<pre>
from lxml import etree

def validate(xml_path: str, xsd_path: str) -> bool:

xmlschema_doc = etree.parse(xsd_path)
xmlschema = etree.XMLSchema(xmlschema_doc)

xml_doc = etree.parse(xml_path)
result = xmlschema.validate(xml_doc)

return result
</pre>
then write and run main.py
<pre>
from validator import validate

if validate("path/to/file.xml", "path/to/scheme.xsd"):
print('Valid! :)')
else:
print('Not valid! :(')
</pre>

Validate OSIS or TEI text

2020-06-08T18:37:54Z

Domcox: /* Python */

= Syntax Check and Valid OSIS/TEI files =

An OSIS or TEI test is an XML Document that must be:
# <b>Well formed</b>, it means that its syntax must conforms to the XML specs. An XML file that is not well formed is not an XML file.
# <b>Valid</b>. A valid XML document is well-formed and conforms to the formal definition provided in a schema (or DTD). A document cannot have elements, attributes, or entities not defined in the schema. A schema can also define how entities may be nested, the possible values of attributes, etc.

There are online facilities for XML validation, many programs capable of schema validation exist and most [http://en.wikipedia.org/wiki/XML_editor XML editors] ([http://xml-copy-editor.sourceforge.net/ XML Copy Editor], [http://en.wikipedia.org/wiki/Oxygen_XML_Editor Oxygen], [http://en.wikipedia.org/wiki/XMLSpy XMLSpy], [http://www.topologi.com/ Topologi], etc.) support some sort of XML schema validation.

= Bible Technologies Group =
The '''BTG''' that sponsored the OSIS committee and hosted the OSIS schema no longer exists.
The schema location therefore now needs to be for a local copy on your computer or to a copy hosted by CrossWire or elsewhere.

For more up to date details, see [[OSIS 211 CR]] which includes CrossWire's own updated schema.

== Schema ==
Before validating XML files, you first need to download a schema from Crosswire.
* For OSIS encoded source files: osisCore.2.1.1-cw-latest.xsd (https://www.crosswire.org/~dmsmith/osis/osisCore.2.1.1-cw-latest.xsd)
* For TEI encoded source files: teiP5osis.2.5.0.xsd (http://www.crosswire.org/OSIS/teiP5osis.2.5.0.xsd)

= Online validators =
The first and simpliest option for checking an XML file is to use
online validators. They will check if your XML is both well-formed and
valid.

Here are two websites, you'll find others on the Internet.

- Core Filing XML Schema Validator
https://www.corefiling.com/opensource/schemaValidate/
Accept huge files (tested with a 5.5MB file)

- FreeFormatter Validator
https://www.freeformatter.com/xml-validator-xsd.html
The maximum size limit for file upload is 2MB

With these validators, you have to upload the XML File and the schema
(.xsd) file to the website before validating.

We no not recommend online validation, it may raises privacy
concerns with copyright texts, and although it may be fine for a one shot
validation task, it becomes quickly boring when you're creating and
editing a text and want periodically validate your work.

= CLI Validators =
When you're editing a text, one of the fastest option for checking your
XML is to use a CLI tool.

== xmllint ==
The simplest way is to use the xmllint program included with libxml2.
For Mac and Linux users, you likely already have xmllint installed.
Windows users willing to try xmllint will find interesting instructions
here:
https://techrina.net/2019/01/25/using-xmllint-program-for-windows-7/

To validate an OSIS xml file enter:

xmllint --noout --schema osisCore.2.1.1-cw-latest.xsd test.osis.xml

To validate a TEI xml file enter:

xmllint --noout --schema teiP5osis.2.5.0.xsd test.tei.xml

== xmlstarlet ==
XMLStarlet is an open source XML toolkit that you can use with Linux,
Mac or Windows. XMLStarlet is linked statically to both libxml2 and
libxslt, so generally all you need to process XML documents is one
executable file, it may be a better option for Windows users.

On Linux, xmlstarlet is available as a regular package.

For Mac or Windows, the download page is at:
http://xmlstar.sourceforge.net/download.php

To validate a TEI XML file enter:

xmlstarlet val --xsd ../../schemas/teiP5osis.2.5.0.xsd test.tei.xml

== Xerces ==
Xerces is Apache's collection of software libraries for parsing,
validating, serializing and manipulating XML. The implementation is
available in the Java, C++ and Perl programming languages, the Java
version having the most features.

=== xerces-c ===
On Ubuntu/debian, you can install xerces-c tools:

apt install libxerces-c-samples

To validate an OSIS XML file enter:

StdInParse -v=always -n -s < test.osis.xml.

You'll find the full syntax here:
https://xerces.apache.org/xerces-c/stdinparse-3.html

=== xsd-validator by Adrian Mouat ===
There isn’t a simple way to immediately run the Xerces validator in
Java from the command line. For that reason, Adrian Mouat wrote a Java
program to solve this issue.

It's called 'xsd-validator', for installing it:

Either clone the git repository at:
https://github.com/amouat/xsd-validator.git
or download xsd-validator zip from:
https://github.com/amouat/xsd-validator/releases/download/v1.0/xsdv-1.0.zip

To validate an OSIS XML file enter:

cd xsd-validator
./xsdv.sh osisCore.2.1.1-cw-latest.xsd test.osis.xml

There is also a cmd file that you can use to run xsdv from a windows Command Prompt.

For installing xsd-validator, run:

sudo ant install

= Editors Supporting Validation =
The final choice is to use an editor with validation on the fly. If
you’re doing a lot of XML editing and validation it may well be worth
looking into one of the editors listed below.

NOTE: If for any reason they do not find a schema, many editor silently fallback to only checking if the file is well-formed, which may generate false-positive results. To be sure, run the Solomon test:
Add tag <code><solomonTest /></code> in your text.
This tag conforms to the XML specifications but is not part of our schemas, so the editor must show up an error.

== Notepad++ ==

With XML Tools plugin for Notepad++, Notepad++ will allow you to clean
up unformatted files, check XML syntax function if you want just to
check your existing XML file for errors, or use Enable Auto Validation
for automatic validation of code as it is being written among other
features.

Go to the “Plugins” menu, then to “Plugin Manager”, then “Show Plugin
Manager”. Look for XML Tools in the opened window, set the checkbox,
and click the button “Install”.

You must restart Notepad ++ after installation.

== Emacs ==

It's a little bit tricky, but you can configure Emacs to provide the
following features:

- Easy navigation
- Validation on the fly
- Auto completion

=== Use nxml-mode for editing XML ===
The first thing to do is to force Emacs to use nxml mode instead of xml
mode when editing XML files. nxml-mode uses the nXML extension to
provide automatic validation and lots of other helpful functions for
editing XML files.

Add the following lines to your ~/.emacs file:
<pre>
(setq auto-mode-alist (cons '("\\.xml$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.xsl$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.xhtml$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.page$" . nxml-mode) auto-mode-alist))

(autoload 'xml-mode "nxml" "XML editing mode" t)

(eval-after-load 'rng-loc
'(add-to-list 'rng-schema-locating-files "~/.schema/schemas.xml"))
</pre>

If you are using Emacs 24 or higher, you will also need this line that
will give you auto-completion:

(global-set-key [C-return] 'completion-at-point)

=== Set-up Crosswire Schemas ===
nxml-mode validates XML files using schemas in relaxng compact format
(.rnc). We have to convert our files from .xsd format to .rnc.

We use Sun RELAX NG Converter, nowadays bundled with the (Sun)
'Multi-Schema Validator' to convert .xsd to .rng, then we use trang to
convert .rng to .rnc:

Install on Fedora:
<pre>
# sudo dnf install msv-rngconv trang
</pre>
==== Convert from .xsd to .rng: ====

rngconv osisCore.2.1.1-cw-latest.xsd > osisCore.2.1.1-cw-latest.rng

==== Convert from .rng to .rnc ====
<pre>
trang -I rng -O rnc osisCore.2.1.1-cw-latest.rng osisCore.2.1.1-cw-latest.rnc
</pre>

=== Tell nxml where to find our schemas ===
We have already (see above) set the variable rng-schema-locating-files
to "~/.schema/schemas.xml

Now, we have to copy our new .rnc schemas in the .schema dir

mkdir -p ~/.schema
cp osisCore.2.1.1-cw-latest.rnc teiP5osis.2.5.0.rnc ~/.schema

and create ~/.schema/schemas.xml:
<pre>
<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
<namespace ns="http://www.crosswire.org/2013/TEIOSIS/namespace" uri="teiP5osis.2.5.0.rnc"/>
<namespace ns="http://www.bibletechnologies.net/2003/OSIS/namespace" uri="osisCore.2.1.1-cw-latest.rnc"/>
</locatingRules>
</pre>

=== Auto-completion ===
Type a < character and hit Ctrl+Enter for a list of valid tags. You can
type a few letters and hit Tab to use auto-completion. Hit Enter to
insert the given tag. This also works with attributes: simply add a
space after the tag, and hit Ctrl+Enter for attribute auto-completion.

=== Links ===
https://fedoraproject.org/wiki/How_to_use_Emacs_for_XML_editing
https://lgfang.github.io/mynotes/emacs/emacs-xml.html#sec-9
https://www.emacswiki.org/emacs/NxmlMode

= Validating from Windows Explorer =
Here is a simple application for validating XML files from within
Windows Explorer.

https://www.codeproject.com/Articles/8431/A-Simple-XML-Validator

= Python =
It's relatively straighforward to validate a file with Python:

Let's create simplest validator.py
<pre>
from lxml import etree

def validate(xml_path: str, xsd_path: str) -> bool:

xmlschema_doc = etree.parse(xsd_path)
xmlschema = etree.XMLSchema(xmlschema_doc)

xml_doc = etree.parse(xml_path)
result = xmlschema.validate(xml_doc)

return result
</pre>
then write and run main.py
<pre>
from validator import validate

if validate("path/to/file.xml", "path/to/scheme.xsd"):
print('Valid! :)')
else:
print('Not valid! :(')
</pre>

Validate OSIS or TEI text

2020-06-08T18:37:43Z

Domcox: /* Validating from Windows Explorer */

= Syntax Check and Valid OSIS/TEI files =

An OSIS or TEI test is an XML Document that must be:
# <b>Well formed</b>, it means that its syntax must conforms to the XML specs. An XML file that is not well formed is not an XML file.
# <b>Valid</b>. A valid XML document is well-formed and conforms to the formal definition provided in a schema (or DTD). A document cannot have elements, attributes, or entities not defined in the schema. A schema can also define how entities may be nested, the possible values of attributes, etc.

There are online facilities for XML validation, many programs capable of schema validation exist and most [http://en.wikipedia.org/wiki/XML_editor XML editors] ([http://xml-copy-editor.sourceforge.net/ XML Copy Editor], [http://en.wikipedia.org/wiki/Oxygen_XML_Editor Oxygen], [http://en.wikipedia.org/wiki/XMLSpy XMLSpy], [http://www.topologi.com/ Topologi], etc.) support some sort of XML schema validation.

= Bible Technologies Group =
The '''BTG''' that sponsored the OSIS committee and hosted the OSIS schema no longer exists.
The schema location therefore now needs to be for a local copy on your computer or to a copy hosted by CrossWire or elsewhere.

For more up to date details, see [[OSIS 211 CR]] which includes CrossWire's own updated schema.

== Schema ==
Before validating XML files, you first need to download a schema from Crosswire.
* For OSIS encoded source files: osisCore.2.1.1-cw-latest.xsd (https://www.crosswire.org/~dmsmith/osis/osisCore.2.1.1-cw-latest.xsd)
* For TEI encoded source files: teiP5osis.2.5.0.xsd (http://www.crosswire.org/OSIS/teiP5osis.2.5.0.xsd)

= Online validators =
The first and simpliest option for checking an XML file is to use
online validators. They will check if your XML is both well-formed and
valid.

Here are two websites, you'll find others on the Internet.

- Core Filing XML Schema Validator
https://www.corefiling.com/opensource/schemaValidate/
Accept huge files (tested with a 5.5MB file)

- FreeFormatter Validator
https://www.freeformatter.com/xml-validator-xsd.html
The maximum size limit for file upload is 2MB

With these validators, you have to upload the XML File and the schema
(.xsd) file to the website before validating.

We no not recommend online validation, it may raises privacy
concerns with copyright texts, and although it may be fine for a one shot
validation task, it becomes quickly boring when you're creating and
editing a text and want periodically validate your work.

= CLI Validators =
When you're editing a text, one of the fastest option for checking your
XML is to use a CLI tool.

== xmllint ==
The simplest way is to use the xmllint program included with libxml2.
For Mac and Linux users, you likely already have xmllint installed.
Windows users willing to try xmllint will find interesting instructions
here:
https://techrina.net/2019/01/25/using-xmllint-program-for-windows-7/

To validate an OSIS xml file enter:

xmllint --noout --schema osisCore.2.1.1-cw-latest.xsd test.osis.xml

To validate a TEI xml file enter:

xmllint --noout --schema teiP5osis.2.5.0.xsd test.tei.xml

== xmlstarlet ==
XMLStarlet is an open source XML toolkit that you can use with Linux,
Mac or Windows. XMLStarlet is linked statically to both libxml2 and
libxslt, so generally all you need to process XML documents is one
executable file, it may be a better option for Windows users.

On Linux, xmlstarlet is available as a regular package.

For Mac or Windows, the download page is at:
http://xmlstar.sourceforge.net/download.php

To validate a TEI XML file enter:

xmlstarlet val --xsd ../../schemas/teiP5osis.2.5.0.xsd test.tei.xml

== Xerces ==
Xerces is Apache's collection of software libraries for parsing,
validating, serializing and manipulating XML. The implementation is
available in the Java, C++ and Perl programming languages, the Java
version having the most features.

=== xerces-c ===
On Ubuntu/debian, you can install xerces-c tools:

apt install libxerces-c-samples

To validate an OSIS XML file enter:

StdInParse -v=always -n -s < test.osis.xml.

You'll find the full syntax here:
https://xerces.apache.org/xerces-c/stdinparse-3.html

=== xsd-validator by Adrian Mouat ===
There isn’t a simple way to immediately run the Xerces validator in
Java from the command line. For that reason, Adrian Mouat wrote a Java
program to solve this issue.

It's called 'xsd-validator', for installing it:

Either clone the git repository at:
https://github.com/amouat/xsd-validator.git
or download xsd-validator zip from:
https://github.com/amouat/xsd-validator/releases/download/v1.0/xsdv-1.0.zip

To validate an OSIS XML file enter:

cd xsd-validator
./xsdv.sh osisCore.2.1.1-cw-latest.xsd test.osis.xml

There is also a cmd file that you can use to run xsdv from a windows Command Prompt.

For installing xsd-validator, run:

sudo ant install

= Editors Supporting Validation =
The final choice is to use an editor with validation on the fly. If
you’re doing a lot of XML editing and validation it may well be worth
looking into one of the editors listed below.

NOTE: If for any reason they do not find a schema, many editor silently fallback to only checking if the file is well-formed, which may generate false-positive results. To be sure, run the Solomon test:
Add tag <code><solomonTest /></code> in your text.
This tag conforms to the XML specifications but is not part of our schemas, so the editor must show up an error.

== Notepad++ ==

With XML Tools plugin for Notepad++, Notepad++ will allow you to clean
up unformatted files, check XML syntax function if you want just to
check your existing XML file for errors, or use Enable Auto Validation
for automatic validation of code as it is being written among other
features.

Go to the “Plugins” menu, then to “Plugin Manager”, then “Show Plugin
Manager”. Look for XML Tools in the opened window, set the checkbox,
and click the button “Install”.

You must restart Notepad ++ after installation.

== Emacs ==

It's a little bit tricky, but you can configure Emacs to provide the
following features:

- Easy navigation
- Validation on the fly
- Auto completion

=== Use nxml-mode for editing XML ===
The first thing to do is to force Emacs to use nxml mode instead of xml
mode when editing XML files. nxml-mode uses the nXML extension to
provide automatic validation and lots of other helpful functions for
editing XML files.

Add the following lines to your ~/.emacs file:
<pre>
(setq auto-mode-alist (cons '("\\.xml$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.xsl$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.xhtml$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.page$" . nxml-mode) auto-mode-alist))

(autoload 'xml-mode "nxml" "XML editing mode" t)

(eval-after-load 'rng-loc
'(add-to-list 'rng-schema-locating-files "~/.schema/schemas.xml"))
</pre>

If you are using Emacs 24 or higher, you will also need this line that
will give you auto-completion:

(global-set-key [C-return] 'completion-at-point)

=== Set-up Crosswire Schemas ===
nxml-mode validates XML files using schemas in relaxng compact format
(.rnc). We have to convert our files from .xsd format to .rnc.

We use Sun RELAX NG Converter, nowadays bundled with the (Sun)
'Multi-Schema Validator' to convert .xsd to .rng, then we use trang to
convert .rng to .rnc:

Install on Fedora:
<pre>
# sudo dnf install msv-rngconv trang
</pre>
==== Convert from .xsd to .rng: ====

rngconv osisCore.2.1.1-cw-latest.xsd > osisCore.2.1.1-cw-latest.rng

==== Convert from .rng to .rnc ====
<pre>
trang -I rng -O rnc osisCore.2.1.1-cw-latest.rng osisCore.2.1.1-cw-latest.rnc
</pre>

=== Tell nxml where to find our schemas ===
We have already (see above) set the variable rng-schema-locating-files
to "~/.schema/schemas.xml

Now, we have to copy our new .rnc schemas in the .schema dir

mkdir -p ~/.schema
cp osisCore.2.1.1-cw-latest.rnc teiP5osis.2.5.0.rnc ~/.schema

and create ~/.schema/schemas.xml:
<pre>
<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
<namespace ns="http://www.crosswire.org/2013/TEIOSIS/namespace" uri="teiP5osis.2.5.0.rnc"/>
<namespace ns="http://www.bibletechnologies.net/2003/OSIS/namespace" uri="osisCore.2.1.1-cw-latest.rnc"/>
</locatingRules>
</pre>

=== Auto-completion ===
Type a < character and hit Ctrl+Enter for a list of valid tags. You can
type a few letters and hit Tab to use auto-completion. Hit Enter to
insert the given tag. This also works with attributes: simply add a
space after the tag, and hit Ctrl+Enter for attribute auto-completion.

=== Links ===
https://fedoraproject.org/wiki/How_to_use_Emacs_for_XML_editing
https://lgfang.github.io/mynotes/emacs/emacs-xml.html#sec-9
https://www.emacswiki.org/emacs/NxmlMode

= Validating from Windows Explorer =
Here is a simple application for validating XML files from within
Windows Explorer.

https://www.codeproject.com/Articles/8431/A-Simple-XML-Validator

== Python ==
It's relatively straighforward to validate a file with Python:

Let's create simplest validator.py
<pre>
from lxml import etree

def validate(xml_path: str, xsd_path: str) -> bool:

xmlschema_doc = etree.parse(xsd_path)
xmlschema = etree.XMLSchema(xmlschema_doc)

xml_doc = etree.parse(xml_path)
result = xmlschema.validate(xml_doc)

return result
</pre>
then write and run main.py
<pre>
from validator import validate

if validate("path/to/file.xml", "path/to/scheme.xsd"):
print('Valid! :)')
else:
print('Not valid! :(')
</pre>

Validate OSIS or TEI text

2020-06-08T18:37:06Z

Domcox: /* Emacs */

= Syntax Check and Valid OSIS/TEI files =

An OSIS or TEI test is an XML Document that must be:
# <b>Well formed</b>, it means that its syntax must conforms to the XML specs. An XML file that is not well formed is not an XML file.
# <b>Valid</b>. A valid XML document is well-formed and conforms to the formal definition provided in a schema (or DTD). A document cannot have elements, attributes, or entities not defined in the schema. A schema can also define how entities may be nested, the possible values of attributes, etc.

There are online facilities for XML validation, many programs capable of schema validation exist and most [http://en.wikipedia.org/wiki/XML_editor XML editors] ([http://xml-copy-editor.sourceforge.net/ XML Copy Editor], [http://en.wikipedia.org/wiki/Oxygen_XML_Editor Oxygen], [http://en.wikipedia.org/wiki/XMLSpy XMLSpy], [http://www.topologi.com/ Topologi], etc.) support some sort of XML schema validation.

= Bible Technologies Group =
The '''BTG''' that sponsored the OSIS committee and hosted the OSIS schema no longer exists.
The schema location therefore now needs to be for a local copy on your computer or to a copy hosted by CrossWire or elsewhere.

For more up to date details, see [[OSIS 211 CR]] which includes CrossWire's own updated schema.

== Schema ==
Before validating XML files, you first need to download a schema from Crosswire.
* For OSIS encoded source files: osisCore.2.1.1-cw-latest.xsd (https://www.crosswire.org/~dmsmith/osis/osisCore.2.1.1-cw-latest.xsd)
* For TEI encoded source files: teiP5osis.2.5.0.xsd (http://www.crosswire.org/OSIS/teiP5osis.2.5.0.xsd)

= Online validators =
The first and simpliest option for checking an XML file is to use
online validators. They will check if your XML is both well-formed and
valid.

Here are two websites, you'll find others on the Internet.

- Core Filing XML Schema Validator
https://www.corefiling.com/opensource/schemaValidate/
Accept huge files (tested with a 5.5MB file)

- FreeFormatter Validator
https://www.freeformatter.com/xml-validator-xsd.html
The maximum size limit for file upload is 2MB

With these validators, you have to upload the XML File and the schema
(.xsd) file to the website before validating.

We no not recommend online validation, it may raises privacy
concerns with copyright texts, and although it may be fine for a one shot
validation task, it becomes quickly boring when you're creating and
editing a text and want periodically validate your work.

= CLI Validators =
When you're editing a text, one of the fastest option for checking your
XML is to use a CLI tool.

== xmllint ==
The simplest way is to use the xmllint program included with libxml2.
For Mac and Linux users, you likely already have xmllint installed.
Windows users willing to try xmllint will find interesting instructions
here:
https://techrina.net/2019/01/25/using-xmllint-program-for-windows-7/

To validate an OSIS xml file enter:

xmllint --noout --schema osisCore.2.1.1-cw-latest.xsd test.osis.xml

To validate a TEI xml file enter:

xmllint --noout --schema teiP5osis.2.5.0.xsd test.tei.xml

== xmlstarlet ==
XMLStarlet is an open source XML toolkit that you can use with Linux,
Mac or Windows. XMLStarlet is linked statically to both libxml2 and
libxslt, so generally all you need to process XML documents is one
executable file, it may be a better option for Windows users.

On Linux, xmlstarlet is available as a regular package.

For Mac or Windows, the download page is at:
http://xmlstar.sourceforge.net/download.php

To validate a TEI XML file enter:

xmlstarlet val --xsd ../../schemas/teiP5osis.2.5.0.xsd test.tei.xml

== Xerces ==
Xerces is Apache's collection of software libraries for parsing,
validating, serializing and manipulating XML. The implementation is
available in the Java, C++ and Perl programming languages, the Java
version having the most features.

=== xerces-c ===
On Ubuntu/debian, you can install xerces-c tools:

apt install libxerces-c-samples

To validate an OSIS XML file enter:

StdInParse -v=always -n -s < test.osis.xml.

You'll find the full syntax here:
https://xerces.apache.org/xerces-c/stdinparse-3.html

=== xsd-validator by Adrian Mouat ===
There isn’t a simple way to immediately run the Xerces validator in
Java from the command line. For that reason, Adrian Mouat wrote a Java
program to solve this issue.

It's called 'xsd-validator', for installing it:

Either clone the git repository at:
https://github.com/amouat/xsd-validator.git
or download xsd-validator zip from:
https://github.com/amouat/xsd-validator/releases/download/v1.0/xsdv-1.0.zip

To validate an OSIS XML file enter:

cd xsd-validator
./xsdv.sh osisCore.2.1.1-cw-latest.xsd test.osis.xml

There is also a cmd file that you can use to run xsdv from a windows Command Prompt.

For installing xsd-validator, run:

sudo ant install

= Editors Supporting Validation =
The final choice is to use an editor with validation on the fly. If
you’re doing a lot of XML editing and validation it may well be worth
looking into one of the editors listed below.

NOTE: If for any reason they do not find a schema, many editor silently fallback to only checking if the file is well-formed, which may generate false-positive results. To be sure, run the Solomon test:
Add tag <code><solomonTest /></code> in your text.
This tag conforms to the XML specifications but is not part of our schemas, so the editor must show up an error.

== Notepad++ ==

With XML Tools plugin for Notepad++, Notepad++ will allow you to clean
up unformatted files, check XML syntax function if you want just to
check your existing XML file for errors, or use Enable Auto Validation
for automatic validation of code as it is being written among other
features.

Go to the “Plugins” menu, then to “Plugin Manager”, then “Show Plugin
Manager”. Look for XML Tools in the opened window, set the checkbox,
and click the button “Install”.

You must restart Notepad ++ after installation.

== Emacs ==

It's a little bit tricky, but you can configure Emacs to provide the
following features:

- Easy navigation
- Validation on the fly
- Auto completion

=== Use nxml-mode for editing XML ===
The first thing to do is to force Emacs to use nxml mode instead of xml
mode when editing XML files. nxml-mode uses the nXML extension to
provide automatic validation and lots of other helpful functions for
editing XML files.

Add the following lines to your ~/.emacs file:
<pre>
(setq auto-mode-alist (cons '("\\.xml$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.xsl$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.xhtml$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.page$" . nxml-mode) auto-mode-alist))

(autoload 'xml-mode "nxml" "XML editing mode" t)

(eval-after-load 'rng-loc
'(add-to-list 'rng-schema-locating-files "~/.schema/schemas.xml"))
</pre>

If you are using Emacs 24 or higher, you will also need this line that
will give you auto-completion:

(global-set-key [C-return] 'completion-at-point)

=== Set-up Crosswire Schemas ===
nxml-mode validates XML files using schemas in relaxng compact format
(.rnc). We have to convert our files from .xsd format to .rnc.

We use Sun RELAX NG Converter, nowadays bundled with the (Sun)
'Multi-Schema Validator' to convert .xsd to .rng, then we use trang to
convert .rng to .rnc:

Install on Fedora:
<pre>
# sudo dnf install msv-rngconv trang
</pre>
==== Convert from .xsd to .rng: ====

rngconv osisCore.2.1.1-cw-latest.xsd > osisCore.2.1.1-cw-latest.rng

==== Convert from .rng to .rnc ====
<pre>
trang -I rng -O rnc osisCore.2.1.1-cw-latest.rng osisCore.2.1.1-cw-latest.rnc
</pre>

=== Tell nxml where to find our schemas ===
We have already (see above) set the variable rng-schema-locating-files
to "~/.schema/schemas.xml

Now, we have to copy our new .rnc schemas in the .schema dir

mkdir -p ~/.schema
cp osisCore.2.1.1-cw-latest.rnc teiP5osis.2.5.0.rnc ~/.schema

and create ~/.schema/schemas.xml:
<pre>
<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
<namespace ns="http://www.crosswire.org/2013/TEIOSIS/namespace" uri="teiP5osis.2.5.0.rnc"/>
<namespace ns="http://www.bibletechnologies.net/2003/OSIS/namespace" uri="osisCore.2.1.1-cw-latest.rnc"/>
</locatingRules>
</pre>

=== Auto-completion ===
Type a < character and hit Ctrl+Enter for a list of valid tags. You can
type a few letters and hit Tab to use auto-completion. Hit Enter to
insert the given tag. This also works with attributes: simply add a
space after the tag, and hit Ctrl+Enter for attribute auto-completion.

=== Links ===
https://fedoraproject.org/wiki/How_to_use_Emacs_for_XML_editing
https://lgfang.github.io/mynotes/emacs/emacs-xml.html#sec-9
https://www.emacswiki.org/emacs/NxmlMode

=== Validating from Windows Explorer ===
Here is a simple application for validating XML files from within
Windows Explorer.

https://www.codeproject.com/Articles/8431/A-Simple-XML-Validator

== Python ==
It's relatively straighforward to validate a file with Python:

Let's create simplest validator.py
<pre>
from lxml import etree

def validate(xml_path: str, xsd_path: str) -> bool:

xmlschema_doc = etree.parse(xsd_path)
xmlschema = etree.XMLSchema(xmlschema_doc)

xml_doc = etree.parse(xml_path)
result = xmlschema.validate(xml_doc)

return result
</pre>
then write and run main.py
<pre>
from validator import validate

if validate("path/to/file.xml", "path/to/scheme.xsd"):
print('Valid! :)')
else:
print('Not valid! :(')
</pre>

Validate OSIS or TEI text

2020-06-08T18:34:48Z

Domcox: /* Emacs */

= Syntax Check and Valid OSIS/TEI files =

An OSIS or TEI test is an XML Document that must be:
# <b>Well formed</b>, it means that its syntax must conforms to the XML specs. An XML file that is not well formed is not an XML file.
# <b>Valid</b>. A valid XML document is well-formed and conforms to the formal definition provided in a schema (or DTD). A document cannot have elements, attributes, or entities not defined in the schema. A schema can also define how entities may be nested, the possible values of attributes, etc.

There are online facilities for XML validation, many programs capable of schema validation exist and most [http://en.wikipedia.org/wiki/XML_editor XML editors] ([http://xml-copy-editor.sourceforge.net/ XML Copy Editor], [http://en.wikipedia.org/wiki/Oxygen_XML_Editor Oxygen], [http://en.wikipedia.org/wiki/XMLSpy XMLSpy], [http://www.topologi.com/ Topologi], etc.) support some sort of XML schema validation.

= Bible Technologies Group =
The '''BTG''' that sponsored the OSIS committee and hosted the OSIS schema no longer exists.
The schema location therefore now needs to be for a local copy on your computer or to a copy hosted by CrossWire or elsewhere.

For more up to date details, see [[OSIS 211 CR]] which includes CrossWire's own updated schema.

== Schema ==
Before validating XML files, you first need to download a schema from Crosswire.
* For OSIS encoded source files: osisCore.2.1.1-cw-latest.xsd (https://www.crosswire.org/~dmsmith/osis/osisCore.2.1.1-cw-latest.xsd)
* For TEI encoded source files: teiP5osis.2.5.0.xsd (http://www.crosswire.org/OSIS/teiP5osis.2.5.0.xsd)

= Online validators =
The first and simpliest option for checking an XML file is to use
online validators. They will check if your XML is both well-formed and
valid.

Here are two websites, you'll find others on the Internet.

- Core Filing XML Schema Validator
https://www.corefiling.com/opensource/schemaValidate/
Accept huge files (tested with a 5.5MB file)

- FreeFormatter Validator
https://www.freeformatter.com/xml-validator-xsd.html
The maximum size limit for file upload is 2MB

With these validators, you have to upload the XML File and the schema
(.xsd) file to the website before validating.

We no not recommend online validation, it may raises privacy
concerns with copyright texts, and although it may be fine for a one shot
validation task, it becomes quickly boring when you're creating and
editing a text and want periodically validate your work.

= CLI Validators =
When you're editing a text, one of the fastest option for checking your
XML is to use a CLI tool.

== xmllint ==
The simplest way is to use the xmllint program included with libxml2.
For Mac and Linux users, you likely already have xmllint installed.
Windows users willing to try xmllint will find interesting instructions
here:
https://techrina.net/2019/01/25/using-xmllint-program-for-windows-7/

To validate an OSIS xml file enter:

xmllint --noout --schema osisCore.2.1.1-cw-latest.xsd test.osis.xml

To validate a TEI xml file enter:

xmllint --noout --schema teiP5osis.2.5.0.xsd test.tei.xml

== xmlstarlet ==
XMLStarlet is an open source XML toolkit that you can use with Linux,
Mac or Windows. XMLStarlet is linked statically to both libxml2 and
libxslt, so generally all you need to process XML documents is one
executable file, it may be a better option for Windows users.

On Linux, xmlstarlet is available as a regular package.

For Mac or Windows, the download page is at:
http://xmlstar.sourceforge.net/download.php

To validate a TEI XML file enter:

xmlstarlet val --xsd ../../schemas/teiP5osis.2.5.0.xsd test.tei.xml

== Xerces ==
Xerces is Apache's collection of software libraries for parsing,
validating, serializing and manipulating XML. The implementation is
available in the Java, C++ and Perl programming languages, the Java
version having the most features.

=== xerces-c ===
On Ubuntu/debian, you can install xerces-c tools:

apt install libxerces-c-samples

To validate an OSIS XML file enter:

StdInParse -v=always -n -s < test.osis.xml.

You'll find the full syntax here:
https://xerces.apache.org/xerces-c/stdinparse-3.html

=== xsd-validator by Adrian Mouat ===
There isn’t a simple way to immediately run the Xerces validator in
Java from the command line. For that reason, Adrian Mouat wrote a Java
program to solve this issue.

It's called 'xsd-validator', for installing it:

Either clone the git repository at:
https://github.com/amouat/xsd-validator.git
or download xsd-validator zip from:
https://github.com/amouat/xsd-validator/releases/download/v1.0/xsdv-1.0.zip

To validate an OSIS XML file enter:

cd xsd-validator
./xsdv.sh osisCore.2.1.1-cw-latest.xsd test.osis.xml

There is also a cmd file that you can use to run xsdv from a windows Command Prompt.

For installing xsd-validator, run:

sudo ant install

= Editors Supporting Validation =
The final choice is to use an editor with validation on the fly. If
you’re doing a lot of XML editing and validation it may well be worth
looking into one of the editors listed below.

NOTE: If for any reason they do not find a schema, many editor silently fallback to only checking if the file is well-formed, which may generate false-positive results. To be sure, run the Solomon test:
Add tag <code><solomonTest /></code> in your text.
This tag conforms to the XML specifications but is not part of our schemas, so the editor must show up an error.

== Notepad++ ==

With XML Tools plugin for Notepad++, Notepad++ will allow you to clean
up unformatted files, check XML syntax function if you want just to
check your existing XML file for errors, or use Enable Auto Validation
for automatic validation of code as it is being written among other
features.

Go to the “Plugins” menu, then to “Plugin Manager”, then “Show Plugin
Manager”. Look for XML Tools in the opened window, set the checkbox,
and click the button “Install”.

You must restart Notepad ++ after installation.

== Emacs ==

It's a little bit tricky, but you can configure Emacs to provide the
following features:

- Easy navigation
- Validation on the fly
- Auto completion

# Use nxml-mode for editing XML
The first thing to do is to force Emacs to use nxml mode instead of xml
mode when editing XML files. nxml-mode uses the nXML extension to
provide automatic validation and lots of other helpful functions for
editing XML files.

Add the following lines to your ~/.emacs file:
<pre>
(setq auto-mode-alist (cons '("\\.xml$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.xsl$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.xhtml$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.page$" . nxml-mode) auto-mode-alist))

(autoload 'xml-mode "nxml" "XML editing mode" t)

(eval-after-load 'rng-loc
'(add-to-list 'rng-schema-locating-files "~/.schema/schemas.xml"))
</pre>

If you are using Emacs 24 or higher, you will also need this line that
will give you auto-completion:

(global-set-key [C-return] 'completion-at-point)

# Set-up Crosswire Schemas
nxml-mode validates XML files using schemas in relaxng compact format
(.rnc). We have to convert our files from .xsd format to .rnc.

We use Sun RELAX NG Converter, nowadays bundled with the (Sun)
'Multi-Schema Validator' to convert .xsd to .rng, then we use trang to
convert .rng to .rnc:

Install on Fedora:
<pre>
# sudo dnf install msv-rngconv trang
</pre>
## Convert from .xsd to .rng:

rngconv osisCore.2.1.1-cw-latest.xsd > osisCore.2.1.1-cw-latest.rng

## Convert from .rng to .rnc
<pre>
trang -I rng -O rnc osisCore.2.1.1-cw-latest.rng osisCore.2.1.1-cw-latest.rnc
</pre>

## Tell nxml where to find our schemas
We have already (see above) set the variable rng-schema-locating-files
to "~/.schema/schemas.xml

Now, we have to copy our new .rnc schemas in the .schema dir

mkdir -p ~/.schema
cp osisCore.2.1.1-cw-latest.rnc teiP5osis.2.5.0.rnc ~/.schema

and create ~/.schema/schemas.xml:
<pre>
<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
<namespace ns="http://www.crosswire.org/2013/TEIOSIS/namespace" uri="teiP5osis.2.5.0.rnc"/>
<namespace ns="http://www.bibletechnologies.net/2003/OSIS/namespace" uri="osisCore.2.1.1-cw-latest.rnc"/>
</locatingRules>
</pre>

# Auto-completion
Type a < character and hit Ctrl+Enter for a list of valid tags. You can
type a few letters and hit Tab to use auto-completion. Hit Enter to
insert the given tag. This also works with attributes: simply add a
space after the tag, and hit Ctrl+Enter for attribute auto-completion.

# Links
https://fedoraproject.org/wiki/How_to_use_Emacs_for_XML_editing
https://lgfang.github.io/mynotes/emacs/emacs-xml.html#sec-9
https://www.emacswiki.org/emacs/NxmlMode

=== Validating from Windows Explorer ===
Here is a simple application for validating XML files from within
Windows Explorer.

https://www.codeproject.com/Articles/8431/A-Simple-XML-Validator

=== Python ===
It's relatively straighforward to validate a file with Python:

Let's create simplest validator.py

from lxml import etree

def validate(xml_path: str, xsd_path: str) -> bool:

xmlschema_doc = etree.parse(xsd_path)
xmlschema = etree.XMLSchema(xmlschema_doc)

xml_doc = etree.parse(xml_path)
result = xmlschema.validate(xml_doc)

return result

then write and run main.py

from validator import validate

if validate("path/to/file.xml", "path/to/scheme.xsd"):
print('Valid! :)')
else:
print('Not valid! :(')

So it should be relatively easy to create a 'Crosswire XML validator'
Nautilus extension to help us validate TEI and OSIS files directly from
the file manager in Fedora/CentOS/Red Hat/Ubuntu.

Validate OSIS or TEI text

2020-06-08T18:32:11Z

Domcox: /* Online validators */

= Syntax Check and Valid OSIS/TEI files =

An OSIS or TEI test is an XML Document that must be:
# <b>Well formed</b>, it means that its syntax must conforms to the XML specs. An XML file that is not well formed is not an XML file.
# <b>Valid</b>. A valid XML document is well-formed and conforms to the formal definition provided in a schema (or DTD). A document cannot have elements, attributes, or entities not defined in the schema. A schema can also define how entities may be nested, the possible values of attributes, etc.

There are online facilities for XML validation, many programs capable of schema validation exist and most [http://en.wikipedia.org/wiki/XML_editor XML editors] ([http://xml-copy-editor.sourceforge.net/ XML Copy Editor], [http://en.wikipedia.org/wiki/Oxygen_XML_Editor Oxygen], [http://en.wikipedia.org/wiki/XMLSpy XMLSpy], [http://www.topologi.com/ Topologi], etc.) support some sort of XML schema validation.

= Bible Technologies Group =
The '''BTG''' that sponsored the OSIS committee and hosted the OSIS schema no longer exists.
The schema location therefore now needs to be for a local copy on your computer or to a copy hosted by CrossWire or elsewhere.

For more up to date details, see [[OSIS 211 CR]] which includes CrossWire's own updated schema.

== Schema ==
Before validating XML files, you first need to download a schema from Crosswire.
* For OSIS encoded source files: osisCore.2.1.1-cw-latest.xsd (https://www.crosswire.org/~dmsmith/osis/osisCore.2.1.1-cw-latest.xsd)
* For TEI encoded source files: teiP5osis.2.5.0.xsd (http://www.crosswire.org/OSIS/teiP5osis.2.5.0.xsd)

= Online validators =
The first and simpliest option for checking an XML file is to use
online validators. They will check if your XML is both well-formed and
valid.

Here are two websites, you'll find others on the Internet.

- Core Filing XML Schema Validator
https://www.corefiling.com/opensource/schemaValidate/
Accept huge files (tested with a 5.5MB file)

- FreeFormatter Validator
https://www.freeformatter.com/xml-validator-xsd.html
The maximum size limit for file upload is 2MB

With these validators, you have to upload the XML File and the schema
(.xsd) file to the website before validating.

We no not recommend online validation, it may raises privacy
concerns with copyright texts, and although it may be fine for a one shot
validation task, it becomes quickly boring when you're creating and
editing a text and want periodically validate your work.

= CLI Validators =
When you're editing a text, one of the fastest option for checking your
XML is to use a CLI tool.

== xmllint ==
The simplest way is to use the xmllint program included with libxml2.
For Mac and Linux users, you likely already have xmllint installed.
Windows users willing to try xmllint will find interesting instructions
here:
https://techrina.net/2019/01/25/using-xmllint-program-for-windows-7/

To validate an OSIS xml file enter:

xmllint --noout --schema osisCore.2.1.1-cw-latest.xsd test.osis.xml

To validate a TEI xml file enter:

xmllint --noout --schema teiP5osis.2.5.0.xsd test.tei.xml

== xmlstarlet ==
XMLStarlet is an open source XML toolkit that you can use with Linux,
Mac or Windows. XMLStarlet is linked statically to both libxml2 and
libxslt, so generally all you need to process XML documents is one
executable file, it may be a better option for Windows users.

On Linux, xmlstarlet is available as a regular package.

For Mac or Windows, the download page is at:
http://xmlstar.sourceforge.net/download.php

To validate a TEI XML file enter:

xmlstarlet val --xsd ../../schemas/teiP5osis.2.5.0.xsd test.tei.xml

== Xerces ==
Xerces is Apache's collection of software libraries for parsing,
validating, serializing and manipulating XML. The implementation is
available in the Java, C++ and Perl programming languages, the Java
version having the most features.

=== xerces-c ===
On Ubuntu/debian, you can install xerces-c tools:

apt install libxerces-c-samples

To validate an OSIS XML file enter:

StdInParse -v=always -n -s < test.osis.xml.

You'll find the full syntax here:
https://xerces.apache.org/xerces-c/stdinparse-3.html

=== xsd-validator by Adrian Mouat ===
There isn’t a simple way to immediately run the Xerces validator in
Java from the command line. For that reason, Adrian Mouat wrote a Java
program to solve this issue.

It's called 'xsd-validator', for installing it:

Either clone the git repository at:
https://github.com/amouat/xsd-validator.git
or download xsd-validator zip from:
https://github.com/amouat/xsd-validator/releases/download/v1.0/xsdv-1.0.zip

To validate an OSIS XML file enter:

cd xsd-validator
./xsdv.sh osisCore.2.1.1-cw-latest.xsd test.osis.xml

There is also a cmd file that you can use to run xsdv from a windows Command Prompt.

For installing xsd-validator, run:

sudo ant install

= Editors Supporting Validation =
The final choice is to use an editor with validation on the fly. If
you’re doing a lot of XML editing and validation it may well be worth
looking into one of the editors listed below.

NOTE: If for any reason they do not find a schema, many editor silently fallback to only checking if the file is well-formed, which may generate false-positive results. To be sure, run the Solomon test:
Add tag <code><solomonTest /></code> in your text.
This tag conforms to the XML specifications but is not part of our schemas, so the editor must show up an error.

== Notepad++ ==

With XML Tools plugin for Notepad++, Notepad++ will allow you to clean
up unformatted files, check XML syntax function if you want just to
check your existing XML file for errors, or use Enable Auto Validation
for automatic validation of code as it is being written among other
features.

Go to the “Plugins” menu, then to “Plugin Manager”, then “Show Plugin
Manager”. Look for XML Tools in the opened window, set the checkbox,
and click the button “Install”.

You must restart Notepad ++ after installation.

== Emacs ==

It's a little bit tricky, but you can configure Emacs to provide the
following features:

- Easy navigation
- Validation on the fly
- Auto completion

# Use nxml-mode for editing XML
The first thing to do is to force Emacs to use nxml mode instead of xml
mode when editing XML files. nxml-mode uses the nXML extension to
provide automatic validation and lots of other helpful functions for
editing XML files.

Add the following lines to your ~/.emacs file:

(setq auto-mode-alist (cons '("\\.xml$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.xsl$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.xhtml$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.page$" . nxml-mode) auto-mode-alist))

(autoload 'xml-mode "nxml" "XML editing mode" t)

(eval-after-load 'rng-loc
'(add-to-list 'rng-schema-locating-files "~/.schema/schemas.xml"))

If you are using Emacs 24 or higher, you will also need this line that
will give you auto-completion:

(global-set-key [C-return] 'completion-at-point)

# Set-up Crosswire Schemas
nxml-mode validates XML files using schemas in relaxng compact format
(.rnc). We have to convert our files from .xsd format to .rnc.

We use Sun RELAX NG Converter, nowadays bundled with the (Sun)
'Multi-Schema Validator' to convert .xsd to .rng, then we use trang to
convert .rng to .rnc:

Install on Fedora:

# sudo dnf install msv-rngconv trang

## Convert from .xsd to .rng:

rngconv osisCore.2.1.1-cw-latest.xsd > osisCore.2.1.1-cw-latest.rng

## Convert from .rng to .rnc

trang -I rng -O rnc osisCore.2.1.1-cw-latest.rng osisCore.2.1.1-cw-latest.rnc

It's a little bit tedious to convert these files. I think you'll be
pleased to find these 2 .rnc files attached.

## Tell nxml where to find our schemas
We have already (see above) set the variable rng-schema-locating-files
to "~/.schema/schemas.xml

Now, we have to copy our new .rnc schemas in the .schema dir

mkdir -p ~/.schema
cp osisCore.2.1.1-cw-latest.rnc teiP5osis.2.5.0.rnc ~/.schema

and create ~/.schema/schemas.xml:

<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
<namespace ns="http://www.crosswire.org/2013/TEIOSIS/namespace" uri="teiP5osis.2.5.0.rnc"/>
<namespace ns="http://www.bibletechnologies.net/2003/OSIS/namespace" uri="osisCore.2.1.1-cw-latest.rnc"/>
</locatingRules>

# Auto-completion
Type a < character and hit Ctrl+Enter for a list of valid tags. You can
type a few letters and hit Tab to use auto-completion. Hit Enter to
insert the given tag. This also works with attributes: simply add a
space after the tag, and hit Ctrl+Enter for attribute auto-completion.

# links
https://fedoraproject.org/wiki/How_to_use_Emacs_for_XML_editing
https://lgfang.github.io/mynotes/emacs/emacs-xml.html#sec-9
https://www.emacswiki.org/emacs/NxmlMode

=== Validating from Windows Explorer ===
Here is a simple application for validating XML files from within
Windows Explorer.

https://www.codeproject.com/Articles/8431/A-Simple-XML-Validator

=== Python ===
It's relatively straighforward to validate a file with Python:

Let's create simplest validator.py

from lxml import etree

def validate(xml_path: str, xsd_path: str) -> bool:

xmlschema_doc = etree.parse(xsd_path)
xmlschema = etree.XMLSchema(xmlschema_doc)

xml_doc = etree.parse(xml_path)
result = xmlschema.validate(xml_doc)

return result

then write and run main.py

from validator import validate

if validate("path/to/file.xml", "path/to/scheme.xsd"):
print('Valid! :)')
else:
print('Not valid! :(')

So it should be relatively easy to create a 'Crosswire XML validator'
Nautilus extension to help us validate TEI and OSIS files directly from
the file manager in Fedora/CentOS/Red Hat/Ubuntu.

Validate OSIS or TEI text

2020-06-08T18:29:18Z

Domcox: /* Schema */

= Syntax Check and Valid OSIS/TEI files =

An OSIS or TEI test is an XML Document that must be:
# <b>Well formed</b>, it means that its syntax must conforms to the XML specs. An XML file that is not well formed is not an XML file.
# <b>Valid</b>. A valid XML document is well-formed and conforms to the formal definition provided in a schema (or DTD). A document cannot have elements, attributes, or entities not defined in the schema. A schema can also define how entities may be nested, the possible values of attributes, etc.

There are online facilities for XML validation, many programs capable of schema validation exist and most [http://en.wikipedia.org/wiki/XML_editor XML editors] ([http://xml-copy-editor.sourceforge.net/ XML Copy Editor], [http://en.wikipedia.org/wiki/Oxygen_XML_Editor Oxygen], [http://en.wikipedia.org/wiki/XMLSpy XMLSpy], [http://www.topologi.com/ Topologi], etc.) support some sort of XML schema validation.

= Bible Technologies Group =
The '''BTG''' that sponsored the OSIS committee and hosted the OSIS schema no longer exists.
The schema location therefore now needs to be for a local copy on your computer or to a copy hosted by CrossWire or elsewhere.

For more up to date details, see [[OSIS 211 CR]] which includes CrossWire's own updated schema.

== Schema ==
Before validating XML files, you first need to download a schema from Crosswire.
* For OSIS encoded source files: osisCore.2.1.1-cw-latest.xsd (https://www.crosswire.org/~dmsmith/osis/osisCore.2.1.1-cw-latest.xsd)
* For TEI encoded source files: teiP5osis.2.5.0.xsd (http://www.crosswire.org/OSIS/teiP5osis.2.5.0.xsd)

= Online validators =
The first and simpliest option for checking an XML file is to use
online validators. They will check if your XML is both well-formed and
valid.

Here are two websites, there are others on the Internet.

- Core Filing XML Schema Validator
https://www.corefiling.com/opensource/schemaValidate/
Accept huge files (tested with a 5.5MB file)

- FreeFormatter Validator
https://www.freeformatter.com/xml-validator-xsd.html
The maximum size limit for file upload is 2MB

With these validators, you have to upload the XML File and the schema
(.xsd) file before validating.

I think we shouldn't recommend online validation, it may raises privacy
concerns with copyright texts, moreover if it's fine for a one shot
validation task, it becomes quickly boring when you're editing and
working on a text.

= CLI Validators =
When you're editing a text, one of the fastest option for checking your
XML is to use a CLI tool.

== xmllint ==
The simplest way is to use the xmllint program included with libxml2.
For Mac and Linux users, you likely already have xmllint installed.
Windows users willing to try xmllint will find interesting instructions
here:
https://techrina.net/2019/01/25/using-xmllint-program-for-windows-7/

To validate an OSIS xml file enter:

xmllint --noout --schema osisCore.2.1.1-cw-latest.xsd test.osis.xml

To validate a TEI xml file enter:

xmllint --noout --schema teiP5osis.2.5.0.xsd test.tei.xml

== xmlstarlet ==
XMLStarlet is an open source XML toolkit that you can use with Linux,
Mac or Windows. XMLStarlet is linked statically to both libxml2 and
libxslt, so generally all you need to process XML documents is one
executable file, it may be a better option for Windows users.

On Linux, xmlstarlet is available as a regular package.

For Mac or Windows, the download page is at:
http://xmlstar.sourceforge.net/download.php

To validate a TEI XML file enter:

xmlstarlet val --xsd ../../schemas/teiP5osis.2.5.0.xsd test.tei.xml

== Xerces ==
Xerces is Apache's collection of software libraries for parsing,
validating, serializing and manipulating XML. The implementation is
available in the Java, C++ and Perl programming languages, the Java
version having the most features.

=== xerces-c ===
On Ubuntu/debian, you can install xerces-c tools:

apt install libxerces-c-samples

To validate an OSIS XML file enter:

StdInParse -v=always -n -s < test.osis.xml.

You'll find the full syntax here:
https://xerces.apache.org/xerces-c/stdinparse-3.html

=== xsd-validator by Adrian Mouat ===
There isn’t a simple way to immediately run the Xerces validator in
Java from the command line. For that reason, Adrian Mouat wrote a Java
program to solve this issue.

It's called 'xsd-validator', for installing it:

Either clone the git repository at:
https://github.com/amouat/xsd-validator.git
or download xsd-validator zip from:
https://github.com/amouat/xsd-validator/releases/download/v1.0/xsdv-1.0.zip

To validate an OSIS XML file enter:

cd xsd-validator
./xsdv.sh osisCore.2.1.1-cw-latest.xsd test.osis.xml

There is also a cmd file that you can use to run xsdv from a windows Command Prompt.

For installing xsd-validator, run:

sudo ant install

= Editors Supporting Validation =
The final choice is to use an editor with validation on the fly. If
you’re doing a lot of XML editing and validation it may well be worth
looking into one of the editors listed below.

NOTE: If for any reason they do not find a schema, many editor silently fallback to only checking if the file is well-formed, which may generate false-positive results. To be sure, run the Solomon test:
Add tag <code><solomonTest /></code> in your text.
This tag conforms to the XML specifications but is not part of our schemas, so the editor must show up an error.

== Notepad++ ==

With XML Tools plugin for Notepad++, Notepad++ will allow you to clean
up unformatted files, check XML syntax function if you want just to
check your existing XML file for errors, or use Enable Auto Validation
for automatic validation of code as it is being written among other
features.

Go to the “Plugins” menu, then to “Plugin Manager”, then “Show Plugin
Manager”. Look for XML Tools in the opened window, set the checkbox,
and click the button “Install”.

You must restart Notepad ++ after installation.

== Emacs ==

It's a little bit tricky, but you can configure Emacs to provide the
following features:

- Easy navigation
- Validation on the fly
- Auto completion

# Use nxml-mode for editing XML
The first thing to do is to force Emacs to use nxml mode instead of xml
mode when editing XML files. nxml-mode uses the nXML extension to
provide automatic validation and lots of other helpful functions for
editing XML files.

Add the following lines to your ~/.emacs file:

(setq auto-mode-alist (cons '("\\.xml$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.xsl$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.xhtml$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.page$" . nxml-mode) auto-mode-alist))

(autoload 'xml-mode "nxml" "XML editing mode" t)

(eval-after-load 'rng-loc
'(add-to-list 'rng-schema-locating-files "~/.schema/schemas.xml"))

If you are using Emacs 24 or higher, you will also need this line that
will give you auto-completion:

(global-set-key [C-return] 'completion-at-point)

# Set-up Crosswire Schemas
nxml-mode validates XML files using schemas in relaxng compact format
(.rnc). We have to convert our files from .xsd format to .rnc.

We use Sun RELAX NG Converter, nowadays bundled with the (Sun)
'Multi-Schema Validator' to convert .xsd to .rng, then we use trang to
convert .rng to .rnc:

Install on Fedora:

# sudo dnf install msv-rngconv trang

## Convert from .xsd to .rng:

rngconv osisCore.2.1.1-cw-latest.xsd > osisCore.2.1.1-cw-latest.rng

## Convert from .rng to .rnc

trang -I rng -O rnc osisCore.2.1.1-cw-latest.rng osisCore.2.1.1-cw-latest.rnc

It's a little bit tedious to convert these files. I think you'll be
pleased to find these 2 .rnc files attached.

## Tell nxml where to find our schemas
We have already (see above) set the variable rng-schema-locating-files
to "~/.schema/schemas.xml

Now, we have to copy our new .rnc schemas in the .schema dir

mkdir -p ~/.schema
cp osisCore.2.1.1-cw-latest.rnc teiP5osis.2.5.0.rnc ~/.schema

and create ~/.schema/schemas.xml:

<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
<namespace ns="http://www.crosswire.org/2013/TEIOSIS/namespace" uri="teiP5osis.2.5.0.rnc"/>
<namespace ns="http://www.bibletechnologies.net/2003/OSIS/namespace" uri="osisCore.2.1.1-cw-latest.rnc"/>
</locatingRules>

# Auto-completion
Type a < character and hit Ctrl+Enter for a list of valid tags. You can
type a few letters and hit Tab to use auto-completion. Hit Enter to
insert the given tag. This also works with attributes: simply add a
space after the tag, and hit Ctrl+Enter for attribute auto-completion.

# links
https://fedoraproject.org/wiki/How_to_use_Emacs_for_XML_editing
https://lgfang.github.io/mynotes/emacs/emacs-xml.html#sec-9
https://www.emacswiki.org/emacs/NxmlMode

=== Validating from Windows Explorer ===
Here is a simple application for validating XML files from within
Windows Explorer.

https://www.codeproject.com/Articles/8431/A-Simple-XML-Validator

=== Python ===
It's relatively straighforward to validate a file with Python:

Let's create simplest validator.py

from lxml import etree

def validate(xml_path: str, xsd_path: str) -> bool:

xmlschema_doc = etree.parse(xsd_path)
xmlschema = etree.XMLSchema(xmlschema_doc)

xml_doc = etree.parse(xml_path)
result = xmlschema.validate(xml_doc)

return result

then write and run main.py

from validator import validate

if validate("path/to/file.xml", "path/to/scheme.xsd"):
print('Valid! :)')
else:
print('Not valid! :(')

So it should be relatively easy to create a 'Crosswire XML validator'
Nautilus extension to help us validate TEI and OSIS files directly from
the file manager in Fedora/CentOS/Red Hat/Ubuntu.

Validate OSIS or TEI text

2020-06-08T18:28:48Z

Domcox:

= Syntax Check and Valid OSIS/TEI files =

An OSIS or TEI test is an XML Document that must be:
# <b>Well formed</b>, it means that its syntax must conforms to the XML specs. An XML file that is not well formed is not an XML file.
# <b>Valid</b>. A valid XML document is well-formed and conforms to the formal definition provided in a schema (or DTD). A document cannot have elements, attributes, or entities not defined in the schema. A schema can also define how entities may be nested, the possible values of attributes, etc.

There are online facilities for XML validation, many programs capable of schema validation exist and most [http://en.wikipedia.org/wiki/XML_editor XML editors] ([http://xml-copy-editor.sourceforge.net/ XML Copy Editor], [http://en.wikipedia.org/wiki/Oxygen_XML_Editor Oxygen], [http://en.wikipedia.org/wiki/XMLSpy XMLSpy], [http://www.topologi.com/ Topologi], etc.) support some sort of XML schema validation.

= Bible Technologies Group =
The '''BTG''' that sponsored the OSIS committee and hosted the OSIS schema no longer exists.
The schema location therefore now needs to be for a local copy on your computer or to a copy hosted by CrossWire or elsewhere.

For more up to date details, see [[OSIS 211 CR]] which includes CrossWire's own updated schema.

== Schema ==
Before validating XML files, you first need to download a schema from Crosswire.
* For OSIS encoded source files: osisCore.2.1.1-cw-latest.xsd https://www.crosswire.org/~dmsmith/osis/osisCore.2.1.1-cw-latest.xsd
* For TEI encoded source files: teiP5osis.2.5.0.xsd http://www.crosswire.org/OSIS/teiP5osis.2.5.0.xsd

= Online validators =
The first and simpliest option for checking an XML file is to use
online validators. They will check if your XML is both well-formed and
valid.

Here are two websites, there are others on the Internet.

- Core Filing XML Schema Validator
https://www.corefiling.com/opensource/schemaValidate/
Accept huge files (tested with a 5.5MB file)

- FreeFormatter Validator
https://www.freeformatter.com/xml-validator-xsd.html
The maximum size limit for file upload is 2MB

With these validators, you have to upload the XML File and the schema
(.xsd) file before validating.

I think we shouldn't recommend online validation, it may raises privacy
concerns with copyright texts, moreover if it's fine for a one shot
validation task, it becomes quickly boring when you're editing and
working on a text.

= CLI Validators =
When you're editing a text, one of the fastest option for checking your
XML is to use a CLI tool.

== xmllint ==
The simplest way is to use the xmllint program included with libxml2.
For Mac and Linux users, you likely already have xmllint installed.
Windows users willing to try xmllint will find interesting instructions
here:
https://techrina.net/2019/01/25/using-xmllint-program-for-windows-7/

To validate an OSIS xml file enter:

xmllint --noout --schema osisCore.2.1.1-cw-latest.xsd test.osis.xml

To validate a TEI xml file enter:

xmllint --noout --schema teiP5osis.2.5.0.xsd test.tei.xml

== xmlstarlet ==
XMLStarlet is an open source XML toolkit that you can use with Linux,
Mac or Windows. XMLStarlet is linked statically to both libxml2 and
libxslt, so generally all you need to process XML documents is one
executable file, it may be a better option for Windows users.

On Linux, xmlstarlet is available as a regular package.

For Mac or Windows, the download page is at:
http://xmlstar.sourceforge.net/download.php

To validate a TEI XML file enter:

xmlstarlet val --xsd ../../schemas/teiP5osis.2.5.0.xsd test.tei.xml

== Xerces ==
Xerces is Apache's collection of software libraries for parsing,
validating, serializing and manipulating XML. The implementation is
available in the Java, C++ and Perl programming languages, the Java
version having the most features.

=== xerces-c ===
On Ubuntu/debian, you can install xerces-c tools:

apt install libxerces-c-samples

To validate an OSIS XML file enter:

StdInParse -v=always -n -s < test.osis.xml.

You'll find the full syntax here:
https://xerces.apache.org/xerces-c/stdinparse-3.html

=== xsd-validator by Adrian Mouat ===
There isn’t a simple way to immediately run the Xerces validator in
Java from the command line. For that reason, Adrian Mouat wrote a Java
program to solve this issue.

It's called 'xsd-validator', for installing it:

Either clone the git repository at:
https://github.com/amouat/xsd-validator.git
or download xsd-validator zip from:
https://github.com/amouat/xsd-validator/releases/download/v1.0/xsdv-1.0.zip

To validate an OSIS XML file enter:

cd xsd-validator
./xsdv.sh osisCore.2.1.1-cw-latest.xsd test.osis.xml

There is also a cmd file that you can use to run xsdv from a windows Command Prompt.

For installing xsd-validator, run:

sudo ant install

= Editors Supporting Validation =
The final choice is to use an editor with validation on the fly. If
you’re doing a lot of XML editing and validation it may well be worth
looking into one of the editors listed below.

NOTE: If for any reason they do not find a schema, many editor silently fallback to only checking if the file is well-formed, which may generate false-positive results. To be sure, run the Solomon test:
Add tag <code><solomonTest /></code> in your text.
This tag conforms to the XML specifications but is not part of our schemas, so the editor must show up an error.

== Notepad++ ==

With XML Tools plugin for Notepad++, Notepad++ will allow you to clean
up unformatted files, check XML syntax function if you want just to
check your existing XML file for errors, or use Enable Auto Validation
for automatic validation of code as it is being written among other
features.

Go to the “Plugins” menu, then to “Plugin Manager”, then “Show Plugin
Manager”. Look for XML Tools in the opened window, set the checkbox,
and click the button “Install”.

You must restart Notepad ++ after installation.

== Emacs ==

It's a little bit tricky, but you can configure Emacs to provide the
following features:

- Easy navigation
- Validation on the fly
- Auto completion

# Use nxml-mode for editing XML
The first thing to do is to force Emacs to use nxml mode instead of xml
mode when editing XML files. nxml-mode uses the nXML extension to
provide automatic validation and lots of other helpful functions for
editing XML files.

Add the following lines to your ~/.emacs file:

(setq auto-mode-alist (cons '("\\.xml$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.xsl$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.xhtml$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.page$" . nxml-mode) auto-mode-alist))

(autoload 'xml-mode "nxml" "XML editing mode" t)

(eval-after-load 'rng-loc
'(add-to-list 'rng-schema-locating-files "~/.schema/schemas.xml"))

If you are using Emacs 24 or higher, you will also need this line that
will give you auto-completion:

(global-set-key [C-return] 'completion-at-point)

# Set-up Crosswire Schemas
nxml-mode validates XML files using schemas in relaxng compact format
(.rnc). We have to convert our files from .xsd format to .rnc.

We use Sun RELAX NG Converter, nowadays bundled with the (Sun)
'Multi-Schema Validator' to convert .xsd to .rng, then we use trang to
convert .rng to .rnc:

Install on Fedora:

# sudo dnf install msv-rngconv trang

## Convert from .xsd to .rng:

rngconv osisCore.2.1.1-cw-latest.xsd > osisCore.2.1.1-cw-latest.rng

## Convert from .rng to .rnc

trang -I rng -O rnc osisCore.2.1.1-cw-latest.rng osisCore.2.1.1-cw-latest.rnc

It's a little bit tedious to convert these files. I think you'll be
pleased to find these 2 .rnc files attached.

## Tell nxml where to find our schemas
We have already (see above) set the variable rng-schema-locating-files
to "~/.schema/schemas.xml

Now, we have to copy our new .rnc schemas in the .schema dir

mkdir -p ~/.schema
cp osisCore.2.1.1-cw-latest.rnc teiP5osis.2.5.0.rnc ~/.schema

and create ~/.schema/schemas.xml:

<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
<namespace ns="http://www.crosswire.org/2013/TEIOSIS/namespace" uri="teiP5osis.2.5.0.rnc"/>
<namespace ns="http://www.bibletechnologies.net/2003/OSIS/namespace" uri="osisCore.2.1.1-cw-latest.rnc"/>
</locatingRules>

# Auto-completion
Type a < character and hit Ctrl+Enter for a list of valid tags. You can
type a few letters and hit Tab to use auto-completion. Hit Enter to
insert the given tag. This also works with attributes: simply add a
space after the tag, and hit Ctrl+Enter for attribute auto-completion.

# links
https://fedoraproject.org/wiki/How_to_use_Emacs_for_XML_editing
https://lgfang.github.io/mynotes/emacs/emacs-xml.html#sec-9
https://www.emacswiki.org/emacs/NxmlMode

=== Validating from Windows Explorer ===
Here is a simple application for validating XML files from within
Windows Explorer.

https://www.codeproject.com/Articles/8431/A-Simple-XML-Validator

=== Python ===
It's relatively straighforward to validate a file with Python:

Let's create simplest validator.py

from lxml import etree

def validate(xml_path: str, xsd_path: str) -> bool:

xmlschema_doc = etree.parse(xsd_path)
xmlschema = etree.XMLSchema(xmlschema_doc)

xml_doc = etree.parse(xml_path)
result = xmlschema.validate(xml_doc)

return result

then write and run main.py

from validator import validate

if validate("path/to/file.xml", "path/to/scheme.xsd"):
print('Valid! :)')
else:
print('Not valid! :(')

So it should be relatively easy to create a 'Crosswire XML validator'
Nautilus extension to help us validate TEI and OSIS files directly from
the file manager in Fedora/CentOS/Red Hat/Ubuntu.

Validate OSIS or TEI text

2020-06-08T17:13:47Z

Domcox: Created page with "An OSIS or TEI test is an XML Document that must be: # <b>Well formed</b>, it means that its syntax must conforms to the XML specs. An XML file that is not well formed is not..."

An OSIS or TEI test is an XML Document that must be:
# <b>Well formed</b>, it means that its syntax must conforms to the XML specs. An XML file that is not well formed is not an XML file.
# <b>Valid</b>. A valid XML document is well-formed and conforms to the formal definition provided in a schema (or DTD). A document cannot have elements, attributes, or entities not defined in the schema. A schema can also define how entities may be nested, the possible values of attributes, etc.

===Bible Technologies Group===
The '''BTG''' that sponsored the OSIS committee and hosted the OSIS schema no longer exists.
The schema location therefore now needs to be for a local copy on your computer or to a copy hosted by CrossWire or elsewhere.

For more up to date details, see [[OSIS 211 CR]] which includes CrossWire's own updated schema.

=== Schema ===
Before validating XML files, we first need to download a schema. At Crosswire, we use:
- For OSIS encoded source files: osisCore.2.1.1-cw-latest.xsd
- For TEI encoded source files: teiP5osis.2.5.0.xsd

You have to download these files here from Crosswire:
https://www.crosswire.org/~dmsmith/osis/osisCore.2.1.1-cw-latest.xsd
http://www.crosswire.org/OSIS/teiP5osis.2.5.0.xsd

=== Online validators ===
The first and simpliest option for checking an XML file is to use
online validators. They will check if your XML is both well-formed and
valid.

Here are two websites, there are others on the Internet.

- Core Filing XML Schema Validator
https://www.corefiling.com/opensource/schemaValidate/
Accept huge files (tested with a 5.5MB file)

- FreeFormatter Validator
https://www.freeformatter.com/xml-validator-xsd.html
The maximum size limit for file upload is 2MB

With these validators, you have to upload the XML File and the schema
(.xsd) file before validating.

I think we shouldn't recommend online validation, it may raises privacy
concerns with copyright texts, moreover if it's fine for a one shot
validation task, it becomes quickly boring when you're editing and
working on a text.

=== CLI Validators ===
When you're editing a text, one of the fastest option for checking your
XML is to use a CLI tool.

==== xmllint ====
The simplest way is to use the xmllint program included with libxml2.
For Mac and Linux users, you likely already have xmllint installed.
Windows users willing to try xmllint will find interesting instructions
here:
https://techrina.net/2019/01/25/using-xmllint-program-for-windows-7/

To validate an OSIS xml file enter:

xmllint --noout --schema osisCore.2.1.1-cw-latest.xsd test.osis.xml

To validate a TEI xml file enter:

xmllint --noout --schema teiP5osis.2.5.0.xsd test.tei.xml

==== xmlstarlet ====
XMLStarlet is an open source XML toolkit that you can use with Linux,
Mac or Windows. XMLStarlet is linked statically to both libxml2 and
libxslt, so generally all you need to process XML documents is one
executable file, it may be a better option for Windows users.

On Linux, xmlstarlet is available as a regular package.

For Mac or Windows, the download page is at:
http://xmlstar.sourceforge.net/download.php

To validate a TEI XML file enter:

xmlstarlet val --xsd ../../schemas/teiP5osis.2.5.0.xsd test.tei.xml

==== Xerces ====
Xerces is Apache's collection of software libraries for parsing,
validating, serializing and manipulating XML. The implementation is
available in the Java, C++ and Perl programming languages, the Java
version having the most features.

On Ubuntu/debian, you can install xerces-c tools:

apt install libxerces-c-samples

To validate an OSIS XML file enter:

StdInParse -v=always -n -s < test.osis.xml.

You'll find the full syntax here:
https://xerces.apache.org/xerces-c/stdinparse-3.html

==== xsd-validator by Adrian Mouat ====
There isn’t a simple way to immediately run the Xerces validator in
Java from the command line. For that reason, Adrian Mouat wrote a Java
program to solve this issue.

It's called 'xsd-validator', for installing it:

Either clone the git repository at:
https://github.com/amouat/xsd-validator.git
or download xsd-validator zip from:
https://github.com/amouat/xsd-validator/releases/download/v1.0/xsdv-1.0.zip

To validate an OSIS XML file enter:

cd xsd-validator
./xsdv.sh osisCore.2.1.1-cw-latest.xsd test.osis.xml

There is also a cmd file that you can use to run xsdv from a windows Command Prompt.

For installing xsd-validator, run:

sudo ant install

=== Editors Supporting Validation ===
The final choice is to use an editor with validation on the fly. If
you’re doing a lot of XML editing and validation it may well be worth
looking into one of the following:

==== Notepad++ ====

With XML Tools plugin for Notepad++, Notepad++ will allow you to clean
up unformatted files, check XML syntax function if you want just to
check your existing XML file for errors, or use Enable Auto Validation
for automatic validation of code as it is being written among other
features.

Go to the “Plugins” menu, then to “Plugin Manager”, then “Show Plugin
Manager”. Look for XML Tools in the opened window, set the checkbox,
and click the button “Install”.

You must restart Notepad ++ after installation.

==== Emacs ====
It's a little bit tricky, but you can configure Emacs to provide the
following features:

- Easy navigation
- Validation on the fly
- Auto completion

# Use nxml-mode for editing XML
The first thing to do is to force Emacs to use nxml mode instead of xml
mode when editing XML files. nxml-mode uses the nXML extension to
provide automatic validation and lots of other helpful functions for
editing XML files.

Add the following lines to your ~/.emacs file:

(setq auto-mode-alist (cons '("\\.xml$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.xsl$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.xhtml$" . nxml-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.page$" . nxml-mode) auto-mode-alist))

(autoload 'xml-mode "nxml" "XML editing mode" t)

(eval-after-load 'rng-loc
'(add-to-list 'rng-schema-locating-files "~/.schema/schemas.xml"))

If you are using Emacs 24 or higher, you will also need this line that
will give you auto-completion:

(global-set-key [C-return] 'completion-at-point)

# Set-up Crosswire Schemas
nxml-mode validates XML files using schemas in relaxng compact format
(.rnc). We have to convert our files from .xsd format to .rnc.

We use Sun RELAX NG Converter, nowadays bundled with the (Sun)
'Multi-Schema Validator' to convert .xsd to .rng, then we use trang to
convert .rng to .rnc:

Install on Fedora:

# sudo dnf install msv-rngconv trang

## Convert from .xsd to .rng:

rngconv osisCore.2.1.1-cw-latest.xsd > osisCore.2.1.1-cw-latest.rng

## Convert from .rng to .rnc

trang -I rng -O rnc osisCore.2.1.1-cw-latest.rng osisCore.2.1.1-cw-latest.rnc

It's a little bit tedious to convert these files. I think you'll be
pleased to find these 2 .rnc files attached.

## Tell nxml where to find our schemas
We have already (see above) set the variable rng-schema-locating-files
to "~/.schema/schemas.xml

Now, we have to copy our new .rnc schemas in the .schema dir

mkdir -p ~/.schema
cp osisCore.2.1.1-cw-latest.rnc teiP5osis.2.5.0.rnc ~/.schema

and create ~/.schema/schemas.xml:

<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
<namespace ns="http://www.crosswire.org/2013/TEIOSIS/namespace" uri="teiP5osis.2.5.0.rnc"/>
<namespace ns="http://www.bibletechnologies.net/2003/OSIS/namespace" uri="osisCore.2.1.1-cw-latest.rnc"/>
</locatingRules>

# Auto-completion
Type a < character and hit Ctrl+Enter for a list of valid tags. You can
type a few letters and hit Tab to use auto-completion. Hit Enter to
insert the given tag. This also works with attributes: simply add a
space after the tag, and hit Ctrl+Enter for attribute auto-completion.

# links
https://fedoraproject.org/wiki/How_to_use_Emacs_for_XML_editing
https://lgfang.github.io/mynotes/emacs/emacs-xml.html#sec-9
https://www.emacswiki.org/emacs/NxmlMode

=== Validating from Windows Explorer ===
Here is a simple application for validating XML files from within
Windows Explorer.

https://www.codeproject.com/Articles/8431/A-Simple-XML-Validator

=== Python ===
It's relatively straighforward to validate a file with Python:

Let's create simplest validator.py

from lxml import etree

def validate(xml_path: str, xsd_path: str) -> bool:

xmlschema_doc = etree.parse(xsd_path)
xmlschema = etree.XMLSchema(xmlschema_doc)

xml_doc = etree.parse(xml_path)
result = xmlschema.validate(xml_doc)

return result

then write and run main.py

from validator import validate

if validate("path/to/file.xml", "path/to/scheme.xsd"):
print('Valid! :)')
else:
print('Not valid! :(')

So it should be relatively easy to create a 'Crosswire XML validator'
Nautilus extension to help us validate TEI and OSIS files directly from
the file manager in Fedora/CentOS/Red Hat/Ubuntu.

TEI Dictionaries

2020-05-31T18:26:11Z

Domcox: /* Validation */

==Introduction==
In SWORD, the "LD" module type is used to contain modules keyed to non-hierarchical keys. Such modules include: dictionaries (indexed by words or numbers), glossaries (simple one-word translation dictionaries), and daily devotionals (indexed by dates).

For lexicons and dictionaries, the use of [http://www.tei-c.org/Guidelines/P5/ Text Encoding Initiative P5] markup is encouraged. TEI P5 is an XML standard, quite similar to OSIS and ThML, intended for encoding all types of electronic documents. Since TEI is modular, it is possible to ignore the majority of its modules and use only a smaller set of tags necessary to our needs.

For the purpose using TEI P5 in SWORD, we have developed a special XML Schema that includes the basic set of P5 modules necessary for dictionaries and adds osisID and osisRef attributes (with their normal OSIS syntax) to many elements. This will permit cross-referencing with OSIS modules and the use of standard Bible references in TEI documents. Our customized TEI schema is available at http://www.crosswire.org/OSIS/teiP5osis.2.5.0.xsd.

==Order==
SWORD uses a strict binary search to find entries and nearest entries in a "LD" module. There are two restrictions that this places upon a TEI dictionary:

1) Keys are unique and cannot be repeated. This poses problems with some dictionaries that have more than 1 entry for a key. These will need to be merged.

2) Entries will be re-ordered (by the importer utility) based upon their UTF-8 code points. Fortunately this turns out to be identical to a simple 8-bit ASCII collation.

Note: Some characters can be composed or decomposed. The tei2mod importer will normalize to NFC using ICU. Any program that does not normalize its search request in exactly the same way cannot be expected to find entries.

==General Structure==

To produce a Lexicon/Dictionary with our customized TEI Schema, you can use this template:
<pre>
<?xml version="1.0" encoding="utf-8"?>
<TEI xmlns="http://www.crosswire.org/2013/TEIOSIS/namespace"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.crosswire.org/2013/TEIOSIS/namespace
http://www.crosswire.org/OSIS/teiP5osis.2.5.0.xsd">
</pre>

===Header===

A header minimally contains information about the title of the electronic text in <titleStmt>, about its publication in <publicationStmt>, and bibliographic information about the source document from which it is derived <sourceDesc>. A minimal TEI header would look as follows:
<pre>
<teiHeader>
<fileDesc>
<titleStmt>
<title>A title statement about the electronic text</title>
</titleStmt>
<publicationStmt>
<p>Information on the publication of the electronic text.</p>
</publicationStmt>
<sourceDesc>
<p>A bibliographic description of the source for the electronic text.</p>
</sourceDesc>
</fileDesc>
</teiHeader>
</pre>

=== Body ===

Here is the general structure of the body content:

<pre>
<text>
<body>
<entryFree sortKey="AARON">
<def>The son of Amram and Jochebed, and the older brother of Moses and Miriam.</def>
</entryFree>
<entryFree sortKey="ABADDON">
<def>Destroyer, the name given to the king of the hosts represented by the locusts.</def>
</entryFree>
....
</body>
</text>
</pre>

1. '''sortKeys are unique and cannot be repeated.'''

2. The container for a dictionary element in TEI is <entry> for structured entries, <entryFree> for any child elements allowed, and <superEntry> to collect entries into a larger one.

* <entry> is strongly structured. It is more like a database row definition. Elements have particular parenting. And whitespace is insignificant. <entry> requires elements to be in a particular order and nested in a particular fashion and may not allow text in places one would want. <entry> seems more appropriate for original works.

* <entryFree> is weakly structured. It is more like a document. The elements can come in any order, nested in any fashion and text can be interspersed as desired. Thus, whitespace is significant. '''For transforming e-texts into TEI, <entryFree> is then highly recommended'''.

* <superEntry> can be used as a collector for several <entry> or <entryFree>. The tei2mod module creator will create an entry for the <superEntry> and one for each <entry> and <entryFree> in it.

3. The engine is designed to support multiple keys in a single dictionary module so something like <entryFree n="ἀγαπάω|agapaō|G25"> would be a feasible entry. A user could look up the same word in different languages modules without having to switch dictionaries.

An example:
<pre>
<entryFree n="H0002|אב">
<title>H2</title>
<orth>אב</orth>
<orth type="trans" rend="bold">'ab</orth>
<pron rend="italic">ab</pron><lb/>
<def>(Chaldee); corresponding to <ref target="Strong:H0001">H1</ref>: - father.</def>
</entryFree>
</pre>

And here a more complicated example from our Webster1913 module
<pre>
<entryFree sortKey="A" split="A|A per se">
<form type="headword"><orth rend="bold">A</orth></form> <pron>(<hi rend="italic">named ā in the English, and most commonly ä in other languages</hi>)</pron>. <def>The first letter of the English and of many other alphabets. The capital A of the alphabets of Middle and Western Europe, as also the small letter (a), besides the forms in Italic, black letter, etc., are all descended from the old Latin A, which was borrowed from the Greek <name type="biologicalSpecies" rend="italic"><ref target="alpha">Alpha</ref></name>, of the same form; and this was made from the first letter (�) of the Phœnician alphabet, the equivalent of the Hebrew <hi rend="italic">Aleph</hi>, and itself from the Egyptian origin. The <hi rend="italic">Aleph</hi> was a consonant letter, with a guttural breath sound that was not an element of Greek articulation; and the Greeks took it to represent their vowel <hi rend="italic">Alpha</hi> with the ä sound, the Phœnician alphabet having no vowel symbols.</def><lb/>
This letter, in English, is used for several different vowel sounds. See <hi rend="italic">Guide to pronunciation</hi>, §§ 43-74. The regular long <hi rend="italic">a</hi>, as in <hi rend="italic">fate</hi>, etc., is a comparatively modern sound, and has taken the place of what, till about the early part of the 17th century, was a sound of the quality of ä (as in <hi rend="italic">far</hi>).<lb/>
<sense n="2"><num type="sense">2.</num> <seg type="specialization" rend="italic">(Mus.)</seg> <def>The name of the sixth tone in the model major scale (that in C), or the first tone of the minor scale, which is named after it the scale in A minor. The second string of the violin is tuned to the A in the treble staff. — A sharp (A♯) is the name of a musical tone intermediate between A and B. — A flat (A♭) is the name of a tone intermediate between A and G.</def></sense><lb/>
<re type="colloc" rend="smaller"><term type="colloc" rend="bold smaller">A per se</term> <etym>(L. <oVar rend="italic">per se</oVar> by itself)</etym>, <def rend="narrow-spacing">one preëminent; a nonesuch.</def> <usg rend="italic"></usg></re><lb/>
<cit type="quotation"><quote>O fair Creseide, the flower and <oVar rend="italic">A per se</oVar><lb/>
Of Troy and Greece.<lb/>
<hi rend="text-align(right)"><persName type="author" rend="italic">Chaucer.</persName></hi></quote></cit><lb/>
</entryFree>
</pre>

==Markup==

===Linking Entries===
There are three kinds of references in a dictionary:

'''Internal references''' to entries in the same dictionary.
<pre><xr type="see">See: <ref target="self:key">key text</ref></xr></pre>
Note: the key text may be any representation of the key. For example, the key may be G0019a and the key text may be 19a.

'''External references''' to entries in another work.
<pre><xr type="xref"><ref target="work:key">key text</ref></xr></pre>
Note: work is the short module name as found ''between'' square brackets as in [Strong]

'''Biblical references''' to scripture passages. These use osisRef and are discussed below.

====OSIS References====

For the purpose of facilitating the marking of Bible references and linking with OSIS documents, two attributes have been borrowed from OSIS:

osisID exists on virtually all elements and contains osisID(s) (optionally with work IDs). An osisID might be used to link from an OSIS document to your TEI dictionary entry.

osisRef exists on the <tt><ref></tt> element. A biblical reference occurring in an entry might be marked as:
<pre><xr type="Bible"><ref osisRef="KJV:Gen.1.5-Gen.1.8">Genesis 1:5-8</ref></xr></pre>

===Rendering Instructions===

TEI is focused on semantic markup, but supports rendering instructions on most elements via the <tt>rend</tt> attribute. This attribute contains a description (or recommendation) of how the enclosed text should be rendered. In addition, if a segment of text should be marked as primarily significant because of its differentiated rendering, it may be marked by either the <emph> or <hi> elements. <emph> indicates that the text is emphasized, whereas the more general and semantically neutral <hi> element simply acts as a place to hang the rend attribute:
<code>I was <emph rend="italic">extremely</emph> excited by the new TEI filters. Yay.
This text is <hi rend="bold">bold</hi></code>
The <tt>rend</tt> attribute may contain a list of values, but these values are not specified by the TEI P5 specification itself. As such, for the purpose of interoperability and consistency, it is important that values for use in Sword be enumerated. Some of these values come from the set of allowed values on the type attribute of OSIS <hi> elements, which in turn borrows from CSS. Other values will generally borrow from CSS conventions.

CrossWire values for the TEI P5 <tt>rend</tt> attribute:
bold 'from OSIS'
illuminated 'from OSIS; an illuminated letter or drop-cap, rendered very large, preferably across multiple subsequent lines of text'
italic 'from OSIS'
line-through 'from OSIS; used for strike-through text'
normal 'from OSIS; used to switch off special rendering while in the midst of a string of special rendering'
small-caps 'from OSIS'
sub 'from OSIS; subscript text'
super 'from OSIS; superscript text'
underline 'from OSIS'

===Images===

You can easily place images in your TEI file using the <graphic /> element. This element is "milestoned," meaning it isn't a container. The forward slash near the end signals that fact. Use the "url" attribute to define the location of the image relative to the compiled module. In the example below, the image "crosswire.jpg" resides in a folder "images" in the same folder as the compiled module. (SVN version)
<pre>
<graphic url="images/crosswire.jpg" />
</pre>

===Tables===

Tables require a bit of work to get set up but can be useful for some purposes. The entire table is contained in a element, and each row is then contained in a <row> element. For each column in each row a <cell> element contains the text of that cell. The following table creates column labels in bold type and includes two columns and two rows below the label row. (SVN version)
<pre>
<table>
<row>
<cell><hi type="bold">Column 1 Label</hi></cell>
<cell><hi type="bold">Column 2 Label</hi></cell>
</row>
<row>
<cell>Column 1, Row 1</cell>
<cell>Column 2, Row 1</cell>
</row>
<row>
<cell>Column 1, Row 2</cell>
<cell>Column 2, Row 2</cell>
</row>
</table>
</pre>

==Validation==

Use of the above XML header will assist in automated validation with most XML Schema Validators.

How to validate with xmllint:
<nowiki>
$ wget http://www.crosswire.org/OSIS/teiP5osis.2.5.0.xsd
$ xmllint --noout --schema teiP5osis.2.5.0.xsd file.tei.xml</nowiki>

See also the TEI Validator online: http://teibyexample.org/xquery/TBEvalidator.xq

==Importing==
The program tei2mod is used to create a SWORD Lexicon/Dictionary/Daily Devotional/Glossary module from valid TEI.

This is a work in progress, so please report any problems found.

The current usage is:
<pre>
You are running tei2mod:
TEI Lexicon/Dictionary/Daily Devotional/Glossary module creation tool for
The SWORD Project

usage: tei2mod <output/path> <teiDoc> [OPTIONS]
-z use ZIP compression (default no compression)
-Z use LZSS compression (default no compression)
-s <2|4> max text size per entry(default 4):
-c <cipher_key> encipher module using supplied key
(default no enciphering)
-N Do not convert UTF-8 or normalize UTF-8 to NFC
(default is to convert to UTF-8, if needed,
and then normalize to NFC. Note: all UTF-8
texts should be normalized to NFC.)

The options -z, -Z, and -s are mutually exclusive.
</pre>

'''Notes:'''
# At this time, enciphering does not work for tei2mod.
# Currently, all compressed SWORD modules use ZIP compression.
# Having keys in the proper order may noticeably improve import time and may affect the module's lookup performance of "adjacent" entries.

==Troubleshooting==
If a module compiles but causes a front-end to crash:
* Double-check the entry id (@n) to make sure there is a unique id for each entry.
* For modules keyed to Strong's numbers, ensure there is "zero-padding," meaning all Strong's numbers should include four digits plus a zero at the beginning. So "G1" should be "00001". If any numbered id is not five digits, it make cause frontends to crash.
* Remove all <tt><div></tt> elements.

==Other helpful sites==

[http://www.tei-c.org/release/doc/tei-p5-doc/en/html/index.html The TEI Guidelines] and in particular, the documentation for [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-entryFree.html <entryFree>], on which most dictionaries should be based.

Tutorial modules accompanied with a dedicated examples section: http://teibyexample.org/TBE.htm

==Sample TEI P5 documents==
* [https://gitlab.com/crosswire-bible-society/webster1913 Webster's Dictionary (1913)]
* [https://gitlab.com/crosswire-bible-society/strongsdic Strong's Dictionary]

[[Category:Guides|TEI Dictionaries]]