[sword-devel] Tagging verses and verse lists

Eeli Kaikkonen eekaikko at mail.student.oulu.fi
Wed Dec 19 05:24:31 MST 2007

Thanks for comments, I have to say that you have probably thought this
more thoroughly than I have. Your point of view is valid throughout but
I still try to give a second opinion...

On Tue, 18 Dec 2007, Jonathan Morgan wrote:
> 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.

That is true. This is, however a tradeoff.

> 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.

Yes, it leads to more work when coding the frontends. But why the
Personal Commentary has failed? Was there ever any such standard? Did
the developers discuss about interoperability?

Here we come to an interesting point. Why there is no api for getting
OSIS div, passage, footnote, word etc? Because the api has to solve a
general problem and move the responsibility to the frontends. Actually
this is exactly the same situation than with the Personal Commentary: we
have (or should have) a standard which has to be obeyed in modules and

My point here is that there are different situations that call for
different solutions. The question is now if this situation (tags, verse
lists, bookmarks...) calls for a general or a specific solution, and how
general or how specific.

> 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.

But again, how general is this problem? If we talk about bookmarks there
would be api for bookmarks. But if you are right and bookmarks are not
the right solution for verse lists there should be api for verse lists.
And if your application uses the verse list in a specific way there are
two possibilities:

1) All applications must use the verse list with the same semantics, not
only with same syntax. If you use it for tagging there will be UI and
end user problems if others use the same list as bookmarks. 2) The api
has to have a way to differentiate between verse lists which are meant
to be used differently. I think this is the only good solution,
otherwise the lists can not be used e.g. for both saveable search result
lists and user defined tags.

And now we are again in the situation which you wanted to avoid: we
don't know what the list (module) contains. We have to have a standard
which says that this is a tag list, that is a search result or some app
specific list.

> > 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?

Why then OSIS allows for custom tags (or at least attributes)? Why the
Sword engine handles (allows) them? Whey there is no api which prevents
duplicated effort?  Because we have a too general problem to be solved
with a specific api.

Besides, when we talk about bookmarks or even Personal Commentary
standard we are talking about a very small subset of any markup. The
problem with html is that the standard has not been followed at all by
the html designers or app developers. We could do better.

> Again, IMHO "this system is more
> general" != "this system is a better solution to the problem".
> Frequently it is the other way round.

You are right about that, though I again say that it depends on the
situation. The solution should be as simple as possible as you also
said, but first we have to see if there really *IS* a more general
problem to solve. I have a bad habit of overengineering, I hope our
views complement each other and we can come to some solution here.

Therefore, I repeat this:
> > Anyways, I would like to see more co-operation between applications
> > whether it be in the engine or in the form of common standards.

	Eeli Kaikkonen (Mr.), Oulu, Finland
	e-mail: eekaikko at mailx.studentx.oulux.fix (with no x)

More information about the sword-devel mailing list