[sword-devel] frontend features, their applicability -- consistency?

Karl Kleinpaste karl at kleinpaste.org
Wed Apr 14 08:25:51 MST 2010

I've had some philosophical meanderings about frontends over the last
several weeks.

One of the best things about The Sword Project is that a whole herd of
applications has been able to grow up around the core engine.  Support
constructs based on platform capability, workflow ideals, toolkit
provision, and other qualifiers have led to a lot of interesting
variability in how each application particularly presents the generic
concept of "Bible study" to the user.  We have a wiki page on choosing the
right application, in order to distinguish some of their features.

But there is concern in my mind about a lack of consistency in how we do
things, and possibly more importantly, where consistency matters.

The immediate example that brings this to mind for me is the recent
discussion on bookmark storage and sync.  The goal sought is an ability to
sync bookmarks across applications, providing e.g. desktop -vs- handheld
consistency.  A fine goal, on its face.

But that mis-interacts with the general net.paranoia level with which we
(are supposed to) provide our applications.  Notably, if the storage is
off-site, then the user will access a network resource, and that bumps
sideways into the necessity of ensuring that the user wants to allow that,
bearing in mind the general perspective of (notably) module managers, for
which we are obligated to warn the user, "If you are in a persecuted
place, avoid packet snooping/traffic analysis: Don't use the mod.mgr."

This brings a couple problems.  First, we have the necessity of the
interaction: Does the user allow this to occur?  If the user declines --
for now, or forever -- then we are left with an application that still
must provide bookmark storage.  That means that we must create 2 retrieval
methods for bookmarks, and that complexifies the bookmark subsystem in the

The result is that, regardless of whether network-sync'able bookmarks ever
get implemented, every application must still provide its own method for
doing so locally.  That will be OS-, language-, toolkit-, and
filesystem-dependent, thus usually not portable.  I'm simply not yet
excited about having to expand this in Xiphos, because the value gained
from doing so likely won't offset the anguish of its development.

But why do I say that?  Because sometimes we have warped ideas of what's
important.  Generally speaking, we are often not like our users.

In a related discussion in the Xiphos devel list, it was pointed out that
we as developers sometimes have an odd perspective about interoperability,
because we keep multiple applications installed in order to test our
features and our modules, and so we think "everyone" must want
"everything" to work together.  On its face...um, yeah, sure, and while
we're at it, we love baseball, motherhood, and apple pie, too.  In
reality, how many Joe Averages are there, who particularly care whether
bookmarks can be sync'd among Xiphos, BPBible, BibleTime, PocketSword,
Bible Desktop, and BibleCS?  Do you (does anyone) actually do remotely the
same kind of study in 2 different applications?  Do you care whether your
tightly-managed bookmarks in Xiphos are directly usable in PocketSword,
which doesn't yet provide bookmark titles, has no hierarchy, and no multi-
verse support?  For facially similar applications (say, Xiphos and
BibleTime, or BPBible and BibleCS, or...pick any pair), does Joe Average
actually use 2 such applications, so that sync rises to the level of
interest, or in fact does he look over a couple of the available
possibilities, and then come down in favor of using just one?

Can we even claim to know?  If so, how?

A prime, on-point example: Since the Dawn Of Net.Time, there has been code
in GnomeSword/Xiphos to import BibleTime bookmarks.  But the code to do so
was so unsupported that it simply stopped working well over a year ago,
when BT left behind its KDE specificity.

Nobody noticed, nobody cared.  I have never seen a bug report or feature
request concerning BibleTime bookmark import.  Not one, not ever, in all
the hundreds of bugs that have ever been reported against Xiphos over the
last decade.

Having noticed the problem because of the discussion on bookmark sync'ing,
I mentioned it to our devel list.  Terry stepped up and fixed it with a
few lines of code.  I tried it out; yup, now it works.  This caused me to
look a little bit into BT bookmarks, at which point I discovered something
really important:

Xiphos uses the exact same bookmark storage format as BT.

I didn't know that until this time.  I didn't know because I had never had
cause to want BT bookmarks in the first place, because Xiphos is my
application of choice, and I do my study in Xiphos, where my bookmarks are
extensive, featureful, titled, commented.  Apparently, Terry simply
inhaled BT's format whole when he first implemented them for GnomeSword.

_In practice_ no one cares about that beneficial compatibility, even when
compatibility comes literally for free.

The practical use case for bookmark sync is undoubtedly desktop -vs-
handheld device, and not for different applications that run in the same
(physical) environment, that is, desktops.  And so where we would be
concerned with sync is between, say, Xiphos and PocketSword...whose
respective metaphors for bookmarks are virtually unrelated.  What will
"sync bookmarks from Xiphos to PocketSword" mean, when my titles, my
hierarchy, and my multi-verse references will simply vanish during the
operation?  Would I ever want to sync back the other way?  No, never,
because too much information would be lost.

Now please let me generalize and extrapolate: This in turn makes me wonder
about baseline capability, and what "should" be part of any Sword
application.  Certainly there are obvious qualifiers on which we would
agree about the bottommost bare minimums: Show selected Bible text,
generally on a per-chapter basis; provide for module installation; provide
search somehow; provide commentaries along with or alongside Bible text;
support UTF-8 to get correct display.  We could create a list of those
kinds of real bare minimums.  (We wouldn't /entirely/ agree on the list,
of course.  But we could probably come close.)

How far beyond these bare minimums should we expect any (all) apps to go?

I'm asking because, when I think about some of the capability that we've
brought to Xiphos in the last couple years, I realize that a lot of it has
no analogue or counterpart in any other Sword application.

Along comes Jane Random, who desperately wants Critical Feature XYZ in her
Bible study application.  She hears about The Sword Project, finds an
application, tries it out, and sees that XYZ isn't there.  And so she
concludes erroneously that The Sword Project isn't worth her time, and
worst of all, she tells her friends about her search for XYZ and how The
Sword Project didn't measure up.

And to think that we have PR problems on our best days...

As to those Critical Features:

Take user-created content, for example.  Aside from the original personal
commentary that many apps support, Xiphos provides multiple such
commentaries, and user-created genbooks (what we call "prayerlists and
journals"), and per-verse user annotations in a "yellow highlighter plus
margin notes" metaphor.  We do these things because users keep asking for
user-editable content.  Our support has gotten good enough that users now
write bug reports about really picky things, like the need to provide
links in their journal text that *either* navigate directly *or* put the
verse list machinery to use.  (This mostly means the distinction of
whether to use sword:// URLs or <scripRef>.)

Do other applications' user communities not ask for the same things?  I
notice that Crossway's new ESV iPhone app is already getting raves because
it provides a note-taking facility.  The iPhone is decidedly *not* well-
suited to composition beyond trivially short texts, yet note-taking is
already considered important there.  Why do other Sword apps not provide
more user content creation?

Consider also image support: Aside from simply displaying images, Xiphos
has provided image resizing since the first time I knew of an image-
containing module, realizing that a monster 3506x2055 map cannot be
expected to be viewed (by a sane person) in an application's subwindow
pane that's only 500x300.  And even so, Xiphos provides external image
viewing (click the image) so that the entire problem can be punted to
something more appropriate when the application itself is simply not
adequate to showing what needs to be showed: A map resized from 3506x2055
to fit within 500x300 will be close to useless, so we let the user hand
the image to an external viewer that can select and zoom.

In late 2007, I first mentioned on this list a need for other apps to gain
an ability to do image resizing.  There were enthusiastic followups at the
time to say that this really should be done.  But no other app has done so:

On the one hand, feature distinctions are useful for advertising one
application over another.  It's a marketing thing: We of the Xiphos team
can talk up our additional capabilities.  On the other hand, I worry that
a lack of consistent provision of some features will lead to a kind of
backlash.  We have enough trouble with PR; if people post in public
forums, "I used Application Foo from The Sword Project, and it doesn't do
XYZ, so I just don't think Sword apps are adequate," we get a bad
reflection on all of us.  The complaint's baselessness does not help us.

I know we're all volunteers, and we all have different emphases and
schedules and workflows and feature design goals.  I don't mean just to
pick on a couple of Xiphos' features specifically; there are surely things
done by other apps that Xiphos is yet missing.

Where does feature consistency matter?
What does bookmark consistency buy for us, other than as a talking point?
Where can we safely ignore whether our applications are consistent with
one another?
What are we to do about providing a sufficiently consistent baseline
user experience?
There's no way to force any application's development team to do new
stuff, so how can we encourage teams to provide more capability, as a
lower bound?

More information about the sword-devel mailing list