Module Development Collaboration

From CrossWire Bible Society
Revision as of 07:58, 30 August 2015 by Refdoc (talk | contribs) (Directory structure)

Jump to: navigation, search

Version control

. CrossWire will provide to module teams who want to collaborate on a module following tools:

  1. A private Git repository - access will be via SSH keys which can act as a scrapbook and collaboration tool
  2. Email notification system - all changes to the repository are automatically notified to all collaborators
  3. Some templates for the repository and a bunch of scripts to make module making easy.

If you want to get such a repository on the CrossWire server please email to modules AT crosswire DOT org.

Directory structure

Our Github repository provides makefiles and scripts to setup a module making environment:

At the root is a bunch of makefile templates. Choose the appropriate, amend it as necessary and rename it "Makefile" and run

 make setup

The makefile will create and setup everything to get started. E.g. the makefile for USFM projects will create a structure like this

  • mods.d -- SWORD module conf file
  • modules -- compiled module data
  • remotescripts -- scripts pulled in from elsewhere
  • bin -- locally provided scripts
  • osis -- OSIS docs for osis2mod or sharing with publisher/3rd parties
  • usfm -- USFM for sharing with author or as an intermediate step in conversion

Depending on the project following directories might be useful.

  • gobible -- compiled Go Bible applications (including any smaller collections)
  • epub -- EPUB for publishing to ebooks
  • thml -- ThML for import to Go Bible?
  • usx -- USX for sharing with author or as an intermediate step in conversion
  • docs -- documentation, correspondence with pubs/authors, permission letters, etc.
  • orig -- source docs from publisher/author
  • fixed -- source docs after correction of errors, inconsistencies, etc. in text or markup


The bin directory (e.g. GerElberfelder above) would contain all module-specific scripts necessary for converting source files to modules and other output formats. So general purpose scripts like would not appear here, instead being installed at some system-wide location outside the tree or being pulled into the "remotescripts" directory.


Following the approximate lead of Sword SVN, keep a ChangeLog for each module in the format:

[date in ISO 8601 format: yyyy-mm-dd]\t[contributor name <contributor email>]\n \t[comments]


The makefile templates we offer run usually following

make clean     (delete all intermediate format files)
make deepclean (resets everything back to the first step, deleting work directories, intermediate files etc.)
make setup     (sets up a working environment with relevant directories, pulls in files, scripts etc)
make all       (make all supported targets: Sword/OSIS/EPUB/ThML/USFM/...)
make sword     (make Sword module plus any necessary intermediate formats, e.g. USFM & OSIS)


Metadata should be collated into a single file (maybe something XML to facilitate validation for automated generation & parsing) the incorporates all necessary metadata for all of our output formats (OSIS, ThML, TEI, EPUB/MOBI, Sword). Investigate Dublin Core & other metadata standards. Consider developing a set of private-use extensions to an existing standard and consistent methods of encoding all of our relevant .conf values in OSIS/ThML/TEI files.