Package: paratext-text-selector
Paratext Text SelectorThis 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.SFMfiles 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 caseFor 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.InstallationDownload and runpython3 setup.py installpip install paratext-text-selectorUsageset-texts <specification file>Specification fileSeetextconfig.txtfor an example specification file. The details of how they work are below.Minimal definition fileEach definition file is composed of sections which are marked by a name surrounded with[and]. Each definition filemusthave a[config]section that must containptpath,outputpath, andprojectnameas 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 = MP1This 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 booksTo get Psalms 1,2 and 30-40 we would add the following section.[Psa]
Chapters = 1,4,30-40What if we want to exclude the following introductory markers in the file that come before the\c 1marker?\id PSA - MP1: project example
\toc3 Psa.
\toc1 Psalms
\toc2 Psalms
\mt1 PsalmsTo do this we simply addNoIntro = true. The config file doesn't care about capitalization sonointro = Truewould also work.NoIntroonly works whenChaptersis being used.[Psa]
Chapters = 1,4,30-40
NoIntro = trueImagine 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 booksWhat 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 = trueThis will copy all chapters ofA0FRTMP1.SFMto 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 theChapterscommand to specify which chapters to include in each. Then we addOutputto 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$2in 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.SFMThis will copy chapter one toA0FRTMP1.SFM, chapter two toStudyMethod.SFM, and chapter three toStudyMethod.SFM. Note that unless we saynointro = true, the intro will automatically be appended to the beginning of the file.Including files from outside the default project folderWhat 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 thePathcommand 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\\MP1btFinding front/back matter book file namesIf you're unsure what the filename is look in the project direction found underMy Paratext 9 Projects. Front and backmatter books usually start withAthe book abbreviation from the Paratext navigation menu should be part of the file's name. The Front matter book might look likeA0FRTMP1.SFM.Other commandsConvertTagsWARNING! this is one of the most difficult features to use correctly because the syntax of the list has to be exactly has follows. The list needs to be wrapped in[ ]and each substitution does as well. Each pair to be substituted needs to be wrapped indoublequotes.  It doesn't matter if you prefix the backslash or not. If you do itmustbe\\\\(yes, four backslashes).It is recommended to add a trailing space after the tag to be replaced,unless that tag is the only thing on a line.If the list is spread over multiple lines, subsequent linesmustbe indented.ConvertTags = [
  ["to replace ", "replacement "],
  ["to replace 2 ", "replacement 2 "]
  ]This would also be a valid format:ConvertTags = [["to replace ", "replacement "], ["to replace 2 ", "replacement 2 "]]Here is an example. The last two lines have the backslash, the first three don't. The tool doesn't care and both will work.ibis the only thing on the line in which it occurs so there is no trailing space after it. If there was, then it would not be replaced.ConvertTags = [
  ["ili ", "li "],
  ["ili2 ", "li2 "],
  ["ib", "b"],
  ["\\\\ip ", "\\\\p "],
  ["\\\\ipr ", "\\\\pr "]
  ]Long story short, if you choose to use this, make sure the syntax is correct and double check the output before you build an app with it.If you need to change the same set of tags in multiple books you can add a[DEFAULT]section with and assign the list to a variable name which can be referenced in the ConvertTags Command as%(varialbe-name)s. See the snippet below:[DEFAULT]
tags = [
  ["ili ", "li "],
  ["ili2 ", "li2 "],
  ["ib", "b"],
  ["\\\\ip ", "\\\\p "],
  ["\\\\ipr ", "\\\\pr "]
  ]

...

[GLO]
ConvertTags = %(tags)sRemoveDraftGloEntries = <marker>This removes any glossary entry that contains the string found in<marker>. For example if you hadRemoveDraftGloEntries = zzzin your specification file, then\k John - zzz: \k*: Stuff about Johnwould not appear in the GLO file output if the command is used. It allows you to use keep drafts in Paratext without having to manually remove them from the SFM files before publishing.RemoveChapterLines = trueThis removes\ctags and their number from the output file. Sometimes useful when copying front/back matter to separate files that don't need chapters.