[sword-devel] Building GenBooks programatically

[Troy A. Griffitts]

Ben Morgan wrote:
> Hi,
> 
> I would like to have the ability to turn gospel harmonies into
> GenBooks from inside my application, and let the user edit them using
> a standard tree control and an editor.
> 
> I have a number of questions:
> 
> 1. How do I create an empty GenBook? How do I install this to the
> user's sword directory (no InstallManager support in Swig bindings yet
> :(
> 
> 2. How do I add content to a GenBook i.e Add/remove nodes, add content, etc.


The write interface for SWModule is fairly short and can be found here:
http://crosswire.org/svn/sword/trunk/include/swmodule.h
(search for: write interface)

There is a small console utility which creates genbooks interactively. 
You can probably lift the code from there.  It is located at:

http://crosswire.org/svn/sword/trunk/utilities/genbookutil.cpp
(A quick look shows that it could use some commenting, especially the 
test, at the start of main. to see if a genbook already exists at the 
path specified, and if not create one.)


> 3. What format is used for genbooks? If the user inputs as html or
> plaintext, do I have to add other formatting?

Markup and data format are 2 independent matters.  Using the RawGenBook 
driver as your data format does not mandate any specific markup in your 
data.  You must choose one and specify it in your .conf file with an 
entry like:

SourceType=OSIS


> 4. Can I link to other nodes inside my genbook (using standard procedures)?

There is a concept in SWORD of key linking, e.g. a commentary which 
comments in one block to John 3:3-16 can add the entry to John 3:3, then 
link 4-16 to John 3:3.  This allows the correct entry to be retrieved 
when a user asks for, say, John 3:16.

You are likely referring to something else we call referencing. 
Currently in SWORD only references to the KJV versification scheme are 
supported.  OSIS supports references to anything, and we plan to support 
the full OSIS spec, so if you'd like, you can chose to use OSIS markup 
in your books and use the <reference> tag to specify a reference to 
yourself.  We've had initial discussion about the implementation of this 
and decided that since the default for SWORD references is Bible.KJV, we 
would imply another osisWork aliased 'self' for easy self reference, e.g.
Please see comments in <reference osisRef="self:/intro">The 
Introduction</reference>

These obviously will not work until the frontends implement code and 
they will likely not do so until the engine provides some concept of how 
to determine the target module of a reference.  All frontends that I am 
aware of assume that the user's preferred Bible (or the current Bible) 
is the target of every reference.

Wish I had better news for you on this one.


> 
> 5. Is it worth placing  something like Feature=Harmony to tell other
> programs that is a harmony?

I would think a Gospel Harmony data module would be wonderful.  I would 
expect it to be something like a Bible module which, when I looked up a 
verse, would return to me verse references for the parallel text in the 
other Gospels.  It would have to be recognized as a special module and 
utilized appropriately in a frontend.  That would be easy to add to the 
engine.  In fact, there have been quite a few suggestions and ideas 
posed about 'special modules' which a frontend could utilize to make 
features available to the user.  We should probably add a .conf flag like:
Public=false
So we can easily distinguish between modules which should be presented 
to the user, against modules intended for programmatic utilization.

What do you think?

	-Troy.


> 
> 
> I'm not even sure how to create a genbook from an imp file. When I
> tried using imp2gbs, and wrote my own mods.conf, it crashed my
> interactive python session when I tried mymod.RenderText() :(

That's odd.  Let me know if you still have troubles after looking at the 
example code.  Markup filter parsers in SWORD assume some level of 
validity with burden of enforcement lying with our import tools (getting 
better all the time).  They do not error out well when they meet with 
malformed markup.  They mostly care about speed and assume preprocessing 
has filtered out errors.

Hope this is somewhat helpful.

	-Troy.



> 
> God Bless,
> Ben
> -------------------------------------------------------------------------------------------
> There is no love sincerer than the love of food.
> George Bernard Shaw (1856-1950)
> 
> _______________________________________________
> sword-devel mailing list: sword-devel at crosswire.org
> http://www.crosswire.org/mailman/listinfo/sword-devel
> Instructions to unsubscribe/change your settings at above page