[sword-devel] Tagging verses and verse lists

[Jonathan Morgan]

On Dec 18, 2007 6:27 AM, Eeli Kaikkonen <eekaikko at mail.student.oulu.fi> wrote:
> On Mon, 17 Dec 2007, Troy A. Griffitts wrote:
>
> > Martin Gruner wrote:
> > > Will this be a part of Sword?
> > >
> > > Troy, what do you say?
> >
> > Since most of our frontends have some type of verse list functionality,
> > I would like for us to have something common in the engine we can all
> > use.  This will also benefit our users, allowing them to share these
> > between applications.  We would all have to agree on an interface
> > though, so I'd appreciate hearing from other frontend developers on the
> > proposed functionality and interface.
>
> So I'll give my 10 eurocents.
>
> I would like to see some standard for bookmarks. It would be great if we
> could share them between platforms/applications. But I think, like Troy,
> that passage list is a bit restricted for bookmarks. BibleTime uses a
> tree for bookmarks though it's quite limited in other aspects.

We have now thrown another concept into the works, "bookmarks".
Possibly they are implemented in the same way, but, coming along as
the user, I see a "bookmark" as a mark for something that I want to go
back to, and so a relatively temporary thing.  I would agree with DM
earlier that such a thing should save the state of the application,
including the module that I am to be looking at.  On the other hand, I
would view "verse lists" as a more permanent thing which I build up
over time, and which is module independent.

See my comments in the previous email as to why I'm not convinced that
a tree is a good addition.

> I don't know enough about the Sword engine or other frontends to give
> any accurate suggestions but instead of a new task-specific Manager and
> API calls I would like to see a more general framework for
> interapplication data exchange.

There are a few good reasons (at least in theory) for being more specific:
1. Restricting work to being done once (in the engine).  If I have a
"general framework" then it is far more likely that every application
will do the same things in slightly different ways.  If I have an API
at the level of intent for a feature then it will work in exactly the
same way across applications, and applications will only need to use
that API.
2. We don't waste time solving problems that we don't need to solve (YAGNI).

> We already have a treelike structure (which can be flat as well) in form
> of genbook module. It can contain headers, text and links, just like
> bookmarks do. If OSIS genbooks could be writable - I don't know if they
> are - we could just write a standard which could be a small subset of
> OSIS plus some custom tags. Then the engine would be free from extra
> Managers and API calls, the applications just had to follow the standard
> when interpreting the xml data. This of course requires some mechanism
> to differentiate between real modules and application data modules. That
> would be the responsibility of the engine and API.

The problem with such a standard is:
1. Each application has to "follow the standard" - things like the
Personal Commentary shows that this is far from reality.  This again
leads to more work and more incompatibility, as per my previous
comment.
2. There is no way to tell that a particular module (let us say "x")
actually contains our bookmarks.  We could make another "standard" for
dealing with this, but again it means that every application has to
follow that standard.  It is much easier to provide an API at the
level of intent and solve the problem once.

> The standard could be flexible enough to enable specialized uses and
> application specific tags. HTML already works like that - if a tag is
> not recognized it's ignored. That way the applications could add their
> own data to the data which the other apps could still use.

HTML is a good example of why this is not a good approach.  Most HTML
parsers are flaky and incompatible - why, when we have a comparatively
simple feature to add, do we need to add application incompatibility
(sorry, "flexibility") and duplicated effort?

> This approach would have the benefit of integration to the existing
> frameworks, for example search and cross-module linking. With this kind
> of system someone could write a barebone systematic theology as
> bookmarks and if a frontend could link Bible references in all modules
> to Bible module verses the frontend would not have to implement any
> special code to link bookmarks, too.

Possibly, but I don't think this either really convincing or
practicable.  Once you throw in application specific data the engine
has just about no guarantee that its search will actually work as
expected and not produce something wierd due to something an
application added three years after the search was written.

> This would also give the application programmers the freedom to save any
> kind of private data with the existing framework. The engine just should
> have a way to read and write files given as arguments. Platform and
> application independent files could have special names or special API
> calls.

There are already APIs in most systems for reading and writing either
plain-text or XML files.  I don't think in most cases there are any
compelling reasons to allow application specific configuration to live
in engine data, when it could just be stored in an external
application specific format that was designed appropriately for the
problem that was being solved.  Again, IMHO "this system is more
general" != "this system is a better solution to the problem".
Frequently it is the other way round.

> BTW, I have also thought about a highlighting feature for Bible modules.
> That could also be implemented with existing editable commentary module
> and a new data standard instead of per-application custom file type or
> API.
>
> Anyways, I would like to see more co-operation between applications
> whether it be in the engine or in the form of common standards.

This proposal may help with application specific data, but I don't see
that it helps particularly with verse lists.  It is far better to
choose a feature and implement well than to try and solve all the
world's problems and incidentally produce a complicated, roundabout
implementation of the feature you actually wanted.  I probably
exaggerate, but I believe that the solution to a problem should be as
simple as possible (and no simpler).

Jon