[bt-devel] refactoring

[Troy A. Griffitts]

On 07/15/2010 03:31 PM, Jaak Ristioja wrote:
> Regarding SWORD, personally, my main blocker is the lack of good
> examples/tutorials on how
> it is supposed to work. Here's a quick list of most important things I
> don't yet
> understand about SWORD, but need to understand to develop BibleTime:
>
>  * how to handle multiple install sources
>  * how to install/remove modules
>  * how to list installed/installable/upgradeable/downgradeable modules
>  * how to get module information (name, description, language(s),
> encryption, version etc)

Initially sword/utilities/installmgr.cpp was written as
sword/examples/installmgr.cpp.  It's purpose was to demonstrate how to
use the new (at the time) install features of the engine.  It still
provides a very concise example for all of the above.  It was moved from
'examples/' to 'utilities/' because it started to become useful for more
than an example.  But in general, the examples/ tests/ and utilities/
folders are a great place to look for an eclectic collection of code
which uses the engine-- though authorship is also eclectic and some may
be more 'proper' than others.

>  * how to read encrypted modules

In the .conf file there is an entry, CipherKey=.  Once this is set to
the correct unlock key, there is no difference in reading encryped modules.

>  * which books/chapters/verses or parts are present in a module

This does not exist.  You can query the versification that a module
implements, but there is no interface for asking what 'coverage' of that
versification is present in a module.  Do you have a suggested interface?

>  * how do I read a specific verse/part of a module

module->setKey("jn.3.16");
cout << module->RenderText();


>  * how do I read footnotes, Strong numbers, cross-references etc?

sword/examples/cmdline/lookup.cpp is a great example for this.

The module->getEntryAttributes() method is how these are exposed from
the engine.


> I have searched but I haven't found any good documentation on this.
> This has been
> implemented in BibleTime before I joined the project. BibleTime and
> SWORD source code
> documentation is not enough. Simple examples and tutorials are needed.

I would love to add to our examples.  Please have a look at what is
there and let's add to it as we answer your questions.

> What I want to archive for BibleTime is a modular backend which (among
> other things)
>   1) were able to interact with SWORD as well as any other library
> capable of providing us
> input data and
>   2) would provide Qt-style models for modules, and for the data
> inside those modules
>
> Blessings! :)
> Jaak
>
> PS: Who wrote the part of BibleTime interacting with SWORD?
> PPS: Some more questions about SWORD:
> 1) Is it possible to install multiple versions of the same module at
> once? will it be
> possible in the future?

Yes, if they are in different install paths; e.g.,
sword.conf:
AugmentPath=/home/ristioja/betamodules
AugmentPath=/home/ristioja/alphamodules
AugmentPath=/home/ristioja/experimentalmodules

I believe Martin asked for this feature a while back and we added it.  I
don't think it is turned on by default.  It looks like we called it
'multiMod' and it is passed as a bool parameter to methods that read
modules: SWMgr c-tor, SWMgr::autmentModules(path, multimod), etc.

If this is false, only one copy will be presented and which copy is
undefined; If this is true, I believe you will get names with _#
instances, e.g., KJV_1, KJV_2, KJV_3

In my opinion, it's better to just change your kjv.conf file to be
[KJV_beta] so you know which one is which.  But we all have different
use cases.


> 2) Is it possible to verify whether a decryption key works?
No; this was on purpose.  It was intented to alleviate brute force loops
against a module.  In the frontends that I have worked on, we present
the user with a screen that asks for the unlock key and give a [Try]
button.  When they press the [Try] button we apply the key to the module
and retrieve some text and present it to the user.  If they are happy,
they can click next. to continue to install.


> 3) What about thread safety?

Each thread should have their own copy of a module.  e.g.,

SWMgr library;
SWModule *kjvDisplay = library.getModule("KJV");
SWModule *kjvSearch = kjvDisplay->clone();

Or easier to manager so you will not need to delete the clones modules:

SWMgr libraryDisplay;
SWMgr librarySearch;

This will give 2 instances of each.

We've tried to make things as threadsafe as possible without adding
'thread-awareness' in the engine.  There are a few remaining 'statics'
that may be dangerous and I'd love to clean up.


> 4) Is it possible to use SWORD without creating any classes that
> inherit from the SWORD
> classes?

Well, sure:

SWMgr library;
SWModule *kjv = library.getModule("KJV");
kjv->setKey("jn.3.16");
cout << kjv->RenderText();

But I'm not sure this is the level of 'use' you want.  Is there a reason
you ask?  The SWORD engine provides adaptor interfaces intended for the
client to 'inherit' and implement.  These are design decisions and good
ones, I hope.


Thanks for your feedback.  Looking forward to improving things for you
and others!  Appreciate your willingness to dialog.

Troy

_______________________________________________
bt-devel mailing list
bt-devel at crosswire.org
http://www.crosswire.org/mailman/listinfo/bt-devel