Note: this article was originally posted in April 2015

The aim of this procedure to show how a USFM marked up plain text scripture book can be converted to a set of single-chapter Adapt It documents ready for adapting work.

(Note, you do not need to do this if you are planning to use Adapt It to collaborate with Paratext or Bibledit, because when collaborating you can select the option to collaborate on a chapter by chapter basis, and the splitting up of a full book into single chapter collaboration documents is done automatically for you.)

However, if you have USFM marked up source text, but do not want to work in collaboration mode, but still would prefer to work on adapting a chapter at a time – here is a handy way to prepare chapter documents that avoids lots of fiddly manual editing and file naming.

The book I will use for this procedure is a gospel of Mark, marked up as USFM plain text, in utf8 encoding. My source text scripture book is in the file: 02-MRK_utf8.txt You can use any scripture book you like, and the name of the file is of no importance.

It can be useful to create each single-chapter document with a constructed name which includes useful information about the book, such as its name, the chapter number, the 3-letter book identification code (like MAT for the book of Matthew), and the United Bible Society’s book number (Genesis is numbered 1, Malachi is 39, Matthew is 41, Revelation is 67; the number 40 is not used.

So a name constructed as follows, would be helpful.

<BookNumber>_<BookID>_CH<ChapterNumber>.xml

So for the book of Mark, which has a <BookNumber> of 42, a <BookID> of MRK, and for chapter 1, the correct form of the final name would be: 42_MRK_CH01.xml

So our goal in this exercise is to use Adapt It to convert the contents of (in my case) a file named
02-MRK_utf8.txt into the following set of sixteen single-chapter files:
42_MRK_CH01.xml
42_MRK_CH02.xml
42_MRK_CH03.xml
….
42_MRK_CH16.xml

In your case, you would use whatever USFM scripture book you want to do this for. It doesn’t have to be Mark. If you use Galations, change the parameters appropriately.
The New Testament 3-letter BookIDs are:
MAT MRK LUK JHN ACT ROM 1CO 2CO GAL EPH PHP COL 1TH 2TH 1TI 2TI TIT PHM HEB JAS 1PE 2PE 1JN 2JN 3JN JUD REV.

The Old Testament ones are:
GEN EXO LEV NUM DEU JPS JDG RUT 1SA 2SA 1KI 2KI 1CH 2CH EZR NEH EST JOB PSA PRO ECC SNG ISA JER LAM EZK DAN HOS JOL AMO OBA JON MIC NAM HAB ZEP HAG ZEC MAL.

The Essence Of The Task: Within Adapt It, using the Split Document command, and choosing the output file name carefully, Adapt It will cut the book document up at each \c marker location, and automatically number the chapters – using 01, 02, 03 etc, and adding .xml at the end. (Adapt It will add leading zeros to small chapter numbers automatically. The leading zeros ensure that the chapter files stay in correct order when displayed in the list boxes of any software.) I suggest making a new (possibly temporary) Adapt It project for doing this task. Here are the steps:

  1. Run Adapt It. In the Start Working… wizard, create a <New Project> – and you need to supply a source language name, and a target language name (any names you like). X and Y would do, for example, so that’s what I will use. Type X into the source language box, Y into the target language box, or whatever other names you prefer. Then click Next>
  2. Go through the wizard pages, accepting the default settings, just click Next> each time a new page of the wizard opens; but at the Case page, click the checkboxes so as to have upper and lower case assocations created, before you click Next>.
  3. At the Document page, Cancel out of the wizard without trying to create a document.
  4. If the Adapt It frame window is small, drag a corner to make it a useful size. Click on the title bar at the top to position the window on the screen where you want it to reside. Then click File > Exit (or click the x button at the top right of the window) to shut Adapt It down. Adapt It will then have created its configuration files, etc.The next steps are what you do to get your scripture text file, (in my case 02-MRK_utf8.txt,) changed into sixteen single-chapter correctly named Adapt It documents. Some of these steps are done in your operating system file browser – I’ll assume Windows is your operating system.
  5. In Windows Explorer, or in your operating system’s file browser, navigate to the project folder. It will be in your Documents folder (or home folder on Linux), and located within the Adapt It work folder, called “Adapt It Unicode Work”, and the project folder will be called “X to Y adaptations” (your name will differ, if you typed names other than X and Y). Open that project folder.
    Notice what is there: a bunch of folders with unusual names starting with an underscore.
    Also a folder called Adaptations, which is where your single-chapter document files will end up, once they are created.
    And a folder with two underscores at its beginning, called “__SOURCE_INPUTS”. Adapt It will look in that folder for its source text files from which to create new documents for adaptation.
  6. In Windows Explorer, select your source text file ( in my case, 02-MRK_utf8.txt ); click the Copy command in the Edit menu (or CTRL+C), then navigate to the
    “…\X to Y adaptations\__SOURCE_INPUTS” folder, and there Paste your source text file.
    That’s all you need Explorer for the moment, so you can minimize it or close it.
  7. Run Adapt It, enter your project (in my case, “X to Y adaptations”), and after clicking Next> you will see the wizard page “Choose a Document”. Click <New Document> if it is not already selected, and then click the Finish button.
  8. You will then see a file navigation window. If it is not open at the __SOURCE_INPUTS folder, navigate to that folder and open it.
    You should then see your source text scripture book file (in my case, 02-MRK_utf8.txt). Double-click it, or click it once and click the Open button.
    Adapt It will then ask you for a filename for the document, just accept whatever it shows you, click the OK button.
    Adapt It will then lay the contents out ready for adaptation. (Except we won’t do any adaptation. We just want to cut the book up into smaller bits, each bit a single chapter.)
  9. We are nearly done. This is the vital bit. Open the Tools menu, and choose “Split document”. This is a screen shot of the Split document window when it opens:
    SplitDocWndw_Empty
  10. Click the radio button “Split into single chapter documents”.
    Then provide the fixed part of each single-chapter document’s name, in the top box (the Obligatory one). In our case, we would type this: 42_MRK_CH
    Do so now.
    (If you are using a different scripture book, then change MRK to whatever 3-letter code is needed for your book, and whatever book number is appropriate at the start of the name. For example, for Galations you would type 49_GAL_CH)
    Notice two things. We do not type any number at the end. Adapt It will automatically add the correct number and any leading zero needed. Second, Adapt It will automatically add the .xml extension to the end, so do not type it.
  11. When you’ve clicked the radio button mentioned above, and typed in the fixed part of the name, then click the Split Now button.
    You need to wait a while – splitting can take a bit of time (30 seconds or more).
    When done successfully, you will see a message saying: “Splitting the document succeeded.”
    Note, the splitting process produces the single-chapter documents, but at the price of consuming the original multi-chapter document. This is normal. It would be confusing to have the same scripture content in different places. Click the OK button to dismiss the message.
  12. The Split document dialog will now be overlaid by the Start Working wizard, which will open at the “Choose a Document” page.
    You will see all your single-chapter documents listed there, in natural order of increasing chapter number.
    If you were going to adapt them, you’d now choose one and click Finish, and then you’d start adapting in the laid out document.
    But we only want to take these single-chapter documents and copy them to some other place – perhaps into the Adaptations folder of a project you’ve already created ready for adaptation work; or to a usb stick to take to someone else, or whatever. So here is what you would do next….
  13. Click the Cancel button.
    The Split document window may still be open, if so click the Close button to close it.
    Nothing more needs to be done in this Adapt It temporary project, so close Adapt It.
  14. In Windows Explorer, navigate to the:
    ….\Adapt It Unicode Work\X to Y adaptations\Adaptations\ folder.
    You will see all the single-chapter documents listed there. Select them all, and then Cut them, and navigate to wherever you want them to permanently live, and Paste them there.
    After that, you can delete the “X to Y adaptations” temporary project folder – which will also delete everything it contains, which is fine provided you’ve saved the single-chapter documents elsewhere first. Or if you think you may do this procedure again for some other scripture books, just keep the temporary project permanently, use it as a handy place to do things like this from time to time.
Preparing Single-Chapter Documents Prior to Adapting