[sword-devel] Tagging verses and verse lists

[Jonathan Morgan]

On Dec 19, 2007 11:50 PM, Eeli Kaikkonen <eekaikko at mail.student.oulu.fi> wrote:
> On Wed, 19 Dec 2007, Jonathan Morgan wrote:
> > Just so that there is no confusion over what I see the semantics of a
> > hierarchical structure to be, here are my proposed semantics:
> > 1. Any topic may contain verses (references if you want to be more
> > generic) and sub-topics.
> > 2. The verses are ordered as the user (or application) enters them,
> > not in any canonical order (though allowing canonical ordering at a
> > later stage may be useful).
> > 3. Sub-topics are probably ordered alphabetically or as the user
> > orders them.  I'm not so sure with this one which is better.
> > 4. A verse is contained in a topic if it is directly contained in that
> > topic or if it is contained in one of the topic's sub-topics.
> > 5. Preferably, the user should be able to view a topic both
> > hierarchically (verses directly contained and sub-topics), or
> > completely (displaying all verses that are contained in a topic, but
> > no sub-topics).
> >
> > Unless anyone convinces me otherwise, these are the semantics I would
> > intend to adopt if I add hierarchical verse list / tagging / etc.
> > support to BPBible.  Comments are welcome.
>
> This looks useful and mature. Some thoughts:
> 3. Definitely "as the user orders them". It's not logical to allow
> user-defined order with references but deny it for "folders". And for
> maximum flexibility and user friendliness the end user should have
> possibility to give the order.

I agree.  The next question is, can we mix verses and topics?  There
are good examples of the two different approaches:
1. FireFox's bookmarks: In these, I can place a folder anywhere I
like, and intermingle it with bookmarks.
2. A standard file explorer, where folders appear up the top, and then
files appear below.

>From the selfish implementer's point of view, I prefer the second
because it's easier to implement.  From a UI design point of view, I'm
inclined to prefer the second because a sub-topic is likely to contain
more than one verse, so it should be at the top to make it faster to
access.

> After this we have of course to decide which data there can be: do we
> need e.g. comments on each topic/folder and each reference? Can one
> reference be one verse, one verse range or several verses/ranges? Etc.

Comments are probably fairly reasonable (I suggested "description" for
verse lists/topics and "comments" for passages, but they are both just
a text field).  It would be up to the UI how these were displayed, but
I would think tooltips would generally be a reasonable choice.

I recommend that a reference be one verse range.  I suggest this
because we already have a list of entries, so there doesn't seem a
compelling reason to allow entries to be lists, but there is very
frequently good cause to treat a range of verses as a single unit (for
example, if I wish to include Genesis 1: 1 - 3, then Genesis 1: 1 - 3
shows my intent, while three entries with Genesis 1:1, Genesis 1:2,
and Genesis 1:3 doesn't).  You could conceivably use the same argument
to include lists, but I don't think that it is very compelling.
(Also, from a UI point of view, most applications are likely to have
support for selection of a verse range, but not for selection of more
than one disjoint verse range [except by typing in the references
manually).

Jon