Difference between revisions of "Module Submission"

From CrossWire Bible Society
Jump to: navigation, search
(Fix confmaker.pl link)
(Changes to reflect the upgraded publishing framework)
Line 1: Line 1:
−
'''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]]''
+
----
 +
'''<span style="color: crimson">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
+
= 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\_].
  
−
# Please check and validate your OSIS or TEI text. Please create a test module for yourself and check it for typical mistakes:
+
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.
−
## 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'''
+
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 reflect 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:
 +
 +
== 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 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.
 +
 +
== Link to 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.
 +
 +
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.
 +
* For upgraded modules, we'll clone tagged releases, so you have to mark your release by running <code>git tag <version></code>.
 +
* 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]]
 
[[Category:Modules]]

Revision as of 20:35, 14 December 2020

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[1] 3 letters for language, followed by a short name descibing the work. Language is encoded in ISO 639-3 code. See [1] for a list of codes.

The name has to be set in CamelCase format. Example for The French Bible David Martin 1707: FreBDM1707[2]

  1. ↑ For historical reasons, modules in English do not have any language prefix.
  2. ↑ The published year was added to differentiate this version from successive revisions in 1744, 1855. Otherwise we could just have named it FreBDM.

How-To name your files

The source files reflect the name of your module in lowercase followed by an extension.

For the configuration file, the extension is .conf.

Extensions for the text file:

  • OSIS: .osis.xml
  • TEI: .tei.xml
  • VPL: .vpl
  • IMP: .imp
  • ThML: .thml

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

How-To prepare your files

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

  1. ↑ Only for Bibles in KJV versification

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 workID and an appropriate osisRefWork 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: 

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

Commentary: 

<osisText osisIDWork="MyModule" osisRefWork="Commentary" xml:lang="gr">

General Book: 

<osisText osisIDWork="MyModule" osisRefWork="GenBook" xml:lang="en">

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: Description, About, DistributionLicense, and TextSource. 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 copyright.pdf, copyright.png...

Submit your files

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

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

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

Link to git Repository

If you built your module on a public Git/GitLab/GitHub, you may want to share the git clone URL in the email.

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 images for dictionaries.
  • For upgraded modules, we'll clone tagged releases, so you have to mark your release by running git tag <version>.
  • 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 git archive and attach the resulting zip file to the email.


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


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.

Retrieved from "https://wiki.crosswire.org/index.php?title=Module_Submission&oldid=16994"