This article is one in a series of articles describing how to get a GL project ready to publish so that others can benefit from it. This article deals with Open Bible Stories (OBS) projects created in translationStudio. A complete OBS project uploaded from tS consists of 700+ text files. These files must be compiled together into 53 Markdown files, one for each story, plus these three:
- front/intro.md
- front/title.md
- back/intro.md
Prerequisites
- The stories have been translated in tS and checked to level 3.
- The reader knows how to copy files between Door43 and a file system on a computer.
Upload to Door43
If you haven’t already, upload your project from tS to Door43.
The uploaded data will be plain text files with UTF-8 character encoding.
The .txt files reside in 50 numbered story folders plus a single front folder.
- One .txt file per OBS chunk, multiple chunks per story, 50 stories
- One reference.txt file per story
- One title.txt file per story and one in the front folder.
- Normally each text file contains one paragraph.
Compile to story files
Copy the entire collection of OBS files to a computer for processing.
I do this by using git clone* commands. For example,
git clone https://git.door43.org/EzekielDabere/ha_obs_text_obs.git
The conversion process will convert and combine the text files for each numbered story to a corresponding, numbered .md file in a content folder under the target directory. The resulting folder structure and format must look like that found in https://git.door43.org/Door43-Catalog/en_obs.
The contents of title.txt becomes a level 1 heading in the output Markdown file. The contents of references.txt becomes a footnote at the bottom of the output file. The contents of the numbered .txt files become paragraphs in the output file. References to OBS images are added before each paragraph in the output file.
The obs_mergetxt2md.py script can do this conversion. If you use this script, or any other script found in https://github.com/unfoldingWord-dev/tools/tree/develop/usfm 1, you will first have to adapt it to your computing environment.
Copy or generate files in front and back folders
You may have to ask for translations of these files if they were not generated/uploaded by tS.
- front/intro.md
- front/title.md
- back/intro.md
Verify the .md files, and make corrections
You should perform as many of these steps as you reasonably can, before requesting publication of the OBS project.
- Delete empty .md files.
- The .md file must use UTF-8 character encoding, with no Byte Order Mark (BOM).
- Each numbered .md file must:
- begin with a valid level 1
<h1>heading, which means a single hash symbol at the beginning of the first line, followed by a space, followed by the story number and title. - Blank line after the first heading.
- Third line is an OBS image link in this form
. The example is for story 1, image 1. - A plain text paragraph follows each image link. No lists, headings, nor special formats are wanted.
- Blank lines separating heading, image links and paragraphs from each other.
- begin with a valid level 1
- No HTML code, such as comments
<!-- -->, <b>, <br>, and
Create a manifest.yaml file for the OBS project
- Borrow a known good manifest.yaml file from another project as a template, but review every line in it.
- Follow the specifications in https://resource-container.readthedocs.io/en/latest/manifest.html .
- Must use UTF-8 character encoding, with no BOM.
- Copy contributor names from the manifest.json file and any other source of names that you have.
- Ensure quotes around version number strings.
- Update the issued and modified dates when any content changes.
- Modify only the modified date if just metadata (manifest) changes. If it is just a cosmetic change of no value to end users, do not even modify the modified date.
- Increment the version string whenever the issued date changes.
- The language|title should be localized if possible.
- The subject field must say “Open Bible Stories”.
- With the exception of the English resources, the publisher field should not say “unfoldingWord”.
- The projects section should look like this, with the title translated into the target language:
- categories:
identifier: obs
path: ‘./content’
sort: 0
title: ‘Open Bible Stories’
versification:
- Validate yaml syntax with an online checker, like yamllint.com.
Upload to Door43
Create a repository in Door43. The repository name should include the language code, an underscore, and “obs”. The name may also include other identifying information, such as the checking level. Upload your OBS directory structure and files to this repository.
As a final verification step, check the rendering on Door43 by using the Preview button on the repository where you stored the OBS project. Look for presence of images between paragraphs, check the index, and read the warnings that were generated. Address whatever doesn’t look right.
Submit a Source Text Request (STR)
Notify the UnfoldingWord team to publish the material by creating a Source Text Request (STR) form: https://git.door43.org/unfoldingWord/SourceTextRequestForm/issues/new. Once your form is submitted, the unfoldingWord team will verify the license release forms, and will perform all the checks and corrections described above. Any issues requiring translator intervention will be noted in the STR, and will block publication until resolved. Check back often on your STRs to monitor their progress.