[sword-devel] Tagging verses and verse lists

[Jonathan Morgan]

On Dec 3, 2007 12:36 AM, Jonathan Morgan <jonmmorgan at gmail.com> wrote:
> 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.)

After discussion with Ben, I have developed a proposed interface for
this feature, given below.  God willing, I plan to implement the
feature in the next two weeks, as well as adding support for it at the
UI level to BPBible as a sample of how I think it should work.  Any
comments on the proposed interface are welcome.

Jon

PassageList API:
typedef PassageListMap std::map<std::string, sword::PassageList>;

/**
Returns the passage list map, which maps unique names to passage lists.
*/
PassageListMap SWMgr::getPassageLists();

/**
Creates a new passage list with the given name, and adds it to the
passage list map.
There must not already be a passage list with the given name.
*/
PassageList SWMgr::addPassageList(std::string name);

/**
Creates a new passage list with the given name, and initialises it with the
given list of passages.
*/
PassageList SWMgr::addPassageList(std::string name, ListKey passages);

/**
Removes the given passage list.
Returns true on success, and false on failure.
*/
bool SWMgr::removePassageList(PassageList);

/**
Removes the passage list with the given name.
Returns true on success, and false on failure.
*/
bool SWMgr::removePassageList(std::string name);

/**
A passage list must have a unique name to identify itself.
It may also have a description of the list, which can be used by the user.
*/
PassageList
===========
PassageList::get/setName()
PassageList::get/setDescription()

/**
Adds the given passage to the end of the passage list.
*/
PassageList::addPassage(PassageEntry passage);
PassageList::addPassage(VerseKey passage);
PassageList::moveUp(int index);
PassageList::moveDown(int index);

/**
Removes the given passage entry from the list.
*/
PassageList::removePassage(PassageEntry passage)
PassageList::removePassage(int index)

/**
Sorts the passage list.  At present, this will only support sorting it in
canonical order, but in the future, other sort orders may be supported.
*/
void PassageList::sort(PassageListSortOrder order)

/**
Gets a list key with all the passages in the passage list.
*/
ListKey PassageList::getListKey();

/**
Creates a new passage list with the same passages as this passage list, but
with the given new name.
*/
PassageList PassageList::clone(std::string newName)

/**
Returns true if the given verse is contained in the passage list.
*/
boolean PassageList::containsVerse(VerseKey verse)

/**
This class wraps around a VerseKey to allow additional attributes to be
attached to an entry in a passage list.  At present, the main addition that
is planned is attaching comments to passage entries.
*/
PassageEntry
============
/**
Creates a passage entry from the given verse.
*/
PassageEntry(VerseKey verse)

/**
VerseKey PassageEntry::get/setPassage()

/**
For later extension.
*/
std::string PassageEntry::get/setComment()