Difference between revisions of "Whiteboard/PersistentKeyList"

From CrossWire Bible Society
Jump to: navigation, search
m (Definitions:: italics and indent)
m (Refdoc moved page DevTools:PersistentKeyList to Whiteboard/PersistentKeyList without leaving a redirect)
(No difference)

Revision as of 09:33, 11 January 2018


Robust definition of a persistent key list that could be used for:

  • Bookmarks
  • Saving search results
  • Topic Tagging
  • Study notes, comments and other annotations
  • History navigation
  • Application state restoration
  • Search Restrictions

(The name "Persistent Key List" might not be a good choice.)


Please correct if you have a better definition.

Key: Unique string used to locate content in a file or data structure e.g. Topic, Reference, Date, Word or Strong's number

Reference: Key used to access verse content in a Bible module, usually in format: <book>\s<chapter>:<verse> e.g. "Gen 1:2"

Range (Ref.): Key used to access a contiguous set of verses usually of the format: <book>\s<chapter>:<verse>[\-[<book>\s]<chapter>:]<verse> e.g. "Gen 1:1-3" or "Gen 1:1-3:1"

Verse: Content retrieved from a Bible using a single Reference. e.g. "In the beginning..."

Passage: Content of a contiguous set of Bible verses using a Range as the Key. e.g. "In the beginning... ...God said it was good".

Bookmark: An N-tree hierarchical structure where nodes can be either a Topic or a Reference

VerseList: A list of References with a Topic as the Key

Use Cases:


The purpose of a bookmark is for a user to get back to a particular place in a book, or module in our case. The user can save and recall a particular view, potentially a parallel view, of modules. The recollection of a bookmark would produce exactly the same view.

Saving a bookmark involves remembering the module(s) being viewed, the options that are in effect and the keys that are being shown. It might also involve remembering a particular location in the key list so that proper scrolling can be restored.

Different applications may have different options.

Search Results

A search request is applied to a module, resulting in some number of hits. Some SWORD applications allow for parallel searching of multiple modules.

Saving a search result stores the module(s) being searched, the options in effect when performing the search, the version of the index, and the actual results. It might not be necessary to actually store the results as they can be re-computed, if the modules have not been deleted.

Topic Tagging

A topic consists of entries identified by key which pertain to the topic. A topic might be broken down into sub-topics. It is reasonable for a topic to contain references from multiple modules, such as Bibles and commentaries.

The main features needed here are:

  • Each key list can be named and the name is used as the topic.
  • The definition of a key list is recursive: It can contained named key lists.

Study Notes, Comments and Other Annotations

An entry, portion of an entry, a search request or a collection of entries can be provided a note/comment/annotation (different words for the same idea). There can be any number of these for an entry. They can also overlap.

The main features needed here are:

  • A key list allows duplicates.
  • Entries in a key list can be simple (e.g. a single key) or complex (e.g. a range of keys).
  • Each entry can be annotated.
  • Location within a key can be provided.

History Navigation

Essentially history navigation is a matter of going forward or back in a list of bookmarks. It might also allow the selection of a particular bookmark.

Application State

Application state is much more complex than just bookmarking all the module views of the application. But bookmarking each view goes a long way toward that.

Search Restrictions

Most (all?) SWORD applications allow search to be restricted to a particular set of keys. A key list should be able to be used for that.