From CrossWire Bible Society
Robust definition of a persistent key list that could be used for:
- 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
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.
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.
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.
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 is much more complex than just bookmarking all the module views of the application. But bookmarking each view goes a long way toward that.
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.