BibleTrans Rationale


The purpose of this document is to explain the programming of BibleTrans so another programmer can understand and (if necessary) maintain it. You should already be familiar with how it works (download the working version, and work through the tutorials in it). If you are just getting started, start with How BibleTrans Works. To understand the data structures used in BibleTrans, you should review the BibleTrans Design Decision Log. BibleTrans is written in a programming language I call Turkish Demitasse (T2, "A Much Stronger Brew Than Java"), which is described elsewhere. T2 resembles C++ and Java, so any competent programmer should be able to pick it up in short order. By the time you read this, the tools and BibleTrans itself should also be running on Windows from C++ files compiled from T2, which process is also described in another place. This document will mostly not repeat what is in those other documents.

BibleTrans is broken into four separately compiled interacting "programs" which load into a single runtime as separate threads, to perform their separate functions. A fifth program builds the database file as described in its own document, but is not distributed as part of the BibleTrans runtime. The rest of this document is concerned with an overview of their duties and interactions, and then the main driver program, which also provides most of the user interface.

This document is still very incomplete. I expect to be working on it from time to time, mostly while waiting for the computer to compile the next working version.

Date of this revision: 2013 May 22
 

RoadMap

We have at least four kinds of source files to work from. First there are the five T2 source code files described here, plus a bunch of source files for the framework. These compile in the usual manner, T2->68K or T2->C->x86.

BibleTrans is the main driver program. It starts up the other three "programs" and is responsible for displaying document pages in the database, and dispatching clicks from those pages or menu commands.

ActImag formats the grammar rules for display, and accepts user input to edit those rules. The rules themselves are displayed as "active images" within the text document pages. Clicks on the images are relayed to ActImag for processing.

DoTrees displays and lets the user edit the tree representation of the Greek text.

ExecEng is the translation engine. It also displays output text and execution status to facilitate debugging.

DocPrep is a stand-alone program with multiple utilities for building the document database used by BibleTrans. The sequence of steps for doing this is currently listed at or near the bottom of its source file, or in less detail in a popup window as one of the options ("Help-Seq") when the program is running. This program takes sooo long on a Windows PC that I've never actually run any part of it (except the final "Load Doc" step) on a PC to completion, so I don't know that it really works there. See "Document Preparation" for more information.

We have a very large text document "xBTdox" (Mac files have an ontological file type, so they do not need name extensions to define them) which DocPrep reads and converts into the resources of "BT_Docs.BTD" (both text pages and the stuff that defines what goes into grammars). Text pages can be displayed by the BibleTrans main program, and the grammar stuff controls how ActImag displays and edits translation grammars (but still within text document pages) described in more detail in "Active Image Data Resource Formats".

The semantic database is constructed manually in DoTrees (see the tutorials in BibleTrans for how to do that), then saved off into exported (text) tree files, which can subsequently be read in and built as "TreeXxxx.BTD" files (the "Xxxx" part of the name is one of about 13 segments, such as "Matt" or "GEPC" (Galatians+Ephesians+Philippians+Colossians) or "Demo". If DoTrees does not see a valid set of tree files, it will rebuild the complete set (possibly only empty stubs) as part of the startup.

Finally, there is a grammar text file for each language grammar -- or perhaps several such files, as used for the tutorials to show the development process. These are usually named by whatever the language is, plus the standard ".txt"  extension. These are manually created within BibleTrans+ActImag (again, see the tutorials in BibleTrans for how to do it), then exported as text. They can subsequently be imported into the internal file format, for example, "English.BTL" for English. BibleTrans looks for all reasonable language files at startup, and automatically adds them to the Language menu.

The translation process adds output text resources to whatever language file is selected as current in the Language menu. These resources can be exported by ExecEng into ordinary text files, representing the translated Bible text.
 

Overview

I'm still in the process of redefining what the data structures should look like to support larger grammars. When that's complete, I will need to modify DocPrep and ActImag and ExecEng to support these new structures. BibleTrans and DoTrees don't look at that data, and should need no modification.

The fundamental T2 interprocess communication medium is an event, and events are used to send user actions such as keystrokes and mouseclicks to the operating program. In BibleTrans and the other three threads, events are also the primary means for sending each other timely information. The database file is open "shared" and all the processes have access to the same data, but it is events that tell each other what to do with it.

Some events can be scripted to run complex operations, such as tutorial setups. BibleTrans manages the scripting engine, which finds its scripts in "sXec" text resources in the document file. Each line of a "sXec" resource is a command that is parsed into an event to send to whichever program knows how to process it. Most of the scripts are triggered by a "P000" message (where "000" is some decimal number, the resource number of the script to be run); these messages are tied to active images that look and act like pushbuttons.

The "Find" event is processed by one of three programs, depending on what is to be found. If the user asks it to find a tree node, then it is sent to DoTrees; named rules are searched by ExecEng; ordinary documents (such as Greek text) are searched by BibleTrans.

Here follow the events used in BibleTrans and its accessory programs.
 

T2 System Events

These events are sent by the T2 system to any operating program, generally whoever opened the front window, on the specified occasions:

"KeyC" This event carries each user keystroke.

"mDwn" "Clik" "2clk" Most user clicks on a window are aimed at "hot spots" which the program has set up with their own event message codes. One or more of these three events happen when the user clicks on some space not so designated.

"mDrg" "Drag" "Drop" Some areas of a window can be designated as suitable for dragging or dropping, and the system generates these events when the user does those actions there.

"OpFi" Dropping a file reference on a window that does not otherwise specify how to respond to such drops sends this event. The program typically responds the same as if the user had selected the "Open File" menu.

"CxMn" "CxMx" In Windows a right-click typically opens a context-sensitive menu under the mouse, which is informed by the (CxMn) event. The Mac does not normally have multiple mouse buttons, so holding the control key down while clicking has the same effect. In T2 you can also hold the mouse button down extra long for the same or similar effect (CxMx).

"wAct" This event is sent to a window when it activates (becomes front) or deactivates (by some other window coming in front of it, so the program can redraw whatever visual indication it has for the window being active. In T2 it is customary to darken inactive windows, but that reaction is not yet implemented in BibleTrans.

"SizW" This event is sent to a window when the user changes its size. It was originally intented to send a comparable event (MovW) when the window is moved, but there is seldom any additional programmatic response to moving a window, so that event has been removed from the T2 system.

"CloW" This event is sent when the user clicks the "go-away" region of a window structure. The program is expected to do whatever clean-up is necessary, then close the window.

"WnUp" This event is sent by the image window manager when a window it manages is opened or closed, so that the program can update its Windows menu, if any. BibleTrans also sends this message itself, for its own windows.

"0Win" This event is sent after the last visible window is closed, so the program can quit if it so chooses.

"Imag" T2 has substantial image-handling routines for complex windows, but BibleTrans does some of its own management. This event is sent when the window needs to be redrawn.
 

Menu Events

These events are encoded in the menus:

"Open" Open (document page)
"OpRf" Open Bible Reference
"CloW" Close front window
"Save" Save (export) whatever data is encoded in the front window
"nxNS" Edit this Node Shape
"Pref" Preferences
"Find" Find (tree node or rule name)
"Welc" Open Welcome page (document #1)
"Scrn" Save This Screen configuration
"NewL" New Language
"Clan" Clone this language
"Tran" Translate
"Debu" Start Debugging
"Stop" Pause translation
"Step" Do one translation Step
"zBkp" Clear All Stops
"ExRn" Toggle Log Trace
"LogF" Set Log File
 

Hotspot Events

The following events are encoded in tree window hotspots. Event names beginning with a "+" represent draggable data:

"+Tre" This is a tree node icon; dragging it gets the whole tree
"+Cmt" This is the comment line of a tree node, if any
"+Nn#" This is the Noun Number of a noun node
"*Bbl" This is the Bible reference line of a node so marked
"+L&N" This is the L&N number of a node
"Slot" This is a semantic role slot of a node (nobody looks at this event)

These events are encoded in document window hotspots, typically within active images:
(TBA)
 

Script Events

These events are sent from predefined scripts:

"DmIm" Load up (from internal resources) a Demo tree (in DoTrees)
"LdTr" Load up (from internal text resource) a tree (in DoTrees, but unused)
"TreR" Open or activate a Tree window and set its rectangle
"TrSc" Open or activate a Tree window and set its scroll
"ScEd" Edit tree operation (in DoTrees), for making minor adjustments before tutorial
"chLN" Change the L&N tag on a specified node (in DoTrees), likewise
"TogT" Open or close node (in DoTrees), likewise
"KeyN" Process this keystroke in DoTrees
"nOtr" Make a clean output resource (in ExecEng)
"XtlR" Open or activate an output window and set its rectangle (in ExecEng)

These script items are not events, but look and behave as if they were:

"NewL" Open and import a specified language file
"R->L" Copy a resource from the document file to the current language
"R->D" Copy a document page from the document file to the current language
"*B4Q" Add information to a script that runs before BibleTrans quits

These are the predefined scripts:

P001 to P059 -- load up respectively Inglish1 to Inglish59 grammar, then maybe also open windows

P070 to P089 -- load up respectively Awa0 to Awa19 grammar, and possibly also matching Demo1 to Demo10 tree

P100 -- Php 1:1 in Demo Tree win, and delete verse 2 from it
P101 -- Php 1:1 in Demo Tree win, complete
P136 -- Demo Setup
P135 -- Demo Setup continued
P137 -- Run Demo 1: translate 3:16 into English
P138 -- Run Demo 2: translate 3:16 into Awa
P163 -- John 3:16 Tree win
P315 -- John 3:16 Tree (unused)
P316 -- John 3:16 Tree win + English
P317 -- Translation Debug
P555 -- 5 Window Positions
P998 -- existing Demo Tree win
P999 -- clean empty Demo Tree win
 

From BibleTrans to Itself

These events are sent by BibleTrans to itself, in addition to scripted messages (above):

"OpSc" This event is sent by a BibleTrans popup menu to open a window for changing a node shape.

"WnUp" This event is sent when a window opens or closes, to refresh the Windows menu.

"CloW" This event is sent to close the front window as part of a larger operation.

"WnSz" This event is sent when a window that has a saved position is opened.

"Pong" This event is sent at the end of a set of screen configuration settings, to let BibleTrans know it finished.

"wDoc" This event is sent when handling an "OpSc" event, to delay setting its scroll until after a window is formatted.

"RgSv" This event is sent as part of the quitting sequence, to save whatever Registry items need it.
 

To/From ActImage

These events are sent between the BibleTrans main program and ActImage for grammar management:

"Ping" This event is sent by BibleTrans to all other processes as part of its startup. They respond with "Pong". When BibleTrans has received all three "Pong"s, it knows they all finished opening their startup documents (or whatever).

"ActF" This event is sent by ActImage to let BibleTrans know it has finished its startup.

"Died" This event is sent by ActImage when it quits, perhaps untimely. BibleTrans can presumably also quit.

"Clan" "NewL" "Lsyn" "nLan" Language selection can happen as a result of any of several causes, and all but DoTrees need to respond to the change. These events are part of that synchronization process.

"LxUs" This event is sent by ActImage as part of searching for a grammar name. It is forwarded to ExecEng to update its internal tables.

"+L&N" "BiRf" "+Bbl" "DocX" "DocT" "OpSc" These events open different kinds of document pages in BibleTrans, or if already open, brings that window to the front. OpSc also scrolls the opened page to a particular target, and DocT scrolls it to the top. ActImage also sends KiSc, but nobody catches it.

"Rule" "LxRu" "imRu" "GWup" "uNoS" "CloX" "StEx" "BkPt" These events are sent to ExecEng by ActImage directly, or else to be forwarded by BibleTrans, mostly for synchronizing Rule windows and grammar import; StEx stops any outstanding translation before importing a new grammar, and BkPt sets a breakpoint.

"TL&N" "NdLx" "PNLs" "UpTr" These events are sent by ActImage to be forwarded by BibleTrans to DoTrees for tree management tasks.

ActImage also sends several events to itself. The two events "LnSf" and "Frsh" are used to refresh an image after some alterations have been made. Lexical rules are managed by ExecEng, so their import must be forwarded there. Because the programs execute asynchronously, ActImage sends the events "ImpX" and "ImDn" to itself (possibly reflected through ExecEng) so that it can know that a particular phase of the process is complete.
 

To/From DoTrees

These events are sent between the BibleTrans main program and DoTrees for tree display management:

"Ping" This event is sent by BibleTrans to all other processes as part of its startup. They respond with "Pong". When BibleTrans has received all three "Pong"s, it knows they all finished opening their startup documents.

"Tbld" This event is sent by DoTrees to let BibleTrans know it is rebuilding the tree files.

"TrDn" This event is sent by DoTrees to let BibleTrans know it finished rebuilding the tree files. It is followed shortly by "TrEx" so BibleTrans can shut down properly (it needs to go through a complete restart after bu8ilding trees).

"TrOK" This event is sent by DoTrees to let BibleTrans know it has finished its startup.

"Died" This event is sent by DoTrees when it quits, perhaps untimely. BibleTrans can presumably also quit.

"WnUp" This event is sent when a window opens or closes, to refresh the Windows menu.

"StEx" This event is sent by DoTrees to ExecEng when translation is requested for a tree node.

"NSed" This event is sent by DoTrees (through BibleTrans) to ActImage when it encounters a previously unknown node shape, so a node shape editor window for it can be opened.

"DocX" This event is sent by a DoTrees popup menu to BibleTrans to open the rationale or help text page for some node.

"+L&N" This event is sent by a DoTrees popup menu to BibleTrans to open the L&N document page for some node.

"Rule" This event is sent by DoTrees (through BibleTrans) to ExecEng to open the grammar rule for some node.

"OpSc" This event is sent by DoTrees popup menu to BibleTrans to open the document for an existing shape.

"NetB" This event is sent by DoTrees to ask BibleTrans to open this verse in the NetBible.

"+Bbl" This event is sent by DoTrees to ask BibleTrans to open this verse in the Greek.

"Open" This event is sent by DoTrees to ask BibleTrans to open and import a tree file.

"TrAc" This event is sent by DoTrees to BibleTrans when a tree window is activated or deactivated.

"Find" This event is sent by DoTrees to BibleTrans in response to a Find request that does not involve tree data.

"WhyH" This event is sent by DoTrees to BibleTrans in response to a "Why hollow?" popup request.

"LnFi" This event is sent by DoTrees to BibleTrans to request a language file to select a variant node. Then it sends "Vsel" with the selected variant.

"TrFi" This event is sent by DoTrees to BibleTrans at startup to request a reference to the document file. BibleTrans responds with "Filt" and the file reference.
 

To/From ExecEng

These events are sent between the BibleTrans main program and ExecEng for managing translation:

"Ping" This event is sent by BibleTrans to all other processes as part of its startup. They respond with "Pong". When BibleTrans has received all three "Pong"s, it knows they all finished opening their startup documents.

"Died" This event is sent by ExecEng when it quits, perhaps untimely. BibleTrans can presumably also quit.

"TrnF" This event is sent by ExecEng to BibleTrans at startup to request a reference to the document file. BibleTrans responds with "Filx" and the file reference.

"WnUp" This event is sent when a window opens or closes, to refresh the Windows menu.

"LnFr" This event is sent by ExecEng to BibleTrans, usually in response to a "Lsyn" event, but also when a rule has been changed (so ActImage can reformat if necessary).

"CloW" Some windows close automatically when execution leaves them; if ExecEng does not own such a window, this event is sent to BibleTrans to be forwarded to whoever owns it.

"Srch" This event is sent by ExecEng to search for information unrelated to rules.

"SvLn" This event is sent by ExecEng to BibleTrans to save the current language data (rules).

"DocX" This event is sent by ExecEng to BibleTrans to open a document selected from a popup.

"Glox" This event is sent by ExecEng to be forwarded to ActImage, to toggle the Gloss checkbox.

"NuOu" This event is sent by ExecEng when a new translation begins, so BibleTrans can update its menu.

"OpSc" This event is sent by ExecEng when a user clicks on a hotspot that cannot be resolved to a rule window, so BibleTrans can open and scroll to whatever is appropriate.

"Rchk" This event is sent by ExecEng when execution pre-op finds incomplete or inconsistent rules, so BibleTrans can request ActImage to find all such problems and display them.

"Find" This event is sent by ExecEng to BibleTrans (to be forwarded to DoTrees) in response to a Find request that involves tree data.

"RgSv" This event is sent by ExecEng when it quits, so BibleTrans can proceed with its Registry save.

"Lsyn"  "imRu" "StEx" "nLan" "ImDn" "ActF"
 

BibleTrans

xxx
 

ActImag

xxx
 

DoTrees

xxx
 

ExecEng

xxx