[sword-devel] Tagging verses and verse lists

[Jonathan Morgan]

On Dec 18, 2007 5:32 AM, Troy A. Griffitts <scribe at crosswire.org> 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.  I would be particularly
> interested in whether you think a 'list' concept meets enough needs to
> warrant a mechanism.  BibleCS has basic verse lists, and also bookmark
> trees.  The bookmark trees seem more useful to me, but I would not have
> a straight forward path to modify BibleCS to use a 'PassageList'
> mechanism for trees.
>
> I have some other comments below.
>
>
> SWMgr is probably not the best place for this functionality.  SWMgr was
> our first 'manager' create 15+ years ago, and now that the engine has
> grown considerably, this should probably be renamed to something like
> SWModuleMgr, as its main purpose is to be a factory to hand back virtual
> base SWModule * objects.

Agreed.

> Are we planning to handle any type of key lists with this interface?
> e.g., both Verse and GenBook references?

We could do this in a later edition.  My problem with having this is
that I do not see as much use for it.  The main difference between the
two (as I see it) is that a GenBook key is module specific, while a
passage can be used with any Bible.  While it is possible that you may
want to link to relevant commentary, dictionary or genbook entries for
a particular topic, it doesn't strike me as quite so compelling.
Another potential difference between a passage and a GenBook entry is
that a passage will typically have a comparatively small body of text,
while an entry has a potentially unbounded body of text, which may
affect how the verse list is displayed (for example, think about the
typical search results dialog for verses - verses can be previewed
well, whole chapters present more difficulty, and a typical entry from
the ISBE would contain far too much text to display).

> We also try to keep the std namespace out of the public interfaces the
> best we can.  It makes bindings easier to implement, thus, where the
> interface methods accept std::string, they should accept const char * or
> SWBuf if they are intentionally non-const.

Fair enough.

> I would suggest something like:
>
> class KeyListMgr {
> public:
>         KeyListMgr(cont char *configPath);
> }
>
> modeled after the LocaleMgr.
>
> This would add a new subdirectory to our config root (along with
> mods.d/, modules/, locales.d/), something like keylists.d/, and I'm sure
> everyone would like to honor a ~/.sword/keylists.d/ as well.
>
> If we are planning to go all out and extend the list interface to a tree
> interface, maybe a more generic name like BookmarkMgr would be better
> suited.

I think that the ideas give fundamentally different ways of organising
information, in the same way as tags and folders are a different way
of organising information.  My proposal has always been about tagging
at the user level.  Passage lists are only a convenient vehicle for
implementing tagging.  The main difference in ideas is that trees
attempt to make users organise their information in a hierarchical
manner, while tagging does not.  I  have a few problems with the idea
of hierarchical passage lists.  You may say that they are more
general, but that added generality does not necessarily equate to more
usefulness.  I wish efficiency of tag creation and usage (something
that no verse list system I have ever used has given me, because they
are verse list centric rather than tag centric).  It is possibly more
intuitive to tag a thing with more than one tag than to try and fit it
into a neat hierarchy.  Tagging is certainly extremely popular,
especially in the web world, and I think it gains considerable
advantage from the fact that I don't have to organise my thoughts in a
hierarchical fashion.

> I realize this doesn't map directly to the purpose that Jonathan
> intended.  I don't know if there is an easy delineation to give us
> multiple uses.

I cannot think of a straightforward way to integrate too many
different ideas, which is why I try to propose a problem and find a
solution that solves that problem well.  In a nutshell, my solution is
intended to provide an efficient way of creating and managing a
potentially entire Bible network of topics and associations, and then
displaying these associations while browsing the Bible.  Most
conventional UIs will break down under this (especially hierarchically
based ones).  I would prefer to have a unified Sword standard, but it
may be easier for me to implement it first in BPBible/Python to show
exactly what my problem is and how I plan to solve it, then open it up
for discussion again.

Jon