Difference between revisions of "Projects:Go Bible/SymScroll"

From CrossWire Bible Society
Jump to: navigation, search
(→‎Go Bible data format: removed "Discretionary (optional)")
(→‎Go Bible Creator support: '''Line break''' and \p)
Line 255: Line 255:
  
 
|-valign="top"
 
|-valign="top"
−
| '''Discretionary line break'''
+
| '''Line break'''
 
<!--Code    !!  USFM    !!  tags        !! ThML      !! OSIS    !! XHTML-TE -->
 
<!--Code    !!  USFM    !!  tags        !! ThML      !! OSIS    !! XHTML-TE -->
−
! \x0A      !! {{yes}}  !!  //         !!          !!          !!         
+
! \x0A      !! {{yes}}  !!  \p         !!          !!          !!         
  
 
|}
 
|}

Revision as of 06:57, 16 April 2011

Symmetric Scrolling Branch

New page under construction.

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
  • Key settings (e.g. for phones with QWERTY keyboard)
  • Font attributes (if available in the phone firmware)

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.

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.

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

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: ๐๑๒๓๔๕๖๗๘๙

Notes:

  1. Limitations: Currently, there is no error message. Go Bible does not check for uniqueness of characters.
  2. 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).
  3. The transformation is done at the individual digit level for decimal notation.
  4. 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.
  5. In numeral systems with further special symbols for 20, 30, 50, etc; these are not catered for.
  6. 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.
  7. Some languages do not have a symbol for numerical zero. See [1] which tabulates Numerals in Unicode.
  8. 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

Go Bible Creator

The SymScroll branch of Go Bible Creator supports the new features. Several new UI properties have been defined. Some further properties are available for use in collections text files.

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-Unassigned: (unassigned)

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-Next: Search Next

UI-Delete-All: Delete All

Notes:

  1. This list may still be incomplete – (e.g. UI properties for selecting font attributes).
  2. 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.
  3. In version 2.4.x, displaying "Delete All" under Bookmarks was a kludge using "UI-Delete" and "UI-All".

Collections text file properties

Here is a list of the new collections text file properties: 

UI-Digits: 0123456789

Note:

  1. This list is still incomplete.
  2. Although UI-Digits looks like a normal UI property, it does not get copied as such into the internal ui.properties 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.

Other improvements

Command line options are now available by which one can choose a baseline Manifest file, a baseline ui.properties, and even the GoBibleCore binaries. This should make GoBibleCreator a bit easier to use with different versions of GoBibleCore.

These new options require documenting.

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)

\x08 – Increment the verse number by one (as opposed to inserting empty verses to increase the verse number).
       This has to be repeated for every verse for which the numbering is not correct.

\x0A – Line break (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 ).

Note:

  1. 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.
  2. Therefore translations with verse range tags will still require a workaround during preprocessing.

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 ThML OSIS XHTML-TE
Delimit red letters \x01 yes \wj_...\wj* yes[1] no no
Delimit translators' additions \x02 yes \add_...\add* no no no
Delimit the name of deity \x03 yes \nd_...\nd*
Delimit quotations \x04 yes \qt_...\qt*
Delimit a proper name \x05 yes \pn_...\pn*
Suppress printing the verse number, etc \x06 yes \s#_text...[2]
Line break, print verse number, resume \x07 yes \s#_text...[3]
Increment the verse number \x08 yes \v_#[4]
Line break \x0A yes \p
  1. ↑ Implements <span class="red">...</span>
  2. ↑ Applied before the title.
  3. ↑ Applied after the title.
  4. ↑ Workaround for missing verses.

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.

Retrieved from "https://wiki.crosswire.org/index.php?title=Projects:Go_Bible/SymScroll&oldid=9943"