Merge pull request #290 from bible-technology/develop

Release 1.0.0-rc1
bible-technology · May 3, 2022 · 8a02ca5 · 8a02ca5
2 parents b4f330a + 11457cc
commit 8a02ca5
Show file tree

Hide file tree

Showing 40 changed files with 144 additions and 113 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -59,7 +59,7 @@
 # The short X.Y version.
 version = u'1.0.0'
 # The full version, including alpha/beta/rc tags.
-release = u'1.0.0-beta1'
+release = u'1.0.0-rc1'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

diff --git a/docs/examples/artifacts/audioTranslation.json b/docs/examples/artifacts/audioTranslation.json
@@ -1,13 +1,13 @@
 {
   "meta": {
-    "version": "1.0.0-beta1",
+    "version": "1.0.0-rc1",
     "category": "source",
     "generator": {
       "softwareName": "DBLImport",
       "softwareVersion": "0.0.0",
       "userName": "Eric Pyle"
     },
-    "defaultLanguage": "en",
+    "defaultLocale": "en",
     "dateCreated": "2018-03-15T19:38:40.762935+00:00",
     "comments": [
       "Updated with working audio files for GEN 1-3 and MAT 1-3, test browser open on success"
@@ -106,7 +106,7 @@
       }
     }
   ],
-  "names": {
+  "localizedNames": {
     "book-gen": {
       "abbr": {
         "en": "Gn"

diff --git a/docs/examples/artifacts/embossedBrailleScripture.json b/docs/examples/artifacts/embossedBrailleScripture.json
@@ -1,13 +1,13 @@
 {
   "meta": {
-    "version": "1.0.0-beta1",
+    "version": "1.0.0-rc1",
     "category": "source",
     "generator": {
       "softwareName": "DBLImport",
       "softwareVersion": "0.0.0",
       "userName": "Jake Kyle"
     },
-    "defaultLanguage": "en",
+    "defaultLocale": "en",
     "dateCreated": "2019-07-17T08:00:56.467963+00:00",
     "comments": ["Braille test"]
   },
@@ -122,7 +122,7 @@
       }
     }
   ],
-  "names": {
+  "localizedNames": {
     "i18n-contents": {
       "short": {
         "en": "Contents"

diff --git a/docs/examples/artifacts/minimalTemplate.json b/docs/examples/artifacts/minimalTemplate.json
@@ -1,11 +1,11 @@
 {
   "meta": {
-    "version": "1.0.0-beta1",
+    "version": "1.0.0-rc1",
     "category": "template",
     "templateName": {
       "en": "A Minimal and Frankly Pointless Template"
     },
-    "defaultLanguage": "en",
+    "defaultLocale": "en",
     "dateCreated": "2018-02-15T22:33:50.875547+00:00"
   },
   "copyright": {

diff --git a/docs/examples/artifacts/signLanguageVideoTranslation.json b/docs/examples/artifacts/signLanguageVideoTranslation.json
@@ -1,13 +1,13 @@
 {
   "meta": {
-    "version": "1.0.0-beta1",
+    "version": "1.0.0-rc1",
     "category": "source",
     "generator": {
       "softwareName": "DBLImport",
       "softwareVersion": "0.0.0",
       "userName": "Elbert Boot"
     },
-    "defaultLanguage": "en",
+    "defaultLocale": "en",
     "dateCreated": "2019-12-10T15:44:10.641544+00:00",
     "comments": ["First submit updated metadata and mpg files"]
   },
@@ -98,7 +98,7 @@
       }
     }
   ],
-  "names": {
+  "localizedNames": {
     "book-luk": {
       "short": {
         "en": "Luc"

diff --git a/docs/examples/artifacts/textStories.json b/docs/examples/artifacts/textStories.json
@@ -1,14 +1,14 @@
 {
   "meta": {
     "category": "source",
-    "version": "1.0.0-beta1",
+    "version": "1.0.0-rc1",
     "dateCreated": "2020-03-31T09:04:10.3+02:00",
     "generator": {
       "softwareName": "SB01Import",
       "softwareVersion": "0.0.0"
     },
     "comments": ["Version 4"],
-    "defaultLanguage": "en"
+    "defaultLocale": "en"
   },
   "idAuthorities": {
     "dcs": {

diff --git a/docs/examples/artifacts/textTranslation.json b/docs/examples/artifacts/textTranslation.json
@@ -1,13 +1,13 @@
 {
   "meta": {
-    "version": "1.0.0-beta1",
+    "version": "1.0.0-rc1",
     "category": "source",
     "generator": {
       "softwareName": "DBLImport",
       "softwareVersion": "0.0.0",
       "userName": "Jeff Klassen"
     },
-    "defaultLanguage": "en",
+    "defaultLocale": "en",
     "dateCreated": "2018-02-15T22:33:50.875547+00:00",
     "normalization": "NFC",
     "comments": ["Testing dblChanges.txt"]
@@ -182,7 +182,7 @@
       }
     }
   ],
-  "names": {
+  "localizedNames": {
     "book-gen": {
       "abbr": {
         "en": "Gn"

diff --git a/docs/examples/artifacts/textTranslation_derived.json b/docs/examples/artifacts/textTranslation_derived.json
@@ -1,14 +1,14 @@
 {
   "meta": {
-    "version": "1.0.0-beta1",
+    "version": "1.0.0-rc1",
     "category": "derived",
     "dateCreated": "2019-02-19T01:02:03+01:00",
     "generator": {
       "softwareName": "Burrito Factory",
       "softwareVersion": "0.1",
       "userName": "Jane Doe"
     },
-    "defaultLanguage": "en",
+    "defaultLocale": "en",
     "comments": ["Experimenting with i18n", "Fixed canon before upload. ~Josh"]
   },
   "idAuthorities": {
@@ -250,7 +250,7 @@
       "size": 99
     }
   },
-  "names": {
+  "localizedNames": {
     "book-gen": {
       "abbr": {
         "fr": "Gn"

diff --git a/docs/examples/artifacts/typesetScripture.json b/docs/examples/artifacts/typesetScripture.json
@@ -1,13 +1,13 @@
 {
   "meta": {
-    "version": "1.0.0-beta1",
+    "version": "1.0.0-rc1",
     "category": "source",
     "generator": {
       "softwareName": "DBLImport",
       "softwareVersion": "0.0.0",
       "userName": "Bev Cope"
     },
-    "defaultLanguage": "en",
+    "defaultLocale": "en",
     "dateCreated": "2018-12-08T12:36:12.329486+00:00",
     "comments": ["Looking for FrontCover.JPG"]
   },

diff --git a/docs/examples/artifacts/wordAlignment.json b/docs/examples/artifacts/wordAlignment.json
@@ -1,14 +1,14 @@
 {
   "meta": {
     "category": "source",
-    "version": "1.0.0-beta1",
+    "version": "1.0.0-rc1",
     "dateCreated": "2020-03-31T09:04:10.3+02:00",
     "generator": {
       "softwareName": "Autographa-Aligner 0.1.0",
       "softwareVersion": "0.0.0"
     },
     "comments": ["Add alignments of all NT books."],
-    "defaultLanguage": "en"
+    "defaultLocale": "en"
   },
   "idAuthorities": {
     "bcs": {

diff --git a/docs/examples/artifacts/xScripture.json b/docs/examples/artifacts/xScripture.json
@@ -1,14 +1,14 @@
 {
   "meta": {
     "category": "source",
-    "version": "1.0.0-beta1",
+    "version": "1.0.0-rc1",
     "dateCreated": "2020-03-31T09:04:10.3+02:00",
     "generator": {
       "softwareName": "SB01Import",
       "softwareVersion": "0.0.0"
     },
     "comments": ["This is fuuuuuuuun!"],
-    "defaultLanguage": "en"
+    "defaultLocale": "en"
   },
   "idAuthorities": {
     "paint-store": {

diff --git a/docs/flavors/extending.rst b/docs/flavors/extending.rst
@@ -1,3 +1,5 @@
+.. _extending_scripture_burrito:
+
 ###########################
 Extending Scripture Burrito
 ###########################
@@ -86,9 +88,9 @@ The easiest way to assemble valid Scripture Burrito is to start with the example
 
    /burritoMetadata/type/flavorDetails
 
-which is where flavor-specific information is stored. For experimenting with this part of the XML while keeping everything else valid, set the flavor to something beginning with "x-". The schema will then allow most well-formed XML within flavorDetails.
+which is where flavor-specific information is stored. For experimenting with this part of the specification while keeping everything else valid, set the flavor to something beginning with "x-". The schema will then allow most well-formed JSON within flavorDetails.
 
-(This task will be much less painful with a schema-aware XML editor that validates XML after each keystroke. https://www.oxygenxml.com/ provide excellent, commercial editors. Open source options include Emacs and command-line validators such as xmllint.)
+(This task will be much less painful with a schema-aware editor that validates after each keystroke. See the `Real Time Editing <https://github.com/bible-technology/scripture-burrito#for-real-time-editing>`_ section of the README for help on this.)
 
 ===============================
 Circulate it, Use it, Refine it

diff --git a/docs/flavors/scripture_audio_flavor.rst b/docs/flavors/scripture_audio_flavor.rst
@@ -1,3 +1,5 @@
+.. _scripture_audio_flavor:
+
 ###############
 Scripture Audio
 ###############

diff --git a/docs/flavors/scripture_braille_flavor.rst b/docs/flavors/scripture_braille_flavor.rst
@@ -1,3 +1,5 @@
+.. _scripture_braille_flavor:
+
 #################
 Scripture Braille
 #################
@@ -70,4 +72,4 @@ This element describes the physical page layout.
 Conventions
 ===========
 
-None.
+None.
diff --git a/docs/flavors/scripture_print_flavor.rst b/docs/flavors/scripture_print_flavor.rst
@@ -1,3 +1,5 @@
+.. _scripture_print_flavor:
+
 ###############
 Scripture Print
 ###############
@@ -114,4 +116,4 @@ The absence of this convention means that nothing maybe assumed about the name o
 Tagged Text Variant
 -------------------
 
-None
+None
diff --git a/docs/flavors/scripture_sign_language_flavor.rst b/docs/flavors/scripture_sign_language_flavor.rst
@@ -1,3 +1,5 @@
+.. _scripture_sign_language_flavor:
+
 #######################
 Scripture Sign Language
 #######################

diff --git a/docs/flavors/scripture_text_flavor.rst b/docs/flavors/scripture_text_flavor.rst
@@ -1,3 +1,5 @@
+.. _scripture_text_flavor:
+
 ##############
 Scripture Text
 ##############

diff --git a/docs/index.rst b/docs/index.rst
@@ -6,50 +6,29 @@ Scripture Burrito Documentation
 
 .. image:: ../logo/burrito_logo.png
 
-This is the official documentation for the evolving Scripture Burrito standard. See the development `milestones here <https://github.com/bible-technology/scripture-burrito/milestones>`_).
+After several years of development and testing, we are pleased to announce the availability of **Scripture Burrito 1.0-rc1** specification! We recommend that developers of Scripture and Scripture-related applications test and adopt this specification for interchanging data with other systems. Out of the box Scripture Burrito is designed to support the following types of data:
 
-**This is 1.0.0-beta1** based on `JSON Schema <https://json-schema.org/>`_.
+- :ref:`scripture_text_flavor`
+- :ref:`scripture_print_flavor`
+- :ref:`scripture_audio_flavor`
+- :ref:`scripture_sign_language_flavor`
+- :ref:`scripture_braille_flavor`
+- :ref:`scriptural_text_stories_flavor`
 
-Feedback
---------
+As interoperability is our primary goal, we are happy to accept proposals for new flavors based on common interchange scenarios. We have provided instructions and examples for :ref:`extending_scripture_burrito` by testing and implementing new flavors (using ``x-`` flavors). When multiple implementations can be demonstrated, we will consider adding them as official flavors in new schema releases.
 
-Feedback may be provided via the `Technology.Bible forum <https://technology.bible/c/sb>`_ or via the `Scripture Burrito Github issues <https://github.com/bible-technology/scripture-burrito/issues>`_.
+If you learn best by example, see the `minimal flavor examples <https://github.com/bible-technology/sb_minimalFlavorExamples>`_.
 
-The :ref:`committee` invites comments on all aspects of this documentation, but has identified some specific issues about which decisions need to be taken:
+This work has been a multi-year collaboration between several organizations, including `American Bible Society <https://americanbible.org/>`_, `Clear.Bible <https://www.clear.bible/>`_, `Eldarion <https://eldarion.com/>`_, `Bridge Connectivity Solutions <https://bridgeconn.com/>`_, `SIL <https://www.sil.org/>`_, `unfoldingWord <https://www.unfoldingword.org/>`_, `United Bible Societies <https://unitedbiblesocieties.org/>`_, and the work has been sponsored by `illumiNations <https://illuminations.bible/>`_.
 
-JSON only for metadata
-......................
+Future Development
+==================
 
-The 0.1.0 specification was based on an XML schema for metadata with a JSON representation. However, the goal for **0.2.0** was to switch to `JSON Schema <https://json-schema.org/>`_ as the only representation of the metadata. This transition is now completed and 0.2.0-beta.2 represents this change.
+See future development `milestones here <https://github.com/bible-technology/scripture-burrito/milestones>`_. The Scripture Burrito :ref:`committee` invites comments on all aspects of the schema and documentation. Please use `Github Issues <https://github.com/bible-technology/scripture-burrito/issues>`_ or `Github Discussions <https://github.com/bible-technology/scripture-burrito/discussions>`_ to provide feedback.
 
-MD5 Checksums
-.............
 
-For ingredient (file) checksums we are using the dated MD5 hashing algorithm. See `our discussion <https://github.com/bible-technology/scripture-burrito/issues/115>`_ about this issue. Please open an issue to let us know if this will be problematic for your use case.
-
-USFM and USX for Scripture Text
-...............................
-
-The current proposal is based on the Digital Bible Library, which chose USX because it can be validated rigorously. As a result of this choice, several large publishing workflows including
-YouVersion and API.Bible use USX.
-
-Much of the Bible translation world uses USFM, which is familiar to
-Bible translators, but which requires bespoke parsing tools, and which can be ambiguous in some circumstances. Also, USX contains machine-readable reference information that cannot be represented
-in USFM at this time. Valid USFM can be round-tripped to USX. USX cannot be round-tripped to USFM without losing the machine-readable references. Invalid USFM may not have an equivalent
-representation in USX.
-
-Paratext currently uses both USFM and USX internally at various points.
-
-The committee's current proposal is
-
-* USFM for translations in progress
-
-* USX for valid content, orientated towards publication (incremental or otherwise)
-
-The committee would appreciate proposals for constructive and technically feasible alternatives.
-
-Content
-=======
+Documentation
+=============
 
 .. toctree::
    :maxdepth: 4

diff --git a/docs/introduction/committee.rst b/docs/introduction/committee.rst
@@ -12,11 +12,13 @@ Current Membership
 
 The working group meets regularly and is now comprised of the following individuals:
 
+* Chuck Barker
+* Eric Pyle
+* James Tauber (implementing developer)
 * Jesse Griffin
 * Joel Mathew
 * Jonathan Robie
 * Tim Steenwyk
-* James Tauber (implementing developer)
 
 =======
 Origins
@@ -25,7 +27,7 @@ Origins
 The Scripture Burrito specification was started by the ETEN Project Portability Working Group which was
 formed after meetings in Philadelphia in July 2018 at American Bible Society. The group met several times
 virtually, culminating in two days of face meetings in Orlando on January 17-18, 2019. That
-meeting was attended by
+meeting was attended by:
 
 * Han Chung
 * Jesse Griffin

diff --git a/docs/introduction/history.rst b/docs/introduction/history.rst
@@ -48,3 +48,18 @@ Building on DBL Metadata
 The ETEN Bible Tools Portability Subcommittee looked at various options and decided to base its work on the "DBL Bundle", which consists of DBL metadata
 XML plus resources such as USX or MP3 files. This format has already been shown to work for thousands of entries. The subcommittee also identified areas
 which required significant work. The DBL origins of the first Scripture Burrito specification are therefore clear, but there are multiple breaking changes.
+
+USFM and USX for Scripture Text
+===============================
+
+Much of the Bible translation world uses USFM, which is familiar to Bible translators, but which requires bespoke parsing tools, and which can be ambiguous in some circumstances. Also, USX contains machine-readable reference information that cannot be represented in USFM at this time. Valid USFM can be round-tripped to USX. USX cannot be round-tripped to USFM without losing the machine-readable references. Invalid USFM may not have an equivalent representation in USX. Paratext currently uses both USFM and USX internally at various points.
+
+For these reasons and more, the current specification supports both USFM and USX. The suggestion is that 
+
+- USFM be used for translations in progress, and
+- USX be used for valid content, orientated towards publication (incremental or otherwise).
+
+Early Work
+==========
+
+The 0.1.0 specification was based on an XML schema for metadata with a JSON representation. However, the goal for 0.2.0 was to switch to `JSON Schema <https://json-schema.org/>`_ as the only representation of the metadata. This transition was completed with the 0.2.0-beta.2 release.