[sword-devel] Tagging verses and verse lists

[Peter von Kaehne]

The thread I pull up here has some relevance

1) it was never concluded in theory and certainly no conclusions ever
put into practice
2) With more and more applications becoming crossplatform there will be
a growing and quite reasonable expectation by users to switch
applications and be able to make use of their old bookmarks in some form.
3) looking at the wiki page on comparison, it is clear that there is a
semblance of practical consensus between the various implementations of
the feature

a) bookmarks should be hierarchical,
b) should be user editable/arrangable,
c) should allow for some comment
d) should allow both bulk addition via searches and by-hand addition
e) should be exportable/sharable

Eeli suggested in this thread that an editable GenBook with some special
features is the overarching  best representation. I agree with this and
suggested the same on gnomesword-devel, where Eeli referred me back to
this old thread.

So, is it time to resume the debate and bring it to a conclusion?

Peter



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.  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.
> 
> Are we planning to handle any type of key lists with this interface? 
> e.g., both Verse and GenBook references?
> 
> 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.
> 
> 
> 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 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.
> 
> 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()
>>>
>>> _______________________________________________
>>> sword-devel mailing list: sword-devel at crosswire.org
>>> http://www.crosswire.org/mailman/listinfo/sword-devel
>>> Instructions to unsubscribe/change your settings at above page
>>
>>
>> _______________________________________________
>> sword-devel mailing list: sword-devel at crosswire.org
>> http://www.crosswire.org/mailman/listinfo/sword-devel
>> Instructions to unsubscribe/change your settings at above page
> 
> 
> _______________________________________________
> sword-devel mailing list: sword-devel at crosswire.org
> http://www.crosswire.org/mailman/listinfo/sword-devel
> Instructions to unsubscribe/change your settings at above page