(Note: This article is intended for module creators and programmers who want to create their own MySword modules or create a program to convert modules from other formats into MySword format.)
MySword uses SQLite database with an extension of mybible for the modules as well as other things like settings, bookmarks, highlights, etc. For content modules, the module type is indicated as a 3 letter extension before the .mybible extension:
- bbl - for Bible
- bok - for Book
- cmt - for Commentary
- dct - for Dictionary
- jor - for Journal
Personal Notes module does not have a special extension, only .mybible, but the internal structure is actually similar to Commentary.Please open a module in an SQLite database manager app to see the actual structure of the database as the complete details will not be documented here.
For content like Bible verse text, personal notes, commentary text, journal entry, etc., HTML is the main format supported as the Android WebView component used is the one used to render content. But for Bible, there are special Bible Tags that can be used.
The Details table contained only one record where details about the module are in the fields. Here are the important fields:
- The abbreviation should be short so that it will easily fit in a small combo box for the Module/Translation selector on the top, especially for smartphones. Also, it should not contain spaces as the space is used a delimiter for the links, e.g. Bible reference link with a specified Bible translation or a Journal link to a specific topic for a specific Journal. You can use an underscore or a hyphen instead of a space though.
- The version of the module in date format YYYY-MM-DD that is used by MySword download screen to determine if the module hosted on MySword website is newer than the currently installed module.
- The 3 letter ISO language code of the language mainly used for the module.
- 0 - left to right
- 1 - right to left (Hebrew, Arabic)
- Used only by Bible
- 1 - The Bible contains the Old Testament
- Used only by Bible
- 1 - The Bible contains the New Testament
- Used by Bible and Dictionary
- 1 - The Bible contains Strong numbers/links; The Dictionary is a Strong dictionary
- Used by Bible to indicate if the default paragraph indent (the first line is indented) is used in paragraph mode. The default is 1 if not specified (with indent), set to 0 if you want no indention.
- Used by Bible and patterned after The Word verse rules but slightly modified for MySword used (that is why not all The Word verse rules are supported by MySword; Please test). A verse rule is a way to replace text in a verse using Regular Expression pattern.
- Format: <verse rule>(<new line><verse rule>)* in Regex form so that means you can have several separated by new lines.
- For the <verse rule> the format is: <RegEx><tab char><Replacement><tab char><AlternateReplacement><tab char><ToggleName>
- In <Replacement>, groups captured by <RegEx> can be referenced via $Position, e.g. $1
- The last 2 are actually optional if you do not want toggle. You can long tap the Bible Preferences button (Bible with Gear icon) to show the Rules that can be toggled. The migration tool will not do the optional though as it has to be manually written. Please see the Byzantine 2005++ module for an example of toggle.
- Module creators can now make a smaller module as they do not have to embed many span tags for color (they can also use the built-in CSS colors of MySword, please check one Color Theme in MySword by copying it and opening the CSS then scroll to the bottom).
- <font color=(blue|red)>(.*?)</font> <span class='$1'>$2</span>
- <O>(.*?)<o> <span class='orange'>$1</span>
- <v>(.*?)</v> <span class='violet'>$1</span>
- <K>(.*?)( )?<k> <span class='red' dir='rtl'>[</span>$1<span class='red' dir='rtl'>]</span>$2
<R>(.*?)( )?<r> <span class='blue' dir='rtl'>(</span>$1$2 <q> <Q><span class='blue' dir='rtl'>)</span><q>
- Note that what looked like a space on the example that separates the <RegEx> and the <Replacement> is actually a tab.
- Used by Dictionary to indicate an alternate field for word without accents. This is especially useful for languages with accents or diacritical marks like Greek, Hebrew, Spanish, etc.
- Used by Dictionary to indicate the relative order of the word entry. If absent, the order taken for the entries is alphabetical.
- Used by all module types to give module creators a way to style any HTML content in the module. For Bibles, you can use this in conjunction with VerseRules to have a shorter but still styled content. Please see also Custom colors below.
- Used by Journal and Book to indicate that it is read-only and cannot be edited. Note that Books are always read-only even if this field is set to 0.
The tags are General Bible Format (GBF) tags patterned after The Word and slightly modified in some areas. Tags are enclosed between < and >. Generally, block tags (with begin and end) where the starting tag is all caps while the ending tag has lower case letters after the upper case first (e.g. <TS> for start and <Ts> for end). Here is the list:
- <CM>- paragraph end marker
- Do not use an HTML paragraph tag (<p>...</p>) as it is already automatically used by MySword for each verse in non-paragraph mode so the output will be very ugly.
- <FI>...<Fi> - Italicized words (added words)
- <FO>...<Fo>- OT quote
- currently not formatted by MySword but is rendered <span class='ot'>...</span> so you can format ot in CustomCSS Details field
- <FR>...<Fr> - words of Jesus in Red
- <FU>...<Fu> - underlined words
- <WGNumber>- Strong Greek tag where Number is the Strong's number
- e.g. <WG5485>
- <WHNumber>- Strong Hebrew tag
- e.g. <WH2617>
- <WTCode>- Morphological tag where Code is the morph code
- e.g. <WTN-NSF>
- Please check TR or Byzantine modules for examples.
- <RF>...<Rf>- Translators' notes
- e.g. <RF>This is a translators' note<Rf>
- There could be an optional text for note link if you do not want the word note; e.g. <RF q=a>This is a translators' note with link a<Rf>
- <RXRef>- Cross-reference
- where Ref is the Bible reference in the format recognized by MySword like b.c.v (book, chapter, verse number) or b.c.v-tv (verse range, tv is to verse number)
- e.g. <RX43.3.16> for John 3:16
- <TS>...<Ts>- Title
- e.g. <TS>Psalm of David<Ts>
- <TSNumber> - TS1, TS2, etc are all just considered ordinary titles and not currently distinguished by MySword
- <PF#>- first line indent where # is the number from 0 to 7
- PI# and PF# are both poetry formatting in case both are not used
- e.g. <PI1><PF1>One tab indent
- <PI#>- indent where # is the number from 0 to 7
- PI# and PF# are both poetry formatting in case both are not used
- e.g. <PI1><PF0>Hanging indent
- <PI0><PF1>Normal paragraph indent (first line is tabbed)
- <CI> - currently just uses a space separator
- <Q>...<q> - Interlinear block
- <E>...<e> or <T>...<t> - English translation
- <X>...<x> - Transliteration
- <D> - currently ignored
- <H>...<h> - Hebrew text, currently ignored
- <G>...<g> - Greek text, currently ignored
- <wh> - Hebrew word marker, currently ignored
- <wg> - Greek word marker, currently ignored
- <wt> - currently ignored
Here is a sample verse in HiSB:
<Q><H><wh>בְּ<D>רֵאשִׁ֖ית<WH7225><h><X>be·re·Shit<x><T>In the beginning<t><q> <Q><H><wh>בָּרָ֣א<WH1254><h><X>ba·Ra<x><T>created<t><q> <Q><H><wh>אֱלֹהִ֑ים<WH430><h><X>E·lo·Him;<x><T>God<t><q> <Q><H><wh>אֵ֥ת<WH853><h><X>'et<x><T><t><q> <Q><H><wh>הַ<D>שָּׁמַ֖יִם<WH8064><h><X>hash·sha·Ma·yim<x><T>the heaven<t><q> <Q><H><wh>וְ<D>אֵ֥ת<WH853><h><X>ve·'Et<x><T><t><q> <Q><H><wh>הָ<D>אָֽרֶץ׃<WH776><h><X>ha·'A·retz.<x><T>the earth<t><q>
And here is a sample verse in ABP:
<TS>The Creation<Ts><Q><wg>εν<WG1722><E> In<e><q> <Q><wg>αρχή<WG746><E> <FI>the<Fi> beginning<e><q> <Q><wg>εποίησεν ο θεός<WG4160><WG3588><WG2316><E> God made<e><q> <Q><wg>τον<WG3588><E> the<e><q> <Q><wg>ουρανόν<WG3772><E> heaven<e><q> <Q><wg>και<WG2532><E> and<e><q> <Q><wg>την<WG3588><E> the<e><q> <Q><wg>γην<WG1093><E> earth.<e><q>
HTML tags are also supported for Bibles but they are not recommended.
Other module types other than the Bible (like Book, Commentary, Dictionary and Journal) do not require special tags as HTML tags will do. Please do not use the above Bible tags as they are not supported.
The most important HTML tag is the a tag used for hyperlink like the example below:
<a href='b43.3.16'>John 3:16</a>
Valid href formats are the following:
- Bible links
- format: bBibleReference
- where BibleReferencecan be:
- numeric like the above example
- text, e.g. bJoh 3:16
- numeric ranges are possible, e.g. b43.3.16-18
- text ranges are also possible, e.g. bJohn 3:16-18
- specific Bible translation can also be specified, e.g. bJoh 3:16-18/NET and b43.3.16.NET (range + Bible is not supported in numeric form though)
- The BibleReference can be optionally suffixed by &w=1 indicating whole chapter to display in case of popup.
- Commentary links
- link within the same active commentary format: cBibleReference
- link to a specified commentary format: c-Commentary BibleReference
- where Commentary is the abbreviation of the target Commentary and BibleReference is the target Bible reference similar to the Bible link above but without the specified Bible
- Note that in the first format, the BibleReference cannot contain a space so only the numeric format is allowed. e.g. c43.3.16
- In the second format, the space between Commentary and BibleReference is required; consequently, the abbreviation of the commentary should not contain any space but the BibleReference can have spaces.
- e.g. c-TSK Joh 3:16
- Personal Notes links
- format: nBibleReference
- where BibleReference is the target Bible reference similar to the Bible link above but without the specified Bible
- Dictionary links
- link within the same active dictionary format: dWord
- link to a specified dictionary format: d-Dictionary Word
- where Dictionary is the abbreviation of the target dictionary and Word is the target word
- Note that in the second format, the space between Dictionary and Word is required; consequently, the abbreviation of the dictionary should not contain any space but the Word can have spaces.
- e.g. d-Webster Grace
- Strong links
- format: sStrongNumber
- where StrongNumber is Strong's number preceeded by G for Greek or H for Hebrew
- e.g. sH2617
- Morphological tag links
- format: mCode
- where Code is the Morphological tag code
- e.g. mN-NSF
- Book links
- link within the same Book format: k-Topic
- link to a specified Book format: k-Book Topic
- where Book is the abbreviation of the target book and Topic is the target topic or book entry/article
- Note that in the second format, the space between Book and Topic is required; consequently, the abbreviation of the book should not contain any space but the Topic can have spaces.
- e.g. k-Atlas 001 - The Ancient Near East
- Journal links
- link within the same Journal format: j-Topic
- link to a specified Journal format: j-Journal Topic
- where Journal is the abbreviation of the target journal and Topic is the target topic or journal entry; if the Journal is not found, the list of Books is checked as in the very old version of MySword, books are not yet separated from journals
- Note that in the second format, the space between Journal and Topic is required; consequently, the abbreviation of the journal should not contain any space but the Topic can have spaces.
- e.g. j-Todo Homework
- Popup Notes
- format: rNotes
- where Notes is any arbitrary notes
- Check Abbott-Smith's Manual Greek Lexicon of the New Testament for examples.
- This is similar to Translators' notes in Bibles as it uses the same format when MySword converts the <RF> tag to HTML.
- e.g. <a class='ref' href='rCommentaries on the Gospel according to St. Mark (Third Edition, 1909) and the Apocalypse of St. John, by H. B. Swete. Macmillan, 1906.'>Swete</a>
Some of the href links can also be optionally followed by #, e.g. <a href='#b43.3.16'>John 3:16</a>. MySword simply strips the # off.
Also note that the content of the href attribute should be valid for HTML where quotes are escaped as necessary (e.g. if you use single quotes as the delimiter for the href, you have to use %27 inside the content).
Hard coding colors is not a good idea because if the user switched to dark background the text would become hard to read. Instead, you can use the following colors styled using CSS:
Here is a sentence with <span class='brown'>brown text</span> and <span class='green'>green text</span>.
Use HTML span tag for embedded text. You can also put the class in a paragraph tag (<p>) if you want the entire paragraph to be in that color.
You can also create your own colors (CSS class names other than those above) and put the color on the Details' CustomCSS field. So that colors do not have to be hard coded on CustomCSS, MySword supports all the predefined colors pulled from the current Color Theme with names similar to those above but with @ symbol as prefix. Here are some examples:
So that the standard colors can be adjusted relative to the Color Theme's values, MySword supports:
- Darken the color by the specified percent or 10%
- Percent numberic value must end with % symbol
- Lighten the color by the specified percent or 10%
- Percent numberic value must end with % symbol
- Adjust the color's hue, lightness and saturation to reproduce more possible colors
- Hue is adjustment to the 0 to 360 degrees color. In the above example, the red hue (color 0 degrees) is adjust to near orange by 15 degrees.
- Lightness and saturation must end with % symbol and can be negative
There is also a color named @body which pulls the current body color in the Color Theme (CSS).
Please always test your defined colors on light as well as in dark background color themes.