Difference between revisions of "Module Development Collaboration"

From CrossWire Bible Society
Jump to: navigation, search
(VCS options: The following version control systems are proposed:)
(Directory structure: added fixes directory, moved metadata to module root dir)
Line 21: Line 21:
 
**** GerElberfelder
 
**** GerElberfelder
 
***** orig    -- source docs from publisher/author
 
***** orig    -- source docs from publisher/author
 +
***** fixed  -- source docs after correction of errors, inconsistencies, etc. in text or markup
 
***** docs    -- documentation, correspondence with pubs/authors, permission letters, etc.
 
***** docs    -- documentation, correspondence with pubs/authors, permission letters, etc.
***** meta    -- metadata, for determining the module conf file properties, etc.
 
 
*****:
 
*****:
 
***** sword  -- compiled Sword module
 
***** sword  -- compiled Sword module
Line 43: Line 43:
 
Following the approximate lead of Sword SVN, keep a ChangeLog for each module in the format:
 
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>]
+
[date in ISO 8601 format: yyyy-mm-dd]\t[contributor name <contributor email>]\n
 
\t[comments]
 
\t[comments]
  
Line 54: Line 54:
 
  make sword    (make Sword module plus any necessary intermediate formats, e.g. USFM & OSIS)
 
  make sword    (make Sword module plus any necessary intermediate formats, e.g. USFM & OSIS)
 
  make epub      (make EPUB module plus any necessary intermediate formats)
 
  make epub      (make EPUB module plus any necessary intermediate formats)
 +
 +
==== metadata ====
 +
 +
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.
  
 
[[Category:Development tools]]
 
[[Category:Development tools]]
 
[[Category:Documentation]]
 
[[Category:Documentation]]
 
[[Category:Modules]]
 
[[Category:Modules]]

Revision as of 20:47, 27 June 2012

VCS options

The following version control systems are proposed:

Directory structure

ROOT/modtype/language/module/formats/

  • sword-modules
    • comments
    • genbook
    • lexdict
    • texts
      • en
      • fr
      • es
      • de
        • GerLuther
        • GerElberfelder
          • orig -- source docs from publisher/author
          • fixed -- source docs after correction of errors, inconsistencies, etc. in text or markup
          • docs -- documentation, correspondence with pubs/authors, permission letters, etc.
          • sword -- compiled Sword module
          • gobible -- compiled Go Bible applications (including any smaller collections)
          • epub -- EPUB for publishing to ebooks
          • osis -- OSIS docs for osis2mod or sharing with publisher/3rd parties
          • thml -- ThML for import to Go Bible?
          • usfm -- USFM for sharing with author or as an intermediate step in conversion
          • usx -- USX for sharing with author or as an intermediate step in conversion

Contents of "module" directory

Scripts

The module 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 usfm2osis.pl would not appear here, instead being installed at some system-wide location outside the sword-modules tree.

ChangeLog

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]

Makefile

Let's use either GNU make for running scripts or possibly something more platform-independent like a Python or Perl script that calls other scripts. Ideally, we should be able to issue commands like:

make clean     (delete all output & intermediate format files)
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)
make epub      (make EPUB module plus any necessary intermediate formats)

metadata

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.