[jsword-devel] a new users perspectives on APIExamples

[DM Smith]

Mike,

Thanks for your feedback.

I have entered an issue into our tracker at: 
http://www.crosswire.org/bugs/browse/JS-86

See below for comments.

DM

Mike Bradley wrote:
> I'll try to summarize my experiences with APIExamples which will 
> hopefully be somewhat indicative of a new users experience.
>
> To start with, here are some things that I assumed as I was getting started:
> I assumed that APIExamples could be run with only the jsword and the 
> common projects checked out of SVN.
> I assumed that APIExamples serves as a primer to get someone familiar 
> with the jsword way of doing things.
> As such, I assumed APIExamples was the place to start to learn jsword
> I assumed that APIExamples would not need additional setup to be run
>   
I think the examples should be self-contained and should satisfy and 
validate their own assumptions.


> I ran into some problems running APIExamples. I'll try to state them 
> clearly without reading too much into the causes.
>
> Problem: I didn't have a KJV Bible
> My solution: I ran bible desktop, downloaded the KJV and then copied the 
> .sword directory from bibledesktop to jsword
> I could have also gotten this to work with the installManager example 
> that DM added to APIExamples (thanks for that btw DM)
>   

This new example should be used to satisfy assumptions.

> Problem: I didn't have a dictionary
> My solution: Same as prior, but using a dictionary instead of the KJV
>   
Ditto.

> Problem: Couldn't search as the ".jsword\lucene\Sword\KJV" directory did 
> not exist (I think that was the problem anyway)
> My solution: Ran bibledesktop, enable searching for KJV, and then copied 
> the .jsword/lucene  directory from bibledesktop to jsword
>   
There needs to be an example of how to index a Bible and how to search it.

> Problem: searchAndShow() seems to be dependent upon bibledesktop. 
> Explanation: searchAndShow() is looking for "xsl/cswing/simple.xsl" 
> which seems to be in the bibledesktop project: 
> "org.crosswire.common.xml.Converter"
> My solution: Haven't worked on fixing this one as I don't think I need 
> it for my purposes
>   
This is easily fixed by adding bibledesktop and common-swing to your 
program.

That said, I think the xsl, converter, XSLTemplates and related code 
should move out of BibleDesktop and into jsword, common and 
common-swing. This would allow more apps to reuse the process.

> Problem: readStyledText() fails to add class 
> "org.crosswire.common.xml.Converter" and throws an exception saying as much.
> My solution: Haven't worked on this one either, but DM said that he 
> fixed it in an earlier check-in.  It is still not working for me, and I 
> thought I was all caught up with the lastest check-ins, but I might not 
> be as I'm still getting used to the subclipse way of doing things (I 
> usually deal with subversion from the command line).  In other words, 
> the problem could very well be only on my end.  I'll work more on 
> figuring out if that is true later.
>   
This should just be a classpath change. This looks like common.jar is 
not on the classpath.

> I'm not necessarily trying to get anyone to fix these.  I think I've 
> gotten just about everything I need working.  I'm just trying to provide 
> some feedback to you in case it is helpful.

These should be improved.

Another improvement might be to create stand-alone programs for each 
task (e.g. install manager, index manager, searcher, lookup, ....).