Projects:Go Bible/SymScroll
Contents
Symmetric Scrolling Branch
- New page under development.
Raison d'être
The motivation for developing the SymScroll branch of Go Bible was to provide support for touch screen only phones that have Java ME. For touch screen phones with a hardware menu button, using SymScroll you can safely get rid of the on-screen virtual keypad and retain full Go Bible functionality, thus taking advantage of the full area of the screen for the application display.
As a sensible prelude for this task, the source code has been refactored. The SymScroll branch of GoBibleCore has been subdivided into many more Java classes than the previous release.
Features
Enhanced/changed features
- Symmetrical scrolling
- Smooth scrolling
- Touch screen full support
New features
- Text added by translators can be displayed (e.g. in italics)
- Line breaks
- Psalm titles & other headings
- Personal names & name of deity
- OT quotations
- Other numeral systems (e.g. Arabic, Devanagari, Thai)
- Search next & search more
- Key settings (e.g. for phones with QWERTY keyboard)
- Font attributes (if available in the phone firmware)
Notes:
- Search results are limited to 50 verses. 'Search Next' finds the next 50 verses containing the search text.
- One of the keys can be assigned to 'Search Next' in a different sense. It goes to the next search result.
- If no search has yet been done, the same key initates a new search.
Improvements
Several software improvements were implemented in the SymScroll branch.
- The painting code has been reworked. It is much faster than the previous code.
Technical details:
- The original code measured the length of each line character by character, giving speed n (n = number of characters in a verse).
- Because of look ahead and caching, at first the SymScroll branch repeated the above process about 4x, on top of other overheads, slowing it down by about the same factor.
- Now, the code defers measuring any length until an entire word is read, speeding the code up by a factor equal to the average word length.
- For Chinese script, where there is no concept of words and spaces, the code is does a binary search (i.e. log_2(n) ) to find the best breaking point.
Remarks within ui.properties:
- The ui.properties file allows remarks to be included. Any line that begins with the hash symbol # is treated as a remark.
Bug fixes
Some existing software bugs are being fixed. Details will be included in the release notes.
Implementation details
Symmetrical scrolling
Pressing 'up' now goes up by one screen, and pressing 'down' still goes down by one screen. This should be much more intuitive than the previous method. [1]
The previous method had its merits, namely speed, which this branch assumes is less relevant in the era of phones that can emulate Nintendo Gameboys.
- ↑ In which 'up' went up to the start of the previous verse.
Smooth scrolling
Touch screen scrolling needed to be smooth. Smooth scrolling is abandonned when a proper 'up' or 'down' key is pressed, after which the application reverts to the original discrete scrolling method.
Touch screen support
The Biblical text display now includes simple book and chapter headings, such that during continued scrolling, there is a better visual feedback for navigating. Horizontal touch screen scrolling navigates to next/previous chapter. The Go Bible Menu is accessed by touching anywhere in the top bar.
Key settings
This new feature facilitates remapping keys to the Go Bible navigation functions, thus making it possible for the user of a phone with a QUERTY keyboard (for example) to assign keys more conveniently. This feature requires several new UI properties.
The new Search Next feature is by default assigned to the previously unused "0" key.
Font attributes
GoBibleCore can now display text with font attributes such as italics or oblique or small caps, providing these attributes are supported by the phone firmware, and providing such attributes make sense for the language's alphabet.
In addition, the user can select alternative rendering methods such as underline, suitable for fonts that don't include italics.
Other numeral systems
The new UI property called UI-Digits facilitates using a different numeral system for chapter and verse numbers. The method is to specify a ten character string corresponding to the digits 0 through 9. Examples:
Default (if omitted):
UI-Digits: 0123456789
Eastern Arabic numerals:
UI-Digits: ٠١٢٣٤٥٦٧٨٩
Farsi numerals:
UI-Digits: ۰۱۲۳۴۵۶۷۸۹
Devanagari numerals:
UI-Digits: ०१२३४५६७८९
Thai numerals:
UI-Digits: ๐๑๒๓๔๕๖๗๘๙
Khmer numerals:
UI-Digits: ០១២៣៤៥៦៧៨៩
Notes:
- Limitations: Currently, there is no error message. Go Bible does not check for uniqueness of characters.
- If there are less than 10 characters, it will revert to default. If there are more than 10 characters, the extra characters will be ignored (since no digits are larger than 9).
- The transformation is done at the individual digit level for decimal notation.
- The transformation applies only to chapter and verse numbers as used by the application, not to any numbers as might be found within the text of some Bible translations.
- In numeral systems with further special symbols for 20, 30, 50, etc; these are not catered for.
- For right to left languages, how different phones handle the bidirectional algorithm when the numeral system is not the default is outside the control of Go Bible software.
- Some languages do not have a symbol for numerical zero. See [2] which tabulates Numerals in Unicode.
- Some phones may display South East Asian numerals with a peculiar font size, relative to the normal text. This is not a Go Bible software issue.
- No semantic check is performed by Go Bible Creator. i.e. The following would be accepted, even though it makes no sense.
UI-Digits: 9876543210
Red Letters for Words of Jesus
This is in additional option under Preferences. It allows the user to switch Red Letters On or Off for any Go Bible applications made from source text that included the required markup.
Custom Verse Numbering
- New feature still under development.
The latest code snapshot (2011-06-29) supports custom verse numbering (including out-of-order verses).
This was achieved by creating an additional file under Bible Data/ to store mapping data (mapping one verse number to another).
- Details to be added later.
Go Bible Creator
The SymScroll branch of Go Bible Creator supports several new features.
- Some new command line options have been added.
- The command line option for update has been extended.
- Some new UI properties have been defined.
- Some further properties are available for use in collections text files.
Command line options
Options are now available by which one can choose a baseline Manifest file template, a baseline ui.properties template, and even the GoBibleCore binaries. This should make GoBibleCreator a bit easier to use with different versions of GoBibleCore.
Usage: (java -jar GoBibleCreator) [ options ] CollectionsFilePath Options: -b (path) - Path to GoBibleCore binaries (.jar) -m (path) - Path to Manifest file template -p (path) - Path to ui.properties template -dh - Show some debug output -u - Update only -d - Set base source text directory
Note: The update only option has been extended to permit the main argument to be an existing GoBibleJARfilePath. This enables any Go Bible application to be upgraded to use the latest binaries, without requiring access to the source text file or a collections text file. Example:
java -jar GoBibleCreator.jar -u <old_gobible>.jar
This will convert an old Go Bible application to the SymScroll edition. Localized UI translations would lack the additional UI items, so these would default to the English UI properties. Yet that would be a spur to urge the user to supply the translations for these, so it becomes a "win-win" situation.
New UI properties
Here is a list of the new and re-used user interface (UI) properties:
UI-Key-Settings: Key Settings UI-Assign-Key: Assign Key UI-Unassign-Key: Unassign Key UI-Action-Next-Book: Next Book UI-Action-Next-Chapter: Next Chapter UI-Action-Next-Screen: Next Screen UI-Action-Next-Verse: Next Verse UI-Action-Next-3-Lines: Next 3 Lines UI-Action-Next-1-Line: Next Line UI-Action-Previous-Book: Previous Book UI-Action-Previous-Chapter: Previous Chapter UI-Action-Previous-Screen: Previous Screen UI-Action-Previous-Verse: Previous Verse UI-Action-Previous-3-Lines: Previous 3 Lines UI-Action-Previous-1-Line: Previous Line UI-Book: Book UI-Chapter: Chapter UI-Verse: Verse UI-Chapter-Reference-%1: Chapter %1 UI-Search-More: Search More UI-Search-Next: Search Next UI-Set-Range: Set Range ... UI-From-Book: From Book UI-To-Book: To Book UI-Delete-All-Bookmarks-Alert: Delete all bookmarks? UI-Delete-All: Delete All UI-Delete-History-Entry: Delete history UI-Delete-All-History-Entries: Delete all history UI-Delete-History-Entry-Alert: Delete this history? UI-Delete-All-History-Entries-Alert: Delete all history? UI-Digits: 0123456789 UI-Red-Letter: Red Letters for words of Jesus
Notes:
- This list may still be incomplete – (e.g. UI properties for selecting font attributes).
- Parameter %1 in UI-Chapter-Reference-%1 is a placeholder for the numerical value. This facilitates having a different position for the number in the displayed chapter headings.
- In version 2.4.x, displaying "Delete All" under Bookmarks was a kludge using "UI-Delete" and "UI-All".
- "From Book" and "To Book" are back in use. When the "Set Range" option is chosen for Search, these labels appear at the head of the lists of available booknames.
- "Search-More" relates to displaying the next set of search results.
- "Search-Next" relates to jumping to the next search result in the text.
Commented ui.properties
Here is the ui.properties file for the SymScroll branch complete with remark lines.
# BibleCanvas Menu Items UI-Goto: Go to UI-Search: Search UI-Search-Next: Search Next UI-Search-Results: Search Results UI-Set-Range: Choose Range... UI-Add-Bookmark: Add Bookmark UI-Bookmarks: Bookmarks UI-History: History UI-Send-MMS: Send MMS UI-Send-SMS: Send SMS UI-Preferences: Preferences UI-Key-Settings: Key Settings UI-About: About UI-Exit: Exit UI-Cancel: Cancel # BibleCanvas Display Elements ## UI-Of... Matthew 1:4 [of] 25 UI-Of: of # Numerals for chapter & verse numbers (example below is Devanagari) ## UI-Digits: ०१२३४५६७८९ UI-Digits: 0123456789 ## UI-Chapter-Reference-%1: Used at the start of chapters. ## e.g. The Gospel according to Matthew // [Chapter 1] UI-Chapter-Reference-%1: Chapter %1 # Key Settings Keys UI-Assign-Key: Assign Key UI-Unassign-Key: Unassign Key UI-Unassigned-Label: (unassigned) UI-Action-Next-1-Line: Next Line UI-Action-Next-3-Lines: Next 3 Lines UI-Action-Next-Book: Next Book UI-Action-Next-Chapter: Next Chapter UI-Action-Next-Screen: Next Screen UI-Action-Next-Verse: Next Verse UI-Action-Previous-1-Line: Previous Line UI-Action-Previous-3-Lines: Previous 3 Lines UI-Action-Previous-Book: Previous Book UI-Action-Previous-Chapter: Previous Chapter UI-Action-Previous-Screen: Previous Screen UI-Action-Previous-Verse: Previous Verse # Search Actions UI-Stop: Stop ## UI-Found: [Searching]: // [Found] nn // [Please Wait...] UI-Searching: Searching UI-Results: Results UI-Found: Found UI-Please-Wait: Please wait # Theme Settings ## UI-Themes: Title of form UI-Themes: Themes ## UI-Theme-*: Names of themes UI-Theme-Blue: Blue UI-Theme-Computer: Computer UI-Theme-Floral: Floral UI-Theme-Natural: Natural UI-Theme-Paper: Paper UI-Theme-Sunshine: Sunshine # Other Settings UI-Change: Change UI-Font-Size: Font size UI-Font-Style: Font style UI-Full-Screen: Full screen UI-Red-Letter: Red Letters for words of Jesus UI-Reverse-Characters: Reverse Characters UI-Reverse-Colours: Reverse Colours UI-Save: Save UI-Select: Select UI-Theme: Theme # Font Size Settings UI-Small: Small UI-Medium: Medium UI-Large: Large # Font Style Settings UI-Bold: Bold UI-Plain: Plain # Full screen settings / Reverse colors settings UI-On: On UI-Off: Off # Search Options UI-Search-Text: Search Text UI-Books: Books UI-All: All UI-Define-Range: Set Range... UI-New-Testament: New Testament UI-Old-Testament: Old Testament UI-Gospels: Gospels UI-Pauls-Letters: Paul's Letters UI-Other-Letters: Other Letters UI-Books-Of-Moses: Books of Moses UI-Historical: Historical UI-Poetic: Poetic UI-Major-Prophets: Major Prophets UI-Minor-Prophets: Minor Prophets # New option available in Search Results ## This finds the next set of [50] results ## The number of displayed results is determined by the ## optional collections file property Go-Bible-Max-Results UI-Search-More: Search More # Send SMS UI-Send-Verses: Send Verses UI-Select-Verses-To-Send: Select verses to send UI-Send: Send ## UI-To: Send from (book, chapter, verse) [to] (verse number) UI-To: to UI-Message-Too-Large-To-Be-Sent: Message too large to be sent UI-Verse-Does-Not-Exist: Verse does not exist UI-Phone-Number: Phone Number ## ?? UI-Back: Back # Goto form: UI-Book: Book UI-Verse: Verse UI-Chapter: Chapter # Bookmarks UI-View: View UI-Delete: Delete UI-Delete-Bookmark: Delete Bookmark UI-Delete-Bookmark-Alert: Delete the selected bookmark? UI-Delete-All-Bookmarks-Alert: Delete all bookmarks? UI-Delete-All: Delete All # History UI-Delete-History-Entry: Delete history UI-Delete-All-History-Entries: Delete all history UI-Delete-History-Entry-Alert: Delete this history? UI-Delete-All-History-Entries-Alert: Delete all history? # Other UI-Error: Error # Obsolete ## Search settings, first and last book to search UI-From-Book: From Book UI-To-Book: To Book ## Displayed when chapter/ book is loaded as it takes some time to load UI-Loading: Loading ## ?? UI-OK: OK
Note:
- This example may not be completely up to date.
Collections text file properties
Here is a list of the new collections text file properties:
MIDlet-Description: A brief description of the Go Bible application Go-Bible-Max-Results: 50
Notes:
- MIDlet-Description: is a required property for JAD files. Previous versions of Go Bible omitted this. Use this for a brief description. Use the existing Info: property to provide a verbose description.
- The value specified for Go-Bible-Max-Results: relates to how many search results are displayed at once. The default is now 50. Using a lower number may improve how Go Bible works on some older phone models. cf. Prior to SymScroll, maximum search results was fixed at 200.
- Corrections to how some existing properties appear in the JAD file are also being tackled. See issue 133 for further details.
Custom manifest file template properties
Go Bible Creator supports using different manifest files. Here is an example of the default manifest template for LTR scripts.
Manifest-Version: 1.0 Go-Bible-Align: Left Go-Bible-Render-Faux-Italic: yes Go-Bible-Render-Faux-Underlined: yes Go-Bible-Render-Faux-Bold: yes Go-Bible-Line-Height: 1.05 Nokia-MIDlet-On-Screen-Keypad: no
Go-Bible-Render-Faux-Italic:
If you have the Go-Bible-Render-Faux-Italic option set in the manifest, all italics will be rendered in grey[1] with dotted underline.[2] Otherwise, the program will use the default Italic font.[3]
- ↑ The current code uses 67% normal text colour, 33% background colour. This should be sufficient for all the preset themes. For words of Jesus, the predefined 'red' colour overrides the grey.
- ↑ Dotted underlines are a drop-in replacement for italics. This follows the convention used in various Chinese Bibles for the words tagged (in USFM) as translators' additions.
- ↑ This method can therefore be used to build a separate Go Bible application for phones that do not support italics, yet without requiring a different collections text file.
Support for XHTML_TE
The SymScroll branch of Go Bible Creator incorporates the extension to specify XHTML_TE as the source text format. The code is as provided by one of the programmers at SIL in Dallas. It was designed to support their FieldWorks Translation Editor, and is used internally by their Pathway publication tool.
Other improvements
Refactoring:
The source code has undergone major reorganization. The following are the new/changed Java classes:
- USFMConverter: Supersedes USFM_Utilities. Contains all the USFM-related methods.
- XMLConverter: Contains all the XML-related helper methods.
- GoBibleCreator: USFM- and XML- specific code have been removed and placed in their respective Converter classes.
Go Bible data format
Go Bible data format already assigned the control character code \x01 to mark both the start and finish as the means to implement the display of red letters for Words of Jesus. As Go Bible made no standard use of control characters, it had been envisaged that any UTF-8 character up to \x1F might be used for further enhancements to the Go Bible data format.
This method has been extended as follows:
\x01 – Delimit red letters \x02 – Delimit translators' additions (e.g. as for words shown as italics in the KJV) \x03 – Delimit the name of deity \x04 – Delimit quotations (e.g. OT quotations shown as oblique in the NKJV) \x05 – Delimit a proper name \x06 – Suppress printing the verse number, if it has not been printed, and change to boldface for titles \x07 – Break a line, print the verse number, and resume normal data (see below) \x0A – Line break (see below) \x0E – Increment the verse number offset (see below) \x0F – Decrement the verse number offset (see below)
Titles
To accommodate titles and descriptive headings without making major design changes to the data format, the following solution has been adopted. Example for canonical Psalm titles.
<VERSE INDEX 0><\x06>For the director of music. Of David.<\x07> In the <\x03>LORD<\x03> I take refuge. How then can you say to me: ... <VERSE INDEX 1>For look,...
To facilitate this new feature, it is apparent that the data format has been extended to permit references to verse 0 in order to accommodate canonical Psalm titles. Even so, the codes <\x06> and <\x07> can be used within other verses, such as to display the Hebrew letter stanza titles for acrostic poems such as Psalm 119.
Line breaks
Discretional line breaks are now permitted within Go Bible data format, coded as EOL marker in Unix \n (i.e. \x0A or LF ).
Notes:
- SymScroll does not support paragraphs or poetry markup. Every verse still begins on a separate line, with the verse number at the start of the line.
- Therefore translations with verse range tags will still require a workaround during preprocessing.
Verse number offset
The displayed verse number = verse index + offset. Internally, when navigating to passages, or when sending SMS, only the verse index is used.
Note:
- This is a solution in place of what was a workaround, where empty verse tags had to be inserted in the USFM files for missing verses.
Go Bible Creator support
- Table showing which markup feature is supported for each source text format. Please update this table.
Markup Feature | Code | USFM | USFM tags[1] | ThML | OSIS | XHTML_TE |
---|---|---|---|---|---|---|
Delimit red letters | \x01 | yes | \wj_...\wj* | yes[2] | no | yes |
Delimit translators' additions | \x02 | yes | \add_...\add* | no | no | yes |
Delimit the name of deity | \x03 | yes | \nd_...\nd* | no | no | yes |
Delimit quotations | \x04 | yes | \qt_...\qt* | no | no | yes |
Delimit a proper name | \x05 | yes | \pn_...\pn* | no | no | yes |
Suppress printing the verse number, etc | \x06 | yes | \s#_text...[3] | no | no | no |
Line break, print verse number, resume | \x07 | yes | \s#_text...[4] | no | no | no |
Line break | \x0A | yes | \p(_text...) | no | no | no |
Increment the verse number offset | \x0E | yes | \v_#[5] | no | no | no |
Decrement the verse number offset | \x0F | yes | \v_#[6] | no | no | no |
- ↑ See the User Reference available at [1]
- ↑ Implements <span class="red">...</span>
- ↑ Applied before the title.
- ↑ Applied after the title.
- ↑ The code must appear at the start of the verse. The code has to be repeated for every verse for which the numbering is not correct.
- ↑ See above.
Backwards compatibility
The SymScroll branch of GoBibleCore is backwards compatible with existing Go Bible applications. This means that earlier applications can be changed to SymScroll merely by replacing the file gobiblecore2.jar and using the Update option of Go Bible Creator to rebuild the application. For Go Bible applications that already have a UI translation, then ideally the new UI properties should be translated prior to the rebuild.
Development Status
The SymScroll branch is still being actively developed. Most of the features are already implemented. The branch is at the testing and debug stage. No milestoned release has yet been announced.
Latest binaries
The latest binaries were uploaded onto Daniel's Symmetric Scrolling GoBible Pages at the University of Cambridge Student-Run Computing Facility (SRCF) server. He has also provided an online tool for users to upgrade their existing binaries.
- This service disappeared when Daniel's account was closed after he graduated. So far we have not replaced it with an equivalent on another server.
See also
- How to change the User Interface (UI) for an existing Go Bible application.