DevTools:JSword/Personal Commentary

Introduction

JSword does not currently support the SWORD Personal Commentary Module. The purpose of this page is to discuss what is necessary to create one. Once implemented and documented in the code, this page should no longer be necessary.

Structure of a SWORD Personal Commentary Module

The SWORD Personal Commentary Module is of type RawFiles.

The empty module consists of the following files:

• In mods.d:
  • personal.conf
• In modules/comments/rawfiles/personal
  • ot -- Old Testament data
  • ot.vss -- Old Testament index
  • nt -- New Testament data
  • nt.vss -- New Testament index

nt and ot are the data files. nt.vss and ot.vss are

After writing the first comment on a verse, two more files appear:

• incfile -- This file has an entry indicating how many verses have been written.
• 0000000 -- This file has the content of the first comment.

If the written entry is on a New Testament verse, then nt and nt.vss are modified. If it is an Old Testament verse, then ot and ot.vss are modified.

Editing the comment on the same verse changes the 0000000 file but not any other files.

Upon writing a second verse another file appears:

• 0000001 -- The content of the second verse's comment.

So these files represent the comments that have been written.

While the stock Personal Commentary module is not encrypted, SWORD allows for it to be.

incfile

This file merely contains a 32-bit little-endian integer, indicating how many verses have been written. It can also be thought of as containing the number for the next entry.

Index file structure (ot.vss and nt.vss)

In SWORD, the index file is an ordered list of entries, with each entry consisting of the tuple (offset,size). In a SWORD module, offset is always a 32-bit little-endian integer. Size can be either 32-bit or 16-bit. In the case of the Personal commentary it is 16-bit. (This can be easily seen by comparing the size of the index to a rawcom (16-bit) and a rawcom4 (32-bit) commentary.)

The index is ordered by the canonical ordering of all the verses in the KJV canon with allowances for meta-verses to hold testament, book and chapter introductions.

Doing a binary compare on the index of before and after writes, will show that the size is always 9 and the offset is always 9 bytes shy of the end of the data file. That is the index records an append to the datafile.

Data file structure (ot and nt)

Each write of the data file appends 9 bytes to the end. These 9 bytes are the name of the file (7 characters) followed by a windows-style newline (\r\n). Note, anything in the datafile that is not indexed is garbage and both the ot and nt files contain garbage.

General Structure of a JSword Driver

TBD