[sword-devel] Topics, Tagging, and passage lists in BPBible

[Jonathan Morgan]

Dear all,

Last year I made a proposal for supporting what I chose to call
"tagging", the idea of creating hierarchical, topic based passage
lists.  In other Bible applications, similar features can also go by
names like bookmarking and verse lists.  This started a lengthy
conversation about I was optimistic and thought it would be done by
the start of this year, because I had spare time over Christmas.  My
ideas about it have changed significantly in many ways while
implementing it, but that is probably to be expected.  Six months
later, the feature is still not really ready for release, but I have
made a preview release based on BPBible 0.3.1 (which I released a few
days ago), and I have merged the changes into BPBible trunk, so they
will need to be somewhat complete before 0.4 (I hope I find time to do
it...).  You can find the release at
http://jonmmorgan.googlepages.com/bpbible (Windows binaries and
source, same as ordinary BPBible releases, only tested on Windows XP).
 Since this is a preview release, it has quite a few rough edges and
areas that need improvement, but the most radical changes are there
and fairly complete.  I am very interested in comments on the
implementation (though of course my time to respond to them, like many
on this list, is limited).  Even in its current state I think it has a
few significant features that no other passage list style tool has.

The main advantages I see in my implementation are:
1. It is very fast to add a verse or passage to a passage list.  From
in the Bible window, you just need to select the passage you want to
add, press 't' (for tag), select the topic you wish to tag the passage
with from a filterable text box, and press OK.  The last used topic is
automatically selected, so it is even faster if you are building up a
pasage list on a particular topic.
2. Topics and passages can have comments associated with them.
3. Passages are supported rather than verses, meaning a range of
verses can be worked with.
4. Each verse can display "tags" for all of the topics that it is
included in, making the topics a visible part of your Bible reading.
>From these, you can view the complete passage list in anchorable
tooltips.

I have included below my original proposal for information.  I have
changed my views on some of the things in there.  Others have just not
been implemented.  However, I think already my implementation handles
efficient tagging of verses in the second style below better than any
other implementation I have seen.

I'm no longer convinced that tags are the best way of visualising
this, and will be investigating alternative representation methods
after bringing this implementation to a somewhat reasonable state of
completeness.

Before I get too many comments about features considered incomplete,
here is information about known problems and future plans:
1. The "Manage Topics" frame was started fairly early in the project
and never looked at since.  This means it is fairly broken (and
doesn't allow common operations like deletion and moving things
around: I said it was a preview release).  I intend to replace this
with a FF 3 Bookmarks style, explorer style tree on left and passages
on right view, so I haven't bothered looking at that any more.

2. The dialog brought up when you click on a tag was experimental, and
I have since abandoned the experiment.  I think it will probably open
a "Manage Topics" window with that topic currently selected once I
implement the new manage topics view.

3. It is not possible to selectively display tags, which could be a
problem if you have a lot of topics.

Future plans:
1. Allow colour of tags to be configured.
2. Allow creation of a passage list from search results.
3. Make certain topics not be displayed as tags.
4. Import and export.
5. (Possibly) Module specific bookmarks (I'm still not convinced of
them, but a lot of sword-devel people liked them, and they could be
useful in some cases.  I haven't even considered where alternate
versification fits into this, but internally the application is just
using VerseKeys).
6. Better methods of topic visualisation.

In short, this is just a preview release.  The two parts of the
interface that I am most interested in comment on are the dialog for
tagging a passage and the inclusion of tags in the text, since I think
they are the most novel, but I am happy for any comments.

Jon

============================================
Original proposal sent to sword-devel:

I have a suggestion for a feature that I would consider very useful in
Bible software.  This idea I originally characterised in terms of
"tagging", but my brother said it sounded very much like verse lists.
My personal view is that verse lists may be useful in implementing
something like tagging, but the two are semantically different (for
example, a verse list tends to imply an order, while tagging doesn't.
Similarly, tagging would tend to be considered to apply to a verse
that was tagged, while a verse list is just a list of verses.)

I'll describe a couple of uses for this feature:
1. When studying a particular topic, verses that relate to the topic
can be tagged with that topic, and then the knowledge that the verse
is related to the topic is saved as part of the software.
2. When reading a particular passage, verses may be noticed that apply
to different topics that the reader is interested in, and each one
tagged with its own topic.

There are quite a few pieces of Bible software that appear to have
verse lists or a similar feature.  However, none that I have tried
would appear to support both these cases well.  They appear to be
oriented to working with a verse list, and typically they will be
oriented to the current verse list.  If I want to perform use (2),
this means that I have to (often tediously) change the current verse
list, so that I can then add the verse to the verse list.

So, based on this, my proposal is as follows:
1. Support for persistent, named verse lists is added to Sword [note
that I use verse lists as the generic name for the concept, but I
think the list should include passages].  I think it is important that
this support is added to Sword, so that I can use my verse lists with
any application.  I believe Sword already supports ListKeys and
similar for things like search, but they are never stored anywhere.
2. Search is extended to include tags/verse lists (e.g. only search
verses with tag, exclude verses with this tag, etc.)
3. It is possible to add and remove passages from a verse list, as
well as creating and deleting verse lists.
4. It is possible to export verse lists as a list of references, or as
the complete set of passages from a particular version (this may be a
front end issue).  Being able to import existing verse lists would be
nice too.  It might also be useful to compare and merge verse lists in
various ways.
5. Verse lists are able to be created from other verse lists (for
example, from a list of search results).
6. Front ends include support for verse lists and tagging.  Possible
features include:
   a. Offering an option to create verse lists or new tags
   b. Tagging the selected verse or passage with a particular tag.
   c. Managing a verse list.
   d. Display all the passages in a verse list.  I would suggest that
this is done however the front end typically displays search results,
for consistency.
7. Adding tag information to the displayed verses as an option.
Possible methods of display are:
   a. The user elects to highlight or mark in some way verses with
particular tags (like many do with physical Bibles).
   b. Tags are displayed embedded in the text after the verse,
similar to how tags are frequently used in other contexts.

I think that 7b would be particularly useful for this feature, since
it gives the user a visual indication of all the information that they
have put into this system when they are using the application.