paratext-text-selector 0.1

Python tool for selecting books and portions of books created with Paratext

Paratext Text Picker

This script aims to fill a gap in the Paratext toolchain by providing a way for users to select chapters and books to be included in an app or other publication without having to manually edit the .SFM files produced by Paratext. Instead, the user creates a specification file that tells this tool what books and chapters to include.

It also includes a variety of other tools that have been useful for preparing books for publication in app form.

Example use case

For example, publish a selection of Psalms would require someone to manually delete the empty chapter and verse markers for the Psalms that have not yet been translated or approved for publication. This tool removes that problem by allowing users to specify which chapters to include and then automatically copying only those chapters.

Installation

1. Download and run python3 setup.py install
2. pip

Usage

set-texts <specification file>

py pt_text_selector/main.py <specification file>

Minimal definition file

Each definition file is composed of sections which are marked by a name surrounded with [ and ]. Each definition file must have a [config] section that must contain ptpath, outputpath, and projectname as shown in the example below. Note lines starting # are comments.

[config]
# Path to SFM files created by Paratext
ptpath = C:\\My Paratext 9 Projects\\MP1
# Path to folder to output files to
outputpath = C:\\MyAppTexts
# Name of the project.
# Should be the same as the project abbreviation in Paratext.
projectname = MP1

This config file is correct, but it doesn't do anything yet. For each file you want to process, create a section with the file name or book abbreviation (like used in the Paratext menu). Note that the script assumes it is processing a biblical book abbreviation; to add other books like front or back matter, use the filename prefixed with a *.

Working with biblical books

To get Psalms 1,2 and 30-40 we would add the following section.

[Psa]
Chapters = 1,4,30-40

What if we want to exclude the following introductory markers in the file that come before the \c 1 marker?

\id PSA - MP1: project example
\toc3 Psa.
\toc1 Psalms
\toc2 Psalms
\mt1 Psalms

To do this we simply add NoIntro = true. The config file doesn't care about capitalization so nointro = True would also work. NoIntro only works when Chapters is being used.

[Psa]
Chapters = 1,4,30-40
NoIntro = true

Imagine that we have already finished Genesis and want to include it in the app too. Simply add the following:

[Psa]
Chapters = 1,4,30-40
NoIntro = true

[Gen]

To include a whole book without modification all we need to is add a section with the book abbreviation or file name.

Working with front and back matter books

What if we want a backmatter or front matter book? For these we need to use the file name and because we're using a file name we need to tell the script by prefixing it with a *.

[*A0FRTMP1.SFM]
nointro = true

This will copy all chapters of A0FRTMP1.SFM to the output directory.

Imagine that in our front matter book we an introduction, Bible reading plan, and suggested Bible study method. We'd like these to be output to separate files so that they will be separate books in our scripture app. We simple create three sections for the same book and use the Chapters command to specify which chapters to include in each. Then we add Output to specify the output file name.

Due to a limitation in the code, each section must have a unique name so we simply add a $ and a number to the end of the file name so that the final name is unique (the $ and number will be deleted from the final file name). Notice that we have *A0FRTMP1.SFM, *A0FRTMP1.SFM$1, and *A0FRTMP1.SFM$2 in the following example.

[*A0FRTMP1.SFM]
chapters = 1
nointro = true

[*A0FRTMP1.SFM$1]
nointro = true
chapters = 2
output = ReadingPlan.SFM

[*A0FRTMP1.SFM$2]
nointro = true
chapters = 3
output = StudyMethod.SFM

This will copy chapter one to A0FRTMP1.SFM, chapter two to StudyMethod.SFM, and chapter three to StudyMethod.SFM. Note that unless we say nointro = true, the intro will automatically be appended to the beginning of the file.

Including files from outside the default project folder

What if you need to include a file that is not in the project folder (i.e. the one specified in the [config] section)? For example, perhaps the introduction is written in the national language and is in the project folder for the back translation. Simply add the Path command to the section for that book to tell the script to look somewhere else for that file.

[*A0FRTMP1bt.SFM]
chapters = 1
Path = C:\\My Paratext 9 Projects\\MP1bt

Finding front/back matter book file names

If you're unsure what the filename is look in the project direction found under My Paratext 9 Projects. Front and backmatter books usually start with A the book abbreviation from the Paratext navigation menu should be part of the file's name. The Front matter book might look like A0FRTMP1.SFM.

Other commands

• ConvertIntroTags = true makes the following replacements:
  • \ili -> \li
  • \ili2 -> \li2
  • \ip -> \p
  • \ipr -> \pr
  • \ib -> \b
• RemoveChapterLines = true removes \c tags and their number from the output file. Sometimes useful when copying front/back matter to separate files that don't need chapters.
• RemoveDraftGloEntries = true removes any glossary entry that contains the string zzz. It's a convention that our team used to specify which GLO entries were still in progress. So \k John - zzz: \k*: Stuff about John would not appear in the GLO file output if the command is used. Note it is possible to use this to remove any line containing zzz from any file. Not sure why you'd want to though.