[sword-devel] compiling modules

[Chris Little]

Hi Beth,

I don't know if I've mentioned or promised this to you before, but we 
have a decent USFM to OSIS converter at 
http://crosswire.org/ftpmirror/pub/sword/utils/perl/usfm2osis.pl

I certainly haven't mentioned this latest version, which is the first 
fairly usable one we've released, since I know it was written more 
recently than the last time we crossed paths. I'm sure SIL and Snowfall 
Software must both have some other decent tools for converting USFM to 
OSIS (though possibly only in-house).

You can definitely do more with OSIS than through other import methods.

We have some module import documentation in progress on our Wiki at 
http://www.crosswire.org/wiki/index.php/DevTools:Modules

It may be worth your trouble to export a module using mod2vpl to see an 
example vpl file, as expected by vpl2mod. E.g. 'mod2vpl ASV 1 > asv.txt' 
will export the module ASV to asv.txt, which can then be re-imported 
with 'vpl2mod asv ./ 1'.

Other comments below, to complement Greg's.

Beth Bryson wrote:
> 2. For vpl2mod, does "prepended verse refs" mean that my text includes
> the prepended verse info, or that I want to tool to prepend them?  My
> text looks like this:
> 
> Matthew 1:1: This is the first verse.
> Matthew 1:2: This is the second verse.
> 
> but it doesn't seem to use that verse information to decide where to put
> the content, regardless of whether I choose 0 or 1 for that argument.  I
> get better results with "1", but I still get a screen full of lines that
> say "problem", with no indication of what the problem is or what line
> the problem occurs on.  (I think it must occur on *all* the lines--there
> are that many lines of it.)

If you use prepended verse refs, that should do away with most of your 
problems. There is no need for additional lines to hold missing verses 
or book/chapter headers. But the format needs to be:

Matthew 1:1 This is the first verse.
Matthew 1:2 This is the second verse.

(No colon after the verse ref. The book names should probably be in 
English.)

> 3. My verse references seem to be ending up in the text.  In MacSWORD, I
> see this:
> 
> Matthew
> 17
> 1 Matthew 17:1: This is the first verse
> 2 Matthew 17:2: This is the second verse
> 
> Is there a way to *not* have the "Matthew 17:1:" appear?  Does this have
> to do with how I built my module?  Is it not parsing my verse refs?  (I
> have tried it both with and without that final colon, and same results
> both ways.)

If they're appearing in the text, they aren't being parsed. With the 
verse refs switch turned on and without the trailing colon, this should 
work correctly. (I just tested it and I don't see any bugs here.)

> 4. The text I'm working with has some verses missing; do I need to put
> placeholder text there?  For instance, if Mt. 2:21 is missing, then the
> contents of Mt. 2:22 end up in Mt. 2:21, etc.

No. If you're using prepended verse refs, just omit any mention of 
omitted verse.

> 5. It seems to be expecting me to have :0 references for all the
> chapters except chapter 1; if I don't, the content is off by one verse
> per chapter (Mt. 2:2 ends up in Mt. 2:1, Mt. 2:3 in 2:2; Mt. 3:3 ends up
> in Mt. 3:1, etc.)  Do I need to be sure there are 2:0, 3:0, etc. references?

If there's heading information, stick it in :0. If not, just omit.

> 6. It seemed like even if I used a 2:0 reference, the contents of that
> didn't show up in MacSWORD.  This is a non-English text, and it would be
> nice to at least have the title of the book appear in the same language
> as the text.  I need to experiment more, but wondered if someone could
> tell me what to expect.

Book names aren't generally stored within a book itself, rather within 
locale files. There should be a way to change the locale (and thus see 
book names and input verse references in languages other than the 
default) but I can't see it in MacSword, so it may be absent.

> 7. I also tried using imp format instead of vpl.  Some things worked
> better, but I still ended up with the references in the text, and
> content offset if there were missing verses.  In this case my input
> looked like this:
> 
> $$$Matthew 1:1
> This is the first verse.
> $$$Matthew 1:2
> This is the second verse.
> 
> Even though I built the imp file in the terminal on my Mac (using my own
> Perl script to convert from USFM), I changed the line endings from Unix
> ones to DOS ones before moving the file over to my Windows virtual
> machine to run imp2vs.exe on it.

I can't see how this is possible. imp2vs doesn't retain the state of 
verse references from one entry to another and has no notion of verse 
ordering, so I don't think it's possible to have verse offset errors. It 
also cannot function at all unless it parses the verse references after 
$$$, so I would guess that you were actually seeing results from one of 
your vpl2mod builds that wasn't overwritten.

Line endings shouldn't matter at all. They're all regularized (I believe 
as Unix endlines).

> 8. The text I'm working with starts out in USFM, and it uses \s markers
> for section headers.  Is there any way to make use of section headers in
> a SWORD module, or are they just tossed?  Do I need to use OSIS format
> or something else if I want to keep them?  Is MacSWORD able to display
> those?  (I also have cross-references and footnotes, but I haven't
> started thinking about whether those could also display.)

I'm not sure whether MacSword can display section headings, but in order 
to encode them in the module, you do have to use OSIS and the osis2mod 
importer. MacSword quite probably display basic things like footnotes & 
cross-refs, but these require some kind of markup that Sword 
understands. (OSIS being the best currently.)

I think I would recommend usfm2osis.pl again. And hopefully it is clear 
enough that you can modify it if need be.

--Chris