[bt-devel] BibleTime's Goals (was Re: New passage selector proposal)

Sat Apr 21 19:56:04 MST 2012

Hi Jaak,

Thanks for the 4 hours to think about and respond.  I am encouraged by 
your desire to try to work more closely together.  I do realize the lack 
of design documentation for a fairly complex engine makes diving in 
difficult and criticism easy, if reasoning is not available.  We can 
talk specifics over the coming months, but I want to say that I will 
commit to drawing up a UML diagram and better document the engine.

On the roadmap, the push to jump to 2.x focuses solely on regularizing 
the public interfaces in the engine.  SWORD was written long before Java 
and the mass adoption of camelCase, so you will see many inconsistencies 
in concepts and naming in the public interfaces.  For the past 10 years 
or so, new methods have followed standard camelCase naming and 
properties have followed the standard pattern:

void setX(const type val);
const type getX() const;

... but there are many methods and concepts still present which predate 
this.  We've been deprecating the older method names and interfaces in 
favor of the newer replacements when added.

But just to say, I understand a cursory glance at the SWORD interfaces 
can look a little strange.  We've budded a few odd limbs over the many 
years of the project.  2.x should fix this perception.

In conclusion, my start of a UML diagram can be found here, which 
contains very basic conceptual information for probably the 12 most 
important (of the over 150) classes.  If an API user sticks to the 
primary interface classes + a handful of derived specifics: SWMgr, 
SWModule, SWKey, VerseKey, ListKey, InstallMgr, a nice user interface 
can be made without much more knowledge.  I tried to show the conceptual 
relationships and have commented on the classes and methods in the 
diagram (I'm not sure how to make dia export something which will show 
comments on hover, but you can double-click and look).  I'm afraid a 
full UML diagram might be overwhelming for an end user if they don't 
know which classes are primarily important, but I understand the need 
for the basic interface classes and a few more.

http://crosswire.org/~scribe/sword.dia

Also, what might be helpful is our IDL we use for the Java binding. 
When I personally generate bindings for the engine (most recently the 
JNI for NDK in Android), this is the interface I usually expose.  It is 
much more concise than looking at all the implementation details.  All 
the rich functionality available on SWORDWeb (

http://www.crosswire.org/study/parallelstudy.jsp?del=all&add=KJV&add=TR&add=Treg&add=NASB&key=John.3.16#cv

) is accessed via this short interface.

http://crosswire.org/svn/sword/trunk/bindings/corba/swordorb.idl

I'll keep plugging away at the documentation and try to continue my 
introductory tutorials I started a while back.

Thanks again for your willingness to try to change things.  I am looking 
forward to working more closely with you and your team over the coming 
months (and Lord willing, years!).

In Him,

Troy

On 04/21/2012 10:15 PM, Jaak Ristioja wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> Hi!
>
> On 20.04.2012 19:07, Troy A. Griffitts wrote:
>> I hear what you're saying Greg, though I find your detailed issues
>> not insurmountable.
>>
>> My comments in this thread are mostly rhetorical; I wasn't looking
>> for technical responses.
>>
>> We need to decide:
>>
>> Are we a community?  Why are we a community?  What EXACTLY do we
>> have in common?  How can we work together on that commonality?  I
>> see that as SWORD.
>>
>> I don't plan on living forever and I would love for the many
>> projects that use the SWORD engine to start owning it more than
>> they do.
>>
>>
>>
>> The vision for SWORD has always been to produce a lean and
>> powerful, cross-platform Bible research framework which many
>> projects can share in using and developing.  I believe we've
>> attained that over its 20 year life-cycle, but I don't believe
>> we've seen the contributions to the core engine that we could see
>> if people would buy in and own it as their backend.  I've
>> personally written at least 5 frontends with the engine and all my
>> frontend work has driven improvements to the engine.  I haven't
>> worked on a frontend in a long time and am no longer on the front
>> lines-- situated to know what improvements now need to be made.  I
>> would love it if each frontend project had one developer who was
>> intimately familiar with SWORD and could liaise between the backend
>> and frontend teams and contribute to both.
>>
>> Greg, I appreciate your contributions to the engine.  Please don't
>> think my goal is to accuse and blame anyone for never contributing
>> to the engine.  I'm just attempting to make our projects think
>> about our involvement with each other and how we can work more
>> closely together.
>
> Ok. Before I start I want to say that I'm largely going to ignore
> everything said on this thread and will try to keep matters simple by
> replying only as a developer, and write about how I think and feel
> about this situation. I will try to be concise.
>
> When I got involved, I got involved with BibleTime. It is a piece of
> software being developed by a small team of volunteering individuals
> in its own repository. BibleTime largely utilizes the Sword library
> for displaying and managing the installed works. I was not present at
> the birth of BibleTime or Sword, but when I joined the cause, I didn't
> see BibleTime and Sword as one project, but two. Regarding the
> development process I have never before considered BibleTime and Sword
> to be one community, although they have appeared somewhat close to one
> another. Whether they were one development community in the past I do
> not know.
>
> My focus has always been on BibleTime and I've tried to improve it as
> best as I've been able to. In this matter my focus has always been on
> BibleTime and I haven't much considered hacking on Sword. The most
> important reasons for this have been that
> 1) I've never actully understood Sword very well
> 2) I haven't much considered that I could change Sword
>
> The first reason might be because the API has always appeared to me to
> be a bit weird (their own string classes, strings as key indexes,
> #includes without a "sword" prefix etc) and I haven't seen much good
> documentation on it. In addition we've had some trouble with Sword in
> BibleTime because the text we get from Sword has sometimes contained
> tags from the underlying markup, or some other weird syntax. In my
> opinion, the worst problem with this is that there is no formal
> specification (formal grammar) for this kind of Sword output and
> parsing/translating it is still a very esoteric matter for me. Maybe
> you do have the knowledge and insight needed for this because you've
> been with the project for long. I don't and I haven't found a simple
> way to get it.
>
> The second reason might be because it has almost never entered my mind
> that I actually could participate in the development of Sword. I think
> Sword has always appeared to me to be rather closed both regarding the
> development process and documentation (e.g. file format specs). I've
> never actually seen or understood what goes on behind the scenes, I
> have no idea how to join or where are documented the procedures about
> how to contribute / submit patches.
>
> Several times I've thought about changing the Sword API. Since
> contributing to Sword has always seemed to me as an obstacle, I have
> rather thought about writing an alternative backend for reading Sword
> modules or forking Sword for BibleTime's purposes and using it as a
> git submodule etc etc. Occasionally I have also arrived to the
> question about fixing some Sword bugs or deficiencies, but I've ended
> up abandoning or working around these as it has seemed to be much easier.
>
> This is how I have thought and felt about this. My intentions have
> been to advance BibleTime, an end-user application depending Qt and Sword.
>
> Maybe there once was a common development community. Either way it
> seems to me there's not much left of it now. I might be mistaken thou,
> because I don't know exactly what the relation BibleTime's older
> developers have had with Sword/Crosswire. However, previous devs leave
> or become inactive and new ones join.
>
> I think the questions to ask should not be about what we are, but
> rather about how do we fix this? How do we build renew our relations
> and (re)build this community? How can we better communicate and help
> each other?
>
> I think the Sword project seriosly needs to think about some changes
> to make it easier for people (me) to contribute. I'm going to be very
> very bold now. Please try to bear in mind I only mean well. I'm going
> to be very bold and suggest the following:
>    1) Migrate to git(orious) (Yeah, I'm being bold and suggest
> gitorious just because that's what BibleTime uses and because I
> personally object the github EULA). Move to a DVCS to provide other
> developers a better way to contribute. Allow them to request their
> changes to be merged to your main repository, talk and work together
> with them when reviewing their changes. Open up the development process.
>    2) Write more documentation. Write better documentation. It must be
> something which actually helps developers understand Sword (ideally
> all of Sword they will ever use). It must help them understand Sword,
> not just use Sword. Architectural (UML) diagrams might help. Document
> the file formats, specify a formal grammar for the texts Sword outputs.
>    3) Be prepared for hardship and change. :)
>
> I believe we would benefit from (re)building this community. But we
> really need to think what we need to do to make this relationship
> work. I'm not sure whether any of us are ready now, but I suggest we
> get ready and try anyway. My suggestions might not be the best ones,
> but these reflect the issues I've been struggling with and which have
> prevented me from becoming "intimate" with Sword.
>
> I hope this helps and that I haven't spent the last (four?) hours on
> this letter for nothing. Let's please try to continue these
> discussions in a manner pleasing to God!
>
> God bless!
> Jaak
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v2.0.18 (GNU/Linux)
>
> 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
> MV2bfwuFyeOFVRF1qz4z
> =7xTi
> -----END PGP SIGNATURE-----
>
> _______________________________________________
> bt-devel mailing list
> bt-devel at crosswire.org
> http://www.crosswire.org/mailman/listinfo/bt-devel