[sword-devel] Creating modules for a beginner

[DM Smith]

On Jan 21, 2008, at 7:51 AM, Joseph Daniel wrote:

> Concerning module creation, I am facing many problems in converting  
> some
> eSword modules to work on the SWORD project. These bible versions  
> are ALAB ,
> GNA and JAB. All are Arabic translations.

We don't condone converting eSword modules. Without permission from  
eSword, you are in violation of the license agreement that is part of  
every module's exe.

However, assuming that you have obtained such permission and also  
permission from the copyright owner, if currently under copyright.....

Did you see our module making instructions on our wiki: http://www.crosswire.org/wiki/index.php/DevTools:Modules

If it is incomplete, we'd like to improve it.

>
>
> I have the permission to copy and distribute them but I am facing many
> problems in converting them. I tried parsing the whole module into  
> verse per
> line format but them vpl2mod tool didn't work.

Please let us know exactly what problem you had. How is your input  
file structured? What command line did you use? Was it that vpl2mod  
failed? That it gave an error message? That the resulting module  
didn't work?

Hopefully the following will fill in the gaps. Let us know what works  
for you and how we can improve our wiki documentation.

vpl2mod should be able to handle anything with a KJV versification. It  
will produce a "raw text" module.

The following is from reading the code. It is possible that I may not  
be understanding what I see.

The basic command is:
vpl2mod <source_vpl_file> </path/to/output/mod/> [0|1 - prepended  
verse refs] [0|1 - NT only]
where the first argument is your vpl input file and the second a path  
to where you want the output files to be placed. Note, that directory/ 
folder/location must already exist.

The next argument indicates one of two different input formats. With  
either format a line beginning with | is a comment line and is ignored.

Basically it can handle one of two formats:
0) VerseText
When this is used, the file must have exactly 31102 lines for then  
entire Bible, or ??? (I don't know the exact number) for the NT only.  
You will notice that this is larger than the number of verses in the  
KJV. This is because we allow for "chapter 0" and "verse 0" for  
introductory materials for Bible, books, and chapters. Blank lines  
must be used for missing entries.

There are versifications other than the KJV. If you have verses not in  
the KJV versification, then append them to the previous verse. If you  
are lacking verses in the KJV versification, leave a blank line.

1) VerseRef VerseText
There is a comment in the code indicating that it is not implemented,  
It looks like it is implemented but it may be broken. If it works, it  
is the preferred format because it is more flexible. For example, it  
doesn't require every verse to be present.

The VerseRef can be pretty much anything that Sword can understand as  
a verse reference, but minimally it needs to match the following  
pattern:
*A*D*:*D*S where
* is any number of any characters leading up to the following
A is anything that satisfies isAlpha
D is anything that satisfies isDigit
: is the literal colon.
S is a blank, a space (not a tab)
  (Note: osisIDs don't have a : and thus would fail to match)

Everything after the first blank is taken as the verse text.
Any line that does not match this pattern (or a comment) will cause  
the program to exit.

With this format, verses don't have to be present or in any particular  
order. However, verses that are outside of the KJV versification will  
be appended to the last seen verse.

The final argument allows for a New Testament only file to be used,  
beginning with Matthew 1:1. This is only of use with a second argument  
of 0.

Note: VPL is an input format. The VerseText can be any kind of  
supported encoding: Plaintext, ThML, OSIS, GBF (please not GBF!) but  
it has to be on a single line.


> I don't understand whether
> vpl alone is  enough or should I still put it in OSIS / thml format.

Another input format is imp. It is like vpl, but can work for any kind  
of module. It is a bit more flexible/forgiving than vpl. With  
Plaintext modules, it handles verses with multiple lines. imp2mod  
handles that.

Both OSIS and ThML can be used as input formats to other module making  
programs.


>
>
> I am sorry if this is a bit off topic but could someone guide me on  
> how to
> do it? The guide on the website seems to be missing a lot of  
> details. Can
> anybody just give me a sample module so I can see how it's working?

You can get the OSIS kjv at www.crosswire.org/~dmsmith/kjv2006

Just run it through osis2mod with (linux commands. windows is similar):
mkdir -p modules/texts/rawtext/kjv
osis2mod modules/texts/rawtext/kjv kjv.xml

Hope this helps.

Working together for His Kingdom,
	DM Smith