[sword-devel] Tagging verses and verse lists

[DM Smith]

On Dec 17, 2007, at 1:32 PM, Troy A. Griffitts 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.

I agree!!!

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

I surely hope so. I am working in BibleDesktop/JSword on a general  
purpose Bookmark facility, but I will wait for the dust to settle on  
this question so that I can ensure file compatibility. Basically, I  
see a need for a KeyList, where each reference is fully qualified,  
OSIS style. That is, it encodes the module type, the module name and  
the reference. Perhaps the versification scheme.

The reason for each:
The module type, such as Bible, Commentary, Dictionary, .... would  
allow one to use a reference against a similar/compatible work.
The module name, such as KJV, NET, ..., would allow one to get the  
reference from the original source.
The reference, would allow a comma separate list of keys, such as  
Bible.KJV.Gen.1.2-Gen.2.3,Gen.4.5,Gen.4.7 (Actually, I don't have a  
problem with each range being separately specified either)

By allowing references from different works, it allows topical tagging  
to be richer. It could gather references from Bibles, Commentaries,  
theological Dictionaries, ....

The list should be ordered. Not merely in canonical/index order, but  
in an order that is meaningful to the user/application. Any  
application should try to honor the order, but doesn't have to.

Finally, the key list should be able to be named by the user. This  
could be the name of the topic.

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

I'd like to suggest that ~ really needs to be better defined for Vista  
and Mac, perhaps Linux as well.

This really needs to be in a proper location for each operating system.


>
>
> 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'd also like to suggest a BookmarkSet, which is a list of lists. This  
would be an alternative to allowing different works in a BookMark list.

>
>
> 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 think that the file definition should allow for extension. If an  
application does not recognize tagged data it would ignore it. My  
preference would be XML along with a schema that allows extension  
(such as TEI does). But a multimap would work as well.

For example, perhaps we would like the user to add a comment to the  
bookmark. Maybe each passage could be annotated. If the bookmark was  
the result of a search, it might be nice to include the search  
request....


>
>
> Just my initial thoughts.  Looking forward to the conversation.
>
> 	-Troy.
>
>
>
>
>>> 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()
>>>