Study Bible Authoring Guide

Extracted text from Paratext7.3StudyBibleAuthoringGuide-v1.0.pdf:

Paratext 7.3

Study Bible Authoring Guide What is a study Bible project? Study Bible USFM Markers How do I create a study Bible project? How do I insert study Bible content? Working with the Study Bible view Inserting book, division, or section introductions Inserting extended footnotes, cross references Inserting sidebars Assigning categories to study Bible content How can I review the quantity and distribution of study content in a project? How can I check whether verse text has been changed? How can I migrate from an (older) multi-project study Bible setup to a single project configuration

What is a study Bible project? Paratext 7.3 introduces the concept of different types of projects, such as a Standard Translation, Back Translation, Daughter Translation etc. One project (a derived project) can be based on another project (a base project). A study Bible project is also a type of derived project which is based on another project. At the time you create a study Bible project, Paratext copies the text of the base project into the new study Bible project. The base project is the existing, completed scripture translation for which the study content is being added. The following study content can be added to a study Bible project: Extended book, division or section introductions (some of which could replace existing introduction material copied from the base project). Extended footnotes that explain difficult passages, enlarge upon important themes, and shed light on the key thought of the passage being discussed. (The text of the base project might still contain other standard footnotes such as information on alternative translations and textual issues.) Cross references to passages that share a theme with the origin verse. (The text of the base project might contain other cross references such as references to the source of a quote.) Sidebars of special topics or information for more in-depth study. You might also think of these items as a kind of mini-article.

Study Bible USFMs To distinguish study Bible content from material that is part of the base scripture text, Paratext uses a small number of additional USFMs which begin with the letter e. Study Bible Extended Footnote: \ef \ef* Study Bible Cross Reference: \ex \ex* Study Bible Sidebar: \esb \esbe

Study Bible content can also be associated with one of a set of user-defined categories using the markers \cat ...\cat*. Important! For detailed information on markers that should be used when authoring study Bible content, go to http://paratext.ubs-translations.org/usfm. Scroll down to the Documentation section. Click on one of the links to open or download one the USFM documentation formats, and search for "Study Bible Content". The USFM manual includes a variety of content and potential formatting examples. The Study Bible view in Paratext assists you with entering the correct USFMs and syntax into the project text.

How do I create a study Bible project? To create a new study Bible project, do the following: 1. From the File menu, select New Project.... 2. In the Project Properties and Settings dialog, follow guide steps 1 through 8 to configure the basic project properties (If the guide is not showing, click on the Show Guide link in the yellow help box located at the bottom of the dialog). 3. From the Type of Project drop-down list, select Study Bible. You may notice that as soon as you do this, the selected stylesheet changes to usfm_sb.sty. Do not change this. 4. From the Based on drop-down list, select the project that your study Bible is based on.

5. Click OK. If the new study Bible project will be shared with other team members (authors, reviewers, obserers) who are also working in Paratext, these users will require access to the base project text as well. Both projects can be shared using Paratexts Send/Receive (project sharing) system.

How do I insert study Bible content? Working with the Study Bible view Paratext 7.3 includes a new study Bible formatted text view, which will assist you in your authoring and editing task by displaying different types of study content at different locations within the project window. The scripture translation body text (the copy of the base text) is displayed in the largest section of the project window, beginning at the top left. Extended footnotes, cross references, and other standard translation notes are displayed in a separate pane at the bottom of the project window. Sidebar content is displayed in a pane at the right side of the project window

When a note or sidebar is selected in the notes or sidebars pane, it will be highlighted with a yellow background color. The origin location will be highlighted with pink. The Notes and Sidebars panes can be closed by clicking on the small x located at the top right corner of each content area. The panes will appear again when adding a new note or sidebar, or by clicking on one of the callers visible in the body text. You can also make them visible by selecting Show Footnotes or Show Sidebars from the View menu.

Before starting to enter study content in the project text, you should check to ensure that the Study Bible view is currently selected for the study Bible project window. Click in the window of your study Bible project, to make it the active window. From the View menu, select Study Bible.

Inserting book, division, or section introductions Extended or alternative book introduction text should simply replace any existing book introduction text copied from the base scripture translation text. Any book identification elements (\h, \toc1, \toc2, \toc3), main title(s), introduction, or table elements can be included within the extended book introduction. Study Bibles also often include additional explanatory text at the beginning of divisions or sections within the scripture text. The following USFM and content sequence can be added to the text: 1. A division (major section) (\ms), or section (\s) marker 2. Optional parallel reference or scope markers (\mr, \sr, \r) 3. One or more introduction paragraph markers (\ip) In some cases the base translation text does NOT already contain a division or section heading. In these cases the major section or section markers should be added to the text. In other cases the base translation text already includes a division or section heading. In these cases the content of the headings can be edited or replaced, if necessary, and introduction paragraph marker(s) added below.

A text without a division heading from the base text. There is an existing section heading.

Division heading + introduction paragraphs added; section introduction paragraphs added.

Inserting extended footnotes and cross references Extended study footnotes or cross references are added to the project text at the specific location where they should occur (as with standard footnotes and cross references). The boundaries of the extended footnote or extended cross reference text are defined by an opening and closing marker (\ef \ef* and \ex \ex*). The remainder of the note should use standard USFMs for footnote or cross reference content. The closing markers (\ef* or \ex*) will not be visible within the text when using the Study Bible view in Paratext. 1. Click in the window of your study Bible project, to make it the active window. 2. Click at the place where the study content should occur in the text. 3. From the Insert menu, select one of the following: Study Bible Extended Footnote (shortcut = CTRL+ALT+F) Study Bible Cross Reference (shortcut = CTRL+ALT+X)

Paratext opens the Notes pane at the bottom of the project window (if it is not already open) and inserts the required initial markup. It places your cursor after the \ft or \xt marker, where you can begin entering the note text or target reference(s). Any existing footnotes or cross references from the base text will also be visible within the Notes pane.

If you select a portion of text in the body text window, and then insert a Study Bible Extended Footnote or Study Bible Cross Reference, the selected portion will be automatically added to a quotation section (indicated by \fq or \xq respectively) within the note markup (shown below).

Extended footnotes and cross references which pertain to the entire verse should be inserted immediately after the space following the verse number.

Inserting sidebars Sidebar content can be inserted anywhere within the paragraph to which it relates, however, Paratext will automatically place the sidebar just above that paragraph. Like extended footnotes or cross references, the boundaries of a sidebar are defined by an opening and closing marker (\esb and \esbe). 1. Click in the window of your study Bible project, to make it the active window. 2. Click at the place where the sidebar will occur in the text (anywhere within the paragraph to which it relates) 3. From the Insert menu, select Study Bible Sidebar (shortcut = CTRL+ALT+S)

Paratext opens the Sidebars pane at the right side of the project window (if it is not already open) and inserts the required initial markup. A new sidebar includes an \ms marker at the very beginning which is used for providing a title to the sidebar content.

Type the sidebar heading following the \ms marker. The remainder of the sidebar can use any standard USFMs for title, paragraph, poetry, table, or special text elements.

Assigning categories to study Bible content Categories can optionally be assigned to extended study notes or sidebars by supplying a category tag (name) inside of opening and closing \cat ...\cat* markers. Category tags are restricted to alphanumeric characters. A list of category tags are defined individually and uniquely for each study Bible project. Categories might be used for a variety of publishing purposes, such as to visually distinguish different category contents, or to select content from specific categories for publishing. If you want to add a category to study content, you must first add one or more categories to the projects study Bible categories list: 1. Click to place your cursor within an extended footnote or sidebar. 2. From the Insert menu, select Study Bible Category. A small pop-up window will appear at the current cursor location. This is the category selection list. If this is the first time a category has been entered for this study Bible project, the list will be empty. 3. Click Edit categories A small dialog will appear in which you can edit the projects Study Bible Note Categories. 4. Type category tags so that each tag is on its own line.

Some example categories are: History, Ideas, Objects, People, Places. 5. Click OK. The new categories will be available whenever you select Study Bible Category from the Insert menu. To add a category to a study note or sidebar, do the following: 1. Place your cursor at the very beginning of an extended footnote or sidebar (the easiest way to do this is to click in the first line of the note or sidebar, and press the Home key on your keyboard). 2. From the Insert menu, select Study Bible Category (CTRL+ALT-C). 3. Select a category from the pop-up category selection list window.

How can I review the quantity and distribution of study content in a project? The introductory topic in this document - What is a study Bible project? - explained that a Study Bible project is initiated as a copy of a base project text. As the authoring process continues, more and more content is added to this new study Bible project text. It can be helpful to periodically review the overall distribution of study content throughout the text, and to be able to see the relative size (weighting) of study material in comparison to the base text. Paratext provides a checking tool which can analyze a study Bible project text and produce a simple report showing the size of the notes and sidebars content as a percent of all text in a chapter. 1. Click in the window of your study Bible project, to make it the active window. 2. From the Checking menu, select Notes Size Report. Paratext will analyze the text and report the results to the List window. Each reference in the list represents information for one chapter of text, as in the following examples: MAT 1:0 16% = 16% (\ef) + 0% (\esb) MAT 2:0 44% = 34% (\ef) + 10% (\esb) MAT 3:0 52% = 28% (\ef) + 24% (\esb) Reference Matthew 1 Matthew 2 Matthew 3 Total Study Content (as a percentage of Bible text) 16 44 52 % extended footnotes (\ef) 16 34 28 % sidebars (\esb) 0 10 24

How can I check whether verse text has been changed? As new study content is added to the study Bible project, it is possible that areas of improvement or areas needing correction in the base project will be noticed. If such changes are made to the base project, the same changes also need to be made to the study Bible project. It is also possible that changes to the verse text in the study Bible could occur accidentally while adding or editing study content. It is important to locate any accidental changes to the verse text in the study Bible project and undo them. Paratext provides a checking tool which can report to the list window any references in which the verse text in the study Bible project is different than the verse text in the base text project (i.e. where it has been altered in one or the other project, deliberately or accidentally). 1. Click in the window of your study Bible project, to make it the active window. 2. From the Checking menu, select Changed Verse Text. Paratext will analyze the text and report the results to the List window. Each reference in the list represents a verse in which the study Bible project contains different text than the base project. The changed text differences are displayed inside of curly braces, as in {original text|changed text}.

You should carefully review this list of changed study Bible verses and then update the base or study Bible project text as needed.

How can I migrate from an (older) multi-project study Bible setup to a single project configuration Important: The procedure described in this section should normally be completed by a Paratext support person. This process only needs to be completed once for study Bible projects which were previously being authored in a multiple-project configuration. Paratext 7.2 (and earlier) supported the concept of maintaining separate projects for base text, study notes, and sidebars (e.g ABC, ABCn, and ABCs). To create one 7.3 study Bible project from the separate projects, do the following: 1. Follow the steps provided in this document for creating a study Bible project. The project you create in step 1 is the project into which the previously-separate notes and sidebars projects will be merged when you finish the following steps. 2. Open a window of the main text project (e.g. ABC) to make it the active window. 3. From the Tools menu, select Advanced, and then select Merge Study Bible Projects.... A study Bible merge settings dialog will appear. 4. Select the existing Notes Project from the drop-down menu. 5. Select the existing Sidebars Project (if applicable). 6. Note Placement - Select whether to establish a connection for notes with the base text project before or after the quoted text. 7. Ignore in Quoted Text - If there are any characters of markers deliberately used in the footnote quotation (\fq) sections of the extended notes, which are not contained in the origin verse text of the base project, these should be entered here (as a regular expression if necessary), separated by the | character. For example, footnote quotations often end with a punctuation character, such as a colon (:). You would need to include a colon : in the Ignore in Quoted Text field. 8. Select the project created in step 1 from the Merged Text Project drop-down menu. You will be asked if it is OK to overwrite the project you selected whenever the "Merge" button is clicked; click OK.

9. Click Merge. You will be warned that books in the new study Bible project will be overwritten, and asked if you wish to do the merge; click OK.

The Notes and Sidebars previously contained in separate study Bible projects will then get copied into a single study Bible project. Paratext will attempt to merge all extended notes at the location where a footnote quotation (\fq) matches the base text . If there are problems with the merge, a "study Bible merge results" list will appear. Fix the errors in the list and repeat the steps above (from step 2 onwards). Pay close attention to whether the entry in the Ignore in Quoted Text field needs adjustment in order for Paratext to properly detect merge locations for footnote quotations (\fq).