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
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.
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.
"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.
"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
"+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)
"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
"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.
"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.
"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.
"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"